Kandidaten ophalen

Haal een gepagineerde lijst op van kandidaten die gekoppeld zijn aan een specifieke gebruiker. Kandidaten zijn beperkt tot de repository van de gebruiker: alleen kandidaten die aan de opgegeven gebruiker zijn gekoppeld, worden geretourneerd.

Authenticatie

Vereist een API sleutel met de candidates:read scope (inbegrepen in de Chrome Plugin preset). Aanroepen met een sleutel zonder deze scope retourneren een 403 met foutcode INSUFFICIENT_SCOPE.

Endpoint

Code

GET /api/v1/candidates

Queryparameters

Parameter	Type	Standaard	Beschrijving
`user_id`	integer	-	Verplicht. Het gebruikers-ID van de tenant wiens kandidatenrepository bevraagd moet worden
`email`	string	-	Filter op exact overeenkomend e-mailadres
`search`	string	-	Zoek in voornaam, achternaam en e-mailadres (gedeeltelijke overeenkomst)
`status`	string	-	Filter op kandidaatstatus (zie Statuswaarden hieronder)
`sort`	string	created_at	Sorteerveld: `created_at`, `first_name`, `last_name`, `email`
`sort_direction`	string	desc	Sorteerrichting: `asc` of `desc`
`page`	integer	1	Paginanummer voor paginering
`per_page`	integer	20	Items per pagina (max: 100)

Statuswaarden

Waarde	Beschrijving
`potential`	Nieuwe kandidaat, nog niet benaderd
`waiting_for_intake`	Benaderd en geïnteresseerd, wacht op intake
`intake_scheduled`	Intakegesprek is ingepland
`active_mediation`	Wordt actief voorgesteld in procedures
`latent_mediation`	Beschikbaar, maar wordt niet actief voorgesteld
`upcoming_employee`	Heeft een aanbod geaccepteerd, start binnenkort
`employee`	Momenteel in dienst
`ex_employee`	Voormalig medewerker
`do_not_contact`	Mag niet benaderd worden

Responsevelden

Veld	Type	Beschrijving
`id`	integer	Uniek kandidaat-ID
`slug`	string	URL-vriendelijke identifier
`first_name`	string	Voornaam
`middle_name`	string\|null	Tussenvoegsel
`last_name`	string	Achternaam
`full_name`	string	Berekende volledige naam
`email`	string	E-mailadres
`mobile_phone`	string\|null	Mobiel telefoonnummer, opgemaakt voor weergave
`fixed_phone`	string\|null	Vast telefoonnummer in onbewerkt E.164-formaat (bijv. `+31201234567`)
`status`	object	Huidige kandidaatstatus
`locality`	string\|null	Plaats/woonplaats
`country_code`	string\|null	ISO 3166-1 alpha-2 landcode
`linkedin_url`	string\|null	LinkedIn-profiel-URL
`profile_completeness`	integer\|null	Percentage profielvolledigheid (0-100)
`avatar`	object	Avatar-afbeeldings-URL's
`created_at`	string	ISO 8601 aanmaakdatum
`updated_at`	string	ISO 8601 datum laatste wijziging

Objectstructuren

Status-object

JSON

{
  "value": "potential",
  "label": "Potential Candidate"
}

Avatar-object

JSON

{
  "small": "https://app.recruitsome.com/media/candidates/42/conversions/avatar-thumb.jpg",
  "medium": "https://app.recruitsome.com/media/candidates/42/conversions/avatar-medium.jpg",
  "large": "https://app.recruitsome.com/media/candidates/42/conversions/avatar-large.jpg"
}

Avatar-URL's kunnen null zijn als de kandidaat geen profielfoto heeft.

Paginering

Het antwoord bevat standaard pagineringsmetadata:

JSON

{
  "data": [...],
  "links": {
    "first": "https://app.recruitsome.com/api/v1/candidates?page=1",
    "last": "https://app.recruitsome.com/api/v1/candidates?page=3",
    "prev": null,
    "next": "https://app.recruitsome.com/api/v1/candidates?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://app.recruitsome.com/api/v1/candidates",
    "per_page": 20,
    "to": 20,
    "total": 52
  }
}

