Recipients API

The Recipients API allows you to manage recipient records and their associated bank accounts. Recipients represent entities that receive payments from your company.

Endpoints

List Recipients - GET /api/v1/companies/{company_id}/recipients
Get Recipient - GET /api/v1/companies/{company_id}/recipients/{id}
Create Recipient - POST /api/v1/companies/{company_id}/recipients
Delete Recipient - DELETE /api/v1/companies/{company_id}/recipients/{id}
Generate Bank Account Token - POST /api/v1/companies/{company_id}/entities/{entity_id}/hosted_page_tokens

List Recipients

Retrieve all active recipients for a company, including their associated bank accounts and payment profiles.

Endpoint

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

Headers

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

Path Parameters

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

Example Request

curl -X GET "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vYXBwL0NvbXBhbnkvMQ/recipients" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
      "name": "Acme Supplies Inc.",
      "email": "accounts@acmesupplies.com",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "bank_accounts": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC8xMjM",
          "current_balance": "0.0",
          "currency": "USD",
          "last_synced_at": null,
          "owner_type": "Counterparty",
          "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
          "created_at": "2025-01-15T11:00:00Z",
          "updated_at": "2025-01-15T11:00:00Z",
          "account_details": [
            {
              "id": "Z2lkOi8vd2FsbGV0LWFwcC9BY2NvdW50RGV0YWlsLzE",
              "account_number_mask": "************0000",
              "account_number_type": "other",
              "created_at": "2025-01-15T11:00:00Z",
              "updated_at": "2025-01-15T11:00:00Z"
            }
          ],
          "routing_details": [
            {
              "id": "Z2lkOi8vd2FsbGV0LWFwcC9Sb3V0aW5nRGV0YWlsLzE",
              "routing_number": "011401533",
              "routing_number_type": "aba",
              "bank_name": "Chase Bank",
              "payment_method": "ach",
              "created_at": "2025-01-15T11:00:00Z",
              "updated_at": "2025-01-15T11:00:00Z"
            }
          ],
          "party_address": null,
          "payment_profiles": [
            {
              "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
              "status": "active",
              "payment_method": "ach",
              "currency": "USD",
              "usage_type": "credit",
              "created_at": "2025-01-15T11:00:00Z",
              "updated_at": "2025-01-15T11:00:00Z"
            }
          ]
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Global ID of the recipient
`name`	string	Recipient's name
`email`	string	Recipient's email address (optional)
`created_at`	string	ISO 8601 timestamp of creation
`updated_at`	string	ISO 8601 timestamp of last update
`bank_accounts`	array	Array of bank account objects associated with this recipient

Bank Account Fields

Field	Type	Description
`id`	string	Global ID of the bank account
`current_balance`	string	Current balance as decimal string
`currency`	string	ISO 4217 currency code
`last_synced_at`	string	ISO 8601 timestamp of last sync (null if never synced)
`owner_type`	string	Type of the account owner (e.g., "Counterparty")
`owner_id`	string	Global ID of the account owner
`account_details`	array	Array of account detail objects
`routing_details`	array	Array of routing detail objects
`party_address`	object	Address information (null if not set)
`payment_profiles`	array	Array of payment profile objects

Account Detail Fields

Field	Type	Description
`id`	string	Global ID of the account detail
`account_number_mask`	string	Masked account number (e.g., "**0000")
`account_number_type`	string	Account number type (e.g., "other", "iban")

Routing Detail Fields

Field	Type	Description
`id`	string	Global ID of the routing detail
`routing_number`	string	Routing number for the payment method
`routing_number_type`	string	Type of routing number (e.g., "aba", "swift")
`bank_name`	string	Name of the bank
`payment_method`	string	Payment method for this routing (e.g., "ach", "swift")

Payment Profile Fields

Field	Type	Description
`id`	string	Global ID of the payment profile
`status`	string	Profile status (active, inactive, draft, failed)
`payment_method`	string	Payment method (ach, swift, sepa, etc.)
`currency`	string	ISO 4217 currency code
`usage_type`	string	Usage type (credit, debit, balance)

Error Responses

401 Unauthorized

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

