Skip to main content

Kandidaat aanmaken

NL EN

Bijgewerkt 15 juni 2026

POST /api/v1/candidates
curl -X POST \
  "https://app.recruitsome.com/api/v1/candidates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
const response = await fetch('https://app.recruitsome.com/api/v1/candidates', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json',
  },
});

const data = await response.json();
console.log(data);
use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_API_KEY')
    ->acceptJson()
    ->post('https://app.recruitsome.com/api/v1/candidates');

$data = $response->json();

Maak een nieuwe kandidaat aan door een cv te uploaden. Het cv wordt asynchroon op de achtergrond verwerkt. De API retourneert direct een processing_id die je kunt vastleggen als referentie voor supportvragen (er is geen endpoint om de voortgang op te vragen). Zodra de verwerking is voltooid, ontvangt de verantwoordelijke gebruiker een melding als assistent verzoek in de applicatie.

Authenticatie

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

Hoe het werkt

Het aanmaken van een kandidaat is een asynchroon proces dat de volgende stappen doorloopt:

  1. Uploaden: je verstuurt het cv via de API
  2. Geaccepteerd: de API retourneert 202 Accepted met een processing_id
  3. Verwerking: AI extraheert kandidaatinformatie uit het cv op de achtergrond
  4. Melding: de gebruiker die is opgegeven via user_id ontvangt een assistent verzoek in de applicatie met het resultaat

Dit is dezelfde verwerkingspipeline als bij het uploaden van een cv via de applicatie-interface. De kandidaat wordt aangemaakt, verrijkt, en de gebruiker wordt op de hoogte gebracht via de normale flow van assistent verzoeken.

Eenvoudig voorbeeld

curl -X POST https://app.recruitsome.com/api/v1/candidates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 1,
    "resume": {
      "filename": "john_doe_cv.pdf",
      "content": "JVBERi0xLjQKJeLj...",
      "mime_type": "application/pdf"
    }
  }'
// Read file and convert to base64
async function fileToBase64(file) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.readAsDataURL(file);
    reader.onload = () => resolve(reader.result.split(',')[1]);
    reader.onerror = reject;
  });
}

const resumeFile = document.getElementById('resume-input').files[0];
const resumeBase64 = await fileToBase64(resumeFile);

const response = await fetch('https://app.recruitsome.com/api/v1/candidates', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    user_id: 1,
    resume: {
      filename: resumeFile.name,
      content: resumeBase64,
      mime_type: resumeFile.type
    }
  })
});

if (response.status === 202) {
  const result = await response.json();
  console.log('Processing started:', result.data.processing_id);
}
import requests
import base64

# Read resume file
with open('resume.pdf', 'rb') as f:
    resume_content = base64.b64encode(f.read()).decode('utf-8')

response = requests.post(
    'https://app.recruitsome.com/api/v1/candidates',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'user_id': 1,
        'resume': {
            'filename': 'resume.pdf',
            'content': resume_content,
            'mime_type': 'application/pdf'
        }
    }
)

if response.status_code == 202:
    result = response.json()
    print('Processing started:', result['data']['processing_id'])

Voorbeeld van een response

JSON
{
  "message": "Resume uploaded successfully. The candidate will be created in the background.",
  "data": {
    "processing_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Met intake-aanmaak

Als de tenant de intake-functie heeft ingeschakeld, kun je verzoeken dat er automatisch een intake wordt aangemaakt voor de nieuwe kandidaat:

Bash
curl -X POST https://app.recruitsome.com/api/v1/candidates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 1,
    "resume": {
      "filename": "jane_smith_cv.pdf",
      "content": "JVBERi0xLjQKJeLj...",
      "mime_type": "application/pdf"
    },
    "create_intake": true
  }'

De create_intake-vlag werkt alleen wanneer de tenant de intake-functie heeft ingeschakeld. Als de functie niet is ingeschakeld, wordt deze parameter stilzwijgend genegeerd.

Requestvelden

Verplichte velden

VeldTypeBeschrijving
user_idintegerVerplicht. Het gebruikers-ID van de tenant om de kandidaat aan te koppelen. Deze gebruiker ontvangt de melding van het assistent verzoek.
resumeobjectVerplicht. Het cv-document dat verwerkt moet worden
resume.filenamestringVerplicht. Originele bestandsnaam (max. 255 tekens)
resume.contentstringVerplicht. Base64-gecodeerde bestandsinhoud
resume.mime_typestringVerplicht. MIME-type van het bestand

Optionele velden

VeldTypeBeschrijving
create_intakebooleanVerzoek om automatisch een intake aan te maken voor de nieuwe kandidaat (vereist de intake-functie)

CV-document

Het cv moet base64-gecodeerd zijn en metadata bevatten:

JSON
{
  "filename": "resume.pdf",
  "content": "base64_encoded_content_here",
  "mime_type": "application/pdf"
}

Ondersteunde documenttypen

Toegestane MIME-typenMax. grootte
application/pdf10MB
application/msword (.doc)10MB
application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx)10MB
application/zip10MB
application/x-ole-storage10MB
application/octet-stream10MB

