Assign candidates

Once the assessment is configured, each assignment starts the candidate’s journey: the agent contacts them through the channel chosen in the iframe.

One candidate

curl https://api-charlee2.skillee.ai/partners/beetween/assessments \
  -H "Authorization: Bearer $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "assessmentId": "<testId>",
    "applicant": {
      "firstName": "Marie",
      "lastName": "Dupont",
      "email": "marie.dupont@example.com",
      "phone": "+33612345678"
    },
    "recruiter": { "email": "recruiter@company.com" }
  }'

The 201 response carries the session ID: { "id": "…" }.

Field	Required	Description
`assessmentId`	yes	The `testId` received from the iframe.
`applicant.email`	yes	The candidate’s e-mail address.
`applicant.phone`	yes	Number in international format (E.164), for example `+33612345678`.
`applicant.firstName`, `applicant.lastName`	no	First name and last name, used in the messages sent to the candidate.
`applicant.planning_date`	no	Preferred call date, in ISO 8601 format.
`recruiter.email`	recommended	The recruiter who made the assignment.

The recruiter

Always send recruiter.email. It attributes the consumption to the client company, whereas the company ID only identifies your ATS. For interview scheduling and e-mails, Skillee also uses this recruiter’s calendar and mailbox: if they have not connected them, the sending is refused and the reason is returned to you.

Idempotency

Assigning the same assessment to the same candidate twice does not create a duplicate: as long as a session is active, the call returns 201 with the existing session. You can therefore replay a call whose response was lost.

A batch of candidates

curl https://api-charlee2.skillee.ai/partners/charlee/v2/launch/interview \
  -H "Authorization: Bearer $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "interview_id": "<testId>",
    "applicants": [
      { "firstName": "Marie", "lastName": "Dupont", "email": "marie.dupont@example.com", "phone": "+33612345678" },
      { "firstName": "Karim", "lastName": "Benali", "email": "karim.benali@example.com", "phone": "+33698765432" }
    ],
    "recruiter": { "email": "recruiter@company.com" }
  }'

The batch can partly succeed: the 200 response lists side by side the sessions created (sessions) and the rejected candidates with their reason (failed). A candidate who already has an active session for this assessment appears there with the reason DUPLICATE_ACTIVE_SESSION. If no session could be created, the response is a 422 listing the reasons; they are detailed in the error codes.

Credits

Each journey consumes the client company’s credits, for single assignments and batches alike. Without enough credits, the assignment is rejected with 402 and the candidate is not contacted.