404 Not Found - Company Not Found

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

Get Recipient

Retrieve detailed information about a specific recipient, including all associated bank accounts and payment profiles.

Endpoint

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

Headers

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

Path Parameters

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

Example Request

curl -X GET "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vYXBwL0NvbXBhbnkvMQ/recipients/Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json"

Success Response (200 OK)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
    "name": "Acme Supplies Inc.",
    "email": "accounts@acmesupplies.com",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "bank_accounts": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC8xMjM",
        "current_balance": "0.0",
        "currency": "USD",
        "last_synced_at": null,
        "owner_type": "Counterparty",
        "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
        "created_at": "2025-01-15T11:00:00Z",
        "updated_at": "2025-01-15T11:00:00Z",
        "account_details": [
          {
            "id": "Z2lkOi8vd2FsbGV0LWFwcC9BY2NvdW50RGV0YWlsLzE",
            "account_number_mask": "************0000",
            "account_number_type": "other",
            "created_at": "2025-01-15T11:00:00Z",
            "updated_at": "2025-01-15T11:00:00Z"
          }
        ],
        "routing_details": [
          {
            "id": "Z2lkOi8vd2FsbGV0LWFwcC9Sb3V0aW5nRGV0YWlsLzE",
            "routing_number": "011401533",
            "routing_number_type": "aba",
            "bank_name": "Chase Bank",
            "payment_method": "ach",
            "created_at": "2025-01-15T11:00:00Z",
            "updated_at": "2025-01-15T11:00:00Z"
          }
        ],
        "party_address": null,
        "payment_profiles": [
          {
            "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
            "status": "active",
            "payment_method": "ach",
            "currency": "USD",
            "usage_type": "credit",
            "created_at": "2025-01-15T11:00:00Z",
            "updated_at": "2025-01-15T11:00:00Z"
          }
        ]
      }
    ]
  }
}

Error Responses

401 Unauthorized

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

404 Not Found - Recipient Not Found

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

Note: This error is also returned if the recipient has been deleted or belongs to a different company.

Create Recipient

Create a new recipient record for your company.

Endpoint

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

Headers

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

Path Parameters

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

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Recipient's name
`email`	string	No	Recipient's email address

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vYXBwL0NvbXBhbnkvMQ/recipients" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Supplies Inc.",
    "email": "accounts@acmesupplies.com"
  }'

Success Response (201 Created)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
    "name": "Acme Supplies Inc.",
    "email": "accounts@acmesupplies.com",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "bank_accounts": []
  }
}

Error Responses

400 Bad Request - Missing Name

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

400 Bad Request - Blank Name

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

401 Unauthorized

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

404 Not Found - Company Not Found

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

Delete Recipient

Delete a recipient. The recipient will be marked as deleted and will no longer appear in recipient lists or be available for new payments. Historical payment data is preserved.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}

Path Parameters

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

Example Request

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

Success Response (204 No Content)

No response body. The recipient has been successfully deleted.

Error Responses

401 Unauthorized

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

404 Not Found - Recipient Not Found

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

Note: This error is also returned if: - The recipient has already been deleted - The recipient belongs to a different company - The recipient ID is invalid

Generate Bank Account Token

Generate a secure, time-limited token that allows a recipient to add their bank account information through TreasuryPath's hosted page.

Endpoint

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

Headers

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

Path Parameters

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

Request Body

Parameter	Type	Required	Description
`purpose`	string	Yes	Must be "recipient_add_bank_account"
`recipient_id`	string	Yes	Global ID of the recipient

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vYXBwL0NvbXBhbnkvMQ/entities/Z2lkOi8vYXBwL0VudGl0eS8x/hosted_page_tokens" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "recipient_add_bank_account",
    "recipient_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ"
  }'

