POST
/
ats
/
candidates
Create candidate
curl --request POST \
  --url https://api.kombo.dev/v1/ats/candidates \
  --header 'Authorization: Bearer <token>' \
  --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",
      "state": "NY"
    },
    "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": "<string>",
  "data": {
    "id": "<string>",
    "remote_id": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "company": "<string>",
    "title": "<string>",
    "confidential": true,
    "source": "<string>",
    "phone_numbers": [],
    "email_addresses": [],
    "social_media": [],
    "location": {
      "city": "<string>",
      "country": "<string>",
      "raw": "<string>",
      "state": "<string>",
      "street_1": "<string>",
      "street_2": "<string>",
      "zip_code": "<string>"
    },
    "custom_fields": {},
    "integration_fields": [
      {
        "id": "5NVFhMpB9Ah6by44tzNjZLyE",
        "key": "firstName",
        "type": "DEFAULT",
        "value": "Frank",
        "label": "First Name"
      },
      {
        "id": "8nuajYpoRd5GnxEQaaWKUDYQ",
        "key": "customTshirtSize",
        "type": "CUSTOM",
        "value": "XL",
        "label": "T-Shirt Size"
      }
    ],
    "remote_url": "<string>",
    "remote_created_at": "2023-11-07T05:31:56Z",
    "remote_updated_at": "2023-11-07T05:31:56Z",
    "remote_data": {},
    "changed_at": "2023-11-07T05:31:56Z",
    "remote_deleted_at": "2023-11-07T05:31:56Z",
    "applications": [
      {
        "id": "<string>",
        "remote_id": "<string>",
        "outcome": "PENDING",
        "rejection_reason_name": "<string>",
        "rejected_at": "2023-11-07T05:31:56Z",
        "remote_url": "<string>",
        "changed_at": "2023-11-07T05:31:56Z",
        "remote_created_at": "2023-11-07T05:31:56Z",
        "remote_updated_at": "2023-11-07T05:31:56Z",
        "current_stage": {
          "id": "<string>",
          "name": "<string>",
          "remote_id": "<string>",
          "index": 2
        },
        "job": {
          "id": "H5daSm8e85Dmvmne3wLeCPhX",
          "name": "Backend Engineer",
          "remote_id": "32"
        }
      }
    ],
    "tags": [
      {
        "id": "26vafvWSRmbhNcxJYqjCzuJg",
        "name": "High Potential",
        "remote_id": "32"
      }
    ]
  },
  "warnings": [
    {
      "message": "<string>"
    }
  ]
}
We recommend using the Create application endpoint instead.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 applicationUsing 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 applications and candidates 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",
      "state": "NY"
    },
    "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"
      ]
    }
  ],
  "remote_fields": {}
}

Authorizations

​
Authorization
string
header
required

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

POST /ats/candidates Request body

​
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 for a job can be retrieved from the get jobs endpoint. The answers will be validated based on the format of the questions. Make sure to follow this schema to avoid errors.

Examples:
[
  {
    "question_id": "D8yPrjXXvA2XeBksTmrVvKSn",
    "answer": "Yes"
  }
]
​
attachments
object[]

An array of the attachments you would like upload.

​
source
object
deprecated

(⚠️ 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

POST /ats/candidates Positive response

​
status
string
required
Allowed value: "success"
​
data
object
required
​
warnings
object[]
required

These are the interaction warnings that are shown in the dashboard. They are meant to provide debug information to you. We recommend logging them to the console.