POST
/
ats
/
candidates
Authorization
Header
Body
curl --request POST \
  --url https://api.kombo.dev/v1/ats/candidates \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Integration-Id: <x-integration-id>' \
  --data '{
  "candidate": {
    "first_name": "Frank",
    "last_name": "Doe",
    "company": "Acme Inc.",
    "title": "Head of Integrations",
    "email_address": "frank.doe@example.com",
    "phone_number": "+1-541-754-3010",
    "gender": "MALE",
    "salary_expectations": {
      "amount": 100000,
      "period": "YEAR"
    },
    "availability_date": "2021-01-01",
    "location": {
      "city": "New York",
      "country": "US"
    },
    "social_links": [
      {
        "url": "https://www.linkedin.com/in/frank-doe-123456789/"
      },
      {
        "url": "https://twitter.com/frankdoe"
      }
    ]
  },
  "application": {
    "job_id": "BDpgnpZ148nrGh4mYHNxJBgx",
    "stage_id": "8x3YKRDcuRnwShdh96ShBNn1"
  },
  "attachments": [
    {
      "name": "Frank Doe CV.txt",
      "data": "SGkgdGhlcmUsIEtvbWJvIGlzIGN1cnJlbnRseSBoaXJpbmcgZW5naW5lZXJzIHRoYXQgbG92ZSB0byB3b3JrIG9uIGRldmVsb3BlciBwcm9kdWN0cy4=",
      "type": "CV",
      "content_type": "text/plain"
    }
  ],
  "screening_question_answers": [
    {
      "question_id": "3phFBNXRweGnDmsU9o2vdPuQ",
      "answer": "Yes"
    },
    {
      "question_id": "EYJjhMQT3LtVKXnTbnRT8s6U",
      "answer": [
        "GUzE666zfyjeoCJX6A8n7wh6",
        "5WPHzzKAv8cx97KtHRUV96U8",
        "7yZfKGzWigXxxRTygqAfHvyE"
      ]
    }
  ]
}'
{
  "status": "success",
  "data": {
    "id": "26vafvWSRmbhNcxJYqjCzuJg",
    "remote_id": "32",
    "first_name": "John",
    "last_name": "Doe",
    "company": "Acme, Inc.",
    "title": "Head of Marketing",
    "confidential": false,
    "source": "Employee Referral",
    "phone_numbers": [
      {
        "phone_number": "+1-541-754-3010",
        "type": "HOME"
      }
    ],
    "email_addresses": [
      {
        "email_address": "john.doe@example.com",
        "type": "PRIVATE"
      }
    ],
    "social_media": [
      {
        "link": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "type": "YOUTUBE",
        "username": null
      }
    ],
    "location": {
      "city": "Berlin",
      "country": "DE",
      "raw": "Berlin, Germany",
      "state": "Berlin",
      "street_1": "Lohmühlenstraße 65",
      "street_2": null,
      "zip_code": "12435"
    },
    "remote_created_at": "2022-04-02T00:00:00.000Z",
    "remote_updated_at": "2022-04-04T00:00:00.000Z",
    "changed_at": "2022-04-04T00:00:00.000Z",
    "remote_deleted_at": null
  },
  "warnings": [
    {
      "message": "<string>"
    }
  ]
}

This endpoint is deprecated!

We realized that in practice it was always more about creating applications instead of candidates, so we created a new, more aptly named one that you should use instead: Create application

Using it also has the benefit that we return the newly created applicant at the root level, so you can easily store its ID.

This endpoint requires the permission Create and manage candidates and applications to be enabled in your scope config.

​
Example Request Body

{
  "candidate": {
    "first_name": "Frank",
    "last_name": "Doe",
    "company": "Acme Inc.",
    "title": "Head of Integrations",
    "email_address": "frank.doe@example.com",
    "phone_number": "+1-541-754-3010",
    "gender": "MALE",
    "salary_expectations": {
      "amount": 100000,
      "period": "YEAR"
    },
    "availability_date": "2021-01-01",
    "location": {
      "city": "New York",
      "country": "US"
    },
    "social_links": [
      {
        "url": "https://www.linkedin.com/in/frank-doe-123456789/"
      },
      {
        "url": "https://twitter.com/frankdoe"
      }
    ]
  },
  "application": {
    "job_id": "BDpgnpZ148nrGh4mYHNxJBgx",
    "stage_id": "8x3YKRDcuRnwShdh96ShBNn1"
  },
  "screening_question_answers": [
    {
      "question_id": "3phFBNXRweGnDmsU9o2vdPuQ",
      "answer": "Yes"
    },
    {
      "question_id": "EYJjhMQT3LtVKXnTbnRT8s6U",
      "answer": [
        "GUzE666zfyjeoCJX6A8n7wh6",
        "5WPHzzKAv8cx97KtHRUV96U8",
        "7yZfKGzWigXxxRTygqAfHvyE"
      ]
    }
  ],
  "attachments": [
    {
      "name": "Frank Doe CV.txt",
      "data": "SGkgdGhlcmUsIEtvbWJvIGlzIGN1cnJlbnRseSBoaXJpbmcgZW5naW5lZXJzIHRoYXQgbG92ZSB0byB3b3JrIG9uIGRldmVsb3BlciBwcm9kdWN0cy4=",
      "type": "CV",
      "content_type": "text/plain"
    }
  ]
}

Authorizations

Authorization
string
headerrequired

Create an API key on the Secrets page in the Kombo dashboard.

Headers

X-Integration-Id
string
required

ID of the integration you want to interact with.

Body

application/json
candidate
object
required
application
object
required

Currently, every candidate has one application. If you are interested in talent pools, please contact Kombo.

screening_question_answers
object[]

Array of answers to screening questions. Currently, not all question types are supported and unsupported ones will not be submitted.

The available questions a job can be retrieved from the get jobs endpoint. The answers will be validated based on the format of the the questions. Make sure to follow this schema to avoid errors.

attachments
object[]

Array of the attachments you would like upload.

source
object

(⚠️ Deprecated - Use automatic source writing instead) Optional source information that will be attached to the candidate. If you're a job board or recruiting service, you can use this to make sure your customers can see which candidates came from you.

This is deprecated because writing sources requires users to do some setup in most ATSs.

gdpr_consent
object

Optional GDPR consent information required in some jurisdictions (like the Czech Republic or Slovakia).

remote_fields
object

Additional fields that we will pass through to specific ATS systems.

Response

200 - application/json
status
enum<string>
required
Available options:
success
data
object
required
warnings
object[]
required
Get candidatesAdd attachment to candidate