Success Response (201 Created)

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJjb21wYW55X2lkIjoiWjJsa09pOHZZWEJ3TDBOdmJYQmhibmt2TVEiLCJlbnRpdHlfaWQiOiJaMmxrT2k4dllYQndMMFZ1ZEdsMGVTOHgiLCJyZWNpcGllbnRfaWQiOiJaMmxrT2k4dmQyRnNiR1YwTFdGd2NDOURiM1Z1ZEdWeWNHRnlkSGt2TVEiLCJwdXJwb3NlIjoicmVjaXBpZW50X2FkZF9iYW5rX2FjY291bnQiLCJleHAiOjE3MDUzMjI0MDB9.signature",
    "purpose": "recipient_add_bank_account",
    "recipient_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ"
  }
}

Response Fields

Field	Type	Description
`token`	string	JWT token valid for 2 hours
`purpose`	string	Token purpose (recipient_add_bank_account)
`recipient_id`	string	Global ID of the recipient

Token Usage

Direct users to the hosted page using the generated token:

{TREASURYPATH_HOSTED_URL}/hosted/recipient/add-bank-account?token={token}

Error Responses

400 Bad Request - Missing Purpose

{
  "errors": [
    {
      "field": "purpose",
      "message": "Purpose is required"
    }
  ]
}

400 Bad Request - Invalid Purpose

{
  "errors": [
    {
      "field": "purpose",
      "message": "Invalid purpose"
    }
  ]
}

400 Bad Request - Wrong Purpose Category

{
  "errors": [
    {
      "field": "purpose",
      "message": "Purpose must be a recipient category"
    }
  ]
}

400 Bad Request - Missing Recipient ID

{
  "errors": [
    {
      "field": "recipient_id",
      "message": "Recipient ID is required"
    }
  ]
}

401 Unauthorized

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

404 Not Found - Recipient Not Found

{
  "errors": [
    {
      "field": "recipient_id",
      "message": "Recipient not found"
    }
  ]
}

422 Unprocessable Entity - Invalid Recipient ID Format

{
  "errors": [
    {
      "field": "recipient_id",
      "message": "Invalid recipient ID format"
    }
  ]
}

422 Unprocessable Entity - Recipient Doesn't Belong to Company

{
  "errors": [
    {
      "field": "recipient_id",
      "message": "Recipient does not belong to this company"
    }
  ]
}

422 Unprocessable Entity - Entity Doesn't Belong to Company

{
  "errors": [
    {
      "field": "entity",
      "message": "Entity does not belong to this company"
    }
  ]
}

Webhooks

When recipients and their bank accounts are created or modified, TreasuryPath sends webhook notifications to your configured endpoints.

BankAccount Created

Sent when a user successfully adds a bank account for a recipient through the hosted page.

{
  "event": "BankAccountEvents::CreatedEvent",
  "timestamp": 1705324800,
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9CYW5rQWNjb3VudC8xMjM",
    "current_balance": "0.0",
    "currency": "USD",
    "last_synced_at": null,
    "owner_type": "Counterparty",
    "owner_id": "Z2lkOi8vd2FsbGV0LWFwcC9Db3VudGVycGFydHkvMQ",
    "created_at": "2025-01-15T11:00:00.000Z",
    "updated_at": "2025-01-15T11:00:00.000Z",
    "account_details": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9BY2NvdW50RGV0YWlsLzE",
        "account_number_mask": "************0000",
        "account_number_type": "other",
        "created_at": "2025-01-15T11:00:00.000Z",
        "updated_at": "2025-01-15T11:00:00.000Z"
      }
    ],
    "routing_details": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9Sb3V0aW5nRGV0YWlsLzE",
        "routing_number": "011401533",
        "routing_number_type": "aba",
        "bank_name": "Chase Bank",
        "payment_method": "ach",
        "created_at": "2025-01-15T11:00:00.000Z",
        "updated_at": "2025-01-15T11:00:00.000Z"
      }
    ],
    "party_address": null,
    "payment_profiles": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
        "status": "active",
        "payment_method": "ach",
        "currency": "USD",
        "usage_type": "credit",
        "created_at": "2025-01-15T11:00:00.000Z",
        "updated_at": "2025-01-15T11:00:00.000Z"
      }
    ]
  }
}

PaymentProfile Created

Sent when a payment profile is created for a recipient's bank account.