Voorbeeldverzoek

Basisverzoek

curl -X GET "https://app.recruitsome.com/api/v1/candidates?user_id=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.recruitsome.com/api/v1/candidates?user_id=1',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://app.recruitsome.com/api/v1/candidates',
    params={'user_id': 1},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

data = response.json()
print(data)

Kandidaat zoeken op e-mailadres

curl -X GET "https://app.recruitsome.com/api/v1/candidates?user_id=1&[email protected]" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.recruitsome.com/api/v1/candidates?user_id=1&[email protected]',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

response = requests.get(
    'https://app.recruitsome.com/api/v1/candidates',
    params={
        'user_id': 1,
        'email': '[email protected]'
    },
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

Met filters

Bash

curl -X GET "https://app.recruitsome.com/api/v1/candidates?user_id=1&search=developer&status=active_mediation&sort=last_name&sort_direction=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Voorbeeldrespons

JSON

{
  "data": [
    {
      "id": 42,
      "slug": "john-doe-amsterdam",
      "first_name": "John",
      "middle_name": null,
      "last_name": "Doe",
      "full_name": "John Doe",
      "email": "[email protected]",
      "mobile_phone": "+31 6 12345678",
      "fixed_phone": null,
      "status": {
        "value": "potential",
        "label": "Potential Candidate"
      },
      "locality": "Amsterdam",
      "country_code": "NL",
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "profile_completeness": 75,
      "avatar": {
        "small": "https://app.recruitsome.com/media/candidates/42/conversions/avatar-thumb.jpg",
        "medium": "https://app.recruitsome.com/media/candidates/42/conversions/avatar-medium.jpg",
        "large": "https://app.recruitsome.com/media/candidates/42/conversions/avatar-large.jpg"
      },
      "created_at": "2024-01-15T09:00:00+00:00",
      "updated_at": "2024-01-20T14:30:00+00:00"
    }
  ],
  "links": {
    "first": "https://app.recruitsome.com/api/v1/candidates?page=1",
    "last": "https://app.recruitsome.com/api/v1/candidates?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://app.recruitsome.com/api/v1/candidates",
    "per_page": 20,
    "to": 1,
    "total": 1
  }
}

Fouten

Status	Wanneer	Body
`422`	`user_id` ontbreekt of verwijst niet naar een bestaande gebruiker	`{"message": "The given data was invalid.", "errors": {"user_id": ["The user id field is required."]}}`
`422`	Het `email`-filter is geen geldig e-mailadres, of `search` overschrijdt 255 tekens	Dezelfde structuur, met het betreffende veld in `errors`
`401`	Ontbrekende of ongeldige API sleutel	`{"message": "Unauthenticated."}`
`403`	De API sleutel mist het `candidates:read`-bereik	`{"message": "This API key does not have the required permission: candidates:read", "error": "INSUFFICIENT_SCOPE", "required_scope": "candidates:read"}`

Opmerkingen

De parameter user_id is verplicht. Kandidaten zijn gekoppeld aan de repository van een specifieke gebruiker.
Alleen kandidaten die aan de opgegeven gebruiker zijn gekoppeld, worden geretourneerd
Zacht verwijderde kandidaten worden automatisch uitgesloten
Het filter email zoekt op exacte overeenkomst. Gebruik search voor gedeeltelijke overeenkomsten.
De parameter search voert een hoofdletterongevoelige, gedeeltelijke zoekopdracht uit op voornaam, achternaam en e-mailadres
mobile_phone wordt opgemaakt voor weergave geretourneerd; fixed_phone wordt als onbewerkte E.164-string geretourneerd
Avatar-URL's kunnen null zijn als de kandidaat geen profielfoto heeft geüpload

Authenticatie

Endpoint

Queryparameters

Statuswaarden

Responsevelden

Objectstructuren

Status-object

Avatar-object

Paginering

Voorbeeldverzoek

Basisverzoek

Kandidaat zoeken op e-mailadres

Met filters

Voorbeeldrespons

Fouten

Opmerkingen

Lees ook