Create Entity (Banking Connectivity)

POST /banking/entities

cURL

Create Individual

curl --request POST \
  --url https://api-sandbox.y.uno/v1/banking/entities \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>' \
  --data '
{
  "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",
    "address_line_2": "Apt 4B",
    "building_number_1": "123",
    "building_number_2": null,
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102",
    "country": "US"
  },
  "entity_detail": {
    "individual": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[e-mail]",
      "date_of_birth": "1990-01-15",
      "gender": "M",
      "country_of_residence": "US",
      "tax_information": [
        {
          "country": "US",
          "tax_id": "123-45-6789",
          "tax_id_type": "SSN",
          "is_primary": true
        }
      ],
      "document": {
        "document_type": "SSN",
        "document_number": "123-45-6789",
        "issuing_country": "US",
        "issued_at": "2010-01-15",
        "expires_at": "2030-01-15"
      }
    },
    "entity": null
  }
}
'

201

Created (Individual)

{
  "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",
    "address_line_2": "Apt 4B",
    "building_number_1": "123",
    "building_number_2": null,
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102",
    "country": "US"
  },
  "entity_detail": {
    "individual": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[e-mail]",
      "date_of_birth": "1990-01-15",
      "gender": "M",
      "country_of_residence": "US",
      "tax_information": [
        {
          "country": "US",
          "tax_id_last_4": "6789",
          "tax_id_type": "SSN",
          "is_primary": true
        }
      ],
      "document": {
        "document_type": "SSN",
        "document_number_last_4": "6789",
        "issuing_country": "US",
        "issued_at": "2010-01-15",
        "expires_at": "2030-01-15"
      }
    },
    "entity": null
  },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-01T10:00:00Z"
}

Create a Yuno entity representing an individual or organization. Set national_entity to INDIVIDUAL or ENTITY and provide the corresponding entity_detail sub-object. See Entity types for details.

Sensitive fields like tax_id and document_number are masked in responses (only last 4 digits returned).

Authorizations

public-api-key · string · header · required

private-secret-key · string · header · required

Headers

x-idempotency-key · string · required

Unique identifier used in HTTP headers to ensure that a request is processed only once, even if it is retried due to network issues or timeouts. See authentication for details (UUID).

Body

application/json

account_id · string · required

The unique identifier of the merchant's Yuno account. Found on the Yuno dashboard (UUID, 36 characters).

Example:

"550e8400-e29b-41d4-a716-446655440000"

merchant_entity_id · string · required

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

Example:

"merchant_user_12345"

national_entity · enum<string> · required

The type of entity being created.

Available options: INDIVIDUAL, ENTITY

Example:

"INDIVIDUAL"

phone · object · required

The entity's phone number.

Show child attributes

address · object · required

The entity's primary address.

Show child attributes

entity_detail · object · required

The detailed information for the entity. Provide either individual or entity based on the national_entity value.

Show child attributes

Response

201

application/json

Created (Individual)

id · string

Example:

"ent_770e8400-e29b-41d4-a716-446655440000"

account_id · string

Example:

"550e8400-e29b-41d4-a716-446655440000"

merchant_entity_id · string

Example:

"merchant_company_789"

national_entity · string

Example:

"ENTITY"

phone · object

Show child attributes

address · object

Show child attributes

entity_detail · object

Show child attributes

created_at · string

Example:

"2026-02-01T10:00:00Z"

updated_at · string

Example:

"2026-02-01T10:00:00Z"