v1

latestOpenAPI 3.0.02026-07-26167441.9 MB

Entities (Banking Connectivity)

Create Entity (Banking Connectivity)

post/banking/entities

Headers

x-idempotency-keystring 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).

Request body

account_idstring required

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

merchant_entity_idstring required

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

national_entity'INDIVIDUAL' | 'ENTITY' required

The type of entity being created.

Example request

{
  "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",
    "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": {
      "name": "Acme Corporation Inc",
      "country": "US",
      "tax_information": [
        {
          "country": "US",
          "tax_id": "12-3456789",
          "tax_id_type": "EIN",
          "is_primary": true
        }
      ],
      "entity_type": "CORPORATION",
      "beneficial_owners": [
        {
          "first_name": "Jane",
          "last_name": "Smith",
          "email": "jane@acme.com",
          "date_of_birth": "1985-03-20",
          "gender": "F",
          "country_of_residence": "US",
          "tax_information": [
            {
              "country": "US",
              "tax_id": "987-65-4321",
              "tax_id_type": "SSN",
              "is_primary": true
            }
          ],
          "document": {
            "document_type": "SSN",
            "document_number": "987-65-4321",
            "issuing_country": "US",
            "issued_at": "2005-03-20"
          },
          "ownership_percentage": 100,
          "title": "CEO",
          "address": {
            "address_line_1": "789 Oak St",
            "building_number_1": "789",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94103",
            "country": "US"
          }
        }
      ]
    }
  }
}

Response

Created (Individual)

idstring

account_idstring

merchant_entity_idstring

national_entitystring

created_atstring

updated_atstring

Example response

{
  "id": "ent_770e8400-e29b-41d4-a716-446655440000",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "merchant_entity_id": "merchant_company_789",
  "national_entity": "ENTITY",
  "phone": {
    "country_code": "+1",
    "number": "4155551234"
  },
  "address": {
    "address_line_1": "456 Market St",
    "building_number_1": "456",
    "city": "San Francisco",
    "state": "CA",
    "zip_code": "94102",
    "country": "US"
  },
  "entity_detail": {
    "entity": {
      "name": "Acme Corporation Inc",
      "country": "US",
      "tax_information": [
        {
          "country": "US",
          "tax_id_last_4": "6789",
          "tax_id_type": "EIN",
          "is_primary": true
        }
      ],
      "entity_type": "CORPORATION",
      "beneficial_owners": [
        {
          "first_name": "Jane",
          "last_name": "Smith",
          "email": "jane@acme.com",
          "date_of_birth": "1985-03-20",
          "gender": "F",
          "country_of_residence": "US",
          "tax_information": [
            {
              "country": "US",
              "tax_id_last_4": "4321",
              "tax_id_type": "SSN",
              "is_primary": true
            }
          ],
          "document": {
            "document_type": "SSN",
            "document_number_last_4": "4321",
            "issuing_country": "US",
            "issued_at": "2005-03-20"
          },
          "ownership_percentage": 100,
          "title": "CEO",
          "address": {
            "address_line_1": "789 Oak St",
            "building_number_1": "789",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94103",
            "country": "US"
          }
        }
      ]
    }
  },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-01T10:00:00Z"
}