Entity Onboarding API

The Entity Onboarding API allows you to manage onboarding data for entities. This data is used when enabling payment integrations (like multi-currency accounts) to pre-populate business information, reducing the data entry required on hosted onboarding pages.

Endpoints

Onboarding Data

Get Onboarding - GET /api/v1/companies/{company_id}/entities/{entity_id}/onboarding
Update Onboarding - PATCH /api/v1/companies/{company_id}/entities/{entity_id}/onboarding

Persons (Beneficial Owners, Directors, etc.)

List Persons - GET /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons
Create Person - POST /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons
Get Person - GET /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons/{id}
Update Person - PATCH /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons/{id}
Delete Person - DELETE /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons/{id}

Attachments (Supporting Documents)

List Attachments - GET /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/attachments
Create Attachment - POST /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/attachments
Delete Attachment - DELETE /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/attachments/{id}

Get Onboarding

Retrieve onboarding data for an entity.

Endpoint

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

Headers

Authorization: Bearer {jwt_token}

Path Parameters

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

Example Request

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

Success Response (200 OK) - With Data

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHlPbmJvYXJkaW5nLzE",
    "status": "draft",
    "submitted_at": null,
    "approved_at": null,
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T10:30:00.000Z",
    "business_details": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQnVzaW5lc3NEZXRhaWwvMQ",
      "business_name": "Acme Corporation",
      "business_name_trading": "Acme Corp",
      "business_structure": "corporation",
      "business_start_date": "2020-01-15",
      "industry_category_code": "5411",
      "description_of_goods_services": "Software development and consulting services",
      "website_url": "https://acme.com",
      "contact_phone": "+1-555-123-4567",
      "state_of_incorporation": "DE",
      "created_at": "2025-10-20T10:30:00.000Z",
      "updated_at": "2025-10-20T10:30:00.000Z",
      "business_address": {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQWRkcmVzcy8x",
        "address_type": "business",
        "line1": "123 Main Street",
        "line2": "Suite 400",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country_alpha2": "US",
        "created_at": "2025-10-20T10:30:00.000Z",
        "updated_at": "2025-10-20T10:30:00.000Z"
      },
      "registration_address": {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQWRkcmVzcy8y",
        "address_type": "registration",
        "line1": "1209 Orange Street",
        "line2": null,
        "city": "Wilmington",
        "state": "DE",
        "postal_code": "19801",
        "country_alpha2": "US",
        "created_at": "2025-10-20T10:30:00.000Z",
        "updated_at": "2025-10-20T10:30:00.000Z"
      },
      "business_identifiers": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQnVzaW5lc3NJZGVudGlmaWVyLzE",
          "identifier_type": "ein",
          "identifier_number": "12-3456789",
          "country_alpha2": "US",
          "created_at": "2025-10-20T10:30:00.000Z",
          "updated_at": "2025-10-20T10:30:00.000Z"
        }
      ]
    },
    "persons": [],
    "primary_contact_email": "admin@acme.com",
    "primary_contact_mobile": "+1-555-987-6543",
    "primary_contact_mobile_country_code": "+1"
  }
}

Success Response (200 OK) - No Onboarding Data

{
  "data": null
}

Error Responses

404 Not Found - Entity Not Found

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

Update Onboarding

Update onboarding data for an entity. This endpoint creates the onboarding record if it doesn't exist.

Important: Entities with an active payment integration cannot have their onboarding data updated.

Endpoint

PATCH /api/v1/companies/{company_id}/entities/{entity_id}/onboarding

Headers

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

Path Parameters

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

Request Body

All sections are optional. Only include the sections you want to update.

{
  "business_details": {
    "business_name": "string",
    "business_name_trading": "string",
    "business_structure": "string",
    "business_start_date": "string (YYYY-MM-DD)",
    "industry_category_code": "string",
    "description_of_goods_services": "string",
    "website_url": "string",
    "contact_phone": "string",
    "state_of_incorporation": "string"
  },
  "business_address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country_alpha2": "string"
  },
  "registration_address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country_alpha2": "string"
  },
  "business_identifiers": [
    {
      "identifier_type": "string",
      "identifier_number": "string",
      "country_alpha2": "string"
    }
  ],
  "primary_contact": {
    "email": "string",
    "mobile": "string",
    "mobile_country_code": "string"
  }
}

Parameters

business_details

