Overview

Double Nickel offers a REST API and outbound webhooks so integration partners can create applicants, retrieve applicant data and documents, and react to applicant status changes in real time. This article covers what's shared by all endpoints: authentication, environments, scopes, rate limits, and error codes.

Surface	What it does
`POST /applicants`	Create an applicant under a client company (see Creating Applicants)
`GET /applicant`	Retrieve an applicant's full profile (see Get Applicant API)
`GET /documents`	List an applicant's documents with secure download URLs (see Documents API)
Applicant Status Webhooks	Receive an HTTPS POST whenever an applicant's status changes (see Applicant Status Webhooks)

This article supersedes the "API Documentation" v1.0 document dated 02/01/2024. If you are working from that document, note that read endpoints and status webhooks have been added since.

Environments

Environment	Base URL
Testing	`https://dashboard-test.getdoublenickel.com/api/`
Production	`https://dashboard.getdoublenickel.com/api/`

Note: The Testing environment is for development and testing only and may occasionally be offline for updates (typically under 15 minutes). Let the Double Nickel team know in advance when you plan to test so we can guarantee availability.

Authentication

The API uses the OAuth 2.0 client credentials (machine-to-machine) flow via Auth0. The Double Nickel team provides three values, issued per environment:

Field	Type	Description
`client_id`	String	Provided by Double Nickel
`client_secret`	String	Provided by Double Nickel
`audience`	String	Provided by Double Nickel

Credentials are environment-specific rather than client-specific: an agency receives one set of credentials that can be reused across multiple client companies. The client-specific values (such as companyId) are passed in each API request instead.

Requesting a token

Environment	Auth Token URL
Testing	`https://double-nickel-test.us.auth0.com/oauth/token`
Production	`https://double-nickel.us.auth0.com/oauth/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.

Calling the API

Every API request must include the token and the Auth-provider header:

Header	Value
`Authorization`	`Bearer <access_token>`
`Auth-provider`	`auth0`
`Content-Type`	`application/json` (for requests with a body)

Scopes

Each endpoint requires a specific scope to be granted to your credential:

Endpoint	Required scope
`POST /applicants`	`create:applicants`
`GET /applicant`	`read:applicants`
`GET /documents`	`read:documents`

A single credential can hold multiple scopes. If your existing integration credential only has create:applicants, contact [email protected] to have the read scopes added — you do not need a separate client_id, and your token request stays the same. Calling an endpoint without the matching scope returns 403 forbidden.

Rate limiting

The rate limit for incoming requests is an average of 5 requests per second per integration. Short bursts beyond the average are allowed. Rate-limited requests return HTTP 429 with the too_many_requests error code — implement exponential backoff. Rate limits may be adjusted in the future to balance demand and reliability.

Status codes and errors

Error responses include a JSON body with an error code and a human-readable message:

{
  "error": "not_found",
  "message": "Applicant not found."
}

HTTP status	Error code	Meaning
200	—	Request successfully processed
400	`invalid_json`	The request body could not be decoded as JSON
400	`bad_request`	The request body failed validation
400	`missing_parameter` / `invalid_parameter`	A required query parameter is missing or invalid (read endpoints)
401	`unauthorized`	The authorization token is not valid
403	`forbidden`	Valid token, but your credential lacks the required scope
404	`not_found`	The requested resource could not be found
405	`method_not_allowed`	Wrong HTTP method for the endpoint
429	`too_many_requests`	Rate limit exceeded — back off and retry
500	`internal_error`	Unexpected server error

Next steps

Creating Applicants (POST /applicants) — for marketing and lead providers sending applicants into Double Nickel
Get Applicant API (GET /applicant) — retrieve an applicant's full profile
Documents API (GET /documents) — retrieve applicant documents with secure download URLs
Applicant Status Webhooks — real-time notifications on status changes

Questions or need help?

For common integration questions, see the API & Webhooks FAQ.

Contact the Double Nickel support team at [email protected].

Double Nickel API: Getting Started