Skip to main content
POST
/
v1
/
banking
/
entities
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": "john@example.com",
      "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
  }
}
'
{
  "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": "john@example.com",
      "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.

​
address
object
required

The entity's primary address.

​
entity_detail
object
required

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

Response

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
​
address
object
​
entity_detail
object
​
created_at
string
Example:

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

​
updated_at
string
Example:

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