Parameter	Type	Required	Description
`business_name`	string	No	Legal business name
`business_name_trading`	string	No	Trading name (DBA)
`business_structure`	string	No	Business structure (see supported values below)
`business_start_date`	string	No	Date business started (YYYY-MM-DD)
`industry_category_code`	string	No	Industry category code (NAICS or similar)
`description_of_goods_services`	string	No	Description of products or services
`website_url`	string	No	Business website URL
`contact_phone`	string	No	Business contact phone number
`state_of_incorporation`	string	No	State/province of incorporation

business_address / registration_address

Parameter	Type	Required	Description
`line1`	string	No	Street address line 1
`line2`	string	No	Street address line 2
`city`	string	No	City
`state`	string	No	State/province
`postal_code`	string	No	Postal/ZIP code
`country_alpha2`	string	No	ISO 3166-1 alpha-2 country code

business_identifiers

Parameter	Type	Required	Description
`identifier_type`	string	Yes	Type of identifier (ein, vat, brn, ssn)
`identifier_number`	string	Yes	Identifier number
`country_alpha2`	string	No	ISO 3166-1 alpha-2 country code

Note: Providing business_identifiers replaces all existing identifiers.

primary_contact

Parameter	Type	Required	Description
`email`	string	No	Primary contact email
`mobile`	string	No	Primary contact mobile phone
`mobile_country_code`	string	No	Mobile country calling code (e.g., "+1")

Example Request

curl -X PATCH "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities/Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ/onboarding" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "business_details": {
      "business_name": "Acme Corporation",
      "business_structure": "corporation",
      "industry_category_code": "5411",
      "business_start_date": "2020-01-15"
    },
    "business_address": {
      "line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country_alpha2": "US"
    },
    "business_identifiers": [
      {
        "identifier_type": "ein",
        "identifier_number": "12-3456789",
        "country_alpha2": "US"
      }
    ],
    "primary_contact": {
      "email": "admin@acme.com",
      "mobile": "+1-555-987-6543"
    }
  }'

Success Response (200 OK)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHlPbmJvYXJkaW5nLzE",
    "status": "draft",
    "submitted_at": null,
    "approved_at": null,
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T15:45:00.000Z",
    "business_details": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQnVzaW5lc3NEZXRhaWwvMQ",
      "business_name": "Acme Corporation",
      "business_name_trading": null,
      "business_structure": "corporation",
      "business_start_date": "2020-01-15",
      "industry_category_code": "5411",
      "description_of_goods_services": null,
      "website_url": null,
      "contact_phone": null,
      "state_of_incorporation": null,
      "created_at": "2025-10-20T10:30:00.000Z",
      "updated_at": "2025-10-20T15:45:00.000Z",
      "business_address": {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQWRkcmVzcy8x",
        "address_type": "business",
        "line1": "123 Main Street",
        "line2": null,
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country_alpha2": "US",
        "created_at": "2025-10-20T10:30:00.000Z",
        "updated_at": "2025-10-20T15:45:00.000Z"
      },
      "registration_address": null,
      "business_identifiers": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQnVzaW5lc3NJZGVudGlmaWVyLzE",
          "identifier_type": "ein",
          "identifier_number": "12-3456789",
          "country_alpha2": "US",
          "created_at": "2025-10-20T15:45:00.000Z",
          "updated_at": "2025-10-20T15:45:00.000Z"
        }
      ]
    },
    "persons": [],
    "primary_contact_email": "admin@acme.com",
    "primary_contact_mobile": "+1-555-987-6543",
    "primary_contact_mobile_country_code": "+1"
  }
}

Error Responses

403 Forbidden - Active Payment Integration

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

422 Unprocessable Entity - Validation Error

{
  "errors": [
    {
      "field": "business_details.business_name",
      "message": "is too long (maximum is 255 characters)"
    }
  ]
}

List Persons

Retrieve all persons (beneficial owners, directors, etc.) for an entity's onboarding.

Endpoint

GET /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons

Headers

Authorization: Bearer {jwt_token}

Path Parameters

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

Example Request

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

