Skip to content

API Basics

This guide covers the fundamental concepts you need to understand when working with the TreasuryPath API.

Authentication

The TreasuryPath API uses JWT (JSON Web Token) authentication. To authenticate:

  1. Obtain API Credentials: Get your API key and secret from your TreasuryPath account
  2. Get JWT Token: Exchange credentials for a JWT token via the sessions endpoint
  3. Use Token: Include the JWT token in the Authorization header for all requests

Authentication Header:

Authorization: Bearer {jwt_token}

For detailed authentication steps and examples, see the Authentication Guide.

Response Format

All API responses follow a consistent JSON structure to make integration predictable and easy to parse.

Success Response

Successful requests return a data object containing the requested resource(s):

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
    "name": "Acme Corporation",
    "country": "US",
    …
  }
}

For list endpoints, data contains an array of resources:

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
      "name": "Acme Corporation",
      …
    },
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzI",
      "name": "Beta Industries",
      …
    }
  ]
}

Error Response

When an error occurs, the API returns a structured error response:

{
  "errors": [
    {
      "field": "amount_cents",
      "message": "must be greater than 0"
    }
  ]
}

Error Response Fields:

  • errors: Array of error objects
  • field: The field or context related to the error
  • message: Human-readable error description

Pagination

List endpoints that return multiple resources include pagination information to help you navigate through large result sets.

Paginated Response Structure

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC82NA",
      "currency": "USD",
      "owner_type": "Entity",
      …
    },
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC82NQ",
      "currency": "USD",
      "owner_type": "Entity",
      …
    },
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC82Ng",
      "currency": "USD",
      "owner_type": "Counterparty",
      …
    }
  ],
  "meta": {
    "total_records": 3,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 20
  },
  "links": {
    "first": "https://api.treasurypath.com/api/v1/companies/{company_id}/bank_accounts?page=1&per_page=20",
    "prev": null,
    "next": null,
    "last": "https://api.treasurypath.com/api/v1/companies/{company_id}/bank_accounts?page=1&per_page=20"
  }
}

Pagination Fields

Meta Object:

  • total_records: Total number of resources across all pages
  • total_pages: Total number of pages available
  • current_page: Current page number (1-indexed)
  • per_page: Number of resources per page

Links Object:

  • first: URL to the first page
  • prev: URL to the previous page (null if on first page)
  • next: URL to the next page (null if on last page)
  • last: URL to the last page

Pagination Query Parameters

Control pagination using URL query parameters:

GET /api/v1/companies/{company_id}/bank_accounts?page=2&per_page=50

Parameters:

  • page: Page number to retrieve (default: 1)
  • per_page: Number of results per page

Navigating Pages:

  • Use the URLs provided in the links object for automatic pagination handling
  • Manually construct URLs with page and per_page parameters for custom control

Best Practices

  • Use Appropriate Page Sizes: Request only what you need. Smaller pages mean faster responses.
  • Follow Link URLs: Use the provided links object URLs rather than constructing your own.
  • Check for Next Page: Always check if links.next exists before fetching more results.
  • Cache Results: Cache paginated data when appropriate to reduce API calls.
  • Handle Empty Results: Check if data is empty or total_records is 0 before processing.

HTTP Status Codes

The TreasuryPath API uses standard HTTP status codes to indicate the success or failure of requests.

Success Codes

Code Status Description
200 OK Request succeeded, resource returned
201 Created Resource successfully created
204 No Content Request succeeded, no response body (e.g., DELETE)

Client Error Codes

Code Status Description
400 Bad Request Invalid request format or malformed JSON
401 Unauthorized Missing or invalid authentication credentials
403 Forbidden Valid credentials but insufficient permissions
404 Not Found Resource does not exist
422 Unprocessable Entity Validation failed
429 Too Many Requests Rate limit exceeded

Server Error Codes

Code Status Description
500 Internal Server Error Unexpected server error occurred

Best Practice: Always check the HTTP status code first, then parse the response body for details.

Rate Limiting

To ensure service stability, the TreasuryPath API implements rate limiting. If you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "errors": [
    {
      "field": "base",
      "message": "Rate limit exceeded. Please try again later."
    }
  ]
}

Recommended Approach:

  • Implement exponential backoff when receiving 429 responses
  • Cache frequently accessed data to reduce API calls
  • Monitor your request patterns to stay within limits

Core Resources

Resource Description
/companies Manage top-level company entities
/entities Manage organizational units within companies
/recipients Manage payment recipients
/bank_accounts View bank account details and payment profiles
/payments Create and manage payment instructions
/quotes Get payment quotes for transactions
/webhooks Configure webhook endpoints for events

Resource Hierarchy

TreasuryPath follows a logical resource hierarchy:

Company
  ├── Entity
  │    └── Bank Accounts
  │         └── Payment Profiles
  └── Recipients
       └── Bank Accounts
            └── Payment Profiles

All API endpoints follow this hierarchy in their URL structure:

/companies/{company_id}/entities/{entity_id}/...
/companies/{company_id}/recipients/{recipient_id}/...

Next Steps