Welcome to Truv’s API developer documentation! Here you'll find everything you need to integrate with Truv.


This documentation covers API Reference sections and pages with details and descriptions.

For questions, email [email protected] or chat with us in the Dashboard.

Supported environments

Truv supports the following three environments. Use the options below to learn more about how Truv integrations work for your customers.

  • Sandbox - For general development, gives access to predefined sample data from payroll providers
  • Development - For testing integrations with live credentials, NOTE: The number of successful Tasks is limited to 50 and not billed.
  • Production - For your production environment, NOTE: Each successful Task is billed.

All API requests use the base, regardless of the environment. Your Access secret determines the environment for each request.


The Truv API requires valid credentials to authenticate. Each call uses API Keys, consisting of the Client ID and Access secret values.

For all three environments, the Client ID value is the same. However, the Access secret value is different for the three environments. View the prefixes below for the Access secret. The table also provides examples for the values.

  • sandbox, dev, prod
client_idPrivate identifier for your teamdd21ca23c12142b6a0970b1e0afedf16
access_secretPrivate key, one for each of the three environmentssandbox-a57b3109f1f4a8b3f2ebbc1c526950f1795464af


Every API request requires both X-Access-Client-ID and X-Access-Secret header values. These two contain the Client ID and the Access secret, respectively.


API keys allow access to sensitive data, so make sure to keep them secure!

Keep the Client ID and Access secret values safe and protected. Store these values in a secure location within your application.


Truv protocols use REST API frameworks. This leverages HTTP requests for communication and response codes for sharing statuses and errors. View the points below for additional information.

  • Responses are in standard JSON
  • Uses HTTPS TLS v1.2+, NOTE: HTTP and HTTPS with TLS versions below 1.2 are not supported.
  • Requests must include Content-Type of application/json, only valid JSON in request body


Manage identifier values from Truv Bridge and API endpoints to maximize security and safety. Truv identifier values allow you to associate API and provider events with your requests.

If contacting the support team, include these values for streamlined solutions.


️Confirm all access_token values are never exposed on the client-side. Store these tokens securely on the backend and associate them with users of your application.

Additional access tokens

Users can create multiple access_tokens if they have accounts with multiple data providers and Links.


Truv API responses use standard HTTP status codes. View the points below for additional patterns.

  • 2xx - Successful requests
  • 4xx - Invalid inputs or invalid actions in the current state
  • 5xx - Rare error on Truv's servers

HTTP responses

The table below covers responses code values and descriptions.

200OKRequest successful
201CreatedRequest successful and resource created
400Bad RequestRequest unacceptable
401UnauthorizedMissing or invalid credentials
403ForbiddenPermission denied
404Not FoundResource does not exist
405Method Not AllowedRequest method not supported by target resource
406Not AcceptableServer cannot produce response matching list of acceptable values defined in request content negotiation headers
410GoneBridge token expired
415Unsupported Media TypeUnsupported request payload format
429Too Many RequestsRequest limit exceeded in given period of time, NOTE: access_token limit only allows an initial request and three refresh requests in a 24-hour period, error results in Refresh limit for the access_token exceeded.
50xInternal server errorError occurred with our API

Error message format

The response body contains the following fields.

  • code - Passes the source of the error
  • message - Communicates issue to the end-user
  • invalid-params - List of form fields and related errors to display to the end user, field parameter indicates form field error in UI

    400 Bad request
            "code": "validation_error",
            "message": "Validation error",
                        "field": "first_name",
                        "message": "First name is required"
                        "field": "last_name",
                        "message": "Last name is required"

    401 Unauthorized
            "code": "expired_token",
            "message": "Public token expired: 48427a36d43c4d5aa6324bc06c692456"

    403 Forbidden
            "code": "incorrect_token",
            "message": "Token is invalid"

Error codes

View more information about the error codes below.

  • validation_error- Any type of invalid input to the API, includes incorrect data format or missing fields
  • expired_token- For a public token expired after 6 hours
  • incorrect_token - Any public or access token cannot be matched with internal storage

Rate limiting

Rate limits safeguard our API's stability. Our rate limiter allows up to 300 requests per minute per Access secret key. For inquiries to increase this limit, contact us.

Requests over the limit return a 429 Too Many Requests error.