Success Response (200 OK)

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uLzE",
      "first_name": "John",
      "middle_name": null,
      "last_name": "Doe",
      "email": "john.doe@acme.com",
      "phone_number": "+1-555-123-4567",
      "date_of_birth": "1980-05-15",
      "nationality": "US",
      "job_title": "CEO",
      "roles": ["beneficial_owner", "director"],
      "created_at": "2025-10-20T10:30:00.000Z",
      "updated_at": "2025-10-20T10:30:00.000Z",
      "residential_address": {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQWRkcmVzcy8z",
        "address_type": "residential",
        "line1": "789 Oak Lane",
        "line2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postal_code": "94301",
        "country_alpha2": "US",
        "created_at": "2025-10-20T10:30:00.000Z",
        "updated_at": "2025-10-20T10:30:00.000Z"
      },
      "identifications": [
        {
          "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uSWRlbnRpZmljYXRpb24vMQ",
          "identification_type": "tax_id",
          "identification_number": "***-**-6789",
          "issuing_country": "US",
          "effective_date": null,
          "expiration_date": null,
          "is_primary": true,
          "tax_id_type": "ssn",
          "created_at": "2025-10-20T10:30:00.000Z",
          "updated_at": "2025-10-20T10:30:00.000Z"
        }
      ]
    }
  ],
  "meta": {
    "total_records": 1,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 20
  },
  "links": {
    "first": "...",
    "prev": null,
    "next": null,
    "last": "..."
  }
}

Create Person

Add a new person (beneficial owner, director, authorized person, etc.) to the entity's onboarding.

Endpoint

POST /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons

Headers

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

Path Parameters

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

Request Body

{
  "first_name": "string",
  "middle_name": "string",
  "last_name": "string",
  "email": "string",
  "phone_number": "string",
  "date_of_birth": "string (YYYY-MM-DD)",
  "nationality": "string",
  "job_title": "string",
  "roles": ["string"],
  "residential_address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country_alpha2": "string"
  },
  "identifications": [
    {
      "identification_type": "string",
      "identification_number": "string",
      "issuing_country": "string",
      "effective_date": "string (YYYY-MM-DD)",
      "expiration_date": "string (YYYY-MM-DD)",
      "is_primary": "boolean",
      "tax_id_type": "string"
    }
  ]
}

Parameters

Person Fields

Parameter	Type	Required	Description
`first_name`	string	No	First name (max 100 characters)
`middle_name`	string	No	Middle name
`last_name`	string	No	Last name (max 100 characters)
`email`	string	No	Email address
`phone_number`	string	No	Phone number
`date_of_birth`	string	No	Date of birth (YYYY-MM-DD)
`nationality`	string	No	ISO 3166-1 alpha-2 country code
`job_title`	string	No	Job title
`roles`	array	No	Array of role strings (see supported values)

Supported Roles

Role	Description
`beneficial_owner`	Person with significant ownership stake
`director`	Company director
`authorized_person`	Person authorized to act on behalf of company
`controlling_person`	Person with significant control
`legal_representative`	Legal representative

residential_address

Parameter	Type	Required	Description
`line1`	string	No	Street address line 1
`line2`	string	No	Street address line 2
`city`	string	No	City
`state`	string	No	State/province
`postal_code`	string	No	Postal/ZIP code
`country_alpha2`	string	No	ISO 3166-1 alpha-2 country code

identifications

Parameter	Type	Required	Description
`identification_type`	string	Yes	Type (passport, drivers_license, tax_id)
`identification_number`	string	Yes	Identification number
`issuing_country`	string	No	ISO 3166-1 alpha-2 country code
`effective_date`	string	No	Date document became valid (YYYY-MM-DD)
`expiration_date`	string	No	Document expiration date (YYYY-MM-DD)
`is_primary`	boolean	No	Whether this is the primary identification
`tax_id_type`	string	No	For tax_id type: ssn or itin

Example Request

curl -X POST "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities/Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ/onboarding/persons" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@acme.com",
    "date_of_birth": "1980-05-15",
    "nationality": "US",
    "job_title": "CEO",
    "roles": ["beneficial_owner", "director"],
    "residential_address": {
      "line1": "789 Oak Lane",
      "city": "Palo Alto",
      "state": "CA",
      "postal_code": "94301",
      "country_alpha2": "US"
    },
    "identifications": [
      {
        "identification_type": "tax_id",
        "identification_number": "123-45-6789",
        "tax_id_type": "ssn",
        "is_primary": true
      }
    ]
  }'

