> ## Documentation Index > Fetch the complete documentation index at: https://docs.y.uno/llms.txt > Use this file to discover all available pages before exploring further. # Create Entity (Banking Connectivity) 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](/reference/banking-connectivity#entity-types) for details. Sensitive fields like `tax_id` and `document_number` are masked in responses (only last 4 digits returned). ## OpenAPI ````yaml openapi/banking-connectivity/entities-banking-connectivity/create-entity.json POST /banking/entities openapi: 3.0.0 info: version: 1.0.0 title: Banking Connectivity servers: - url: https://api-sandbox.y.uno/v1 security: - public-api-key: [] private-secret-key: [] paths: /banking/entities: post: tags: - Entities (Banking Connectivity) summary: Create Entity (Banking Connectivity) operationId: post_v1-banking-connectivity-entities parameters: - in: header name: x-idempotency-key schema: type: string description: >- 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](/reference/authentication#idempotency) for details (UUID). required: true requestBody: content: application/json: schema: type: object required: - account_id - merchant_entity_id - national_entity - phone - address - entity_detail properties: account_id: type: string description: >- The unique identifier of the merchant's Yuno account. Found on the [Yuno dashboard](https://dashboard.y.uno/) (UUID, 36 characters). example: 550e8400-e29b-41d4-a716-446655440000 merchant_entity_id: type: string description: >- The merchant's own identifier for this entity, used for reconciliation. example: merchant_user_12345 national_entity: type: string description: The type of entity being created. enum: - INDIVIDUAL - ENTITY example: INDIVIDUAL phone: type: object description: The entity's phone number. required: - country_code - number properties: country_code: type: string description: The phone country code (e.g., `+1`). example: '+1' number: type: string description: The phone number without the country code. example: '2025551234' address: type: object description: The entity's primary address. required: - address_line_1 - city - state - zip_code - country properties: address_line_1: type: string description: The primary street address. example: 123 Main St address_line_2: type: string nullable: true description: The secondary address line (apartment, suite, etc.). example: Apt 4B building_number_1: type: string nullable: true description: The primary building number. example: '123' building_number_2: type: string nullable: true description: The secondary building number. example: null city: type: string description: The city name. example: San Francisco state: type: string description: The state or province. example: CA zip_code: type: string description: The postal or ZIP code. example: '94102' country: type: string description: >- The country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). example: US entity_detail: type: object description: >- The detailed information for the entity. Provide either `individual` or `entity` based on the `national_entity` value. properties: individual: type: object nullable: true description: >- Individual person details. Required when `national_entity` is `INDIVIDUAL`. properties: first_name: type: string description: The individual's first name. example: John last_name: type: string description: The individual's last name. example: Doe email: type: string description: The individual's email address. example: john@example.com date_of_birth: type: string description: The date of birth (YYYY-MM-DD). example: '1990-01-15' gender: type: string description: The individual's gender. enum: - M - F example: M country_of_residence: type: string description: >- The country of residence ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). example: US tax_information: type: array description: Tax identification records for the individual. items: type: object required: - country - tax_id - tax_id_type - is_primary properties: country: type: string description: The tax jurisdiction country code. example: US tax_id: type: string description: The tax identification number. example: 123-45-6789 tax_id_type: type: string description: The type of tax identification. enum: - SSN - EIN - ITIN - VAT - ABN - NIF - TIN - OTHER example: SSN is_primary: type: boolean description: Whether this is the primary tax residency. example: true document: type: object description: The primary identification document. required: - document_type - document_number - issuing_country properties: document_type: type: string description: The type of identity document. example: SSN document_number: type: string description: The document number. example: 123-45-6789 issuing_country: type: string description: >- The country that issued the document ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). example: US issued_at: type: string nullable: true description: The date the document was issued (YYYY-MM-DD). example: '2010-01-15' expires_at: type: string nullable: true description: The document expiration date (YYYY-MM-DD). example: '2030-01-15' entity: type: object nullable: true description: >- Business or organization details. Required when `national_entity` is `ENTITY`. properties: name: type: string description: The business or organization name. example: Acme Corporation Inc country: type: string description: >- The country of incorporation ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). example: US tax_information: type: array description: Business tax identification records. items: type: object required: - country - tax_id - tax_id_type - is_primary properties: country: type: string description: The tax jurisdiction country code. example: US tax_id: type: string description: The tax identification number. example: 12-3456789 tax_id_type: type: string description: The type of tax identification. enum: - SSN - EIN - ITIN - VAT - ABN - NIF - TIN - OTHER example: EIN is_primary: type: boolean description: Whether this is the primary tax residency. example: true entity_type: type: string description: The type of business entity. enum: - CORPORATION example: CORPORATION beneficial_owners: type: array description: The beneficial owners of the business entity. items: type: object required: - first_name - last_name - email - date_of_birth - country_of_residence - ownership_percentage properties: first_name: type: string description: The owner's first name. example: Jane last_name: type: string description: The owner's last name. example: Smith email: type: string description: The owner's email address. example: jane@acme.com date_of_birth: type: string description: The owner's date of birth (YYYY-MM-DD). example: '1985-03-20' gender: type: string description: The owner's gender. enum: - M - F example: F country_of_residence: type: string description: >- The owner's country of residence ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). example: US tax_information: type: array description: Tax identification records for the owner. items: type: object properties: country: type: string description: The tax jurisdiction country code. example: US tax_id: type: string description: The tax identification number. example: 987-65-4321 tax_id_type: type: string description: The type of tax identification. enum: - SSN - EIN - ITIN - VAT - ABN - NIF - TIN - OTHER example: SSN is_primary: type: boolean description: >- Whether this is the primary tax residency. example: true document: type: object description: The owner's primary identification document. properties: document_type: type: string description: The type of identity document. example: SSN document_number: type: string description: The document number. example: 987-65-4321 issuing_country: type: string description: The country that issued the document. example: US issued_at: type: string nullable: true description: >- The date the document was issued (YYYY-MM-DD). example: '2005-03-20' expires_at: type: string nullable: true description: The document expiration date (YYYY-MM-DD). example: null ownership_percentage: type: number description: >- The percentage of ownership in the business (0-100). example: 100 title: type: string description: The owner's title or role in the organization. example: CEO address: type: object description: The owner's residential address. properties: address_line_1: type: string description: The primary street address. example: 789 Oak St address_line_2: type: string nullable: true description: The secondary address line. example: null building_number_1: type: string nullable: true description: The primary building number. example: '789' building_number_2: type: string nullable: true description: The secondary building number. example: null city: type: string description: The city name. example: San Francisco state: type: string description: The state or province. example: CA zip_code: type: string description: The postal or ZIP code. example: '94103' country: type: string description: >- The country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). example: US examples: Create Individual: summary: Create Individual value: 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 Create Entity: summary: Create Entity value: 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 address_line_2: null building_number_1: '456' building_number_2: null city: San Francisco state: CA zip_code: '94102' country: US entity_detail: individual: null 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' expires_at: null ownership_percentage: 100 title: CEO address: address_line_1: 789 Oak St address_line_2: null building_number_1: '789' building_number_2: null city: San Francisco state: CA zip_code: '94103' country: US responses: '201': content: application/json: schema: type: object properties: id: type: string example: ent_770e8400-e29b-41d4-a716-446655440000 account_id: type: string example: 550e8400-e29b-41d4-a716-446655440000 merchant_entity_id: type: string example: merchant_company_789 national_entity: type: string example: ENTITY phone: type: object properties: country_code: type: string example: '+1' number: type: string example: '4155551234' address: type: object properties: address_line_1: type: string example: 456 Market St address_line_2: {} building_number_1: type: string example: '456' building_number_2: {} city: type: string example: San Francisco state: type: string example: CA zip_code: type: string example: '94102' country: type: string example: US entity_detail: type: object properties: individual: {} entity: type: object properties: name: type: string example: Acme Corporation Inc country: type: string example: US tax_information: type: array items: type: object properties: country: type: string example: US tax_id_last_4: type: string example: '6789' tax_id_type: type: string example: EIN is_primary: type: boolean example: true default: true entity_type: type: string example: CORPORATION beneficial_owners: type: array items: type: object properties: first_name: type: string example: Jane last_name: type: string example: Smith email: type: string example: jane@acme.com date_of_birth: type: string example: '1985-03-20' gender: type: string example: F country_of_residence: type: string example: US tax_information: type: array items: type: object properties: country: type: string example: US tax_id_last_4: type: string example: '4321' tax_id_type: type: string example: SSN is_primary: type: boolean example: true default: true document: type: object properties: document_type: type: string example: SSN document_number_last_4: type: string example: '4321' issuing_country: type: string example: US issued_at: type: string example: '2005-03-20' expires_at: {} ownership_percentage: type: integer example: 100 default: 0 title: type: string example: CEO address: type: object properties: address_line_1: type: string example: 789 Oak St address_line_2: {} building_number_1: type: string example: '789' building_number_2: {} city: type: string example: San Francisco state: type: string example: CA zip_code: type: string example: '94103' country: type: string example: US created_at: type: string example: '2026-02-01T10:00:00Z' updated_at: type: string example: '2026-02-01T10:00:00Z' examples: Created (Individual): summary: Created (Individual) value: 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' Created (Entity): summary: Created (Entity) value: 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 address_line_2: null building_number_1: '456' building_number_2: null city: San Francisco state: CA zip_code: '94102' country: US entity_detail: individual: null 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' expires_at: null ownership_percentage: 100 title: CEO address: address_line_1: 789 Oak St address_line_2: null building_number_1: '789' building_number_2: null city: San Francisco state: CA zip_code: '94103' country: US created_at: '2026-02-01T10:00:00Z' updated_at: '2026-02-01T10:00:00Z' description: Created (Individual) '400': content: application/json: schema: type: object properties: code: type: string example: VALIDATION_ERROR messages: type: array items: type: string example: national_entity is required http_code: type: integer example: 400 default: 0 examples: Validation Error: summary: Validation Error value: code: VALIDATION_ERROR messages: - national_entity is required http_code: 400 description: Bad Request '409': content: application/json: schema: type: object properties: {} examples: Duplicate Entity: summary: Duplicate Entity value: code: DUPLICATE_ENTITY messages: - >- Entity with merchant_entity_id 'merchant_user_12345' already exists http_code: 409 description: Conflict components: securitySchemes: public-api-key: type: apiKey in: header name: public-api-key private-secret-key: type: apiKey in: header name: private-secret-key ````