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 a candidate and post a comment 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).

Example: Create an application with a new candidate

{
  "model": {
    "candidate": {
      "last_name": "LastName",
      "first_name": "FirstName",
      "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

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

POST application existing candidate with attachment

• Required fields: file_name, content_base64

• Optional fields: raw_text

• What is content_base64?

  • It's the file's raw bytes encoded as a Base64 string, since JSON can't carry binary data directly. Supply only the raw Base64 text — do not include a data-URI prefix like data:application/pdf;base64,. Pair it with file_name (including the extension) so the file is stored with the correct name and type. To generate it, Base64-encode the file with any standard tool — for example base64 -i resume.pdf on macOS, or base64.b64encode(open("resume.pdf", "rb").read()) in Python.

{
  "model": {
    "candidate": "{candidate_uuid}",
    "source": "Merge",
    "job": "{job_uuid}",
    "integration_params": {
      "attachments": [
        {
          "file_name": "Candidate Resume.pdf",
          "integration_params": {
            "content_base64": "JVBERi0x...",
            "raw_text": "optional parsed text"
          }
        }
      ]
    }
  }
}

POST application existing candidate with a comment

• Required fields: candidate, job, body

• Optional fields: activity_type_native (defaults to NOTE), pinned, timestamp, created_at

{
  "model": {
    "candidate": "{candidate_uuid}",
    "source": "Merge",
    "job": "{job_uuid}",
    "integration_params": {
      "activities": [
        {
          "body": "Please email this candidate about next steps",
          "activity_type_native": "EMAIL",
          "pinned": true,
          "timestamp": "2026-10-01T15:17:00Z"
        }
      ]
    }
  }
}

Troubleshooting common issues

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.