Success Response (201 Created)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uLzE",
    "first_name": "John",
    "middle_name": null,
    "last_name": "Doe",
    "email": "john.doe@acme.com",
    "phone_number": null,
    "date_of_birth": "1980-05-15",
    "nationality": "US",
    "job_title": "CEO",
    "roles": ["beneficial_owner", "director"],
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T10:30:00.000Z",
    "residential_address": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQWRkcmVzcy8z",
      "address_type": "residential",
      "line1": "789 Oak Lane",
      "line2": null,
      "city": "Palo Alto",
      "state": "CA",
      "postal_code": "94301",
      "country_alpha2": "US",
      "created_at": "2025-10-20T10:30:00.000Z",
      "updated_at": "2025-10-20T10:30:00.000Z"
    },
    "identifications": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uSWRlbnRpZmljYXRpb24vMQ",
        "identification_type": "tax_id",
        "identification_number": "123-45-6789",
        "issuing_country": null,
        "effective_date": null,
        "expiration_date": null,
        "is_primary": true,
        "tax_id_type": "ssn",
        "created_at": "2025-10-20T10:30:00.000Z",
        "updated_at": "2025-10-20T10:30:00.000Z"
      }
    ]
  }
}

Error Responses

403 Forbidden - Active Payment Integration

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

422 Unprocessable Entity - Validation Error

{
  "errors": [
    {
      "field": "roles",
      "message": "contains invalid values: invalid_role"
    }
  ]
}

Get Person

Retrieve a specific person from the entity's onboarding.

Endpoint

GET /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons/{id}

Headers

Authorization: Bearer {jwt_token}

Path Parameters

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

Example Request

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

Success Response (200 OK)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uLzE",
    "first_name": "John",
    "middle_name": null,
    "last_name": "Doe",
    "email": "john.doe@acme.com",
    "phone_number": "+1-555-123-4567",
    "date_of_birth": "1980-05-15",
    "nationality": "US",
    "job_title": "CEO",
    "roles": ["beneficial_owner", "director"],
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T10:30:00.000Z",
    "residential_address": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQWRkcmVzcy8z",
      "address_type": "residential",
      "line1": "789 Oak Lane",
      "line2": null,
      "city": "Palo Alto",
      "state": "CA",
      "postal_code": "94301",
      "country_alpha2": "US",
      "created_at": "2025-10-20T10:30:00.000Z",
      "updated_at": "2025-10-20T10:30:00.000Z"
    },
    "identifications": [
      {
        "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uSWRlbnRpZmljYXRpb24vMQ",
        "identification_type": "tax_id",
        "identification_number": "***-**-6789",
        "issuing_country": "US",
        "effective_date": null,
        "expiration_date": null,
        "is_primary": true,
        "tax_id_type": "ssn",
        "created_at": "2025-10-20T10:30:00.000Z",
        "updated_at": "2025-10-20T10:30:00.000Z"
      }
    ]
  }
}

Error Responses

404 Not Found - Person Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Person not found"
    }
  ]
}

Update Person

Update an existing person in the entity's onboarding.

Endpoint

PATCH /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons/{id}

Headers

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

Path Parameters

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

Request Body

Same format as Create Person. All fields are optional - only include fields you want to update.

Note: Providing identifications replaces all existing identifications for this person.

Example Request

curl -X PATCH "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities/Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ/onboarding/persons/Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uLzE" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "job_title": "President & CEO",
    "roles": ["beneficial_owner", "director", "authorized_person"]
  }'

Success Response (200 OK)

Returns the updated person object (same format as Get Person).

Error Responses

403 Forbidden - Active Payment Integration

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

404 Not Found - Person Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Person not found"
    }
  ]
}

Delete Person

Remove a person from the entity's onboarding.

Endpoint

DELETE /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/persons/{id}

Headers

Authorization: Bearer {jwt_token}

Path Parameters

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

Example Request

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

Success Response (200 OK)

{
  "message": "Person deleted successfully"
}

Error Responses

403 Forbidden - Active Payment Integration

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

404 Not Found - Person Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Person not found"
    }
  ]
}

Attachments

Attachments allow you to upload supporting documents for onboarding verification. Documents can be attached to different parts of the onboarding: the entity onboarding itself, business details, persons, or person identifications.

Attachments Endpoints

List Attachments - GET /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/attachments
Create Attachment - POST /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/attachments
Delete Attachment - DELETE /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/attachments/{id}

List Attachments

Retrieve all attachments for an entity's onboarding. This includes attachments on the entity onboarding, business details, persons, and person identifications.

Endpoint

GET /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/attachments

Headers

