Welcome to Truv’s API developer documentation! Here you'll find everything you need to integrate with Truv. If you have any questions, email [email protected] or chat with us in the Dashboard.

We support three environments:

Sandbox is used for general development. It gives you access to predefined sample data so you can understand exactly what data you'll get back from payroll providers.
Development is used to test your integration with live credentials. The number of successful Tasks here is limited to 50 and not billed.
Production is used for your production environment; each successful Task is billed.

All API requests should be made to https://prod.truv.com/v1/ regardless of your environment. Your Access secret determines which environment your calls will use.

Authentication

Every call to the Truv API requires you to use your API keys, which consist of a Client ID and an Access secret. Your Client ID will remain the same regardless of your environment, but you will get a different Access key for each environment. Each key is prefixed with sandbox, dev, or prod so you know which one to use.

All API requests require the X-Access-Client-Id and X-Access-Secret headers which should contain your Client ID and Access secret respectively.

Your API keys carry many privileges, so make sure to keep them secure! Don't share your Client ID or Access secret with anyone and never use your API keys in the front end of your application.

Protocols

Truv uses a REST API framework that leverages HTTP requests to communicate and HTTP response codes to indicate statuses and errors.
All responses come in standard JSON format.
Truv's API is served over HTTPS TLS v1.2+ to ensure data privacy; HTTP and HTTPS with TLS versions below 1.2 are not supported.
All requests must include a Content-Type of application/json and the body must be valid JSON.

Security

It’s critical to properly handle identifiers returned by Bridge and direct API endpoints.

Truv's identifiers let you associate API and Provider events with your requests, and will help our support team resolve your support issues faster.

❗
️Make sure access_token is never exposed on the client-side. You should store these tokens securely on the backend and associate them with users of your application.

🚧
User can create multiple access_tokens if they have accounts with multiple data providers.

Errors

Our API responses use standard HTTP status codes:

2xx status codes indicate success
4xx status codes indicate invalid input or invalid action in the current state
5xx status codes indicate a rare error on Truv's servers

HTTP Responses

Code	Title	Description
200	OK	The request was successful.
201	Created	The request was successful and a resource was created.
400	Bad Request	The request was unacceptable.
401	Unauthorized	Missing or invalid credentials.
403	Forbidden	Permission denied.
404	Not Found	The resource does not exist.
405	Method Not Allowed	The request method is known by the server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request's content negotiation headers.
410	Gone	Bridge token is expired.
415	Unsupported Media Type	The request's payload format is in an unsupported format.
429	Too Many Requests	Too many requests have been sent in a given period of time. Note: There is a per access_token limit that will allow an initial request and 3 refreshed in a 24-hour period. If exceeded, you will receive a error: "Refresh limit for the access_token exceeded".
50X	Internal Server Error	An error occurred with our API.

Error message format

The response body contains the following fields:

code is used to pass the source of the error.
message is used to communicate what went wrong to the end-user.
invalid-params is a list of form fields and related errors to display to the end user. field parameter indicates UI where the form field error occurred.

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

validation_error: any type of erroneous input to the API, including incorrect data format or missing fields.
expired_token: used when a public token expires after 6 hours.
incorrect_token: used when any token (public or access) cannot be matched with internal storage.

Rate Limiting

We use rate limiting to safeguard the stability of our API. Our rate limiter allows up to 300 requests per minute per access_secret key. To increase this limit, please contact us.

Any request over the limit will return a 429 Too Many Requests error.