Overview
This guide is for marketing and lead-generation partners who send applicants into Double Nickel. One endpoint is involved — POST /applicants — and this page covers everything you need end to end: credentials, getting a token, and making the request.
What you'll need from Double Nickel
The Double Nickel team provides these values before you start:
Value | What it's for |
| Authentication credentials, issued per environment |
| Identifies the client company the applicant belongs to |
| Identifies your source/campaign and determines the associated job listing |
Credentials are environment-specific rather than client-specific: as an agency you receive one set of credentials that can be reused across multiple client companies. The client-specific values (companyId, trackingLinkId) are passed in each request instead.
Environments
Environment | API base URL | Auth token URL |
Testing |
|
|
Production |
|
|
Step 1: Get an access token
curl --request POST \
--url https://double-nickel.us.auth0.com/oauth/token \
--header 'content-type: application/json' \
--data '{"client_id":"XXXXX","client_secret":"XXXXX","audience":"XXXXX","grant_type":"client_credentials"}'
Response:
{
"access_token": "XXXXXXXXXX",
"token_type": "Bearer",
"expires_in": 86400
}Access tokens are valid for 24 hours. Cache and reuse a token until it expires rather than requesting a new one for every request — repeatedly requesting fresh tokens can result in Double Nickel revoking access.
Step 2: Create the applicant
Send the token in the Authorization header and include the Auth-provider header on every request:
Header | Value |
|
|
|
|
|
|
Request payload
Field | Type | Required | Description & limits |
| String | Yes | Applicant's first name, 2–100 characters |
| String | No | Applicant's middle name, up to 100 characters |
| String | Yes | Applicant's last name, 1–100 characters |
| String | Yes | US/Canada phone number. Non-digit characters are stripped and |
| String | Yes | Must be a valid email address |
| Number | No | CDL experience in years, 0–50 (decimals allowed, e.g. |
| String | No | 5-digit ZIP or ZIP+4 ( |
| String | Yes | Provided by the Double Nickel team, and must belong to the company in |
| String | Yes | Provided by the Double Nickel team |
| String | No | The |
| Array | No | Answers to the client company's custom screening questions, one item per answered question. See Custom question answers below. |
Custom question answers (optional)
Some client companies add their own screening questions to the application, for example "Do you have a hazmat endorsement?" or "Preferred route type". If you collect those answers on your side, send them with the applicant and they appear on the applicant's profile for the recruiter, exactly as if the driver had answered them on the Double Nickel short form.
Double Nickel provides the question list for each client: every question's questionId, its type, and the option IDs for choice questions. Send one item per answered question:
"customQuestions": [
{ "questionId": "0b7e9f12-6c3a-4d58-8e21-9a4f7c3b2d10", "answer": "Flatbed and reefer" },
{ "questionId": "7d2f5b9a-e1c4-4a83-9f67-3b8d0c2e4a55", "answer": true },
{ "questionId": "e8c3a6f1-4b9d-47e2-a0c5-6f1d9b3e7c88", "answer": "2a9f4c7e-1d6b-48a3-b5e9-0c3f7a2d8e41" },
{ "questionId": "f1b6d9c4-7e2a-4c58-9d13-5a8e2f4b6c77", "answer": ["6c1e9a3f-8d4b-42f7-a2c6-9e5b1d7f3a90", "9e4b2d7a-3f1c-4e86-b7a1-2c8d5f9e0b64"] }
]
The answer format depends on the question type:
Question type |
| Also accepted |
Short text | String, up to 500 characters |
|
Long text | String, up to 5,000 characters |
|
Yes / no |
|
|
Single choice | One option ID as a string | A one-item list |
Multiple choice | A list of option IDs | A comma-separated string of option IDs |
The string forms exist for tools such as Zapier that send every value as text.
Entirely optional. Leave
customQuestionsout, or send an empty list, and the request behaves exactly as described above. Most integrations do not send it.Send only what you have. Unanswered questions are simply left off. An empty string is treated as unanswered.
Answers never block the applicant. An item that cannot be stored (unknown question ID, an answer of the wrong type, an unknown option ID, text over the length limit, or a second item for the same question) is skipped and the applicant is still created with the remaining answers. The response does not change, so validate on your side before sending, and contact us if answers are not showing up on applicants.
Behavior notes
Unknown fields are silently ignored. No error is returned for unrecognized field names, so a typo means the value is quietly dropped.
Validation failures are not field-specific. Any invalid field returns the same response —
{"error": "bad_request", "message": "Invalid request body"}— so validate on your side before sending.The endpoint returns
200(not201) on success.
Response
{
"applicantId": "983ad3fc-6fd7-4535-a1d9-2191e6104714"
}Full example
curl -X POST "https://dashboard.getdoublenickel.com/api/applicants" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer yourAccessTokenHere" \
-H "Auth-provider: auth0" \
-d '{
"firstName": "John",
"middleName": "Alexander",
"lastName": "Doe",
"phone": "+15551234567",
"email": "[email protected]",
"cdlExperience": 5.5,
"zipCode": "75201",
"trackingLinkId": "983ABad3fc-6fd7-4535-a1d9-2191e6104714",
"companyId": "your-company-id",
"customQuestions": [
{ "questionId": "7d2f5b9a-e1c4-4a83-9f67-3b8d0c2e4a55", "answer": true },
{ "questionId": "e8c3a6f1-4b9d-47e2-a0c5-6f1d9b3e7c88", "answer": "2a9f4c7e-1d6b-48a3-b5e9-0c3f7a2d8e41" }
]
}'
Errors and rate limits
HTTP status | Error code | Meaning |
400 |
| The request body could not be decoded as JSON |
400 |
| The request body failed validation |
401 |
| The authorization token is not valid |
403 |
| Your credential lacks the required permission — contact us |
429 |
| Rate limit exceeded (average 5 requests/second per integration) — back off and retry |
500 |
| Unexpected server error |
Questions or need help?
Contact the Double Nickel support team at [email protected]. The Testing environment may occasionally be offline for updates (typically under 15 minutes) — let us know in advance when you plan to test so we can guarantee availability.
Looking for the rest of the API — reading applicant data, retrieving documents, or status webhooks? See the Developers & API collection.
