Revision History

Version Description Date By
1.0 (latest) Added /POST applicants API documentation 02/01/2024 @Anonymous

Introduction

Welcome to Double Nickel’s API documentation! This document is designed to provide external integration partners with comprehensive guidelines on interacting with our RESTful API.

Our API aims to simplify the applicant management process, enabling partners to effectively create an applicant under their client’s company data.

Audience

This document, intended for developers familiar with RESTful APIs, HTTP methods, and JSON formats, outlines the initial capability to create applicant records, setting the stage for future updates and expansions.

Endpoints

Double Nickel offers two distinct environments for submitting requests:

The specific URLs for submitting requests to these environments are as follows:

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

<aside> ❗ Given that Testing environment serves for development and testing, its availability for testing might occasionally be interrupted. It could be temporarily offline for updates, typically lasting no longer than 15 minutes. For testing purposes, it’s advisable to inform Double Nickel team in advance to guarantee the environment’s availability during your testing period.

</aside>

Authentication | Authorization

Fields

To authenticate your request, you must supply a valid token in the Authorization header of your HTTPS request. Please review the following information for a description of how to use the token for authentication per endpoints.

Node Data Type Required Description
client_id String Required Provided by Double Nickel.
client_secret String Required Provided by Double Nickel.
audience String Required Provided by Double Nickel.

<aside> ❗ To interact with the Double Nickel API, it's essential to obtain an integration credentials per environment beforehand for authentication and authorization. Please make sure to secure your security token before initiating the development process. Double Nickel team will provide client_id, client_secret and audience fields

</aside>

<aside> ❗ The credentials referenced above are environment-specific rather than client-specific. As an agency, you'll be provided with a dedicated set of credentials to generate tokens, which can be reused across multiple clients. The only client-specific elements will be included within the API request payload itself.

</aside>

<aside> ⛔ Access tokens remain valid for a period of 24 hours. To optimize usage, it's essential to cache and reuse an existing access token until it expires, rather than obtaining a new one with every single request. Failing to adhere to this practice may result in Double Nickel revoking your access privileges.

</aside>

Request

Auth token environment:

Environment Auth Token URL
Testing https://double-nickel-test.us.auth0.com/oauth/token
Production https://double-nickel.us.auth0.com/oauth/token

Response

{
  "access_token": "XXXXXXXXXX",
  "token_type": "Bearer"
	"expires_in": 86400
}

Sending the token to the API

curl --request POST \\
  --url <https://dashboard.getdoublenickel.com/api/> \\
  --header 'authorization: Bearer <access_token here>'
  --header 'auth-provider: auth0'

Status Codes

HTTP response codes are used to indicate general classes of success and error.

Success Codes

HTTP Status Description
200 OK - Request successfully processed.

Error Codes

Error responses contain more detail about the error in the response body, in the "code" and "message"properties.

HTTP Status Code Message
400 invalid_json The request body could not be decoded as JSON.
bad_request This request is not supported.
401 unauthorized The authorization token is not valid.
403 forbidden The request was valid but you don't have permissions to perform the action.
404 not_found The requested resource could not be found.
429 too_many_requests Too many requests hit the API too quickly. We recommend implementing exponential backoff.
500 internal_error A generic error message for an unexpected condition encountered by the server.

Rate Limiting

Rate-limited requests will return a "too_many_requests" error code (HTTP response status 429). The rate limit for incoming requests per integration is an average of 5 requests per second. Some bursts beyond the average rate are allowed.

<aside> ❗ Rate limits may change

In the future, we plan to adjust rate limits to balance for demand and reliability.

</aside>

API

POST /applicants

Request

Payload

Field Type Required? Description Limits Example
firstName String Yes Applicant’s first name Up to 100 characters "John"
middleName String No Applicant’s middle name Up to 100 characters "Alexander"
lastName String Yes Applicant’s last name Up to 100 characters "Doe"
phone String Yes Applicant’s phone number, including country code Must be a valid phone number "+12345678901"
email String Yes Applicant’s email address Must be a valid email address "[email protected]"
cdlExperience Float (Number, integer) No Applicant’s CDL experience in years Must be a number 5.5
zipCode String No Applicant’s zip code Must be a valid zipcode 5 characters "11201"
trackingLinkId String Yes A unique identifier provided to track the source or campaign of the applicant - This value will be provided by Double Nickel team Up to 100 characters "983ABad3fc-6fd7-4535-a1d9-2191e6104714"
companyId String Yes A unique identifier provided to track the source or campaign of the applicant - This value will be provided by Double Nickel team "983ABad3fc-6fd7-4535-a1d9-2191e6104714"

Response

Field Type Required? Description Example
applicantId String Yes A unique identifier provided for the applicant "983ad3fc-6fd7-4535-a1d9-2191e6104714"

Example - Curl

Questions or need help?

If you have any questions or need further help with the API, please don't hesitate to reach out to the Double Nickel support team. We're here to help you make the most of our services. You can contact us via: