Candidates

Read and edit candidate profiles. Only candidates with at least one application at the tenant are accessible via the API.

Privacy — Access Restriction

The candidates API only returns candidates who have applied for at least one job at your tenant. Cross-tenant data access is not possible.

Candidate Object

FeldTypPflichtBeschreibung
idintegerOptionalUnique candidate ID
first_namestringOptionalFirst name
last_namestringOptionalLast name
emailstringOptionalEmail address
phonestring|nullOptionalPhone number
current_job_titlestring|nullOptionalCurrent job titlez.B. First Officer
nationalitystring|nullOptionalNationality (ISO 3166-1 alpha-2)z.B. DE
locationstring|nullOptionalCurrent location
linkedin_urlstring|nullOptionalLinkedIn profile URL
applications_countintegerOptionalNumber of applications at the tenant
created_atdatetimeOptionalRegistration timestamp

GET /candidates — List Candidates

GEThttps://api.aeroselect.io/api/v2/external/candidates
cURLBash
curl "https://api.aeroselect.io/api/v2/external/candidates?page=1" \
  -H "X-API-Key: ak_live_YOUR_KEY"
Response 200JSON
{
  "data": [
    {
      "id": 55,
      "first_name": "Max",
      "last_name": "Müller",
      "email": "[email protected]",
      "phone": "+49 170 123 4567",
      "current_job_title": "First Officer A320",
      "nationality": "DE",
      "location": "Frankfurt am Main",
      "applications_count": 2,
      "created_at": "2026-03-15T09:00:00Z"
    }
  ],
  "meta": { "total": 312, "page": 1, "per_page": 25 }
}

GET /candidates/{id} — Get Single Candidate

GEThttps://api.aeroselect.io/api/v2/external/candidates/{id}
Bash
curl "https://api.aeroselect.io/api/v2/external/candidates/55" \
  -H "X-API-Key: ak_live_YOUR_KEY"

PATCH /candidates/{id} — Edit Candidate

Edits selected fields of a candidate profile. Requires scope candidates:write. Only explicitly permitted fields can be edited — sensitive fields like email are write-protected.

PATCHhttps://api.aeroselect.io/api/v2/external/candidates/{id}

Editable Fields

FeldTypPflichtBeschreibung
phonestringOptionalPhone number
current_job_titlestringOptionalCurrent job title
nationalitystringOptionalNationality (ISO 3166-1 alpha-2)
locationstringOptionalCurrent location
linkedin_urlstringOptionalLinkedIn profile URL

Read-only Fields (not editable via API)

FeldTypPflichtBeschreibung
emailstringOptionalEmail address — only changeable by the candidate themselves
first_namestringOptionalFirst name — only changeable by the candidate themselves
last_namestringOptionalLast name — only changeable by the candidate themselves
cURLBash
curl -X PATCH "https://api.aeroselect.io/api/v2/external/candidates/55" \
  -H "X-API-Key: ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+49 170 987 6543",
    "current_job_title": "Captain A320",
    "location": "München"
  }'
Node.jsJavaScript
const response = await fetch(
  `https://api.aeroselect.io/api/v2/external/candidates/55`,
  {
    method: "PATCH",
    headers: {
      "X-API-Key": process.env.AEROSELECT_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone: "+49 170 987 6543",
      current_job_title: "Captain A320",
    }),
  }
);
const { data: candidate } = await response.json();