Skip to content

Lead intake API

The lead intake API takes one lead per request from another system: your own website form, a job board feed, another applicant tracking system. Each lead goes through the same intake as your careers page: the candidate is found or created, the application is added, and the lead shows in Attract > Leads with Captured by set to API.

  • To see the keys: See the keys of the lead intake API (platform.lead_api_keys.read).
  • To create and revoke keys: Create and revoke keys of the lead intake API (platform.lead_api_keys.manage).
  • The developer who connects the other system. The key is a secret: call the API from a server, never from a web page.

See Roles and permissions.

  • The Recruit module must be on for your company. With it off, the API answers 403 module_disabled.
  • To send leads for a job, the job must be open or paused. Take its id, or the address of its public page (see Jobs).
  1. Open Platform in the menu on the left, then Integrations. The Lead intake API tab opens.
  2. Select Create key.
  3. In Create a key, type a Name after the system that will use it, for example Website form or Indeed feed, so you know which one to revoke later. Select Create key.
  4. In Copy your key, select Copy and store the key somewhere safe. It will not be shown again. Select Done.

The table shows each key with its Name, the first characters of the Key, Created by, Created, Last used and Status. Your company can have up to 20 active keys. To stop a key, select Revoke and confirm with Revoke key: requests with it stop working right away, and the leads it already sent stay where they are. This cannot be undone.

The screen also has an Example request with your address, and the API reference link opens the full description of the route.

Open the screenshot at full size in a new tab:Platform > Integrations, Lead intake API tab: the Create key button, the table of keys with name, key, created by, created, last used, status and Revoke, the Example request, the limit of 120 requests a minute and the API reference link.

Send POST /public/v1/leads to the address of your API, with the key in the Authorization header. The address and the key below are examples; use the address of the Example request and your own key.

Terminal window
curl -X POST https://api.example.com/public/v1/leads \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"candidate": {
"firstName": "Jordan",
"lastName": "Reyes",
"email": "jordan.reyes@example.com",
"phone": "+12145550142",
"state": "TX",
"cdlClass": "A",
"experienceYears": 4
},
"jobSlug": "regional-reefer-driver",
"source": { "channel": "job_board", "detail": "Indeed" },
"consents": [
{ "channel": "sms", "granted": true, "text": "I agree to receive text messages about jobs.", "locale": "en" }
],
"externalId": "your-lead-id-1001"
}'

A lead that was taken in answers 201 Created:

{
"candidateId": "6f1c2a8e-0b7d-4d1e-9a51-2f6a3c9d8e10",
"applicationId": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
"duplicate": false
}

duplicate is true when the email or the phone already belonged to a candidate of your company: the lead was added to that candidate, and no second candidate was created.

Unknown fields are ignored with no error. A field name typed wrong is an unknown field: externalID instead of externalId is dropped.

Field Required What it holds
candidate.firstName Yes 1 to 100 characters.
candidate.lastName No Up to 100 characters. A lead may arrive with one name only.
candidate.email One of the two An email address.
candidate.phone One of the two A US number in any format, or E.164 (+12145550142).
candidate.city No Up to 100 characters.
candidate.state No Two-letter US state, for example TX.
candidate.postalCode No 5-digit ZIP code or ZIP+4.
candidate.cdlClass No A, B or C; null for no CDL.
candidate.endorsements No A list of H, N, P, S, T, X, without repetition.
candidate.experienceYears No Whole years, 0 to 60.
candidate.preferredLocale No en or es: the language the candidate is contacted in.
jobId No The id of an open or paused job of your company. Without jobId and jobSlug, the lead is a general application.
jobSlug No The address of the public page of the job, instead of jobId. Send one or the other, not both.
source.channel No job_board, social_media, company_website, referral, walk_in, event, agency, qr_code or other. Absent: other.
source.detail No Up to 100 characters: the name of the job board, the event or the agency.
source.linkCode No The code of one of your tracked links (the last part of its short address).
source.utm No source, medium, campaign, term and content, up to 200 characters each.
consents No At most one per channel: sms, voice, email, ai_contact or call_recording. Each has granted (true or false), the text the person accepted (required with granted: true, up to 4,000 characters) and its locale.
screeningAnswers No Up to 50 answers, each with the questionId of a screening question of the job and its value: yes or no, a number, one option, a list of options or a text.
externalId No Your own id of the lead, up to 200 characters.

Rules that matter:

  • Same person, same candidate. A candidate with the same email or phone is reused, never created twice. A lead for a job the candidate already applied to is added to that application.
  • Idempotency. Send your own id in externalId. The same externalId sent again, even at the same moment, answers 201 with the lead already created and creates nothing.
  • Consent date. A consent is dated when the lead arrives. A consent with capturedAt is refused with 400 and nothing is created.
  • Tracked links. With source.linkCode of one of your links, the lead is credited to the link, with its channel, its campaign and, on a referral link, the person who referred, whatever source.channel says. Each UTM value written on the link wins; the ones you send only fill what the link left empty. A link that is archived, or of a campaign that ended, still credits the lead. A code that is not of one of your links is ignored with no error.
Status Code When
201 The lead was taken in, or was already there (externalId repeated).
400 validation_failed A field is invalid. issues names each one by its path, for example candidate.email or consents.0.text.
400 invalid_reference jobId or jobSlug is not a job of your company.
401 unauthenticated The key is missing, unknown, revoked or malformed.
403 module_disabled Recruit is turned off for your company.
403 cross_site_request The request came from a web page of another site. Call the API from a server.
413 payload_too_large The body is larger than 100 kB.
429 rate_limited Past a limit. Wait the seconds of Retry-After.
503 service_unavailable Try the same request again after Retry-After.

Every error has the same body: code, message, status, requestId and, for invalid fields, issues.

The limits are 120 requests a minute per key and 600 requests a minute per IP address. Every authenticated answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the minute starts again).

The lead shows in Attract > Leads with Captured by set to API, and its candidate is in Recruit with the application. The Last used column of the key shows when it last sent a lead that was taken in.