Overview

This guide provides best practices, key considerations, and sample request bodies to help you successfully POST to AgileATS.

POST application

Our POST application functionality lets you optionally create the candidate in the same request.

POST application with new candidate

A new candidate requires first_name, last_name, a PERSONAL email address, and integration_params.recruitable (true or false). For phone numbers, you can set the type to WORK and/or MOBILE (one of each).

Disclaimer: Only the first city in the locations array is written to the candidate's record in AgileATS, and city names must be valid.

Example: Create an application with a new candidate

{
  "model": {
    "candidate": {
      "last_name": "LastName",
      "first_name": "FirstName",
      "title": "Software Engineer",
      "locations": ["San Francisco"],
      "phone_numbers": [
        {
          "value": "+1234567890",
          "phone_number_type": "WORK"
        },
        {  
          "value": "+1234567890",
          "phone_number_type": "MOBILE"
        }
      ],
      "email_addresses": [
        {
          "value": "[email protected]",
          "email_address_type": "PERSONAL"
        }
      ],
      "integration_params": {
        "recruitable": true
      }
    },
    "source": "Merge",
    "job": "{job_uuid}"
  }
}

POST application with existing candidate

Example: Create an application with an existing candidate

{
  "model": {
    "source": "Merge",
    "candidate": "{candidate_uuid}",
    "job": "{job_uuid}"
  }
}

Troubleshooting

Errors and how to fix them:

Duplicate candidate email — creating a new candidate with an email already in AgileATS fails. Reference the existing candidate by UUID instead of creating a new one.

Duplicate application — a candidate can only have one application per job. Re-POSTing the same candidate and job fails, so don't re-submit; the application already exists.