Documents API: Retrieving Applicant Documents (GET /documents)

Overview

The Documents API lets partners securely retrieve the documents associated with an applicant — CDL licenses, consent forms, background reports, MVR, PSP, Clearinghouse queries, medical certificates, onboarding paperwork, and the applicant's completed, signed DOT application (category DOT_APP).

Partners typically call this API after receiving an Applicant Status Webhook (for example when an applicant is moved to onboarding or reaches HIRED) to download or sync documents into an internal system.

For authentication, environments, and error conventions shared by all endpoints, see "Double Nickel API: Getting Started & Creating Applicants". This endpoint requires the read:documents scope on your credential.

Endpoint

This endpoint uses the GET method with query-string parameters. (Earlier versions of this documentation showed POST /documents — the endpoint only accepts GET and responds 405 method_not_allowed to anything else.)

GET https://dashboard.getdoublenickel.com/api/documents?applicantId=<applicantId>&companyId=<companyId>&limit=20&offset=0

Query parameters

Name	Type	Required	Description
`applicantId`	string	Yes	Applicant ID received from a webhook or API (10–100 characters)
`companyId`	string	Yes	Your Double Nickel company identifier (10–100 characters)
`limit`	integer	No	Max records to return, 1–100. Default: 20
`offset`	integer	No	Starting index for pagination. Default: 0

Request headers

Header	Value
`Authorization`	`Bearer <access_token>`
`Auth-provider`	`auth0`
`Accept`	`application/json`

Successful response (200)

{
  "items": [
    {
      "documentId": "8c2d4f6a-1e3b-4d5c-9a7f-0b2e4c6d8f1a",
      "fileName": "CDL_License.pdf",
      "category": "CDL",
      "expirationDate": "2027-10-27T00:00:00.000Z",
      "createdAt": "2026-08-27T15:12:22.145Z",
      "updatedAt": "2026-08-27T15:15:32.145Z",
      "downloadUrl": "https://cdn.getdoublenickel.com/company/.../CDL_License.pdf?Expires=...&Signature=...&Key-Pair-Id=..."
    },
    {
      "documentId": "1e3b4d5c-9a7f-0b2e-4c6d-8f1a8c2d4f6a",
      "fileName": "MVR_Report.pdf",
      "category": "MVR",
      "expirationDate": null,
      "createdAt": "2026-08-26T09:41:03.812Z",
      "updatedAt": "2026-08-26T09:41:03.812Z",
      "downloadUrl": "https://cdn.getdoublenickel.com/company/.../MVR_Report.pdf?Expires=...&Signature=...&Key-Pair-Id=..."
    }
  ],
  "totalCount": 23,
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Field reference

Field	Type	Description
`items[].documentId`	string	Unique identifier for the document
`items[].fileName`	string	Original uploaded file name (may be an empty string)
`items[].category`	string	Document category — see the full list below
`items[].expirationDate`	ISO datetime or null	Null unless the document type has an expiration
`items[].createdAt`	ISO datetime	When the document was uploaded
`items[].updatedAt`	ISO datetime	Last update timestamp
`items[].downloadUrl`	string	Signed, time-limited URL for downloading the file. In rare cases where the underlying file is unavailable this is an empty string — skip those items and contact support.
`totalCount`	integer	Total number of documents for the applicant
`pagination.limit`	integer	Max documents returned in this page
`pagination.offset`	integer	Starting index of this page
`pagination.hasMore`	boolean	Whether additional pages are available

Results are sorted newest first (by createdAt descending). Only active documents are returned — archived and deleted documents are excluded.

Downloading files

The downloadUrl is a short-lived signed CloudFront URL:

URLs expire 5 minutes after the API response is generated.
They can be used directly in a browser or HTTP client — no additional authentication header is needed on the download request itself.
Do not store them long-term. Download promptly after fetching the list, and re-fetch the document list to get fresh URLs if they expire.

Document categories

The category field is always one of the values below. Categories shown under Settings → Document Templates in the dashboard only reflect the categories you have configured templates for — the API may return any value in this list.

Value	Description
`DOT_APP`	DOT employment application (including the completed, signed application PDF)
`MVR`	Motor Vehicle Record
`PSP`	Pre-employment Screening Program report
`BACKGROUND_CHECK`	Background check report
`CLEARING_HOUSE`	FMCSA Drug & Alcohol Clearinghouse query
`CDL`	Commercial Driver's License
`CDLIS`	Commercial Driver's License Information System record
`DOT_MEDICAL`	DOT medical card
`VERIFICATION_OF_EMPLOYMENT`	Verification of Employment (VOE)
`DRUG_AND_ALCOHOL_TESTING`	Drug and alcohol test results
`MEDICAL_EXAMINATION`	Medical examination report
`PAPERWORK`	General onboarding paperwork
`ORIENTATION`	Orientation documents
`HANDBOOK`	Employee handbook
`CONSENT`	Consent forms
`ROAD_TEST`	Road test certificate
`TWIC_CARD`	Transportation Worker Identification Credential
`VISA`	Visa documentation
`FAST`	Free and Secure Trade card
`GAFETE_UNICO`	Mexican Gafete Único
`GAFETE_ANAM`	ANAM (Mexican customs) credential
`INE`	Mexican INE identity card
`DAC`	DAC (HireRight) employment history report
`INSPECTION`	Vehicle or driver inspection record
`JOB_OFFER`	Job offer letter
`BENEFITS`	Benefits enrollment documents
`PAYROLL`	Payroll documents
`DISCIPLINARY`	Disciplinary action records
`TRAINING`	Training records or certificates
`EQUIPMENT`	Equipment assignment or acknowledgment
`OTHER`	Document that doesn't fit any other category

New category values are occasionally added as new document types are supported. Handle unknown values gracefully — for example by routing them to a default or OTHER bucket — rather than failing.

Error responses

HTTP status	Error code	Example message
400	`missing_parameter`	Applicant ID is required.
400	`invalid_parameter`	Limit must be between 1 and 100.
401	`unauthorized`	The authorization token is not valid.
403	`forbidden`	You do not have permission to access this resource. (missing `read:documents` scope)
404	`not_found`	Applicant not found.
405	`method_not_allowed`	Method POST not allowed. Only GET is supported.
500	`internal_error`	Error processing request.

Typical flow with webhooks

Receive an Applicant Status Webhook notification.
Extract applicantId and companyId from the payload.
Call GET /documents (paginating with limit/offset until hasMore is false).
Download the files you need via the signed URLs, promptly.
Store or process them internally.

Questions or need help?

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

Get Applicant API: Retrieving Applicant Details (GET /applicant)