> ## 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.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Crear entidad (Banking Connectivity)

> Crea una entidad individual o empresarial para el onboarding de banking connectivity

Crea una entidad de Yuno que representa a una persona o a una organización. Define `entity_type` como `INDIVIDUAL` o `BUSINESS` y proporciona el sub-objeto `entity_detail` correspondiente. Consulta [Entity types](https://docs.y.uno/es/reference/banking-connectivity.md#entity-types) para más detalles.

Los campos sensibles como `tax_id` y `document_number` se enmascaran en las respuestas (por ejemplo `*******6789`).


## OpenAPI

````yaml openapi/es/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
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - public-api-key: []
    private-secret-key: []
paths:
  /banking/entities:
    post:
      tags:
        - Entities (Banking Connectivity)
      summary: Crear entidad (Banking Connectivity)
      operationId: post_v1-banking-connectivity-entities
      parameters:
        - in: header
          name: x-idempotency-key
          schema:
            type: string
          description: >-
            Identificador único que se usa en los encabezados HTTP para asegurar
            que una solicitud se procese una sola vez, aunque se reintente por
            problemas de red o tiempos de espera agotados. Consulta
            [autenticación](/es/reference/getting-started/authentication#idempotency)
            para ver los detalles (UUID).
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - account_id
                - merchant_entity_id
                - entity_type
                - phone
                - address
                - entity_detail
              properties:
                account_id:
                  type: string
                  description: >-
                    El identificador único de la cuenta de Yuno del comercio. Lo
                    encuentras en el [Dashboard de
                    Yuno](https://dashboard.y.uno/) (UUID, 36 caracteres).
                  example: 550e8400-e29b-41d4-a716-446655440000
                merchant_entity_id:
                  type: string
                  description: >-
                    El identificador propio del comercio para esta entidad, que
                    se usa para la conciliación.
                  example: merchant_user_12345
                entity_type:
                  type: string
                  description: El tipo de entidad que se crea.
                  enum:
                    - INDIVIDUAL
                    - BUSINESS
                  example: INDIVIDUAL
                phone:
                  type: object
                  description: El número de teléfono de la entidad.
                  required:
                    - country_code
                    - number
                  properties:
                    country_code:
                      type: string
                      description: El código de país del teléfono (por ejemplo, `+1`).
                      example: '+1'
                    number:
                      type: string
                      description: El número de teléfono sin el código de país.
                      example: '2025551234'
                address:
                  type: object
                  description: La dirección principal de la entidad.
                  required:
                    - address_line_1
                    - city
                    - state
                    - zip_code
                    - country
                  properties:
                    address_line_1:
                      type: string
                      description: La dirección principal (calle).
                      example: 123 Main St
                    address_line_2:
                      type: string
                      nullable: true
                      description: >-
                        La segunda línea de la dirección (departamento, oficina,
                        etc.).
                      example: Apt 4B
                    building_number:
                      type: string
                      nullable: true
                      description: El número principal del edificio.
                      example: '123'
                    city:
                      type: string
                      description: El nombre de la ciudad.
                      example: San Francisco
                    state:
                      type: string
                      description: El estado o la provincia.
                      example: CA
                    zip_code:
                      type: string
                      description: El código postal.
                      example: '94102'
                    country:
                      type: string
                      description: >-
                        El código de país ([ISO 3166-1
                        alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
                      example: US
                entity_detail:
                  type: object
                  description: >-
                    La información detallada de la entidad. Envía `individual` o
                    `business` según el valor de `entity_type`.
                  properties:
                    individual:
                      type: object
                      nullable: true
                      description: >-
                        Datos de la persona física. Obligatorio cuando
                        `entity_type` es `INDIVIDUAL`.
                      properties:
                        first_name:
                          type: string
                          description: El nombre del individuo.
                          example: John
                        last_name:
                          type: string
                          description: El apellido del individuo.
                          example: Doe
                        email:
                          type: string
                          description: La dirección de email del individuo.
                          example: john@example.com
                        date_of_birth:
                          type: string
                          description: La fecha de nacimiento (YYYY-MM-DD).
                          example: '1990-01-15'
                        gender:
                          type: string
                          description: El género del individuo.
                          enum:
                            - MALE
                            - FEMALE
                            - OTHER
                          example: MALE
                        country_of_residence:
                          type: string
                          description: >-
                            El país de residencia ([ISO 3166-1
                            alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
                          example: US
                        tax_information:
                          type: array
                          description: Registros de identificación fiscal del individuo.
                          items:
                            type: object
                            required:
                              - country
                              - tax_id
                              - tax_id_type
                              - is_primary
                            properties:
                              country:
                                type: string
                                description: El código del país de la jurisdicción fiscal.
                                example: US
                              tax_id:
                                type: string
                                description: El número de identificación fiscal.
                                example: 123-45-6789
                              tax_id_type:
                                type: string
                                description: El tipo de identificación fiscal.
                                enum:
                                  - SSN
                                  - EIN
                                  - ITIN
                                  - VAT
                                  - ABN
                                  - NIF
                                  - TIN
                                  - OTHER
                                example: SSN
                              is_primary:
                                type: boolean
                                description: Indica si es la residencia fiscal principal.
                                example: true
                        document:
                          type: object
                          description: El documento de identificación principal.
                          required:
                            - document_type
                            - document_number
                            - issuing_country
                          properties:
                            document_type:
                              type: string
                              description: El tipo de documento de identidad.
                              example: SSN
                            document_number:
                              type: string
                              description: El número del documento.
                              example: 123-45-6789
                            issuing_country:
                              type: string
                              description: >-
                                El país que emitió el documento ([ISO 3166-1
                                alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
                              example: US
                            issuing_date:
                              type: string
                              nullable: true
                              description: La fecha de emisión del documento (YYYY-MM-DD).
                              example: '2010-01-15'
                            expiry_date:
                              type: string
                              nullable: true
                              description: >-
                                La fecha de vencimiento del documento
                                (YYYY-MM-DD).
                              example: '2030-01-15'
                    business:
                      type: object
                      nullable: true
                      description: >-
                        Datos de la empresa u organización. Obligatorio cuando
                        `entity_type` es `BUSINESS`.
                      properties:
                        business_name:
                          type: string
                          description: El nombre de la empresa u organización.
                          example: Acme Corporation Inc
                        country:
                          type: string
                          description: >-
                            El país de constitución ([ISO 3166-1
                            alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
                          example: US
                        tax_information:
                          type: array
                          description: Registros de identificación fiscal de la empresa.
                          items:
                            type: object
                            required:
                              - country
                              - tax_id
                              - tax_id_type
                              - is_primary
                            properties:
                              country:
                                type: string
                                description: El código del país de la jurisdicción fiscal.
                                example: US
                              tax_id:
                                type: string
                                description: El número de identificación fiscal.
                                example: 12-3456789
                              tax_id_type:
                                type: string
                                description: El tipo de identificación fiscal.
                                enum:
                                  - SSN
                                  - EIN
                                  - ITIN
                                  - VAT
                                  - ABN
                                  - NIF
                                  - TIN
                                  - OTHER
                                example: EIN
                              is_primary:
                                type: boolean
                                description: Indica si es la residencia fiscal principal.
                                example: true
                        business_type:
                          type: string
                          description: El tipo de entidad empresarial.
                          enum:
                            - CORPORATION
                            - PARTNERSHIP
                            - SOLE_PROPRIETOR
                            - LLC
                            - NONPROFIT
                          example: CORPORATION
                        beneficial_owners:
                          type: array
                          description: Los beneficiarios finales de la entidad empresarial.
                          items:
                            type: object
                            required:
                              - first_name
                              - last_name
                              - email
                              - date_of_birth
                              - country_of_residence
                              - ownership_percentage
                            properties:
                              first_name:
                                type: string
                                description: El nombre del propietario.
                                example: Jane
                              last_name:
                                type: string
                                description: El apellido del propietario.
                                example: Smith
                              email:
                                type: string
                                description: La dirección de email del propietario.
                                example: jane@acme.com
                              date_of_birth:
                                type: string
                                description: >-
                                  La fecha de nacimiento del propietario
                                  (YYYY-MM-DD).
                                example: '1985-03-20'
                              gender:
                                type: string
                                description: El género del propietario.
                                enum:
                                  - MALE
                                  - FEMALE
                                  - OTHER
                                example: FEMALE
                              country_of_residence:
                                type: string
                                description: >-
                                  El país de residencia del propietario ([ISO
                                  3166-1
                                  alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
                                example: US
                              tax_information:
                                type: array
                                description: >-
                                  Registros de identificación fiscal del
                                  propietario.
                                items:
                                  type: object
                                  properties:
                                    country:
                                      type: string
                                      description: >-
                                        El código del país de la jurisdicción
                                        fiscal.
                                      example: US
                                    tax_id:
                                      type: string
                                      description: El número de identificación fiscal.
                                      example: 987-65-4321
                                    tax_id_type:
                                      type: string
                                      description: El tipo de identificación fiscal.
                                      enum:
                                        - SSN
                                        - EIN
                                        - ITIN
                                        - VAT
                                        - ABN
                                        - NIF
                                        - TIN
                                        - OTHER
                                      example: SSN
                                    is_primary:
                                      type: boolean
                                      description: >-
                                        Indica si es la residencia fiscal
                                        principal.
                                      example: true
                              document:
                                type: object
                                description: >-
                                  El documento de identificación principal del
                                  propietario.
                                properties:
                                  document_type:
                                    type: string
                                    description: El tipo de documento de identidad.
                                    example: SSN
                                  document_number:
                                    type: string
                                    description: El número del documento.
                                    example: 987-65-4321
                                  issuing_country:
                                    type: string
                                    description: El país que emitió el documento.
                                    example: US
                                  issuing_date:
                                    type: string
                                    nullable: true
                                    description: >-
                                      La fecha de emisión del documento
                                      (YYYY-MM-DD).
                                    example: '2005-03-20'
                                  expiry_date:
                                    type: string
                                    nullable: true
                                    description: >-
                                      La fecha de vencimiento del documento
                                      (YYYY-MM-DD).
                                    example: null
                              ownership_percentage:
                                type: number
                                description: >-
                                  El porcentaje de participación en la empresa
                                  (0-100).
                                example: 100
                              title:
                                type: string
                                description: >-
                                  El cargo o rol del propietario en la
                                  organización.
                                example: CEO
                              address:
                                type: object
                                description: El domicilio del propietario.
                                properties:
                                  address_line_1:
                                    type: string
                                    description: La dirección principal (calle).
                                    example: 789 Oak St
                                  address_line_2:
                                    type: string
                                    nullable: true
                                    description: La segunda línea de la dirección.
                                    example: null
                                  building_number:
                                    type: string
                                    nullable: true
                                    description: El número principal del edificio.
                                    example: '789'
                                  city:
                                    type: string
                                    description: El nombre de la ciudad.
                                    example: San Francisco
                                  state:
                                    type: string
                                    description: El estado o la provincia.
                                    example: CA
                                  zip_code:
                                    type: string
                                    description: El código postal.
                                    example: '94103'
                                  country:
                                    type: string
                                    description: >-
                                      El código de país ([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
                  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'
              Create Entity:
                summary: Create Entity
                value:
                  account_id: 550e8400-e29b-41d4-a716-446655440000
                  merchant_entity_id: merchant_company_789
                  entity_type: BUSINESS
                  phone:
                    country_code: '+1'
                    number: '4155551234'
                  address:
                    address_line_1: 456 Market St
                    address_line_2: null
                    building_number: '456'
                    city: San Francisco
                    state: CA
                    zip_code: '94102'
                    country: US
                  entity_detail:
                    business:
                      business_name: Acme Corporation Inc
                      country: US
                      tax_information:
                        - country: US
                          tax_id: 12-3456789
                          tax_id_type: EIN
                          is_primary: true
                      business_type: CORPORATION
                      beneficial_owners:
                        - first_name: Jane
                          last_name: Smith
                          email: jane@acme.com
                          date_of_birth: '1985-03-20'
                          gender: FEMALE
                          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
                            issuing_date: '2005-03-20'
                            expiry_date: null
                          ownership_percentage: 100
                          title: CEO
                          address:
                            address_line_1: 789 Oak St
                            address_line_2: null
                            building_number: '789'
                            city: San Francisco
                            state: CA
                            zip_code: '94103'
                            country: US
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 770e8400-e29b-41d4-a716-446655440000
                  account_id:
                    type: string
                    example: 550e8400-e29b-41d4-a716-446655440000
                  merchant_entity_id:
                    type: string
                    example: merchant_company_789
                  entity_type:
                    type: string
                    example: BUSINESS
                  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:
                        type: string
                        example: '456'
                      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: {}
                      business:
                        type: object
                        properties:
                          business_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_last4:
                                  type: string
                                  example: '*******6789'
                                tax_id_type:
                                  type: string
                                  example: EIN
                                is_primary:
                                  type: boolean
                                  example: true
                                  default: true
                          business_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: FEMALE
                                country_of_residence:
                                  type: string
                                  example: US
                                tax_information:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      country:
                                        type: string
                                        example: US
                                      tax_id_last4:
                                        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_last4:
                                      type: string
                                      example: '*******4321'
                                    issuing_country:
                                      type: string
                                      example: US
                                    issuing_date:
                                      type: string
                                      example: '2005-03-20'
                                    expiry_date: {}
                                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:
                                      type: string
                                      example: '789'
                                    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: 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'
                Created (Entity):
                  summary: Created (Entity)
                  value:
                    id: 770e8400-e29b-41d4-a716-446655440000
                    account_id: 550e8400-e29b-41d4-a716-446655440000
                    merchant_entity_id: merchant_company_789
                    entity_type: BUSINESS
                    phone:
                      country_code: '+1'
                      number: '4155551234'
                    address:
                      address_line_1: 456 Market St
                      address_line_2: null
                      building_number: '456'
                      city: San Francisco
                      state: CA
                      zip_code: '94102'
                      country: US
                    entity_detail:
                      individual: null
                      business:
                        business_name: Acme Corporation Inc
                        country: US
                        tax_information:
                          - country: US
                            tax_id_last4: '*******6789'
                            tax_id_type: EIN
                            is_primary: true
                        business_type: CORPORATION
                        beneficial_owners:
                          - first_name: Jane
                            last_name: Smith
                            email: jane@acme.com
                            date_of_birth: '1985-03-20'
                            gender: FEMALE
                            country_of_residence: US
                            tax_information:
                              - country: US
                                tax_id_last4: '*******4321'
                                tax_id_type: SSN
                                is_primary: true
                            document:
                              document_type: SSN
                              document_number_last4: '*******4321'
                              issuing_country: US
                              issuing_date: '2005-03-20'
                              expiry_date: null
                            ownership_percentage: 100
                            title: CEO
                            address:
                              address_line_1: 789 Oak St
                              address_line_2: null
                              building_number: '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'
          description: Creado (individuo)
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_PARAMETERS
                  messages:
                    type: array
                    items:
                      type: string
                      example: The field 'entity_type' is required.
                  http_code:
                    type: integer
                    example: 400
                    default: 0
              examples:
                Missing entity_type:
                  summary: Missing entity_type
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - The field 'entity_type' is required.
                    http_code: 400
                Invalid gender:
                  summary: Invalid gender
                  value:
                    code: VALIDATION_ERROR
                    messages:
                      - >-
                        Invalid value 'M' on json field:
                        'entity_detail.individual.gender'
                    http_code: 400
                Entity detail mismatch:
                  summary: Entity detail mismatch
                  value:
                    code: ENTITY_DETAIL_MISMATCH
                    messages:
                      - >-
                        entity_detail must match entity_type: provide
                        'individual' for INDIVIDUAL or 'business' for BUSINESS.
                    http_code: 400
          description: Solicitud incorrecta
        '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: Conflicto
components:
  securitySchemes:
    public-api-key:
      type: apiKey
      in: header
      name: public-api-key
    private-secret-key:
      type: apiKey
      in: header
      name: private-secret-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.