Create Entity (Banking Connectivity)

POST

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",
  "entity_type": "INDIVIDUAL",
  "phone": {
    "country_code": "+1",
    "number": "2025551234"
  },
  "address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "building_number": "123",
    "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": "MALE",
      "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",
        "issuing_date": "2010-01-15",
        "expiry_date": "2030-01-15"
      }
    }
  }
}
'

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_entity_id": "merchant_user_12345",
  "entity_type": "INDIVIDUAL",
  "phone": {
    "country_code": "+1",
    "number": "2025551234"
  },
  "address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "building_number": "123",
    "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": "MALE",
      "country_of_residence": "US",
      "tax_information": [
        {
          "country": "US",
          "tax_id_last4": "*******6789",
          "tax_id_type": "SSN",
          "is_primary": true
        }
      ],
      "document": {
        "document_type": "SSN",
        "document_number_last4": "*******6789",
        "issuing_country": "US",
        "issuing_date": "2010-01-15",
        "expiry_date": "2030-01-15"
      }
    },
    "business": 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 entity_type to INDIVIDUAL or BUSINESS 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 (for example *******6789).

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"

entity_type

enum<string>

required

The type of entity being created.

Available options:

INDIVIDUAL,

BUSINESS

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 business based on the entity_type value.

Show child attributes

Response

Created (Individual)

string

Example:

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

account_id

string

Example:

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

merchant_entity_id

string

Example:

"merchant_company_789"

entity_type

string

Example:

"BUSINESS"

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"

⌘I

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",
  "entity_type": "INDIVIDUAL",
  "phone": {
    "country_code": "+1",
    "number": "2025551234"
  },
  "address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "building_number": "123",
    "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": "MALE",
      "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",
        "issuing_date": "2010-01-15",
        "expiry_date": "2030-01-15"
      }
    }
  }
}
'

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_entity_id": "merchant_user_12345",
  "entity_type": "INDIVIDUAL",
  "phone": {
    "country_code": "+1",
    "number": "2025551234"
  },
  "address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "building_number": "123",
    "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": "MALE",
      "country_of_residence": "US",
      "tax_information": [
        {
          "country": "US",
          "tax_id_last4": "*******6789",
          "tax_id_type": "SSN",
          "is_primary": true
        }
      ],
      "document": {
        "document_type": "SSN",
        "document_number_last4": "*******6789",
        "issuing_country": "US",
        "issuing_date": "2010-01-15",
        "expiry_date": "2030-01-15"
      }
    },
    "business": null
  },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-01T10:00:00Z"
}

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Transaction Reporting

Routing Recommendations

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions Plans

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

FX Rates

Banking Connectivity

Webhooks

Authorizations

Headers

Body

Response