Connect your custom ATS

This guide is for two sorts of reader: a customer whose ATS was built in house, along with the engineers who will do the work, and an ATS provider integrating their own product with First. First cannot connect to an ATS until it exposes API endpoints for us to call. This guide specifies the endpoints you need to build.

The whole loop, in order:

1. You expose GET /jobs. We poll it every 15 minutes and mirror your open jobs as roles in First.
2. A candidate applies to one of those roles and answers the role's questions.
3. When they submit, we POST the application to the matching job in your ATS, with their CV, their answers and a link back to First.
4. First screens them against the role's criteria. Those results reach your ATS through part two.

That is two endpoints, JSON over HTTPS, and one credential. There are no webhooks or callbacks, nothing to install and nothing to run on a schedule: First makes all the calls and you are the server. If you already have a REST API, most of the work is mapping your field names onto ours.

Transport

• HTTPS only, TLS 1.2 or better, with a certificate from a public CA. We cannot integrate with an API on a private network unless you can expose a public endpoint. An allowlist of our egress IPs is fine, just ask us for them.
• JSON request and response bodies. Multipart is acceptable for file upload only.
• A single stable base URL per environment, e.g. https://ats.example.com/api/v1. If it varies per customer (https://{tenant}.example.com/api/v1), tell us the template. We already support per-tenant subdomains.
• Version your API in the path. We pin to a version, and you can then evolve underneath it.

Authentication

In order of preference:

1. Bearer token: Authorization: Bearer <token>. Long-lived, revocable, scoped to an account rather than a person. This is what most of our integrations use and it is the least work for both sides.
2. API key header: X-API-Key: <key>. Fine.
3. Basic auth. Fine.

We store all credentials encrypted at rest and never log them.

Identifiers, timestamps and text

• Every job and candidate needs a stable, immutable, unique identifier. We persist it as the link between a First role or application and your record; if it changes, the link breaks.
• Strings preferred. Integers are fine, but be consistent. Do not send "id": 42 from one endpoint and "id": "42" from another.
• ISO 8601 with a timezone offset: 2026-08-04T09:30:00Z. Not epoch seconds, not local time without an offset.
• Job descriptions may be HTML or Markdown. Say which. We convert HTML to Markdown on import, so semantic HTML is fine and <div> soup is not.
• UTF-8 throughout. Candidate names contain accents and non-Latin scripts.

Pagination and filtering

Any list endpoint must paginate. Either style works:

// Cursor / next-link style (preferred)
{
  "jobs": [ /* … */ ],
  "paging": { "next": "https://ats.example.com/api/v1/jobs?cursor=eyJ" }
}

// Page-number style
{
  "jobs": [ /* … */ ],
  "paging": { "page": 1, "per_page": 50, "total_pages": 7, "total": 312 }
}

Omit paging.next (or return an empty page) when there are no more results. Do not loop back to page one. Keep ordering stable across pages. A default page size of 50 to 100 is ideal.

One filter does most of the work and saves both of us a great deal of traffic: updated_after on jobs, ISO 8601. Without it we must pull your entire job list every 15 minutes and diff it ourselves. That works, but it is wasteful.

Errors

Use real HTTP status codes, and keep them consistent:

The 404 / 422 distinction matters more than it looks. 422 is how we tell a business-rule refusal apart from a transient failure. If you return 500 for business-rule refusals, we will retry forever and generate noise for both of us.

Include a machine-readable body:

{
  "error": "candidate_already_exists",
  "message": "A candidate with that email already exists on job 9f3a."
}

Rate limits

Tell us the limits and return them in headers. We already honour Retry-After and a reset-timestamp header, and back off exponentially otherwise. We cap our own volume too. Job creation per sync run and candidate writes per batch are both bounded, so a first sync against a large ATS spreads over several runs rather than arriving as a spike.

The paths and field names below are a reference shape, not a mandate. If your API already exists and looks different, that is usually fine. We write a per-provider adapter anyway and can map field names, wrapper objects and ID types. What we cannot map around is missing capability: an endpoint that does not exist, an ID that is not stable, a list that cannot be filtered or paged.

