API reference

A REST API over your jobs, candidates, applications and interviews. JSON in, JSON out, one header for authentication — 40 endpoints, each with the exact request and response below.

Before you start

Create a key in the app under Settings → API & Keys and send it as X-API-Key on every request. A key acts as the person who created it — the same role and job access, scoped to one business. Bodies are JSON and camelCase; lists are cursor-paginated.

Base URL

https://app.sortlistnow.com/api/v1

Jobs

Roles you are hiring for — create them, publish them, and read the AI profile that scores candidates against them.

GET/jobsList jobs

Every role in your business, newest first. Cursor-paginated, and filterable by status.

Request

curl "https://app.sortlistnow.com/api/v1/jobs?limit=20" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "records": [
    {
      "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
      "title": "Senior Backend Engineer",
      "slug": "senior-backend-engineer",
      "locationType": "onsite",
      "employmentType": "full_time",
      "status": "open"
    }
  ],
  "cursor": {
    "hasMore": true,
    "perPage": 20,
    "totalRecords": 137,
    "nextCursor": "eyJpZCI6IjlmOGMxYjJlIn0"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.

POST/jobsCreate a job

Creates a role in draft. Publishing is a separate call, so you can build it up first.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/jobs" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Senior Backend Engineer",
  "profileType": "software_engineering",
  "description": "We're hiring a backend engineer to own our ingestion pipeline.",
  "department": "Engineering",
  "location": "Remote — India",
  "locationType": "onsite",
  "employmentType": "full_time",
  "requirements": "5+ years with Python and Postgres at scale.",
  "preferredQualifications": "Experience with event-driven ingestion.",
  "matchingCriteria": "Weight backend depth over breadth.",
  "compensationMin": 1800000,
  "compensationMax": 2600000
}'

Body

{
  "title": "Senior Backend Engineer",
  "profileType": "software_engineering",
  "description": "We're hiring a backend engineer to own our ingestion pipeline.",
  "department": "Engineering",
  "location": "Remote — India",
  "locationType": "onsite",
  "employmentType": "full_time",
  "requirements": "5+ years with Python and Postgres at scale.",
  "preferredQualifications": "Experience with event-driven ingestion.",
  "matchingCriteria": "Weight backend depth over breadth.",
  "compensationMin": 1800000,
  "compensationMax": 2600000
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "title": "Senior Backend Engineer",
    "slug": "senior-backend-engineer",
    "locationType": "onsite",
    "employmentType": "full_time",
    "description": "We're hiring a backend engineer to own our ingestion pipeline.",
    "compensationCurrency": "INR",
    "status": "open",
    "visibility": "internal"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

GET/jobs/{job_id}Get a job

The full role, including compensation, requirements and its current status.

Request

curl "https://app.sortlistnow.com/api/v1/jobs/{jobId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "title": "Senior Backend Engineer",
    "slug": "senior-backend-engineer",
    "locationType": "onsite",
    "employmentType": "full_time",
    "description": "We're hiring a backend engineer to own our ingestion pipeline.",
    "compensationCurrency": "INR",
    "status": "open",
    "visibility": "internal"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

PUT/jobs/{job_id}Update a job

Partial update — send only the fields you are changing. Omitted fields keep their values.

Request

curl -X PUT "https://app.sortlistnow.com/api/v1/jobs/{jobId}" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Senior Backend Engineer",
  "profileType": "software_engineering",
  "department": "Engineering",
  "location": "Remote — India",
  "locationType": "onsite",
  "employmentType": "full_time",
  "description": "We're hiring a backend engineer to own our ingestion pipeline.",
  "requirements": "5+ years with Python and Postgres at scale.",
  "preferredQualifications": "Experience with event-driven ingestion.",
  "matchingCriteria": "Weight backend depth over breadth.",
  "compensationMin": 1800000,
  "compensationMax": 2600000
}'

Body