Authorization: Bearer {jwt_token}

Path Parameters

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

Example Request

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

Success Response (200 OK)

{
  "data": [
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQXR0YWNobWVudC8x",
      "category": "business_document",
      "document_type": "certificate_of_incorporation",
      "tag": "CERTIFICATE_OF_INCORPORATION",
      "side": null,
      "description": "Certificate of Incorporation",
      "original_filename": "cert_of_inc.pdf",
      "content_type": "application/pdf",
      "file_size": 245632,
      "upload_status": "pending",
      "attachable_type": "EntityOnboarding",
      "attachable_id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHlPbmJvYXJkaW5nLzE",
      "created_at": "2025-10-20T10:30:00.000Z",
      "updated_at": "2025-10-20T10:30:00.000Z"
    },
    {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQXR0YWNobWVudC8y",
      "category": "identity_document",
      "document_type": "passport",
      "tag": null,
      "side": "front",
      "description": "Passport front page",
      "original_filename": "passport_front.jpg",
      "content_type": "image/jpeg",
      "file_size": 1024567,
      "upload_status": "pending",
      "attachable_type": "OnboardingPersonIdentification",
      "attachable_id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uSWRlbnRpZmljYXRpb24vMQ",
      "created_at": "2025-10-20T11:00:00.000Z",
      "updated_at": "2025-10-20T11:00:00.000Z"
    }
  ],
  "meta": {
    "total_records": 2,
    "total_pages": 1,
    "current_page": 1,
    "per_page": 20
  },
  "links": {
    "first": "...",
    "prev": null,
    "next": null,
    "last": "..."
  }
}

Create Attachment

Upload a new attachment for onboarding verification. Files are stored locally and automatically synced to the payment provider when multi-currency is enabled.

Endpoint

POST /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/attachments

Headers

Authorization: Bearer {jwt_token}
Content-Type: multipart/form-data

Path Parameters

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

Request Body (multipart/form-data)

Parameter	Type	Required	Description
`file`	file	Yes	The file to upload
`category`	string	Yes	Document category (see supported values below)
`document_type`	string	No	Type of document (see supported values below)
`tag`	string	No	Provider tag for categorization
`side`	string	No	For identity documents: `front` or `back`
`description`	string	No	Human-readable description of the document
`attachable_type`	string	No	Type of record to attach to (default: entity_onboarding)
`attachable_id`	string	No	ID of the record to attach to (GlobalID format)

Attachable Types

Type	Description
`entity_onboarding`	Attach to the main onboarding record (default)
`business_detail`	Attach to business details
`person`	Attach to a specific person
`identification`	Attach to a person's identification document

Example Request - Business Document

curl -X POST "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities/Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ/onboarding/attachments" \
  -H "Authorization: Bearer {jwt_token}" \
  -F "file=@certificate_of_incorporation.pdf" \
  -F "category=business_document" \
  -F "document_type=certificate_of_incorporation" \
  -F "tag=CERTIFICATE_OF_INCORPORATION" \
  -F "description=Certificate of Incorporation"

Example Request - Identity Document for Person

curl -X POST "https://api.treasurypath.com/api/v1/companies/Z2lkOi8vd2FsbGV0LWFwcC9Db21wYW55LzE/entities/Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHkvMQ/onboarding/attachments" \
  -H "Authorization: Bearer {jwt_token}" \
  -F "file=@passport_front.jpg" \
  -F "category=identity_document" \
  -F "document_type=passport" \
  -F "side=front" \
  -F "description=Passport front page" \
  -F "attachable_type=identification" \
  -F "attachable_id=Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nUGVyc29uSWRlbnRpZmljYXRpb24vMQ"

Success Response (201 Created)

{
  "data": {
    "id": "Z2lkOi8vd2FsbGV0LWFwcC9PbmJvYXJkaW5nQXR0YWNobWVudC8x",
    "category": "business_document",
    "document_type": "certificate_of_incorporation",
    "tag": "CERTIFICATE_OF_INCORPORATION",
    "side": null,
    "description": "Certificate of Incorporation",
    "original_filename": "certificate_of_incorporation.pdf",
    "content_type": "application/pdf",
    "file_size": 245632,
    "upload_status": "pending",
    "attachable_type": "EntityOnboarding",
    "attachable_id": "Z2lkOi8vd2FsbGV0LWFwcC9FbnRpdHlPbmJvYXJkaW5nLzE",
    "created_at": "2025-10-20T10:30:00.000Z",
    "updated_at": "2025-10-20T10:30:00.000Z"
  }
}

