GET/candidates

Search Candidates

Search across all resumes with their application history and AI scores. Useful for building custom dashboards or syncing with your HRIS.

🔒 Scope required: read or candidate:read

Query Parameters

Parameter	Type	Default	Description
`page`	string	`"1"`	Page number
`limit`	string	`"20"`	Results per page (max 100)
`search`	string	—	Search by file name

Example

curl "https://api.scootsign.com/api/v1/candidates?search=john&limit=10" \
  -H "X-API-Key: aram_ent_a1b2c3d4e5f6..."

Response

{
  "success": true,
  "data": [
    {
      "id": "res_abc123",
      "fileName": "john_doe_resume.pdf",
      "parseStatus": "COMPLETED",
      "metadata": {
        "skills": ["Node.js", "React", "PostgreSQL"],
        "experience": "6 years"
      },
      "applications": [
        {
          "id": "app_1",
          "status": "SHORTLISTED",
          "aiScores": [{ "overallScore": 92.5 }],
          "jobDescription": {
            "id": "jd_abc123",
            "title": "Senior Backend Engineer"
          }
        }
      ],
      "createdAt": "2026-03-01T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 3,
    "pages": 1
  }
}

Response Fields

Each candidate includes their resume data plus nested applications:

Field	Type	Description
`id`	string	Resume ID
`fileName`	string	Original file name
`parseStatus`	string	`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`
`metadata`	object	Parsed resume data (skills, experience, etc.)
`applications`	array	All applications with AI scores and JD info
`applications[].aiScores`	array	AI match scores (highest first)
`applications[].jobDescription`	object	The JD this application is for

Use Cases

HRIS sync: Pull all candidates and their scores into your HR system
Custom dashboards: Build hiring analytics on top of Aram’s AI scoring
Pipeline tracking: Monitor candidate progress across multiple JDs