Entities API

The Entities API allows you to create, retrieve, update, list, and delete entity information. Entities are organizational units within a company that can hold bank accounts, have financial connections, and manage operations.

Endpoints

List Entities - GET /api/v1/companies/{company_id}/entities
Create Entity - POST /api/v1/companies/{company_id}/entities
Get Entity - GET /api/v1/companies/{company_id}/entities/{id}
Update Entity - PATCH /api/v1/companies/{company_id}/entities/{id}
Delete Entity - DELETE /api/v1/companies/{company_id}/entities/{id}

List Entities

Retrieve all entities for a specific company.

Endpoint

GET /api/v1/companies/{company_id}/entities

Headers

Authorization: Bearer {jwt_token}

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	ID of the company

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (default: 20, max: 100)

Example Request

curl -X GET "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities?page=1&per_page=20" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ",
      "name": "US Subsidiary",
      "country_alpha2": "US",
      "company_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
      "created_at": "2025-10-20T10:30:00.000Z",
      "updated_at": "2025-10-20T10:30:00.000Z"
    },
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMg",
      "name": "UK Branch",
      "country_alpha2": "GB",
      "company_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
      "created_at": "2025-10-19T14:20:00.000Z",
      "updated_at": "2025-10-20T09:15:00.000Z"
    }
  ],
  "meta": {
    "total_records": 2,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 20
  },
  "links": {
    "first": "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities?page=1&per_page=20",
    "prev": null,
    "next": null,
    "last": "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities?page=1&per_page=20"
  }
}

Error Responses

401 Unauthorized - Invalid Token

{
  "errors": [
    {
      "field": "token",
      "message": "Missing or invalid token"
    }
  ]
}

404 Not Found - Company Not Found

{
  "errors": [
    {
      "field": "company_id",
      "message": "Company not found or not accessible in this workspace"
    }
  ]
}

Create Entity

Create a new entity under a company.

Important Note: Companies can have only one active entity. If you attempt to create a second entity, you'll receive a 422 Unprocessable Entity error.

Endpoint

POST /api/v1/companies/{company_id}/entities

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	ID of the company

Request Body

{
  "name": "string",
  "country_alpha2": "string"
}

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Legal or display name of the entity
`country_alpha2`	string	Yes	ISO 3166-1 alpha-2 country code (e.g., US, GB, DE)

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Subsidiary",
    "country_alpha2": "US"
  }'

Success Response (201 Created)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ",
    "name": "US Subsidiary",
    "country_alpha2": "US",
    "company_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T10:30:00.000Z"
  }
}

Error Responses

400 Bad Request - Missing Name

{
  "errors": [
    {
      "field": "name",
      "message": "Entity name is required"
    }
  ]
}

400 Bad Request - Missing Country Alpha2

{
  "errors": [
    {
      "field": "country_alpha2",
      "message": "Country alpha2 code is required"
    }
  ]
}

400 Bad Request - Invalid Country Alpha2

{
  "errors": [
    {
      "field": "country_alpha2",
      "message": "Invalid country alpha2 code"
    }
  ]
}

404 Not Found - Company Not Found

{
  "errors": [
    {
      "field": "company_id",
      "message": "Company not found or not accessible in this workspace"
    }
  ]
}

422 Unprocessable Entity - Validation Error

{
  "errors": [
    {
      "field": "name",
      "message": "has already been taken"
    }
  ]
}

422 Unprocessable Entity - Company Already Has Entity

{
  "errors": [
    {
      "field": "base",
      "message": "This company already has an existing entity"
    }
  ]
}

Get Entity

Retrieve details of a specific entity.

Endpoint

GET /api/v1/companies/{company_id}/entities/{id}

Headers

Authorization: Bearer {jwt_token}

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	ID of the company
`id`	string	Yes	ID of the entity

Example Request

curl -X GET "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities/Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ",
    "name": "US Subsidiary",
    "country_alpha2": "US",
    "company_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T10:30:00.000Z"
  }
}

Error Responses

400 Bad Request - Missing Entity ID

{
  "errors": [
    {
      "field": "entity_id",
      "message": "Entity ID is required"
    }
  ]
}

404 Not Found - Entity Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Entity not found or not accessible in this company"
    }
  ]
}

404 Not Found - Company Not Found

{
  "errors": [
    {
      "field": "company_id",
      "message": "Company not found or not accessible in this workspace"
    }
  ]
}

Update Entity

Update an existing entity's information.

Important: Entities with an active payment integration cannot be updated. Updates are only allowed during the initial integration setup phase.

Endpoint

PATCH /api/v1/companies/{company_id}/entities/{id}

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	ID of the company
`id`	string	Yes	ID of the entity

Request Body

{
  "name": "string",
  "country_alpha2": "string"
}

Parameters

Parameter	Type	Required	Description
`name`	string	No	Legal or display name of the entity
`country_alpha2`	string	No	ISO 3166-1 alpha-2 country code (e.g., US, GB, DE)

