Creating Applicants (POST /applicants) | Double Nickel Help Center

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

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"
  }'

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.