Quickstart

An integration always follows the same flow: your ATS opens a configuration session, the recruiter sets up the assessment in an iframe, then you assign that assessment to candidates. Skillee runs the conversation and sends the result back to your tool.

Before you start

You need the company ID (company_id) that Skillee gives you on activation: 32 hexadecimal characters, for example abc123def4567890abc123def4567890.

Calls are made to https://api-charlee2.skillee.ai. The legacy host https://api-charlie.skillee.ai serves the same application: an existing integration has nothing to change.

Authentication

Every call carries the company ID in the Authorization header:

Authorization: Bearer abc123def4567890abc123def4567890

Some routes also accept company_id in the body or as a query parameter. When the ID is present in both places, the two values must be identical, otherwise the call is rejected with 401. A value that is not made of 32 hexadecimal characters is rejected with 400.

The flow

Open the configuration session. Your server sends the job offer to Skillee and receives the iframe URL. The call is idempotent: the same job offer always maps to the same recruitment.

curl https://api-charlee2.skillee.ai/partners/beetween/assessment-builder-sessions \
  -H "Authorization: Bearer $COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "offerId": "OFFER-2026-001",
    "jobTitle": "Order picker",
    "jobDescription": "Permanent contract in Lyon, daytime hours, forklift licence a plus…"
  }'

{ "iframeUrl": "https://…" }

Display the iframe. The recruiter chooses the agent, the channel and the questions, then confirms. The iframe then sends your page the assessment ID, the testId. See Configuration iframe.
Store the testId with the job offer in your ATS. It identifies the assessment for all future assignments.

Assign the assessment to a candidate. Skillee contacts them straight away.

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" }
  }'

{ "id": "…" }

See Assign candidates for batches, idempotency and credits.

Results

Skillee sends your ATS each candidate’s progress: pending, answered (with the score and the report) or failed (with the reason). These updates go through the connection our team sets up with you on activation; there is nothing to poll on your side.

Without the iframe

If you build your own configuration screen, call POST /partners/charlee/v2/list/assessments directly to read the existing assessments for a job offer, then POST /partners/charlee/v2/create/interview to create or update one. The response of the latter carries the interview_id, which plays the role of the testId. Both routes are described in the API reference.

Going further