Custom attributes are special fields that you can add to a candidate's record to store additional information about the candidate. Custom attributes can be used to track information that is not included in the default candidate fields, such as a candidate's skills or availability.

There are several different types of custom attributes that you can use, depending on the type of information you want to track. The available attribute types are:

text: A short text field (up to 255 characters)
number: A numeric field
url: A URL field
multiple_choice: A multiple choice field, where the candidate can select one or more options from a predefined list
datetime: A date and time field
boolean: A field that can have a value of true or false
free_text: A free-text field that can store larger amounts of text

A custom attribute can be set on a candidate any time, but will only be available in the UI once there is a custom attribute in Great Question. This can only currently be done via the UI

To add custom attributes to a candidate's record, you can use the extra parameter in the /v1/candidates endpoint. The extra parameter is a special object that allows you to add any number of custom attributes to a candidate's record. Here's an example of how to use the extra parameter to add a custom attribute to a candidate's record:

POST /v1/candidates
Authorization: Bearer <TOKEN>

{
  "candidate": {
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "skills": ["Java", "Python", "C++"]
    }
  }
}

In the example above, we added a custom attribute called skills with a value of ["Java", "Python", "C++"]. This attribute will be stored in the candidate's record, and can be accessed and used like any other attribute.

Posts are considered upserts. We match on email and consider this unique on the account. If an existing record is found it will be updated.

To update a custom attribute on a candidate's record, you can use the PATCH method to update the candidate's information. In the request body, include the updated values for the custom attributes you want to update. Here's an example of how to update a custom attribute using the PATCH method:

PATCH /v1/candidates/<CANDIDATE_ID>
Authorization: Bearer <TOKEN>

{
  "candidate": {
    "skills": ["Java", "Python", "C++", "Go"]
   }
}

In the example above, we updated the skills custom attribute for the candidate with the ID <CANDIDATE_ID>. The updated attribute will be stored in the candidate's record, replacing the previous value.

Custom attributes can be very useful for storing and tracking additional information about candidates. They can be used in many different ways, depending on your specific needs. Some examples of common use cases for custom attributes include:

plan type
account status
number of purchases
start date
website