Create Entity

Register an individual or business entity for BaaS operations

POST /v1/baas/entities

Individual

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_entity_id": "merchant_user_12345",
  "national_entity": "INDIVIDUAL",
  "phone": {
    "country_code": "+1",
    "number": "2025551234"
  },
  "address": {
    "address_line_1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102",
    "country": "US"
  },
  "entity_detail": {
    "individual": {
      "first_name": "Dee",
      "last_name": "Hock",
      "email": "[e-mail]",
      "date_of_birth": "1990-01-15",
      "gender": "M",
      "country_of_residence": "US",
      "tax_information": [
        {
          "country": "US",
          "tax_id": "123456789",
          "tax_id_type": "SSN",
          "is_primary": true
        }
      ]
    }
  }
}

201 Created

{
  "id": "ent_660e8400-e29b-41d4-a716-446655440000",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_entity_id": "merchant_user_12345",
  "national_entity": "INDIVIDUAL",
  "phone": {
    "country_code": "+1",
    "number": "2025551234"
  },
  "address": {
    "address_line_1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102",
    "country": "US"
  },
  "entity_detail": {
    "individual": {
      "first_name": "Dee",
      "last_name": "Hock",
      "email": "[e-mail]",
      "date_of_birth": "1990-01-15"
    }
  },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-01T10:00:00Z"
}

Headers

x-idempotency-key · string · required

Unique UUID to ensure the request is processed only once.

Body

account_id · string · required

The unique identifier of the merchant’s Yuno account (UUID, 36 characters).

merchant_entity_id · string · required

The merchant’s own identifier for this entity, used for reconciliation.

national_entity · string · required

Type of entity. Values: INDIVIDUAL, ENTITY.

phone · object · required

Show phone

country_code · string · required

Country dialing code (e.g., +1).

number · string · required

Phone number.

address · object · required

Show address

address_line_1 · string · required

Street address.

address_line_2 · string

Additional address information.

city · string · required

City name.

state · string · required

State or province code.

zip_code · string · required

Postal code.

country · string · required

ISO 3166-1 alpha-2 country code.

entity_detail · object · required

Contains either individual or entity details based on national_entity type.

Show entity_detail. Individual

individual.first_name · string · required

First name.

individual.last_name · string · required

Last name.

individual.email · string · required

Email address.

individual.date_of_birth · string · required

Date of birth in YYYY-MM-DD format.

individual.gender · string

M or F.

individual.country_of_residence · string

ISO 3166-1 alpha-2 country code.

individual.tax_information · array

Array of tax identifiers. Each item includes country, tax_id, tax_id_type (SSN, EIN, ITIN, VAT, ABN, NIF, TIN, OTHER), and is_primary.

Show entity_detail. Business

entity.name · string · required

Business name.

entity.country · string · required

Country of incorporation.

entity.entity_type · string · required

Business type (e.g., CORPORATION).

entity.tax_information · array

Array of tax identifiers.

entity.beneficial_owners · array

Array of beneficial owners with personal details, ownership_percentage, and title.

Response

id · string

Entity identifier.

account_id · string

Associated Yuno account.

merchant_entity_id · string

Merchant’s reconciliation identifier.

national_entity · string

INDIVIDUAL or ENTITY.

phone · object

Phone details.

address · object

Address details.

entity_detail · object

Individual or business details.

created_at · string

ISO 8601 timestamp.

updated_at · string

ISO 8601 timestamp.

Individual

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_entity_id": "merchant_user_12345",
  "national_entity": "INDIVIDUAL",
  "phone": {
    "country_code": "+1",
    "number": "2025551234"
  },
  "address": {
    "address_line_1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102",
    "country": "US"
  },
  "entity_detail": {
    "individual": {
      "first_name": "Dee",
      "last_name": "Hock",
      "email": "[e-mail]",
      "date_of_birth": "1990-01-15",
      "gender": "M",
      "country_of_residence": "US",
      "tax_information": [
        {
          "country": "US",
          "tax_id": "123456789",
          "tax_id_type": "SSN",
          "is_primary": true
        }
      ]
    }
  }
}

201 Created

{
  "id": "ent_660e8400-e29b-41d4-a716-446655440000",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_entity_id": "merchant_user_12345",
  "national_entity": "INDIVIDUAL",
  "phone": {
    "country_code": "+1",
    "number": "2025551234"
  },
  "address": {
    "address_line_1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102",
    "country": "US"
  },
  "entity_detail": {
    "individual": {
      "first_name": "Dee",
      "last_name": "Hock",
      "email": "[e-mail]",
      "date_of_birth": "1990-01-15"
    }
  },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-01T10:00:00Z"
}