Skip to main content
POST
/
ats
/
candidates
Python
from kombo import Kombo
from kombo.utils import parse_datetime


with Kombo(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as k_client:

    res = k_client.ats.create_candidate(candidate={
        "first_name": "Frank",
        "last_name": "Doe",
        "email_address": "[email protected]",
        "company": "Acme Inc.",
        "title": "Head of Integrations",
        "phone_number": "+1-541-754-3010",
        "location": {
            "city": "New York",
            "country": "US",
            "state": "NY",
        },
        "gender": "MALE",
        "availability_date": parse_datetime("2021-01-01T00:00:00Z"),
        "salary_expectations": {
            "period": "YEAR",
            "amount": 100000,
        },
        "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",
            "content_type": "text/plain",
            "data": "SGkgdGhlcmUsIEtvbWJvIGlzIGN1cnJlbnRseSBoaXJpbmcgZW5naW5lZXJzIHRoYXQgbG92ZSB0byB3b3JrIG9uIGRldmVsb3BlciBwcm9kdWN0cy4=",
            "type": "CV",
        },
    ])

    # Handle response
    print(res)
{
  "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": "[email protected]",
        "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"
    },
    "custom_fields": {},
    "integration_fields": [],
    "remote_url": "https://app.greenhouse.io/people/32",
    "remote_created_at": "2022-04-02T00:00:00.000Z",
    "remote_updated_at": "2022-04-04T00:00:00.000Z",
    "remote_data": null,
    "changed_at": "2022-04-04T00:00:00.000Z",
    "remote_deleted_at": null,
    "applications": [
      {
        "id": "H77fDF8uvEzGNPRubiz5DvQ7",
        "remote_id": "32",
        "outcome": "HIRED",
        "rejection_reason_name": null,
        "rejected_at": null,
        "remote_url": "https://app.greenhouse.io/applications/32",
        "changed_at": "2022-04-04T00:00:00.000Z",
        "remote_created_at": "2022-04-02T00:00:00.000Z",
        "remote_updated_at": "2022-04-04T00:00:00.000Z",
        "current_stage": {
          "id": "5J7L4b48wBfffYwek9Az9pkM",
          "name": "Initial Screening",
          "remote_id": "32",
          "index": 2
        },
        "job": {
          "id": "H5daSm8e85Dmvmne3wLeCPhX",
          "name": "Backend Engineer",
          "remote_id": "32"
        }
      }
    ],
    "tags": [
      {
        "id": "26vafvWSRmbhNcxJYqjCzuJg",
        "name": "High Potential",
        "remote_id": "32"
      }
    ]
  },
  "warnings": [
    {
      "message": "This is an example warning!"
    }
  ]
}
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": "[email protected]",
    "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.

​
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.

​
sourced_by
object

Credit the recruiter or team member who sourced this candidate.

While the source field tracks the channel/platform (e.g., "Awesome Jobboard"), the sourced_by field tracks the individual person responsible for finding the candidate.

​
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.