Companies API

The Companies API allows you to create, retrieve, update, list, and delete company information. Companies are the primary organizational entities in TreasuryPath that hold bank accounts, payment profiles, and other financial resources.

Endpoints

List Companies - GET /api/v1/companies
Create Company - POST /api/v1/companies
Get Company - GET /api/v1/companies/{id}
Update Company - PATCH /api/v1/companies/{id}
Delete Company - DELETE /api/v1/companies/{id}

List Companies

Retrieve all companies in your workspace.

Endpoint

GET /api/v1/companies

Headers

Authorization: Bearer {jwt_token}

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?page=1&per_page=20" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
      "name": "Acme Corporation",
      "country": "US",
      "default_currency": "USD",
      "created_at": "2025-10-20T10:30:00.000Z",
      "updated_at": "2025-10-20T10:30:00.000Z"
    },
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzI",
      "name": "TechStart Inc",
      "country": "GB",
      "default_currency": "GBP",
      "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?page=1&per_page=20",
    "prev": null,
    "next": null,
    "last": "https://api.treasurypath.com/api/v1/companies?page=1&per_page=20"
  }
}

Error Responses

401 Unauthorized - Invalid Token

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

Create Company

Create a new company in your workspace. The company will be created with the api_client role, indicating it was created via the API.

Endpoint

POST /api/v1/companies

Headers

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

Request Body

{
  "name": "string",
  "default_currency": "string",
  "country": "string"
}

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Legal or display name of the company
`default_currency`	string	Yes	ISO 4217 currency code (e.g., USD, EUR, GBP)
`country`	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" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "default_currency": "USD",
    "country": "US"
  }'

Success Response (201 Created)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
    "name": "Acme Corporation",
    "country": "US",
    "default_currency": "USD",
    "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": "Company name is required"
    }
  ]
}

400 Bad Request - Missing Default Currency

{
  "errors": [
    {
      "field": "default_currency",
      "message": "Default currency is required"
    }
  ]
}

422 Unprocessable Entity - Validation Error

{
  "errors": [
    {
      "field": "default_currency",
      "message": "must be a valid ISO currency code"
    }
  ]
}

Get Company

Retrieve details of a specific company by ID.

Endpoint

GET /api/v1/companies/{id}

Headers

Authorization: Bearer {jwt_token}

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The ID of the company to retrieve

Example Request

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

Success Response (200 OK)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
    "name": "Acme Corporation",
    "country": "US",
    "default_currency": "USD",
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T10:30:00.000Z"
  }
}

Error Responses

404 Not Found - Company Not Found

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

Update Company

Update details of an existing company.

Important: Companies cannot be updated once the Airwallex payment integration is fully completed. During the initial integration setup phase, updates are allowed. This restriction protects financial data integrity and prevents issues with historical records and currency conversions.

Endpoint

PATCH /api/v1/companies/{id}

Headers

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

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The ID of the company to update

Request Body

{
  "name": "string",
  "country": "string",
  "default_currency": "string"
}

Parameters

Parameter	Type	Required	Description
`name`	string	No	Updated company name
`country`	string	No	Updated ISO 3166-1 alpha-2 country code
`default_currency`	string	No	Updated ISO 4217 currency code

Note: You only need to include the fields you want to update. All updates are blocked once the Airwallex payment integration is fully completed.

Example Request

curl -X PATCH "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation Ltd"
  }'

Success Response (200 OK)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
    "name": "Acme Corporation Ltd",
    "country": "US",
    "default_currency": "USD",
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T11:45:00.000Z"
  }
}

Error Responses

403 Forbidden - Active Payment Integration

When attempting to update a company with a completed Airwallex integration:

{
  "errors": [
    {
      "field": "base",
      "message": "Company cannot be updated once it has active payment integrations"
    }
  ]
}

Note: This error occurs when the Airwallex payment integration has been fully completed and is now active.

404 Not Found - Company Not Found

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

422 Unprocessable Entity - Validation Error

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

Delete Company

Delete a company. The company will be soft deleted and excluded from list operations.

Important: - Only companies created via the API can be deleted - Companies cannot be deleted once the Airwallex payment integration is fully completed. During the initial integration setup phase, deletion is allowed.

Endpoint

DELETE /api/v1/companies/{id}

Headers

Authorization: Bearer {jwt_token}

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The ID of the company to delete

Example Request

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

Success Response (200 OK)

{
  "message": "Company deleted successfully"
}

Error Responses

403 Forbidden - Not API Created

When attempting to delete a company that was not created via API:

{
  "errors": [
    {
      "field": "base",
      "message": "This company cannot be deleted. Only companies created via API are eligible for deletion"
    }
  ]
}

403 Forbidden - Active Payment Integration

When attempting to delete a company with a completed Airwallex integration:

{
  "errors": [
    {
      "field": "base",
      "message": "Company cannot be deleted once it has active payment integrations"
    }
  ]
}

Note: This error occurs when the Airwallex payment integration has been fully completed and is now active. Companies that are still in the initial integration setup phase can still be deleted.

404 Not Found - Company Not Found

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

422 Unprocessable Entity - Failed to Delete

{
  "errors": [
    {
      "field": "base",
      "message": "Failed to delete company"
    }
  ]
}

Company Object

Attributes

Attribute	Type	Description
`id`	string	Unique identifier for the company
`name`	string	Legal or display name of the company
`country`	string	ISO 3166-1 alpha-2 country code
`default_currency`	string	ISO 4217 currency code for the company's default currency
`created_at`	string	ISO 8601 timestamp when the company was created
`updated_at`	string	ISO 8601 timestamp when the company was last updated

Notes

Pagination

The list endpoint supports pagination to efficiently handle large numbers of companies: - Default page size: 20 companies - Maximum page size: 100 companies - Use page and per_page query parameters to control pagination

Soft Delete

The delete operation performs a soft delete rather than permanently removing the company: - Deleted companies are excluded from list operations by default - Deleted companies can still be retrieved by ID if needed

Currency Codes

The default_currency field must be a valid ISO 4217 currency code. Common examples: - USD - United States Dollar - EUR - Euro - GBP - British Pound Sterling - CAD - Canadian Dollar - AUD - Australian Dollar

Country Codes

The country field uses ISO 3166-1 alpha-2 country codes. Common examples: - US - United States - GB - United Kingdom - DE - Germany - CA - Canada - AU - Australia

Using Company IDs

The company ID returned from the create endpoint should be used in subsequent API calls. For example: - To create payments: POST /api/v1/companies/{company_id}/payments - To list bank accounts: GET /api/v1/companies/{company_id}/bank_accounts - To manage webhooks: GET /api/v1/companies/{company_id}/webhook_endpoints

Rate Limiting

API requests are rate limited per API key and workspace. If you exceed the rate limit, you will receive a 429 Too Many Requests response.