Ingest an applicant

Ingests an applicant from your platform and starts screening. The applicant’s registry is resolved from location_ref, so you do not pass an organization — one call, one applicant, wherever they applied.

Several locations at once. Send location_refs (an array of 1–20 location refs) instead of location_ref to put one applicant at several locations in one call. Send exactly one of the two. You get one candidate with one application per location, and the response lists them in applications[]. The applicant is screened once: one heads-up SMS and one screening call cover every location named in the request. All the locations must be in the same registry, or the request fails with 400 location_refs_span_organizations and nothing is created. See the multiple locations guide.

What happens next. The applicant receives a heads-up SMS immediately and an AI screening call a few minutes later. Results land in the registry’s CONFIRM portal, at the portal_url in the response.

Store two things: candidate_id and portal_url. The first is the durable correlation key; the second is your “View Full Details” link.

Idempotency. Re-submitting the same applicant returns the existing IDs with deduped: true and a 200. A duplicate never conflicts and never creates a second application on the same location. Matching is by your external_ref first, then by phone number, then by email — so an applicant who reaches a registry through both your intake form and a job board resolves to one person, not two.

Shared phones and emails stay separate people. A phone or email match only links to a candidate you have not already sent under a different external_ref (in practice, someone who applied through a job board). Two applicants you send with different refs are always two candidates, even when they share a household phone or email, and neither one’s details are changed by the other.

Consent governs contact. consent.contact must be true for CONFIRM to text or call. Send false (or omit it) and the applicant is still created and visible in the portal, but no outreach happens and the response returns screening: "skipped_no_consent". This is the TCPA boundary: we contact within minutes of ingest, so consent is not something to assume.

Consent (or a phone) sent later starts screening. If you first send an applicant without consent, or without a usable phone, and later re-send them with it, that re-send starts screening: 200, deduped: true, screening: "enqueued". This happens once, and only while the applicant is still new: if a recruiter has already moved them on in CONFIRM, the re-send changes nothing about their screening.

Unknown locations fail loudly. A location_ref we don’t recognise returns 404 unknown_location_ref rather than dropping the applicant. The same request succeeds on retry once the location exists.

Closed locations take no new applicants. A location closed with PATCH /locations/{ref} returns 409 location_closed for someone new. An applicant you sent before it closed still returns 200 with deduped: true. With location_refs, one closed location the applicant is not already at fails the whole request with 409 location_closed before anything is created; reopen it or leave it out, then retry.

Distance at intake. Send the applicant’s address and CONFIRM measures their commute to each location. A location they live too far from (beyond its maximum commute distance) is ruled out straight away: that application gets screening: "skipped_ruled_out", its status becomes rejected, and it is left out of the screening call. Other locations are unaffected.

A location sent after the call. If the applicant’s screening call has not been placed yet, a new location joins it. If the call has already happened, the new location gets a short follow-up call that asks only the questions the applicant has not already answered, with no second heads-up SMS. If nothing is left to ask, no call is placed and the outcome at the new location is decided from the earlier answers. If the first call is still in progress, the new location waits for it. In each case the response reports screening: "enqueued", and the result arrives as screening.completed and candidate.status_changed for that location. See follow-up calls.

Held for a calendar. Screening calls are held while the registry’s workspace has no connected calendar. When screening is enqueued and the workspace has none, screening_hold is "calendar_not_connected"; the call goes out once a calendar is connected. See the calendar guide.

Same location ref in several registries. If you use one location ref in more than one registry, pass organization_ref to say which; without it the request returns 409 ambiguous_location_ref.