ATS Integration API

Connect your Applicant Tracking System to Maatrics: add candidates, receive results, and pull reports over a simple REST API.

External recruiting systems use this API to push candidates into Maatrics assessments, then track and retrieve their results. Candidates are matched across systems by remote_id — the unique id your ATS assigns. You choose it when adding applicants; Maatrics echoes it back in every response and webhook.

1.  ATS       ──GET   /assessments                ──▶  discover assessments
2.  ATS       ──POST  /assessments/:id/applicants ──▶  add candidates → invite_url
3.  Candidate ── completes the assessment in Maatrics
4.  Maatrics  ──POST  webhook_url                 ──▶  result (applicant.analyzed)
5.  ATS       ──GET   /applicants/:remote_id      ──▶  poll status / results
6.  ATS       ──GET   /api/ats/file/:remote_id    ──▶  download PDF report

Authentication

Every /api/v1/ats/* request must include a Bearer token. Tokens are issued per integration and begin with the prefix ats_ followed by 48 characters. A token is valid only while its integration is active.

Authorization: Bearer ats_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Get or rotate your token from the Maatrics panel (ATS Integrations). The file endpoint /api/ats/file/:remoteId is the only public endpoint — the remote_id UUID itself acts as the access key, so treat report URLs as secrets.

Endpoints

curl -X GET "https://api.maatrics.com/api/v1/ats/assessments" \
  -H "Authorization: Bearer ats_xxx"

curl -X GET "https://api.maatrics.com/api/v1/ats/assessments/9bk2f1a7c3" \
  -H "Authorization: Bearer ats_xxx"

curl -X GET "https://api.maatrics.com/api/v1/ats/assessments/9bk2f1a7c3/applicants" \
  -H "Authorization: Bearer ats_xxx"

curl -X POST "https://api.maatrics.com/api/v1/ats/assessments/9bk2f1a7c3/applicants" \
  -H "Authorization: Bearer ats_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "applicants": [
      {
        "remote_id": "cand-3f2a9b7c",
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]"
      }
    ]
  }'

curl -X GET "https://api.maatrics.com/api/v1/ats/applicants/cand-3f2a9b7c" \
  -H "Authorization: Bearer ats_xxx"

curl -X GET "https://api.maatrics.com/api/ats/file/cand-3f2a9b7c" -o report.pdf

Result Webhook

When a candidate's analysis is published, Maatrics POSTs the payload below to your integration's webhook_url. Respond 2xx quickly, dedupe by remote_id, then fetch the PDF from report_url and/or call the candidate status endpoint for the structured results. The payload carries a report_data that varies by assessment type; an example payload for each of the three types is shown below.

The result shape depends on the assessment type. Before processing a result, switch on type and parse report_data accordingly — the Usage tab below shows exactly that.

// On a result webhook — or the candidate status response —
// branch on `type` to parse report_data / results correctly:
function handleResult(payload) {
  switch (payload.type) {
    case "language":
      // word_accuracy, speaking_fluency, vocabulary, grammar, general_level
      return renderLanguageReport(payload.report_data);

    case "proficiency":
      // proficiencies[] — each with nested actions[]
      return renderProficiencyReport(payload.report_data);

    case "technical":
    case "technical_code":
      // proficiencies[] + skills[]
      return renderTechnicalReport(payload.report_data);

    default:
      return; // unknown type — ignore
  }
}

Errors

Standard HTTP status codes are used. Validation failures return 422 with a field-keyed errors object. Every request is logged server-side for audit and debugging.