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

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.

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.