{
  "title": "Senior Backend Engineer",
  "profileType": "software_engineering",
  "department": "Engineering",
  "location": "Remote — India",
  "locationType": "onsite",
  "employmentType": "full_time",
  "description": "We're hiring a backend engineer to own our ingestion pipeline.",
  "requirements": "5+ years with Python and Postgres at scale.",
  "preferredQualifications": "Experience with event-driven ingestion.",
  "matchingCriteria": "Weight backend depth over breadth.",
  "compensationMin": 1800000,
  "compensationMax": 2600000
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "title": "Senior Backend Engineer",
    "slug": "senior-backend-engineer",
    "locationType": "onsite",
    "employmentType": "full_time",
    "description": "We're hiring a backend engineer to own our ingestion pipeline.",
    "compensationCurrency": "INR",
    "status": "open",
    "visibility": "internal"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

DELETE/jobs/{job_id}Delete a job

Removes the role and everything hanging off it: applications, offers, placements.

Request

curl -X DELETE "https://app.sortlistnow.com/api/v1/jobs/{jobId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "outcome": "advance",
  "ref": "…",
  "context": {},
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
403ACCESS_DENIEDThe key's user does not have a role that may delete.
404RESOURCE_ABSENTNo record with that id in your business.

POST/jobs/{job_id}/analyzeAnalyse a job

Queues AI analysis to build the job profile. Returns immediately — poll the status endpoint.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/jobs/{jobId}/analyze" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "outcome": "advance",
  "ref": "…",
  "context": {},
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.

POST/jobs/{job_id}/closeClose a job

Stops the role accepting applications and frees its slot against your open-role limit.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/jobs/{jobId}/close" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "title": "Senior Backend Engineer",
    "slug": "senior-backend-engineer",
    "locationType": "onsite",
    "employmentType": "full_time",
    "description": "We're hiring a backend engineer to own our ingestion pipeline.",
    "compensationCurrency": "INR",
    "status": "open",
    "visibility": "internal"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.

GET/jobs/{job_id}/profileGet the job profile

The AI-built profile: the skills, seniority and signals used to score candidates.

Request

curl "https://app.sortlistnow.com/api/v1/jobs/{jobId}/profile" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "jobId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "analysisStatus": "open",
    "analyzedAt": "2026-09-20T10:15:00Z",
    "analysisModel": "video",
    "seniorityLevel": "…",
    "minExperience": 1800000,
    "maxExperience": 2600000
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

POST/jobs/{job_id}/publishPublish a job

Moves the role to open so it accepts applications. Counts against your plan's open-role limit.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/jobs/{jobId}/publish" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "title": "Senior Backend Engineer",
    "slug": "senior-backend-engineer",
    "locationType": "onsite",
    "employmentType": "full_time",
    "description": "We're hiring a backend engineer to own our ingestion pipeline.",
    "compensationCurrency": "INR",
    "status": "open",
    "visibility": "internal"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.

GET/jobs/{job_id}/screening-questionsList screening questions

The questions applicants answer on the careers page for this role.

Request

curl "https://app.sortlistnow.com/api/v1/jobs/{jobId}/screening-questions" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "records": [
    {
      "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
      "position": 1,
      "question": "How many years have you worked with Postgres?",
      "answerType": "technical",
      "required": false,
      "maxWords": 2600000
    }
  ],
  "cursor": {
    "hasMore": true,
    "perPage": 20,
    "totalRecords": 137,
    "nextCursor": "eyJpZCI6IjlmOGMxYjJlIn0"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

PUT/jobs/{job_id}/screening-questionsReplace screening questions

Replaces the whole set in one call. Send the full list you want, in order.

Request

curl -X PUT "https://app.sortlistnow.com/api/v1/jobs/{jobId}/screening-questions" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "questions": [
    {
      "question": "How many years have you worked with Postgres?",
      "answerType": "technical",
      "required": false,
      "maxWords": 2600000
    }
  ]
}'

Body

{
  "questions": [
    {
      "question": "How many years have you worked with Postgres?",
      "answerType": "technical",
      "required": false,
      "maxWords": 2600000
    }
  ]
}

Response

{
  "records": [
    {
      "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
      "position": 1,
      "question": "How many years have you worked with Postgres?",
      "answerType": "technical",
      "required": false,
      "maxWords": 2600000
    }
  ],
  "cursor": {
    "hasMore": true,
    "perPage": 20,
    "totalRecords": 137,
    "nextCursor": "eyJpZCI6IjlmOGMxYjJlIn0"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

GET/jobs/{job_id}/profile/statusGet profile status

Whether the profile is queued, running, ready or failed. Poll this after analyse.

Request

curl "https://app.sortlistnow.com/api/v1/jobs/{jobId}/profile/status" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "jobId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "analysisStatus": "open",
    "analyzedAt": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

Candidates

People in your talent pool, their resumes, and the parsed profile behind every match score.

GET/candidatesList candidates

Everyone in your candidate pool. Cursor-paginated, with search and filter parameters.

Request

curl "https://app.sortlistnow.com/api/v1/candidates?limit=20" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "records": [
    {
      "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
      "email": "ada@example.com",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "createdAt": "2026-09-20T10:15:00Z",
      "currentCompany": "Acme Corp"
    }
  ],
  "cursor": {
    "hasMore": true,
    "perPage": 20,
    "totalRecords": 137,
    "nextCursor": "eyJpZCI6IjlmOGMxYjJlIn0"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.

POST/candidatesCreate a candidate

Adds someone to your pool. Email is unique per business, so a repeat is rejected.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/candidates" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "phone": "+91 98765 43210",
  "linkedinUrl": "https://linkedin.com/in/adalovelace",
  "location": "Remote — India",
  "currentCompany": "Acme Corp",
  "currentTitle": "Senior Backend Engineer",
  "yearsOfExperience": 6,
  "source": "linkedin",
  "sourceDetail": "linkedin"
}'

Body

{
  "email": "ada@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "phone": "+91 98765 43210",
  "linkedinUrl": "https://linkedin.com/in/adalovelace",
  "location": "Remote — India",
  "currentCompany": "Acme Corp",
  "currentTitle": "Senior Backend Engineer",
  "yearsOfExperience": 6,
  "source": "linkedin",
  "sourceDetail": "linkedin"
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "phone": "+91 98765 43210",
    "linkedinUrl": "https://linkedin.com/in/adalovelace",
    "location": "Remote — India"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
409DUPLICATE_RESOURCEA candidate with that email already exists in your business.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

GET/candidates/{candidate_id}Get a candidate

The full record: contact details, experience, documents and profile.

Request

curl "https://app.sortlistnow.com/api/v1/candidates/{candidateId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "phone": "+91 98765 43210",
    "linkedinUrl": "https://linkedin.com/in/adalovelace",
    "location": "Remote — India"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

PUT/candidates/{candidate_id}Update a candidate

Partial update — send only the fields you are changing.

Request

curl -X PUT "https://app.sortlistnow.com/api/v1/candidates/{candidateId}" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "phone": "+91 98765 43210",
  "linkedinUrl": "https://linkedin.com/in/adalovelace",
  "location": "Remote — India",
  "currentCompany": "Acme Corp",
  "currentTitle": "Senior Backend Engineer",
  "yearsOfExperience": 6,
  "source": "linkedin",
  "sourceDetail": "linkedin",
  "profileSummary": "Eight years in backend engineering, strong Python and Postgres."
}'

Body

{
  "email": "ada@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "phone": "+91 98765 43210",
  "linkedinUrl": "https://linkedin.com/in/adalovelace",
  "location": "Remote — India",
  "currentCompany": "Acme Corp",
  "currentTitle": "Senior Backend Engineer",
  "yearsOfExperience": 6,
  "source": "linkedin",
  "sourceDetail": "linkedin",
  "profileSummary": "Eight years in backend engineering, strong Python and Postgres."
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "email": "ada@example.com",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "phone": "+91 98765 43210",
    "linkedinUrl": "https://linkedin.com/in/adalovelace",
    "location": "Remote — India"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

DELETE/candidates/{candidate_id}Delete a candidate

Removes the candidate and their applications. Resume files in storage are kept.

Request

curl -X DELETE "https://app.sortlistnow.com/api/v1/candidates/{candidateId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "outcome": "advance",
  "ref": "…",
  "context": {},
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
403ACCESS_DENIEDThe key's user does not have a role that may delete.
404RESOURCE_ABSENTNo record with that id in your business.

GET/candidates/for-job/{job_id}List candidates for a job

Candidates matched to a role, with their match score against its profile.

Request

curl "https://app.sortlistnow.com/api/v1/candidates/for-job/{jobId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

POST/candidates/{candidate_id}/analyzeAnalyse a candidate

Queues resume parsing and profile building. Returns immediately — poll the status endpoint.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/candidates/{candidateId}/analyze" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "outcome": "advance",
  "ref": "…",
  "context": {},
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.

GET/candidates/{candidate_id}/profileGet the candidate profile

The AI-built profile: skills, seniority and experience parsed from their resume.

Request

curl "https://app.sortlistnow.com/api/v1/candidates/{candidateId}/profile" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "candidateId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "analysisStatus": "open",
    "analyzedAt": "2026-09-20T10:15:00Z",
    "analysisModel": "video",
    "profileType": "technical",
    "yearsOfExperience": 6,
    "seniorityLevel": "…"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

POST/candidates/{candidate_id}/resumeUpload a resume

Multipart upload of a PDF, DOC, DOCX or TXT. Stored against the candidate.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/candidates/{candidateId}/resume" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -F "file=@resume.pdf"

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "candidateId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "documentType": "technical",
    "fileName": "ada-lovelace-resume.pdf",
    "filePath": "ada-lovelace-resume.pdf",
    "fileType": "technical",
    "fileSizeBytes": 1,
    "uploadedAt": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.

GET/candidates/{candidate_id}/profile/statusGet profile status

Whether the profile is queued, running, ready or failed. Poll this after analyse.

Request

curl "https://app.sortlistnow.com/api/v1/candidates/{candidateId}/profile/status" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "candidateId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "analysisStatus": "open",
    "analyzedAt": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

GET/candidates/{candidate_id}/documents/{document_id}/downloadDownload a document

Returns the stored file itself — a resume or attachment — not JSON.

Request

curl "https://app.sortlistnow.com/api/v1/candidates/{candidateId}/documents/{documentId}/download" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

The file itself, with its original content type.

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

Applications

The link between a candidate and a role, and the pipeline stage it currently sits in.

GET/applicationsList applications

Applications across your roles, filterable by job and stage.

Request

curl "https://app.sortlistnow.com/api/v1/applications?limit=20" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.

POST/applicationsCreate an application

Puts an existing candidate onto a role's pipeline at its first stage.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/applications" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jobId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
  "candidateId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
  "currentStage": "screening",
  "internalNotes": "Strong systems thinking; follow up on scaling experience."
}'

Body

{
  "jobId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
  "candidateId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
  "currentStage": "screening",
  "internalNotes": "Strong systems thinking; follow up on scaling experience."
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "jobId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "candidateId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "currentStage": "screening",
    "status": "open",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "overallScore": 82,
    "screeningScore": 82
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
409DUPLICATE_RESOURCEThat candidate has already applied to this role.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

GET/applications/{app_id}Get an application

One application with its stage, match score and linked candidate and job.

Request

curl "https://app.sortlistnow.com/api/v1/applications/{applicationId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "businessId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "jobId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "candidateId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "currentStage": "screening",
    "status": "open",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "overallScore": 82,
    "screeningScore": 82
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

GET/applications/pipeline/{job_id}Get a job's pipeline

Every stage for a role with the applications in each — the kanban board as data.

Request

curl "https://app.sortlistnow.com/api/v1/applications/pipeline/{jobId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": [
    {
      "stage": "screening",
      "applications": [],
      "count": 137,
      "hasMore": true
    }
  ],
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

GET/applications/{app_id}/screening-answersGet screening answers

What this applicant answered to the role's screening questions.

Request

curl "https://app.sortlistnow.com/api/v1/applications/{applicationId}/screening-answers" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "records": [
    {
      "questionId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
      "questionText": "How many years have you worked with Postgres?",
      "answerType": "technical",
      "answerRating": 1,
      "answerBoolean": false,
      "answerText": "Six years, mostly on high-write OLTP systems."
    }
  ],
  "cursor": {
    "hasMore": true,
    "perPage": 20,
    "totalRecords": 137,
    "nextCursor": "eyJpZCI6IjlmOGMxYjJlIn0"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

Interviews

Scheduling, outcomes and interviewer feedback for everything booked against an application.

GET/interviewsList interviews

Scheduled interviews with their job and candidate context.

Request

curl "https://app.sortlistnow.com/api/v1/interviews?limit=20" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": [
    {
      "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
      "applicationId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
      "roundNumber": 1,
      "interviewType": "technical",
      "status": "open",
      "locationType": "Remote — India"
    }
  ],
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.

POST/interviewsSchedule an interview

Books an interview against an application, with a time, type and round.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/interviews" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "applicationId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
  "roundNumber": 1,
  "interviewType": "technical",
  "scheduledStart": "2026-09-20T10:15:00Z",
  "scheduledEnd": "2026-09-20T10:15:00Z",
  "timezone": "…",
  "location": "Remote — India",
  "locationType": "Remote — India",
  "videoLink": "https://meet.google.com/abc-defg-hij",
  "interviewers": [],
  "feedbackDeadline": "2026-09-20T10:15:00Z",
  "focusNotes": "Strong systems thinking; follow up on scaling experience."
}'

Body

{
  "applicationId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
  "roundNumber": 1,
  "interviewType": "technical",
  "scheduledStart": "2026-09-20T10:15:00Z",
  "scheduledEnd": "2026-09-20T10:15:00Z",
  "timezone": "…",
  "location": "Remote — India",
  "locationType": "Remote — India",
  "videoLink": "https://meet.google.com/abc-defg-hij",
  "interviewers": [],
  "feedbackDeadline": "2026-09-20T10:15:00Z",
  "focusNotes": "Strong systems thinking; follow up on scaling experience."
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "applicationId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "roundNumber": 1,
    "interviewType": "technical",
    "locationType": "Remote — India",
    "status": "open",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "scheduledStart": "2026-09-20T10:15:00Z",
    "scheduledEnd": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

GET/interviews/{interview_id}Get an interview

One interview with its schedule, interviewers and meeting link.

Request

curl "https://app.sortlistnow.com/api/v1/interviews/{interviewId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "applicationId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "roundNumber": 1,
    "interviewType": "technical",
    "locationType": "Remote — India",
    "status": "open",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "scheduledStart": "2026-09-20T10:15:00Z",
    "scheduledEnd": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

PUT/interviews/{interview_id}Update an interview

Partial update — reschedule, change the round, or swap the meeting link.

Request

curl -X PUT "https://app.sortlistnow.com/api/v1/interviews/{interviewId}" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "interviewType": "technical",
  "scheduledStart": "2026-09-20T10:15:00Z",
  "scheduledEnd": "2026-09-20T10:15:00Z",
  "timezone": "…",
  "location": "Remote — India",
  "locationType": "Remote — India",
  "videoLink": "https://meet.google.com/abc-defg-hij",
  "interviewers": [],
  "feedbackDeadline": "2026-09-20T10:15:00Z",
  "focusNotes": "Strong systems thinking; follow up on scaling experience."
}'

Body

{
  "interviewType": "technical",
  "scheduledStart": "2026-09-20T10:15:00Z",
  "scheduledEnd": "2026-09-20T10:15:00Z",
  "timezone": "…",
  "location": "Remote — India",
  "locationType": "Remote — India",
  "videoLink": "https://meet.google.com/abc-defg-hij",
  "interviewers": [],
  "feedbackDeadline": "2026-09-20T10:15:00Z",
  "focusNotes": "Strong systems thinking; follow up on scaling experience."
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "applicationId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "roundNumber": 1,
    "interviewType": "technical",
    "locationType": "Remote — India",
    "status": "open",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "scheduledStart": "2026-09-20T10:15:00Z",
    "scheduledEnd": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

DELETE/interviews/{interview_id}Delete an interview

Removes the interview and its feedback. Cancelling is usually what you want instead.

Request

curl -X DELETE "https://app.sortlistnow.com/api/v1/interviews/{interviewId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "outcome": "advance",
  "ref": "…",
  "context": {},
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
403ACCESS_DENIEDThe key's user does not have a role that may delete.
404RESOURCE_ABSENTNo record with that id in your business.

GET/interviews/by-application/{application_id}List interviews for an application

Every interview booked against one application, oldest first.

Request

curl "https://app.sortlistnow.com/api/v1/interviews/by-application/{applicationId}" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": [
    {
      "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
      "applicationId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
      "roundNumber": 1,
      "interviewType": "technical",
      "status": "open",
      "locationType": "Remote — India"
    }
  ],
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

PUT/interviews/feedback/{feedback_id}Update feedback

Edits feedback already submitted — corrections and afterthoughts.

Request

curl -X PUT "https://app.sortlistnow.com/api/v1/interviews/feedback/{feedbackId}" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "overallRating": 1,
  "recommendation": "hire",
  "criteriaScores": {},
  "strengths": "…",
  "concerns": "…",
  "detailedNotes": "Strong systems thinking; follow up on scaling experience."
}'

Body

{
  "overallRating": 1,
  "recommendation": "hire",
  "criteriaScores": {},
  "strengths": "…",
  "concerns": "…",
  "detailedNotes": "Strong systems thinking; follow up on scaling experience."
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "interviewId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "interviewerUserId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "overallRating": 1,
    "recommendation": "hire",
    "criteriaScores": {},
    "strengths": "…",
    "concerns": "…",
    "detailedNotes": "Strong systems thinking; follow up on scaling experience.",
    "submittedAt": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

POST/interviews/{interview_id}/cancelCancel an interview

Marks it cancelled with a reason, keeping the record and its history.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/interviews/{interviewId}/cancel" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cancellationReason": "Candidate withdrew"
}'

Body

{
  "cancellationReason": "Candidate withdrew"
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "applicationId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "roundNumber": 1,
    "interviewType": "technical",
    "locationType": "Remote — India",
    "status": "open",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "scheduledStart": "2026-09-20T10:15:00Z",
    "scheduledEnd": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

POST/interviews/{interview_id}/completeComplete an interview

Marks it done, which is what unlocks feedback and moves the pipeline on.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/interviews/{interviewId}/complete" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "overallRecommendation": "hire"
}'

Body

{
  "overallRecommendation": "hire"
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "applicationId": "3b17d0aa-8c24-4f6b-b1e2-77a9c4de5f08",
    "roundNumber": 1,
    "interviewType": "technical",
    "locationType": "Remote — India",
    "status": "open",
    "createdAt": "2026-09-20T10:15:00Z",
    "updatedAt": "2026-09-20T10:15:00Z",
    "scheduledStart": "2026-09-20T10:15:00Z",
    "scheduledEnd": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

GET/interviews/{interview_id}/feedbackList feedback

Every interviewer's feedback for this interview, with scores and notes.

Request

curl "https://app.sortlistnow.com/api/v1/interviews/{interviewId}/feedback" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": [
    {
      "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
      "interviewId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
      "interviewerUserId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
      "overallRating": 1,
      "recommendation": "hire",
      "criteriaScores": {}
    }
  ],
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
404RESOURCE_ABSENTNo record with that id in your business.

POST/interviews/{interview_id}/feedbackSubmit feedback

Adds one interviewer's verdict, rating and notes to a completed interview.

Request

curl -X POST "https://app.sortlistnow.com/api/v1/interviews/{interviewId}/feedback" \
  -H "X-API-Key: $SORTLIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "interviewerUserId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
  "overallRating": 1,
  "recommendation": "hire",
  "criteriaScores": {},
  "strengths": "…",
  "concerns": "…",
  "detailedNotes": "Strong systems thinking; follow up on scaling experience."
}'

Body

{
  "interviewerUserId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
  "overallRating": 1,
  "recommendation": "hire",
  "criteriaScores": {},
  "strengths": "…",
  "concerns": "…",
  "detailedNotes": "Strong systems thinking; follow up on scaling experience."
}

Response

{
  "payload": {
    "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "interviewId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
    "interviewerUserId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "overallRating": 1,
    "recommendation": "hire",
    "criteriaScores": {},
    "strengths": "…",
    "concerns": "…",
    "detailedNotes": "Strong systems thinking; follow up on scaling experience.",
    "submittedAt": "2026-09-20T10:15:00Z"
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.
402SUBSCRIPTION_EXPIREDSubscription lapsed. Reads keep working; writes are refused until it is renewed.
404RESOURCE_ABSENTNo record with that id in your business.
422INPUT_REJECTEDA field is missing or invalid — the body names which.

AI jobs

Background AI work queued for your business, so you can poll what is still running.

GET/ai-jobsList AI jobs

Background AI work queued for your business, with status and progress.

Request

curl "https://app.sortlistnow.com/api/v1/ai-jobs?limit=20" \
  -H "X-API-Key: $SORTLIST_API_KEY"

Response

{
  "payload": {
    "jobs": [
      {
        "id": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31",
        "taskType": "technical",
        "status": "open",
        "createdAt": "2026-09-20T10:15:00Z",
        "refType": "technical",
        "refId": "9f8c1b2e-4a77-4c21-9f1d-2b6e5a0c7d31"
      }
    ],
    "summary": {
      "total": 137,
      "pending": 1,
      "processing": 1,
      "completed": 1,
      "failed": 1,
      "paused": 1
    },
    "pausedByType": [
      {
        "taskType": "technical",
        "count": 137
      }
    ]
  },
  "_meta": {
    "requestId": "c2a5e918-15d7-4a3e-9bb0-6d41f2c8e7aa",
    "ts": "2026-09-20T10:15:00Z"
  }
}

Errors

401AUTHENTICATION_REQUIREDKey missing, unknown, expired or revoked.