Skip to main content

Creating Applicants (POST /applicants)

For marketing and lead providers: send applicants into Double Nickel with POST /applicants - credentials, token setup, request fields, validation rules, and a full example.

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

client_id, client_secret, audience

Authentication credentials, issued per environment

companyId

Identifies the client company the applicant belongs to

trackingLinkId

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

https://dashboard-test.getdoublenickel.com/api/

https://double-nickel-test.us.auth0.com/oauth/token

Production

https://dashboard.getdoublenickel.com/api/

https://double-nickel.us.auth0.com/oauth/token

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

Authorization

Bearer <access_token>

Auth-provider

auth0

Content-Type

application/json

Request payload

Field

Type

Required

Description & limits

firstName

String

Yes

Applicant's first name, 2–100 characters

middleName

String

No

Applicant's middle name, up to 100 characters

lastName

String

Yes

Applicant's last name, 1–100 characters

phone

String

Yes

US/Canada phone number. Non-digit characters are stripped and +1 is prepended when no country code is present; the result must be a valid E.164 US number (+1 followed by 10 digits). "(555) 123-4567", "5551234567", and "+15551234567" are all accepted.

email

String

Yes

Must be a valid email address

cdlExperience

Number

No

CDL experience in years, 0–50 (decimals allowed, e.g. 5.5). Values above 50 are rejected.

zipCode

String

No

5-digit ZIP or ZIP+4 ("75201" or "75201-6789"). Geocoded to set the applicant's address.

trackingLinkId

String

Yes

Provided by the Double Nickel team, and must belong to the company in companyId

companyId

String

Yes

Provided by the Double Nickel team

recruiterId

String

No

The employeeId of a recruiter to assign as the applicant's lead recruiter

customQuestions

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

answer

Also accepted

Short text

String, up to 500 characters

Long text

String, up to 5,000 characters

Yes / no

true or false

"true" or "false" as strings

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 customQuestions out, 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 (not 201) 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

invalid_json

The request body could not be decoded as JSON

400

bad_request

The request body failed validation

401

unauthorized

The authorization token is not valid

403

forbidden

Your credential lacks the required permission — contact us

429

too_many_requests

Rate limit exceeded (average 5 requests/second per integration) — back off and retry

500

internal_error

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.

Did this answer your question?