Error Responses

400 Bad Request - File Missing

{
  "errors": [
    {
      "field": "file",
      "message": "File is required"
    }
  ]
}

403 Forbidden - Active Payment Integration

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

422 Unprocessable Entity - Validation Error

{
  "errors": [
    {
      "field": "category",
      "message": "is not included in the list"
    }
  ]
}

Delete Attachment

Remove an attachment from the onboarding.

Endpoint

DELETE /api/v1/companies/{company_id}/entities/{entity_id}/onboarding/attachments/{id}

Headers

Authorization: Bearer {jwt_token}

Path Parameters

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

Example Request

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

Success Response (200 OK)

{
  "message": "Attachment deleted successfully"
}

Error Responses

403 Forbidden - Active Payment Integration

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

404 Not Found - Attachment Not Found

{
  "errors": [
    {
      "field": "id",
      "message": "Attachment not found"
    }
  ]
}

Data Types

Onboarding Status

Status	Description
`draft`	Onboarding data is being collected
`submitted`	Onboarding has been submitted to payment provider
`approved`	Onboarding has been approved by payment provider
`rejected`	Onboarding was rejected by payment provider

Business Structure

Value	Description
`sole_proprietorship`	Sole Proprietorship
`partnership`	Partnership
`llc`	Limited Liability Company
`corporation`	Corporation
`nonprofit`	Nonprofit Organization
`cooperative`	Cooperative
`trust`	Trust
`government`	Government Entity

Identifier Types

Type	Description
`ein`	Employer Identification Number
`vat`	Value Added Tax Number
`brn`	Business Registration Number
`ssn`	Social Security Number

Identification Types (for Persons)

Type	Description
`passport`	Passport
`drivers_license`	Driver's License
`tax_id`	Tax Identification

Tax ID Types

Type	Description
`ssn`	Social Security Number
`itin`	Individual Taxpayer Identification Number

Attachment Categories

Category	Description
`business_document`	Business-related documents
`identity_document`	Identity verification documents
`person_document`	Person-related supporting documents
`additional_file`	Other supporting files

Attachment Document Types

Type	Description
`passport`	Passport
`drivers_license`	Driver's License
`personal_id`	Personal ID Card
`tax_id`	Tax Identification Document
`certificate_of_incorporation`	Certificate of Incorporation
`ownership_structure`	Ownership Structure Document
`proof_of_address`	Proof of Address
`bank_statement`	Bank Statement
`other`	Other Document Type

Business Document Tags

Tag	Description
`CERTIFICATE_OF_INCORPORATION`	Certificate of Incorporation
`CERTIFICATE_OF_REGISTRATION`	Certificate of Registration
`OWNERSHIP_STRUCTURE`	Ownership Structure
`ANNUAL_REPORT`	Annual Report
`FINANCIAL_STATEMENTS`	Financial Statements
`BANK_STATEMENT`	Bank Statement
`SUPPORTIVE_OTHER`	Other Supporting Document

Person Document Tags

Tag	Description
`PPTA_LETTER`	PPTA Letter
`CHANGE_OF_NAME_CERTIFICATE`	Change of Name Certificate
`PROOF_OF_ADDRESS`	Proof of Address
`SUPPORTIVE_OTHER`	Other Supporting Document

Workflow

Typical Onboarding Flow

Create Entity - Use the Entities API to create an entity
Update Onboarding Data - Use PATCH /onboarding to add business details, addresses, and identifiers
Add Persons - Use POST /onboarding/persons to add beneficial owners, directors, etc.
Upload Documents - Use POST /onboarding/attachments to upload supporting documents (certificates, IDs, etc.)
Enable Multi-Currency - Use the Multi-Currency Enablement API to enable payment features

Note: When multi-currency is enabled, all uploaded attachments are automatically synced to the payment provider. You don't need to manage the sync process manually.

Pre-populated Data Benefits

When onboarding data and documents are provided via API before enabling multi-currency:

Business information is pre-filled on hosted onboarding pages
Supporting documents are automatically submitted for verification
Users only need to complete remaining required fields
Reduces onboarding friction and completion time
Enables programmatic control over the onboarding process

Entities API - Manage entities
Multi-Currency Enablement API - Enable payment features
Setup Your Organization - Organization setup guide