Skip to content

README.md

Latest commit

 

History

History
2186 lines (1591 loc) · 624 KB

README.md

File metadata and controls

2186 lines (1591 loc) · 624 KB

Ats

Overview

Available Operations

get_applications

Retrieve all applications.

Visit our in-depth guides to learn more about:

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_applications(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, updated_after matches when the returned record changed, or when related data changed as described below.

| Path | Relationship | Target Record |
| --- | --- | --- |
| candidate | n/a | ✓ Yes |
| candidate → tags | ✗ No | ✗ No |
| current_stage | n/a | ✓ Yes |
| job | ✗ No | ✗ No |
| interviews | ✓ Yes | ✓ Yes |
| offers | ✓ Yes | ✓ Yes |

Relationship: Whether adding or removing entries from this list triggers an update (n/a for single references that are not lists). Target Record: Whether changes to the linked record itself trigger an update.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
outcomes List[str] ➖ Filter by a comma-separated list of PENDING, HIRED, DECLINED
* PENDING: The application is still being processed.
* HIRED: The candidate was hired.
* DECLINED: The candidate was declined.


Leave this blank to get results matching all values.
job_ids List[str] ➖ Filter by a comma-separated list of job IDs. We will only return applications that are related to any of the jobs.
job_remote_ids List[str] ➖ Filter by a comma-separated list of job remote IDs. We will only return applications that are related to any of the jobs.
current_stage_ids List[str] ➖ Filter by a comma-separated list of application stage IDs. We will only return applications that are currently in any of the stages.
remote_created_after date ➖ Filter applications by the day they were created in the remote system. This allows you to get applications that were created on or after a certain day.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsApplicationsResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

move_application_to_stage

Moves an application to a specified stage. Use job-specific stages from GET /jobs, not the deprecated /application-stages endpoint.

This endpoint requires the permission **Set application stage** to be enabled in [your scope config](/scopes).

Example Request Body

{
  "stage_id": "3PJ8PZhZZa1eEdd2DtPNtVup",
  "remote_fields": {}
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.move_application_to_stage(application_id="<id>", stage_id="<id>")

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.move_application_to_stage(application_id="<id>", stage_id="<id>")

    # Handle response
    print(res)

Example Usage: example1

from kombo import Kombo


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

    res = k_client.ats.move_application_to_stage(application_id="GRKdd9dibYKKCrmGRSMJf3wu", stage_id="3PJ8PZhZZa1eEdd2DtPNtVup")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
application_id str ✔️ The Kombo ID of the application you want to move to a different stage.
stage_id str ✔️ The Kombo ID of the stage to move the application to. This stage must be allowed for the job that the application is connected to. Get available stages from the stages property on the job, not from the deprecated application-stages endpoint.
remote_fields Optional[models.PutAtsApplicationsApplicationIDStageRequestBodyRemoteFields] ➖ Additional fields that we will pass through to specific ATS systems.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PutAtsApplicationsApplicationIDStagePositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

add_application_result_link

Add a result link to an application.

This can, for example, be used to link a candidate back to a test result/assessment in your application. As not all ATS tools have a "result link" feature, we sometimes repurpose other fields to expose it.

This endpoint requires the permission **Add result links** to be enabled in [your scope config](/scopes).

Example Request Body

{
  "application_id": "8Xi6iZrwusZqJmDGXs49GBmJ",
  "label": "Assessment Result",
  "url": "https://example.com/test-results/5BtP1WC1UboS7CF3yxjKcvjG",
  "details": {
    "custom_field_name_prefix": "Acme:",
    "attributes": [
      {
        "key": "Score",
        "value": "100%"
      },
      {
        "key": "Time",
        "value": "2:30h"
      }
    ]
  },
  "remote_fields": {}
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.add_application_result_link(application_id="<id>", label="<value>", url="https://dapper-grandson.com/")

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.add_application_result_link(application_id="<id>", label="<value>", url="https://dapper-grandson.com/")

    # Handle response
    print(res)

Example Usage: example1

from kombo import Kombo


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

    res = k_client.ats.add_application_result_link(application_id="8Xi6iZrwusZqJmDGXs49GBmJ", label="Assessment Result", url="https://example.com/test-results/5BtP1WC1UboS7CF3yxjKcvjG", details={
        "custom_field_name_prefix": "Acme:",
        "attributes": [
            {
                "key": "Score",
                "value": "100%",
            },
            {
                "key": "Time",
                "value": "2:30h",
            },
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
application_id str ✔️ The Kombo ID of the application you want to create the link for.
label str ✔️ If we can display a display name for the link, we will use this label.
url str ✔️ URL of the link.
details Optional[models.PostAtsApplicationsApplicationIDResultLinksRequestBodyDetails] ➖ Additional details with attributes that will be added to the result. This can be percentages, scores, or any text.

We generally recommend using short attribute keys and a short custom_field_name_prefix to avoid overflowing the ATS UI.
remote_fields Optional[models.PostAtsApplicationsApplicationIDResultLinksRequestBodyRemoteFields] ➖ Additional fields that we will pass through to specific ATS systems.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsApplicationsApplicationIDResultLinksPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

add_application_note

Add a note to an application.

Add extra information to an application. This can be any extra text information you want to add to an application.

This endpoint requires the permission **Add notes** to be enabled in [your scope config](/scopes).

Example Request Body

{
  "content": "A new message from the candidate is available in YourChat!",
  "content_type": "PLAIN_TEXT",
  "remote_fields": {}
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.add_application_note(application_id="<id>", content="<value>", content_type="PLAIN_TEXT")

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.add_application_note(application_id="<id>", content="<value>", content_type="PLAIN_TEXT")

    # Handle response
    print(res)

Example Usage: example1

from kombo import Kombo


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

    res = k_client.ats.add_application_note(application_id="8Xi6iZrwusZqJmDGXs49GBmJ", content="A new message from the candidate is available in YourChat!", content_type="PLAIN_TEXT")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
application_id str ✔️ The Kombo ID of the application you want to create the note for.
content str ✔️ UTF-8 content of the note.
content_type models.ContentType ✔️ Content type of the note. Currently only PLAIN_TEXT is supported.
remote_fields Optional[models.PostAtsApplicationsApplicationIDNotesRequestBodyRemoteFields] ➖ Tool specific remote fields for the note.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsApplicationsApplicationIDNotesPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_application_attachments

Get attachments from a candidate or application.

Get attachments from an application. If the ATS stores the attachments on the candidate, it will get the attachments from the corresponding candidate instead.

This endpoint requires the permission **Read document attachments** to be enabled in [your scope config](/scopes).

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_application_attachments(application_id="8Xi6iZrwusZqJmDGXs49GBmJ")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
application_id str ✔️ The Kombo ID of the application you want to obtain attachments for.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsApplicationsApplicationIDAttachmentsPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

add_application_attachment

Uploads an attachment file for the specified applicant.

If adding an attachment to an application is not supported by the integration, the attachment will be [added to the candidate](/ats/v1/post-candidates-candidate-id-attachments) instead. This endpoint requires the permission **Add attachments** to be enabled in [your scope config](/scopes).

Example Request Body

{
  "application_id": "GRKdd9dibYKKCrmGRSMJf3wu",
  "attachment": {
    "name": "Frank Doe CV.txt",
    "data": "SGkgdGhlcmUsIEtvbWJvIGlzIGN1cnJlbnRseSBoaXJpbmcgZW5naW5lZXJzIHRoYXQgbG92ZSB0byB3b3JrIG9uIGRldmVsb3BlciBwcm9kdWN0cy4=",
    "type": "CV",
    "content_type": "text/plain"
  },
  "remote_fields": {}
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.add_application_attachment(application_id="<id>", attachment={
        "name": "<value>",
        "type": "CV",
    })

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.add_application_attachment(application_id="<id>", attachment={
        "name": "<value>",
        "type": "CV",
    })

    # Handle response
    print(res)

Example Usage: example1

from kombo import Kombo


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

    res = k_client.ats.add_application_attachment(application_id="GRKdd9dibYKKCrmGRSMJf3wu", attachment={
        "name": "Frank Doe CV.txt",
        "content_type": "text/plain",
        "data": "SGkgdGhlcmUsIEtvbWJvIGlzIGN1cnJlbnRseSBoaXJpbmcgZW5naW5lZXJzIHRoYXQgbG92ZSB0byB3b3JrIG9uIGRldmVsb3BlciBwcm9kdWN0cy4=",
        "type": "CV",
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
application_id str ✔️ POST /ats/applications/:application_id/attachments Parameter
attachment models.PostAtsApplicationsApplicationIDAttachmentsRequestBodyAttachment ✔️ N/A
remote_fields Optional[models.PostAtsApplicationsApplicationIDAttachmentsRequestBodyRemoteFields] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsApplicationsApplicationIDAttachmentsPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

reject_application

Rejects an application with a provided reason.

Rejects an application with a provided reason. Optionally, you can provide a free text note. You can get the list of rejection reasons with our Get rejection reasons endpoint.

This endpoint requires the permission **Reject applications** to be enabled in [your scope config](/scopes).

Example Request Body

{
  "rejection_reason_id": "3PJ8PZhZZa1eEdd2DtPNtVup",
  "note": "Candidate was a great culture fit but didn't bring the hard skills we need.",
  "remote_fields": {}
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.reject_application(application_id="<id>", rejection_reason_id="<id>")

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.reject_application(application_id="<id>", rejection_reason_id="<id>")

    # Handle response
    print(res)

Example Usage: example1

from kombo import Kombo


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

    res = k_client.ats.reject_application(application_id="GRKdd9dibYKKCrmGRSMJf3wu", rejection_reason_id="3PJ8PZhZZa1eEdd2DtPNtVup", note="Candidate was a great culture fit but didn't bring the hard skills we need.")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
application_id str ✔️ The Kombo ID of the application you want to reject.
rejection_reason_id str ✔️ The Kombo ID of the rejection reason.
note Optional[str] ➖ A optional free text rejection note. Passed through if possible.
remote_fields Optional[models.PostAtsApplicationsApplicationIDRejectRequestBodyRemoteFields] ➖ Additional fields that we will pass through to specific ATS systems.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsApplicationsApplicationIDRejectPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_candidates

Retrieve all candidates.

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_candidates(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, updated_after matches when the returned record changed, or when related data changed as described below.

| Path | Relationship | Target Record |
| --- | --- | --- |
| applications | ✓ Yes | ✓ Yes |
| applications → current_stage | ✗ No | ✗ No |
| applications → job | ✗ No | ✗ No |
| tags | ✓ Yes | ✗ No |

Relationship: Whether adding or removing entries from this list triggers an update (n/a for single references that are not lists). Target Record: Whether changes to the linked record itself trigger an update.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
email Optional[str] ➖ Filter the candidates based on an email address. When set, returns only the candidates where the given email is in email_addresses. This filter is case-insensitive.
job_ids List[str] ➖ Filter by a comma-separated list of job IDs. We will only return candidates that have applied to any of the jobs.
first_name Optional[str] ➖ Filter candidates by first name. This filter is case-insensitive and matches the exact first name. Fuzzy matching might be enabled in the future, so consider this for your implementation.
last_name Optional[str] ➖ Filter candidates by last name. This filter is case-insensitive and matches the exact last name. Fuzzy matching might be enabled in the future, so consider this for your implementation.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsCandidatesResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

create_candidate

Create a new candidate and application for the specified job.

**We recommend using the [Create application](/ats/v1/post-jobs-job-id-applications) 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](/ats/v1/post-jobs-job-id-applications)

  Using it also has the benefit that we return the newly created applicant at the root level, so you can easily store its ID.
</Warning>
This endpoint requires the permission **Create applications and candidates** to be enabled in [your scope config](/scopes).

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": {}
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.create_candidate(candidate={
        "first_name": "Crystal",
        "last_name": "Prohaska",
        "email_address": "Adelia.Littel99@yahoo.com",
    }, application={
        "job_id": "<id>",
    }, screening_question_answers=[
        {
            "question_id": "D8yPrjXXvA2XeBksTmrVvKSn",
            "answer": "Yes",
        },
    ])

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.create_candidate(candidate={
        "first_name": "Crystal",
        "last_name": "Prohaska",
        "email_address": "Adelia.Littel99@yahoo.com",
    }, application={
        "job_id": "<id>",
    }, screening_question_answers=[
        {
            "question_id": "D8yPrjXXvA2XeBksTmrVvKSn",
            "answer": "Yes",
        },
    ])

    # Handle response
    print(res)

Example Usage: example1

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": "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)

Parameters

Parameter Type Required Description Example
candidate models.PostAtsCandidatesRequestBodyCandidate ✔️ N/A
application models.PostAtsCandidatesRequestBodyApplication ✔️ Currently, every candidate has one application. If you are interested in talent pools, please contact Kombo.
screening_question_answers List[models.PostAtsCandidatesRequestBodyScreeningQuestionAnswer] ➖ 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.		 [
{
"question_id": "D8yPrjXXvA2XeBksTmrVvKSn",
"answer": "Yes"
}
]
attachments List[models.PostAtsCandidatesRequestBodyAttachment] ➖ An array of the attachments you would like upload.
source Optional[models.PostAtsCandidatesRequestBodySource] ➖ : warning: ** DEPRECATED : This will be removed in a future release, please migrate away from it as soon as possible.

(⚠️ 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 Optional[models.PostAtsCandidatesRequestBodySourcedBy] ➖ 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 Optional[models.PostAtsCandidatesRequestBodyGdprConsent] ➖ Optional GDPR consent information required in some jurisdictions (like the Czech Republic or Slovakia).
remote_fields Optional[models.PostAtsCandidatesRequestBodyRemoteFields] ➖ Additional fields that we will pass through to specific ATS systems.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsCandidatesPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_candidate_attachments

Get attachments from a candidate, including all attachments of all of their applications.

This endpoint requires the permission **Read document attachments** to be enabled in [your scope config](/scopes).

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_candidate_attachments(candidate_id="8Xi6iZrwusZqJmDGXs49GBmJ")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
candidate_id str ✔️ The Kombo ID of the candidate you want to obtain attachments for.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsCandidatesCandidateIDAttachmentsPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

add_candidate_attachment

Uploads an attachment file for the specified candidate.

**We recommend using the [add attachment to application](/ats/v1/post-applications-application-id-attachments) endpoint instead.**

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

This endpoint requires the permission **Add attachments** to be enabled in [your scope config](/scopes).

Example Request Body

{
  "candidate_id": "GRKdd9dibYKKCrmGRSMJf3wu",
  "attachment": {
    "name": "Frank Doe CV.txt",
    "data": "SGkgdGhlcmUsIEtvbWJvIGlzIGN1cnJlbnRseSBoaXJpbmcgZW5naW5lZXJzIHRoYXQgbG92ZSB0byB3b3JrIG9uIGRldmVsb3BlciBwcm9kdWN0cy4=",
    "type": "CV",
    "content_type": "text/plain"
  }
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.add_candidate_attachment(candidate_id="<id>", attachment={
        "name": "<value>",
        "type": "COVER_LETTER",
    })

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.add_candidate_attachment(candidate_id="<id>", attachment={
        "name": "<value>",
        "type": "COVER_LETTER",
    })

    # Handle response
    print(res)

Example Usage: example1

from kombo import Kombo


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

    res = k_client.ats.add_candidate_attachment(candidate_id="GRKdd9dibYKKCrmGRSMJf3wu", attachment={
        "name": "Frank Doe CV.txt",
        "content_type": "text/plain",
        "data": "SGkgdGhlcmUsIEtvbWJvIGlzIGN1cnJlbnRseSBoaXJpbmcgZW5naW5lZXJzIHRoYXQgbG92ZSB0byB3b3JrIG9uIGRldmVsb3BlciBwcm9kdWN0cy4=",
        "type": "CV",
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
candidate_id str ✔️ The Kombo ID of the candidate you want to add the attachment to.
attachment models.PostAtsCandidatesCandidateIDAttachmentsRequestBodyAttachment ✔️ N/A
remote_fields Optional[models.PostAtsCandidatesCandidateIDAttachmentsRequestBodyRemoteFields] ➖ Additional fields that we will pass through to specific ATS systems.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsCandidatesCandidateIDAttachmentsPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

add_candidate_result_link

Add a result link to a candidate.

**We recommend to use [add result link to application](/ats/v1/post-applications-application-id-result-links) instead.**

This can, for example, be used to link a candidate back to a test result/assessment in your application. As not all ATS tools have a "result link" feature, we sometimes repurpose other fields to expose it.

This endpoint requires the permission **Add result links** to be enabled in [your scope config](/scopes).

Example Request Body

{
  "label": "Assessment Result",
  "url": "https://example.com/test-results/5BtP1WC1UboS7CF3yxjKcvjG",
  "details": {
    "custom_field_name_prefix": "Acme:",
    "attributes": [
      {
        "key": "Score",
        "value": "100%"
      },
      {
        "key": "Time",
        "value": "2:30h"
      }
    ]
  },
  "remote_fields": {}
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.add_candidate_result_link(candidate_id="<id>", label="<value>", url="https://thrifty-cellar.net")

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.add_candidate_result_link(candidate_id="<id>", label="<value>", url="https://thrifty-cellar.net")

    # Handle response
    print(res)

Example Usage: example1

from kombo import Kombo


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

    res = k_client.ats.add_candidate_result_link(candidate_id="8Xi6iZrwusZqJmDGXs49GBmJ", label="Assessment Result", url="https://example.com/test-results/5BtP1WC1UboS7CF3yxjKcvjG", details={
        "custom_field_name_prefix": "Acme:",
        "attributes": [
            {
                "key": "Score",
                "value": "100%",
            },
            {
                "key": "Time",
                "value": "2:30h",
            },
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
candidate_id str ✔️ The Kombo ID of the candidate you want to add the result link to.
label str ✔️ If the system allows us to display a display name for the link, we will use this label.
url str ✔️ URL of the link.
details Optional[models.PostAtsCandidatesCandidateIDResultLinksRequestBodyDetails] ➖ Additional details with attributes that will be added to the result. This can be percentages, scores, or any text.

We generally recommend using short attribute keys and a short custom_field_name_prefix to avoid overflowing the ATS UI.
remote_fields Optional[models.PostAtsCandidatesCandidateIDResultLinksRequestBodyRemoteFields] ➖ Additional fields that we will pass through to specific ATS systems.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsCandidatesCandidateIDResultLinksPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

add_candidate_tag

Add a tag to a candidate.

Kombo takes care of creating the tag if required, finding out the right ID, and appending it to the list of tags.

This endpoint requires the permission **Manage tags** to be enabled in [your scope config](/scopes).

Example Request Body

{
  "tag": {
    "name": "Excellent Fit"
  }
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.add_candidate_tag(candidate_id="<id>", tag={
        "name": "<value>",
    })

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.add_candidate_tag(candidate_id="<id>", tag={
        "name": "<value>",
    })

    # Handle response
    print(res)

Example Usage: example1

from kombo import Kombo


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

    res = k_client.ats.add_candidate_tag(candidate_id="8Xi6iZrwusZqJmDGXs49GBmJ", tag={
        "name": "Excellent Fit",
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
candidate_id str ✔️ The Kombo ID of the candidate you want to add the tag to.
tag models.PostAtsCandidatesCandidateIDTagsRequestBodyTag ✔️ N/A
remote_fields Optional[models.PostAtsCandidatesCandidateIDTagsRequestBodyRemoteFields] ➖ Additional fields that we will pass through to specific ATS systems.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsCandidatesCandidateIDTagsPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

remove_candidate_tag

Remove a tag from a candidate based on its name.

This will also succeed if the tag does not exist on the candidate.

This endpoint requires the permission **Manage tags** to be enabled in [your scope config](/scopes).

Example Request Body

{
  "tag": {
    "name": "Excellent Fit"
  }
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.remove_candidate_tag(candidate_id="<id>", tag={
        "name": "<value>",
    })

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.remove_candidate_tag(candidate_id="<id>", tag={
        "name": "<value>",
    })

    # Handle response
    print(res)

Example Usage: example1

from kombo import Kombo


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

    res = k_client.ats.remove_candidate_tag(candidate_id="8Xi6iZrwusZqJmDGXs49GBmJ", tag={
        "name": "Excellent Fit",
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
candidate_id str ✔️ The Kombo ID of the candidate you want to remove the tag from.
tag models.DeleteAtsCandidatesCandidateIDTagsRequestBodyTag ✔️ N/A
remote_fields Optional[models.DeleteAtsCandidatesCandidateIDTagsRequestBodyRemoteFields] ➖ Additional fields that we will pass through to specific ATS systems.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.DeleteAtsCandidatesCandidateIDTagsPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_tags

Retrieve all tags.

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_tags(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, only changes to the returned record itself are considered.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsTagsResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_application_stages

Get all application stages available in the ATS.

**This endpoint is deprecated!**

Get all application stages available in the ATS. This is deprecated because most ATS systems have separate sets of stages for each job. We'd recommend using the stages property from the GET Jobs endpoint instead.

Important: Using global stages can cause "Stage not found" errors when moving applications, especially with systems like Workable that have job-specific stages.

Moving Applications Guide.

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_application_stages(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, only changes to the returned record itself are considered.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsApplicationStagesResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_jobs

Retrieve all jobs.

Visit our in-depth guides to learn more about:

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_jobs(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, updated_after matches when the returned record changed, or when related data changed as described below.

| Path | Relationship | Target Record |
| --- | --- | --- |
| stages | ✓ Yes | ✗ No |
| screening_questions | ✓ Yes | ✗ No |
| job_postings | ✓ Yes | ✓ Yes |
| hiring_team | ✓ Yes | ✗ No |

Relationship: Whether adding or removing entries from this list triggers an update (n/a for single references that are not lists). Target Record: Whether changes to the linked record itself trigger an update.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
job_codes List[str] ➖ Filter by a comma-separated list of job codes.
post_url Optional[str] ➖ Filter by the post_url field. Can be used to find a job based on its public posting URL.
statuses List[str] ➖ Filter by a comma-separated list of OPEN, CLOSED, DRAFT, ARCHIVED

Leave this blank to get results matching all values.
employment_types List[str] ➖ Filter by a comma-separated list of FULL_TIME, PART_TIME, CONTRACT, SEASONAL, INTERNSHIP

Leave this blank to get results matching all values.
visibilities List[str] ➖ Filter by a comma-separated list of PUBLIC, INTERNAL, UNLISTED, CONFIDENTIAL

Leave this blank to get results matching all values.
remote_created_after date ➖ Filter jobs by the day they were created in the remote system. This allows you to get jobs that were created on or after a certain day.
name_contains Optional[str] ➖ Filter by the name field. Can be used to find a job by keywords present in the job name.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsJobsResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

create_application

Create a new application and candidate for the specified job.

Visit our in-depth guides to learn more about:

This endpoint requires the permission **Create applications and candidates** to be enabled in [your scope config](/scopes).

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",
      "zip_code": "10016",
      "state": "NY",
      "country": "US"
    }
  },
  "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": {}
}

Example Usage: Error Response

from kombo import Kombo


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

    res = k_client.ats.create_application(job_id="<id>", candidate={
        "first_name": "Jayda",
        "last_name": "Rogahn",
        "email_address": "Rowena74@hotmail.com",
    }, screening_question_answers=[
        {
            "question_id": "D8yPrjXXvA2XeBksTmrVvKSn",
            "answer": "Yes",
        },
    ])

    # Handle response
    print(res)

Example Usage: Minimal Error Response

from kombo import Kombo


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

    res = k_client.ats.create_application(job_id="<id>", candidate={
        "first_name": "Jayda",
        "last_name": "Rogahn",
        "email_address": "Rowena74@hotmail.com",
    }, screening_question_answers=[
        {
            "question_id": "D8yPrjXXvA2XeBksTmrVvKSn",
            "answer": "Yes",
        },
    ])

    # Handle response
    print(res)

Example Usage: example1

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_application(job_id="BDpgnpZ148nrGh4mYHNxJBgx", 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",
            "zip_code": "10016",
        },
        "gender": "MALE",
        "availability_date": parse_datetime("2021-01-01T00:00:00Z"),
        "salary_expectations": {
            "period": "YEAR",
            "amount": 100000,
        },
    }, stage_id="8x3YKRDcuRnwShdh96ShBNn1", attachments=[
        {
            "name": "Frank Doe CV.txt",
            "content_type": "text/plain",
            "data": "SGkgdGhlcmUsIEtvbWJvIGlzIGN1cnJlbnRseSBoaXJpbmcgZW5naW5lZXJzIHRoYXQgbG92ZSB0byB3b3JrIG9uIGRldmVsb3BlciBwcm9kdWN0cy4=",
            "type": "CV",
        },
    ], screening_question_answers=[
        {
            "question_id": "3phFBNXRweGnDmsU9o2vdPuQ",
            "answer": "Yes",
        },
        {
            "question_id": "EYJjhMQT3LtVKXnTbnRT8s6U",
            "answer": [
                "GUzE666zfyjeoCJX6A8n7wh6",
                "5WPHzzKAv8cx97KtHRUV96U8",
                "7yZfKGzWigXxxRTygqAfHvyE",
            ],
        },
    ])

    # Handle response
    print(res)

Parameters

Parameter Type Required Description Example
job_id str ✔️ The Kombo ID or Remote ID of the Job this candidate should apply for. If you want to use the ID of the integrated system (remote_id) you need to prefix the id with "remote:". You can use the remote ID if you do not want to sync jobs.
candidate models.PostAtsJobsJobIDApplicationsRequestBodyCandidate ✔️ N/A
stage_id Optional[str] ➖ Stage this candidate should be in. If left out, the default stage for this job will be used. You can obtain the possible stage_ids from the get-jobs endpoint.
attachments List[models.PostAtsJobsJobIDApplicationsRequestBodyAttachment] ➖ Array of the attachments you would like to upload. The first CV in the attachments will be treated as the resume of the candidate when the tool allows previewing a resume.
source Optional[models.PostAtsJobsJobIDApplicationsRequestBodySource] ➖ : warning: ** DEPRECATED : This will be removed in a future release, please migrate away from it as soon as possible.

(⚠️ 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 Optional[models.PostAtsJobsJobIDApplicationsRequestBodySourcedBy] ➖ 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 Optional[models.PostAtsJobsJobIDApplicationsRequestBodyGdprConsent] ➖ Optional GDPR consent information required in some jurisdictions (like the Czech Republic or Slovakia).
remote_fields Optional[models.PostAtsJobsJobIDApplicationsRequestBodyRemoteFields] ➖ Additional fields that we will pass through to specific ATS systems.
screening_question_answers List[models.PostAtsJobsJobIDApplicationsRequestBodyScreeningQuestionAnswer] ➖ 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.		 [
{
"question_id": "D8yPrjXXvA2XeBksTmrVvKSn",
"answer": "Yes"
}
]
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsJobsJobIDApplicationsPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_users

Retrieve all users.

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_users(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, updated_after matches when the returned record changed, or when related data changed as described below.

| Path | Relationship | Target Record |
| --- | --- | --- |
| system_role_assignment | ✓ Yes | ✓ Yes |

Relationship: Whether adding or removing entries from this list triggers an update (n/a for single references that are not lists). Target Record: Whether changes to the linked record itself trigger an update.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
emails List[str] ➖ Filter by a comma-separated list of emails. We will only return users who have any of the emails. The format of the emails is case-insensitive.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsUsersResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_roles

Retrieve all roles.

Visit our in-depth guide about roles to learn more.

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_roles(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, only changes to the returned record itself are considered.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
scopes List[str] ➖ Filter by a comma-separated list of SYSTEM, JOB
* SYSTEM: System-wide roles that apply globally (e.g., an "Admin" role).
* JOB: Job-scoped roles that apply to specific jobs (e.g., a "Hiring Manager" role).


Leave this blank to get results matching all values.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsRolesResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_offers

Retrieve all offers.

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_offers(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, updated_after matches when the returned record changed, or when related data changed as described below.

| Path | Relationship | Target Record |
| --- | --- | --- |
| application | n/a | ✓ Yes |
| application → candidate | ✗ No | ✗ No |
| application → job | ✗ No | ✗ No |

Relationship: Whether adding or removing entries from this list triggers an update (n/a for single references that are not lists). Target Record: Whether changes to the linked record itself trigger an update.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsOffersResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_rejection_reasons

Retrieve all rejection reasons.

Get all rejection reasons available in the system. The Kombo ID is required in the associated reject application action.

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_rejection_reasons(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, only changes to the returned record itself are considered.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsRejectionReasonsResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

get_interviews

Retrieve all interviews.

Top level filters use AND, while individual filters use OR if they accept multiple arguments. That means filters will be resolved like this: (id IN ids) AND (remote_id IN remote_ids)

Example Usage

from kombo import Kombo


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

    res = k_client.ats.get_interviews(page_size=100, include_deleted=False, ignore_unsupported_filters=False)

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter Type Required Description
cursor Optional[str] ➖ An optional cursor string used for pagination. This can be retrieved from the next property of the previous page response.
page_size Optional[int] ➖ The number of results to return per page. Maximum is 250.
updated_after date ➖ Filter the entries based on the modification date in format YYYY-MM-DDTHH:mm:ss.sssZ. Returns records where either the record itself OR its nested data has been updated since this timestamp, even if the record's own changed_at field remains unchanged.

If you want to track entry deletion, also set the include_deleted=true query parameter, because otherwise, deleted entries will be hidden.

For more details, see Understanding changed_at vs updated_after Behavior.

For this endpoint, updated_after matches when the returned record changed, or when related data changed as described below.

| Path | Relationship | Target Record |
| --- | --- | --- |
| interviewers | ✓ Yes | ✗ No |
| application | n/a | ✓ Yes |
| application → candidate | ✗ No | ✗ No |
| application → job | ✗ No | ✗ No |

Relationship: Whether adding or removing entries from this list triggers an update (n/a for single references that are not lists). Target Record: Whether changes to the linked record itself trigger an update.
include_deleted Optional[bool] ➖ By default, deleted entries are not returned. Use the include_deleted query param to include deleted entries too.
ignore_unsupported_filters Optional[bool] ➖ When set to true, filters targeting fields not supported by this integration will be ignored instead of filtering out all results.
ids List[str] ➖ Filter by a comma-separated list of IDs such as 222k7eCGyUdgt2JWZDNnkDs3,B5DVmypWENfU6eMe6gYDyJG3.
remote_ids List[str] ➖ Filter by a comma-separated list of remote IDs.
job_ids List[str] ➖ Filter by a comma-separated list of job IDs. We will only return interviews for applications associated with any of these jobs.
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetAtsInterviewsResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*

import_tracked_application

Import tracked application

Retroactively import existing applications into Kombo's tracking system. This is particularly useful if you have enabled the 'sync only created applications' setting and want to start tracking applications that were created before using Kombo.

To import an application, you'll need to provide specific identifiers based on the ATS. The available id_type values are defined by Kombo based on the tool's API capabilities. Please reach out to Kombo support if you require further types to be supported.

Once imported, Kombo will automatically fetch and update the application's complete data during the next sync.

Example Request Body

{
  "tracked_at": "2024-04-12T14:33:47.000Z",
  "successfactors": {
    "id_type": "application_remote_id",
    "application_remote_id": "1224042"
  }
}

Example Usage: Error Response

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.import_tracked_application(tracked_at=parse_datetime("2024-07-27T05:49:24.648Z"))

    # Handle response
    print(res)

Example Usage: Minimal Error Response

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.import_tracked_application(tracked_at=parse_datetime("2024-07-27T05:49:24.648Z"))

    # Handle response
    print(res)

Example Usage: example1

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.import_tracked_application(tracked_at=parse_datetime("2024-04-12T14:33:47Z"), successfactors={
        "id_type": "application_remote_id",
        "application_remote_id": "1224042",
    })

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
tracked_at date ✔️ YYYY-MM-DDTHH:mm:ss.sssZ
erecruiter Optional[models.PostAtsImportTrackedApplicationRequestBodyErecruiterUnion] ➖ N/A
successfactors Optional[models.PostAtsImportTrackedApplicationRequestBodySuccessfactorsUnion] ➖ N/A
recruitee Optional[models.PostAtsImportTrackedApplicationRequestBodyRecruiteeUnion] ➖ N/A
greenhouse Optional[models.PostAtsImportTrackedApplicationRequestBodyGreenhouseUnion] ➖ N/A
onlyfy Optional[models.PostAtsImportTrackedApplicationRequestBodyOnlyfyUnion] ➖ N/A
smartrecruiters Optional[models.PostAtsImportTrackedApplicationRequestBodySmartrecruitersUnion] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.PostAtsImportTrackedApplicationPositiveResponse

Errors

Error Type Status Code Content Type
errors.KomboAtsError default application/json
errors.SDKDefaultError 4XX, 5XX */*