Setup Your Organization

This guide walks you through setting up your organizational structure in TreasuryPath by creating a company and its entity. This is the foundation for all financial operations in TreasuryPath.

What You'll Learn

How to create a company via the API
How to create an entity under your company
Understanding the company-entity relationship
Next steps after setting up your organization

Prerequisites

Before you begin, make sure you have:

✅ API credentials (API key and secret)
✅ A valid JWT token (see Authentication)
✅ Your company's basic information (name, country, currency)
✅ Your entity's basic information (name, country)

Understanding Companies and Entities

Company: The primary organizational container that represents your business. It holds: - Default currency and country settings - API access and permissions - Overall organizational configuration

Entity: An organizational unit within a company that can: - Hold bank accounts - Have financial connections - Process payments and transactions

One Entity Per Company

Currently, each company can have only one active entity. Attempting to create a second entity will result in an error.

Step 1: Create Your Company

First, create your company with its basic information.

Prepare Company Information

Field	Description	Example
Name	Legal or display name of your company	"Acme Corporation"
Default Currency	Primary currency for operations (ISO 4217 code)	"USD", "GBP", "EUR"
Country	Company's primary country (ISO 3166-1 alpha-2 code)	"US", "GB", "CA"

Create the Company

curl -X POST "https://api.treasurypath.com/api/v1/companies" \
  -H "Authorization: Bearer {your_jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "default_currency": "USD",
    "country": "US"
  }'

Success Response

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

Save Your Company ID

Copy and save the id field from the data object - you'll need this company_id for creating the entity and all future operations.

Step 2: Create Your Entity

Now create an entity under your newly created company.

Prepare Entity Information

Field	Description	Example
Name	Display name for this organizational unit	"Acme Corp US"
Country	Entity's country (ISO 3166-1 alpha-2 code)	"US", "GB", "CA"

Entity Country

The entity country doesn't have to match the company country. For example, a US company can have a UK entity for its European operations.

Create the Entity

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

Replace {company_id} with the ID you received when creating the company.

Success Response

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ",
    "name": "Acme Corp",
    "country_alpha2": "US",
    "company_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE",
    "created_at": "2025-11-17T10:35:00.000Z",
    "updated_at": "2025-11-17T10:35:00.000Z"
  }
}

Save Your Entity ID

Copy and save the entity id - you'll need this for connecting bank accounts and enabling features.

Step 3: Verify Your Setup

List Your Companies

Verify your company was created:

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

List Your Entities

Verify your entity was created:

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

Get Specific Company Details

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

Get Specific Entity Details

curl -X GET "https://api.treasurypath.com/api/v1/companies/{company_id}/entities/{entity_id}" \
  -H "Authorization: Bearer {your_jwt_token}"

Common Errors

Company Creation Errors

Missing Required Fields

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

Solution: Ensure all required fields (name, default_currency, country) are provided.

Invalid Currency Code

{
  "errors": [
    {
      "field": "default_currency",
      "message": "Invalid currency code"
    }
  ]
}

Solution: Use a valid ISO 4217 currency code. Common codes include: - USD - US Dollar - EUR - Euro - GBP - British Pound - CAD - Canadian Dollar - AUD - Australian Dollar

See the full list at ISO 4217.

Invalid Country Code

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

Solution: Use a valid ISO 3166-1 alpha-2 country code. Common codes include: - US - United States - GB - United Kingdom - CA - Canada - AU - Australia - DE - Germany

See the full list at ISO 3166-1.

Entity Creation Errors

Company Not Found

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

Solution: Verify you're using the correct company_id from Step 1. Ensure the company exists and you have access to it.

Entity Already Exists

{
  "errors": [
    {
      "field": "entity",
      "message": "Company already has an active entity"
    }
  ]
}

Solution: Each company can have only one active entity. If you need to modify the existing entity, use the update endpoint instead of creating a new one.

Missing Entity Name

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

Solution: Provide a name field in your request body.

Authentication Errors

Invalid or Expired Token

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

Solution: Ensure your JWT token is valid and included in the Authorization header. JWT tokens expire after 24 hours - generate a new one if needed using your API credentials.

What's Next?

Now that you've set up your organizational structure, you can:

Enable Multi-Currency Feature - Enable multi-currency support for cross-border payments
Connect Bank Accounts - Link your bank accounts to start processing payments
Add Recipients - Set up payment recipients
Make Your First Payment - Create and execute a payment

API Reference

For complete API documentation, see:

Companies API Reference - Full companies endpoint documentation
Entities API Reference - Full entities endpoint documentation
Company Data Model - Detailed company property descriptions
Entity Data Model - Detailed entity property descriptions
Authentication - How to get JWT tokens

Need Help?

Check the FAQ for common questions
Contact support at support@treasurypath.com