# API

# Authentication

Tratta API uses Access Tokens to authenticate requests. You can request this token by clicking here (opens new window) and filling out the form. Along with the access token, you'll also receive your organization's UUID, which is part of the endpoint.

Authentication to the API is performed via bearer auth included in the Authorization header of the HTTP request.

curl https://<org-uuid>.production.tratta.io/api/v1/transactions \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Environments

The Tratta API is available in production and sandbox environments. The sandbox environment can be used to test your integration. Separate API keys are available for each environment.

# Sandbox

Sandbox environment is available at

curl https://<org-uuid>.sandbox.tratta.io/api/v1

# Production

Production environment is available at

curl https://<org-uuid>.production.tratta.io/api/v1

# Rate Limiting

All requests to API are limited by default to 300 requests per minute. You can request to increase the quota by speaking with your Tratta point of contact.

If you reach the limit the api will respond with an 429 status response.

# Pagination

API results are paginated by default, with 10 records per page. You can adjust this number using the limit parameter.

# Parameters

limit optional

A limit on the number of records to be returned, between 1 and 500.

# Returns

Pagination can be found in the meta and links properties of the response. Paginated links preserve query parameters.

meta

from_submitted_date and to_submitted_date represent submitted_date for the first and last records in the returned page.

"meta" : {
  "from_submitted_date": '2020-10-10 10:30:00',
  "to_submitted_date": '2020:10-10 10:00:00',
  "from" : 1,
  "current_page" : 1,
  "total" : 2229980,
  "to" : 20,
  "last_page" : 111499,
  "per_page" : "20",
  "path" : "https://<org-uuid>.production.tratta.io/api/v1/transactions"
}

links

"links" : {
  "prev" : null,
  "next" : "https://<org-uuid>.production.tratta.io/api/v1/transactions?page=2&limit=10",
  "first" : "https://<org-uuid>.production.tratta.io/api/v1/transactions?page=1&limit=10",
  "last" : "https://<org-uuid>.production.tratta.io/api/v1/transactions?page=111499&limit=10"
}

# Requests

Body parameters in the documentation usually have validation rules or abbreviations associated with them.

# optional

The property must either be missing from the body payload or in a valid format specified by other validation rules.

# Response Codes

Tratta uses conventional HTTP response codes to indicate the success or failure of an API request. The table below contains a summary of the typical response codes:

# Success Response

Success response comes in the following format with 2XX HTTP status code

{
  "data": "array or object"
}

# Error Response

Error response comes in the following format with 4XX HTTP status code

{
  "error": "error message",
  "errorCode": "optional error code"
}

# Including Related Resources

If there's a relation between API resources, you can include the whole related resource object in response using include in query parameters.

For example

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/1234-5678 \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -d include="customer" \
 -G

{
  # debt account parameters
  "customer": "object",
}

If you want to include multiple related resources, you can delimit them with comma: ?include=customer,payments.