Send take-home invitations or let candidates choose a live interview time.

Invites

POST /api/v1/invites invites a candidate to an assessment. What the candidate receives depends on that assessment's delivery mode, configured in Litmus. The invite request does not change the delivery mode.

Take-home and live interview invites

Read the pipeline to find the assessment's delivery_mode and assessment_id. Pass assessment_id explicitly so the invite targets the intended take-home or live round.

If your automation already chooses the interview time, use POST /interviews directly. It can create the candidate and sends the booking confirmation, so a separate invite is unnecessary.

Send an assessment invite

POST /api/v1/invites · Required scope: invites:write.

The example below targets one assessment explicitly. Use an async assessment ID for a take-home invitation or a sync assessment ID for a scheduling invitation.

curl --fail-with-body -X POST https://litmushiring.com/api/v1/invites \
  -H "Authorization: Bearer $LITMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posting_id": "posting_abc123",
    "assessment_id": "asmt_ghi789",
    "candidate_email": "candidate@example.com",
    "candidate_name": "Sample Candidate"
  }'

Returns:

{
  "invite_id": "cand_xyz789",
  "invite_url": "https://litmushiring.com/sign-in?assessmentToken=...",
  "reused": false
}

Returns 201 with invite_id (the candidate record ID), invite_url, and reused: false for a new invitation. Litmus sends the invitation email automatically. You can also display invite_url in your own portal; this does not suppress the email.

Find the posting ID in its dashboard URL (/company/posting/{id}) or through GET /roles. A cohort uses the same request shape with its ID as posting_id. The assessment must be ready for invitations and the posting must be open. Self-select assessment groups are not supported by this endpoint.

For live self-scheduling, configure interviewer availability before sending the invite. Without available times, the candidate cannot complete the booking.

Retries

Invitations are matched by assessment and normalized candidate email. Repeating an invitation returns 200 with the existing invite_id and reused: true. It does not send another email or return the original sign-in link.

{
  "invite_id": "cand_xyz789",
  "reused": true
}

Save invite_url when creating a new invitation if your integration needs to display it. Retrying the request cannot retrieve that URL.

Errors