API Reference

Creating your first candidate

Welcome to the guide for creating your first candidate using the /v1/candidates endpoint. This guide will walk you through the process of creating a new candidate, including adding custom attributes through the extra parameter.

First, make sure you have an authorization token. This is required for all requests to the /v1/candidates endpoint. You can obtain an authorization token by following the instructions in our guide on authentication.

Once you have an authorization token, you can use it to make a POST request to the /v1/candidates endpoint to create a new candidate. In the request body, include the candidate's information in the following format:

{
  "data": {
    "type": "candidate",
    "attributes": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "extra": {
        "country_code": "US"
      }
    }
  }
}

The extra parameter is a special attribute that allows you to add custom attributes to the candidate's record. In the example above, we added a country_code attribute with a value of US. You can add any custom attributes you need by adding them to the extra object in the request body.

Here's an example of a complete request to create a new candidate, including the authorization token:

POST /v1/candidates
Authorization: Bearer <TOKEN>

{
  "data": {
    "type": "candidate",
    "attributes": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe",
      "extra": {
        "country_code": "US"
      }
    }
  }
}

If the request is successful, you will receive a response with a 200 status code and the newly created candidate's information in the following format:

{
  "data": {
    "id": "74",
    "type": "customer",
    "attributes": {
      "created_at": "2022-12-07T05:17:58.529Z",
      "updated_at": "2022-12-07T05:17:58.529Z",
      "deleted_at": null,
      "id": 74,
      "last_contacted_at": null,
      "name": "Jeanette Dare LLD",
      "email": "[email protected]",
      "phone_number": null,
      "first_name": "Jeanette",
      "last_name": "Dare LLD",
      "timezone": null,
      "email_valid": true,
      "phone_number_valid": null,
      "extra": {
        "country_code": null
      },
      "consent": null,
      "opted_in": null,
      "unsubscribed": false,
      "consented_at": null,
      "unsubscribed_at": null,
      "health_status": {}
    }