{
  "event": "PaymentProfileEvents::CreatedEvent",
  "timestamp": 1705324800,
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS80NTY",
    "status": "active",
    "payment_method": "ach",
    "currency": "USD",
    "usage_type": "credit",
    "created_at": "2025-01-15T11:00:00.000Z",
    "updated_at": "2025-01-15T11:00:00.000Z"
  }
}

For more information about webhooks, see the Webhooks Reference.

Common Workflows

Creating a Recipient and Collecting Bank Account

Create the recipient

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

Generate a bank account token

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

Direct users to hosted page

{TREASURYPATH_HOSTED_URL}/hosted/recipient/add-bank-account?token={token}

Receive webhook notifications
BankAccountEvents::CreatedEvent
PaymentProfileEvents::CreatedEvent

Retrieve updated recipient details

GET /api/v1/companies/{company_id}/recipients/{recipient_id}

Create payments using the payment profile

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

Deleting an Inactive Recipient

DELETE /api/v1/companies/{company_id}/recipients/{recipient_id}

The recipient is marked as deleted and will no longer: - Appear in recipient lists - Be available for new payments - Be accessible via the GET endpoint

Historical payment data remains preserved for record-keeping.

Best Practices

Recipient Creation

Descriptive Names: Use clear, descriptive names for easy identification
Optional Email: Email is not required and can be reused across recipients
Store IDs: Save the recipient id returned on creation for future operations

Token Generation

Just-in-Time: Generate tokens only when needed
Short Lifespan: Tokens expire after 2 hours
One-Time Use: Generate fresh tokens for each bank account addition session
Secure Transmission: Always use HTTPS when transmitting tokens

Payment Profile Usage

Active Status: Only use payment profiles with active status
Currency Matching: Ensure payment currency matches profile currency
Usage Type: Use credit type profiles as to_profile_id when sending payments to recipients
Automatic Selection: TreasuryPath automatically determines the best payment method for each bank account

Webhook Integration

Event Handling: Implement handlers for BankAccountEvents::CreatedEvent and PaymentProfileEvents::CreatedEvent
Idempotency: Design webhook handlers to be idempotent
Signature Verification: Always verify webhook signatures
Error Handling: Implement retry logic for failed webhook processing

Add Your First Recipient - Complete guide to working with recipients
Bank Accounts Data Model - Understanding bank account structure
Payments API - Creating payments to recipients
Webhooks Reference - Setting up and handling webhooks

Recipients API

Endpoints

List Recipients

Endpoint

Headers

Path Parameters

Example Request

Success Response (200 OK)

Response Fields

Bank Account Fields

Account Detail Fields

Routing Detail Fields

Payment Profile Fields

Error Responses

401 Unauthorized

404 Not Found - Company Not Found

Get Recipient

Endpoint

Headers

Path Parameters

Example Request

Success Response (200 OK)

Error Responses

401 Unauthorized

404 Not Found - Recipient Not Found

Create Recipient

Endpoint

Headers

Path Parameters

Request Body

Example Request

Success Response (201 Created)

Error Responses

400 Bad Request - Missing Name

400 Bad Request - Blank Name

401 Unauthorized

404 Not Found - Company Not Found

Delete Recipient

Endpoint

Headers

Path Parameters

Example Request

Success Response (204 No Content)

Error Responses

401 Unauthorized

404 Not Found - Recipient Not Found

Generate Bank Account Token

Endpoint

Headers

Path Parameters

Request Body

Example Request

Success Response (201 Created)

Response Fields

Token Usage

Error Responses

400 Bad Request - Missing Purpose

400 Bad Request - Invalid Purpose

400 Bad Request - Wrong Purpose Category

400 Bad Request - Missing Recipient ID

401 Unauthorized

404 Not Found - Recipient Not Found

422 Unprocessable Entity - Invalid Recipient ID Format

422 Unprocessable Entity - Recipient Doesn't Belong to Company

422 Unprocessable Entity - Entity Doesn't Belong to Company

Webhooks

BankAccount Created

PaymentProfile Created

Common Workflows

Creating a Recipient and Collecting Bank Account

Deleting an Inactive Recipient

Best Practices

Recipient Creation

Token Generation

Payment Profile Usage

Webhook Integration

Related Resources