If you are designing from scratch and have no opinion, copying this shape verbatim is the cheapest and fastest option for both sides.

{
  "jobs": [],
  "paging": { "next": "https://ats.example.com/api/v1/jobs?cursor=eyJ" }
}

{
    "jobs": [
      {
        "id": "job_9f3a",
        "title": "Senior Backend Engineer",
        "internal_title": "Senior Backend Engineer, Platform (London)",
        "status": "open",
        "visibility": "public",
        "url": "https://careers.example.com/jobs/senior-backend-engineer",
        "description_html": "<h2>About the role</h2><p>You will…</p>",
        "description_md": "## About the role\n\nYou will…",
        "categories": ["Technology", "Engineering", "Platform"],
        "locations": [
          {
            "title": "London office",
            "address": {
              "line_one": "1 Example Street",
              "line_two": "Floor 3",
              "city": "London",
              "region": "England",
              "postcode": "EC1A 1AA",
              "country": "GB"
            },
            "coordinates": { "latitude": 51.5072, "longitude": -0.1276 }
          },
          { "title": "Remote, United Kingdom" }
        ],
        "workplace_type": "hybrid",
        "employment_type": "full_time",
        "compensation": {
          "salary": {
            "type": "salary-range",
            "currency": "GBP",
            "min_value": 75000,
            "max_value": 95000,
            "frequency": "yearly"
          },
          "incentive_compensation": "10% annual bonus and share options",
          "estimate_only": false,
          "display_to_applicants": true
        },
        "team": [
          { "full_name": "Alex Doe", "email": "alex@example.com", "role": "admin", "is_hiring_manager": true },
          { "full_name": "Sam Ray", "email": "sam@example.com", "role": "member" }
        ],
        "created_at": "2026-07-02T11:04:00Z",
        "updated_at": "2026-08-04T08:41:00Z"
      }
    ],
    "paging": { "next": "https://ats.example.com/api/v1/jobs?cursor=eyJ" }
  }

// A single figure. Any frequency, so this one is a contractor day rate
{
  "salary": {
    "type": "salary",
    "currency": "GBP",
    "value": 450,
    "frequency": "daily"
  }
}

// A range, with the optional extras
{
  "salary": {
    "type": "salary-range",
    "currency": "GBP",
    "min_value": 75000,
    "max_value": 95000,
    "frequency": "yearly"
  },
  "incentive_compensation": "10% annual bonus and share options",
  "estimate_only": false,
  "display_to_applicants": true
}

{ "application": {} }

{
  "application": {
    "id": "app_88",
    "url": "https://admin.example.com/share-application/org_1/app_88",
    "submitted_at": "2026-08-04T09:31:22Z",
    "email": "jo.bloggs@example.com",
    "full_name": "Jo Bloggs",
    "preferred_name": "Jo",
    "phone": "+44 7700 900000",
    "linkedin_url": "https://www.linkedin.com/in/jobloggs",
    "location": {
      "city": "London",
      "country": "GB",
      "latitude": 51.5072,
      "longitude": -0.1276
    },
    "cv": {
      "url": "https://files.first.example/…?signature=…",
      "filename": "Jo_Bloggs_CV.pdf"
    },
    "answers": [
      { "question": "Do you have the right to work in the UK?", "answer": "Yes" },
      { "question": "Notice period", "answer": "1 month" }
    ],
    "source": { "type": "direct", "method": "applied", "name": "First" }
  }
}

{
  "application": {
    "id": "your_ref_8871",
    "job_id": "job_9f3a",
    "email": "jo.bloggs@example.com",
    "created_at": "2026-08-04T09:31:22Z"
  }
}

Send us this and we can scope the build accurately.

• API reference for every endpoint you are providing, with request and response schemas
• A real captured JSON response for each one, rather than a hand-written example. We validate against your responses, and prose always misses a null or an ID that is sometimes numeric
• Your complete enum values: job statuses, visibility, employment and workplace types, and team roles
• Pagination style and page size limits
• Auth method and token lifetime
• Somewhere to build against: a sandbox with credentials, seeded with jobs that have descriptions, or a test role in your live environment
• Production base URL, how you issue credentials, and a named technical contact