De typen application/zip, application/x-ole-storage en application/octet-stream worden geaccepteerd omdat browsers en oudere Word-bestanden het MIME-type van .doc/.docx vaak verkeerd rapporteren. Geef het type door dat je bestands-API retourneert. Het bestand zelf moet wel een PDF- of Word-document zijn om de AI-verwerking te laten slagen.

Let op

Base64-codering vergroot de bestandsgrootte met ongeveer 33%. Een bestand van 10 MB wordt na base64-codering ongeveer 13,3 MB.

Foutafhandeling

Validatiefouten (422)

JSON
{
  "message": "The given data was invalid.",
  "errors": {
    "user_id": ["The specified user does not exist."],
    "resume": ["A resume document is required to create a candidate."],
    "resume.mime_type": ["The resume must be a PDF or Word document (application/pdf, application/msword, or application/vnd.openxmlformats-officedocument.wordprocessingml.document)."]
  }
}

Het resume.mime_type-bericht noemt de belangrijkste documenttypen. Het endpoint accepteert ook de fallback-MIME-types die hierboven onder Ondersteunde documenttypen staan vermeld. Je ziet deze fout alleen wanneer het type buiten de volledige lijst valt.

Ongeldige Base64-inhoud (422)

JSON
{
  "message": "The given data was invalid.",
  "errors": {
    "resume.content": ["The resume content is not valid base64 encoded data."]
  }
}

Bestandsgrootte overschreden (422)

JSON
{
  "message": "The given data was invalid.",
  "errors": {
    "resume": ["The resume file size exceeds the maximum allowed limit of 10MB."]
  }
}

Rate limiting (429)

Het endpoint accepteert 10 verzoeken per minuut per API sleutel. Bij overschrijding ontvang je de standaard throttle-respons met een Retry-After-header (het aantal seconden tot het venster wordt gereset):

JSON
{
  "message": "Too Many Attempts."
}

Serverfout (500)

JSON
{
  "message": "An unexpected error occurred while processing the resume.",
  "error": "PROCESSING_FAILED"
}

Wat er na het indienen gebeurt

Zodra de API 202 Accepted retourneert, gebeurt het volgende op de achtergrond:

  1. CV-analyse: AI extraheert persoonlijke gegevens, werkervaring, opleiding en vaardigheden uit het cv
  2. Duplicaatdetectie: Het systeem controleert of er al een kandidaat met hetzelfde e-mailadres bestaat
  3. Kandidaat aanmaken: Als de kandidaat nieuw is, wordt het profiel aangemaakt met de geëxtraheerde gegevens
  4. Verrijkingsworkflow: Aanvullende AI-verwerking verrijkt het kandidaatprofiel (taganalyse, samenvattingen genereren)
  5. Notificatie: De gebruiker die is opgegeven via user_id ontvangt een assistent verzoek met het resultaat

Mogelijke uitkomsten

ScenarioWat er gebeurt
Nieuwe kandidaatDe kandidaat wordt aangemaakt. De gebruiker ontvangt een "kandidaat aangemaakt"-notificatie.
Bestaande kandidaat (zelfde e-mailadres)Het cv wordt ter beoordeling bijgevoegd. De gebruiker ontvangt een "cv beoordelen"-notificatie.
Geen e-mailadres in cvDe kandidaat wordt opgeslagen als "in afwachting". De gebruiker ontvangt een "aanvulling nodig"-notificatie.
VerwerkingsfoutDe gebruiker ontvangt een "verwerking mislukt"-notificatie.

Tip

Alle uitkomsten resulteren in een assistent verzoek-notificatie aan de gebruiker. Je hoeft dus niet te pollen voor de status. De gebruiker kan direct in de applicatie de juiste actie ondernemen.

Opmerkingen

  • De user_id moet verwijzen naar een geldige gebruiker binnen de tenant. Deze gebruiker wordt de "eigenaar" van de kandidaat en ontvangt alle notificaties.
  • De verwerking is doorgaans binnen enkele minuten afgerond, afhankelijk van de complexiteit van het cv.
  • De processing_id is een UUID die je kunt opslaan ter referentie. Het primaire notificatiemechanisme is echter het assistent verzoek.
  • Vergeet niet om persoonsgegevens te verwerken conform de AVG-vereisten.