Bijgewerkt 15 juni 2026
/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:
- Uploaden: je verstuurt het cv via de API
- Geaccepteerd: de API retourneert
202 Acceptedmet eenprocessing_id - Verwerking: AI extraheert kandidaatinformatie uit het cv op de achtergrond
- Melding: de gebruiker die is opgegeven via
user_idontvangt 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
{
"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:
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
| Veld | Type | Beschrijving |
|---|---|---|
user_id | integer | Verplicht. Het gebruikers-ID van de tenant om de kandidaat aan te koppelen. Deze gebruiker ontvangt de melding van het assistent verzoek. |
resume | object | Verplicht. Het cv-document dat verwerkt moet worden |
resume.filename | string | Verplicht. Originele bestandsnaam (max. 255 tekens) |
resume.content | string | Verplicht. Base64-gecodeerde bestandsinhoud |
resume.mime_type | string | Verplicht. MIME-type van het bestand |
Optionele velden
| Veld | Type | Beschrijving |
|---|---|---|
create_intake | boolean | Verzoek 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:
{
"filename": "resume.pdf",
"content": "base64_encoded_content_here",
"mime_type": "application/pdf"
}Ondersteunde documenttypen
| Toegestane MIME-typen | Max. grootte |
|---|---|
application/pdf | 10MB |
application/msword (.doc) | 10MB |
application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx) | 10MB |
application/zip | 10MB |
application/x-ole-storage | 10MB |
application/octet-stream | 10MB |
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)
{
"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)
{
"message": "The given data was invalid.",
"errors": {
"resume.content": ["The resume content is not valid base64 encoded data."]
}
}Bestandsgrootte overschreden (422)
{
"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):
{
"message": "Too Many Attempts."
}Serverfout (500)
{
"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:
- CV-analyse: AI extraheert persoonlijke gegevens, werkervaring, opleiding en vaardigheden uit het cv
- Duplicaatdetectie: Het systeem controleert of er al een kandidaat met hetzelfde e-mailadres bestaat
- Kandidaat aanmaken: Als de kandidaat nieuw is, wordt het profiel aangemaakt met de geëxtraheerde gegevens
- Verrijkingsworkflow: Aanvullende AI-verwerking verrijkt het kandidaatprofiel (taganalyse, samenvattingen genereren)
- Notificatie: De gebruiker die is opgegeven via
user_idontvangt een assistent verzoek met het resultaat
Mogelijke uitkomsten
| Scenario | Wat er gebeurt |
|---|---|
| Nieuwe kandidaat | De 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 cv | De kandidaat wordt opgeslagen als "in afwachting". De gebruiker ontvangt een "aanvulling nodig"-notificatie. |
| Verwerkingsfout | De 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_idmoet 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_idis 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.