Note: All parameters are optional. Only include the fields you want to update.

Example Request

curl -X PATCH "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities/Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "United States Subsidiary LLC"
  }'

Success Response (200 OK)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ",
    "name": "United States Subsidiary LLC",
    "country_alpha2": "US",
    "company_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T15:45:00.000Z"
  }
}

Error Responses

404 Not Found - Entity Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Entity not found or not accessible in this company"
    }
  ]
}

422 Unprocessable Entity - Validation Error

{
  "errors": [
    {
      "field": "name",
      "message": "can't be blank"
    }
  ]
}

403 Forbidden - Active Payment Integration

{
  "errors": [
    {
      "field": "base",
      "message": "Cannot update entity with active payment integration"
    }
  ]
}

Delete Entity

Delete an entity.

Important: Entities with an active payment integration cannot be deleted. Deletion is only allowed during the initial integration setup phase.

Endpoint

DELETE /api/v1/companies/{company_id}/entities/{id}

Headers

Authorization: Bearer {jwt_token}

Path Parameters

Parameter	Type	Required	Description
`company_id`	string	Yes	ID of the company
`id`	string	Yes	ID of the entity

Example Request

curl -X DELETE "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities/Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "message": "Entity deleted successfully"
}

Error Responses

404 Not Found - Entity Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Entity not found or not accessible in this company"
    }
  ]
}

403 Forbidden - Active Payment Integration

{
  "errors": [
    {
      "field": "base",
      "message": "Cannot delete entity with active payment integration"
    }
  ]
}

Data Types

Entity Object

Field	Type	Description
`id`	string	Unique identifier for the entity
`name`	string	Legal or display name of the entity
`country_alpha2`	string	ISO 3166-1 alpha-2 country code (e.g., "US", "GB")
`company_id`	string	ID of the company this entity belongs to
`created_at`	string	ISO 8601 timestamp when entity was created
`updated_at`	string	ISO 8601 timestamp when entity was last updated

Supported Countries

The country_alpha2 field in requests accepts ISO 3166-1 alpha-2 country codes. Common examples:

Code	Country
US	United States
GB	United Kingdom
CA	Canada
AU	Australia
DE	Germany
FR	France
JP	Japan
SG	Singapore

Pagination

All list endpoints support pagination with the following parameters:

Parameter	Type	Default	Description
`page`	integer	1	The page number to retrieve
`per_page`	integer	20	Number of items per page (max: 100)

The response includes:

meta: Pagination metadata (total records, pages, current page)
links: URLs for first, previous, next, and last pages

Rate Limiting

API requests are subject to 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."
    }
  ]
}

Idempotency

Entity creation and update operations are idempotent. If you retry a request with the same idempotency key, you'll receive the same response without creating duplicate entities.

Include an Idempotency-Key header:

curl -X POST "https://api.treasurypath.com/api/v1/companies/{company_id}/entities" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{
    "name": "US Subsidiary",
    "country_alpha2": "US"
  }'

Webhooks

Entity operations trigger webhook events when you have webhooks configured:

Event	Triggered When
`entity.created`	A new entity is created
`entity.updated`	An entity is updated
`entity.deleted`	An entity is deleted

See the Webhooks Guide for more information.

Companies API - Manage parent companies
Bank Accounts API - Manage entity bank accounts
Setup Your Organization - Guide to creating companies and entities

Entities API

Endpoints

List Entities

Endpoint

Headers

Path Parameters

Query Parameters

Example Request

Success Response (200 OK)

Error Responses

401 Unauthorized - Invalid Token

404 Not Found - Company Not Found

Create Entity

Endpoint

Headers

Path Parameters

Request Body

Parameters

Example Request

Success Response (201 Created)

Error Responses

400 Bad Request - Missing Name

400 Bad Request - Missing Country Alpha2

400 Bad Request - Invalid Country Alpha2

404 Not Found - Company Not Found

422 Unprocessable Entity - Validation Error

422 Unprocessable Entity - Company Already Has Entity

Get Entity

Endpoint

Headers

Path Parameters

Example Request

Success Response (200 OK)

Error Responses

400 Bad Request - Missing Entity ID

404 Not Found - Entity Not Found

404 Not Found - Company Not Found

Update Entity

Endpoint

Headers

Path Parameters

Request Body

Parameters

Example Request

Success Response (200 OK)

Error Responses

404 Not Found - Entity Not Found

422 Unprocessable Entity - Validation Error

403 Forbidden - Active Payment Integration

Delete Entity

Endpoint

Headers

Path Parameters

Example Request

Success Response (200 OK)

Error Responses

404 Not Found - Entity Not Found

403 Forbidden - Active Payment Integration

Data Types

Entity Object

Supported Countries

Pagination

Rate Limiting

Idempotency

Webhooks

Related Resources