Overview

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 https://prod.truv.com/v1/ base, regardless of the environment. Your Access secret determines the environment for each request.

Authentication

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

Value	Description	Example
`client_id`	Private identifier for your team	`dd21ca23c12142b6a0970b1e0afedf16`
`access_secret`	Private key, one for each of the three environments	`sandbox-a57b3109f1f4a8b3f2ebbc1c526950f1795464af`

Headers

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.

Protocols

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

Security

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.

❗
Warning
️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.

Errors

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.

Code	Title	Description
200	OK	Request successful
201	Created	Request successful and resource created
400	Bad Request	Request unacceptable
401	Unauthorized	Missing or invalid credentials
403	Forbidden	Permission denied
404	Not Found	Resource does not exist
405	Method Not Allowed	Request method not supported by target resource
406	Not Acceptable	Server cannot produce response matching list of acceptable values defined in request content negotiation headers
410	Gone	Bridge token expired
415	Unsupported Media Type	Unsupported request payload format
429	Too Many Requests	Request 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`.
50x	Internal server error	Error 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

Response
    application/json

    400 Bad request
    {
        "error":
        {
            "code": "validation_error",
            "message": "Validation error",
            "extra":
            {
                "invalid-params":
                [
                    {
                        "field": "first_name",
                        "message": "First name is required"
                    },
                    {
                        "field": "last_name",
                        "message": "Last name is required"
                    }
                ]
            }
        }
    }

Response
    application/json

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

Response
    application/json

    403 Forbidden
    {
        "error":
        {
            "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.