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


with SDK(
    integration_id="workday:HWUTwvyx2wLoSUHphiWVrp28",
    api_key="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.ats.create_candidate(candidate={
        "first_name": "Frank",
        "last_name": "Doe",
        "email_address": "frank.doe@example.com",
        "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": "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"
    },
    "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!"
    }
  ]
}

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.

​
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
Examples:
{
  "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"
  },
  "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
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.