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"
    },
    "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": null,
      "country": null,
      "raw": null,
      "state": null,
      "street_1": null,
      "street_2": null,
      "zip_code": null
    },
    "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_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>",
        "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 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 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"
    },
    "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

The body is of type object.

Response

200
application/json

POST /ats/candidates Positive response

The response is of type object.