> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumx.io/llms.txt > Use this file to discover all available pages before exploring further. # Create an associated party > This endpoint creates an associated party (UBO, shareholder, or representative) for a business customer. ## OpenAPI ````yaml /openapi/api-production.yaml post /customers/{id}/associated-parties openapi: 3.1.0 info: version: 1.0.0 title: Lumx API description: >- A cross-border banking API with instant settlements and unmatched liquidity, powered by stablecoins. servers: - url: https://api.lumx.io - url: https://api-sandbox.lumx.io security: [] paths: /customers/{id}/associated-parties: post: tags: - Customers summary: Create an associated party description: >- This endpoint creates an associated party (UBO, shareholder, or representative) for a business customer. parameters: - name: id in: path required: true schema: type: string format: uuid description: Customer's unique identifier. - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: examples: UBO: $ref: '#/components/examples/AssociatedPartyUBOExample' ShareholderIndividual: $ref: >- #/components/examples/AssociatedPartyShareholderIndividualExample ShareholderBusiness: $ref: >- #/components/examples/AssociatedPartyShareholderBusinessExample Representative: $ref: '#/components/examples/AssociatedPartyRepresentativeExample' schema: $ref: '#/components/schemas/AssociatedPartyRequest' responses: '201': description: Associated party successfully created. content: application/json: examples: UBO: $ref: '#/components/examples/AssociatedPartyUBOResponseExample' schema: $ref: '#/components/schemas/AssociatedPartyResponse' security: - apiKey: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string format: uuid description: >- Optional UUID v4 idempotency key. If you resend the same key with a different request body, the API returns a 409 error. Cached responses include the header `X-Idempotency-Cached: true`. Keys expire after 24 hours. examples: AssociatedPartyUBOExample: value: type: INDIVIDUAL roles: - UBO name: Maria Santos birthDate: '1985-07-10' email: maria.santos@example.com taxId: 987.654.321-00 address: country: BRA line1: Rua das Acácias, 456 city: Rio de Janeiro state: RJ postalCode: 20000-000 ownershipPercentage: 40 AssociatedPartyShareholderIndividualExample: value: type: INDIVIDUAL roles: - SHAREHOLDER name: Pedro Oliveira birthDate: '1978-12-05' email: pedro.oliveira@example.com taxId: 111.222.333-44 address: country: BRA line1: Av. Brasil, 789 city: São Paulo state: SP postalCode: 01000-000 ownershipPercentage: 35 AssociatedPartyShareholderBusinessExample: value: type: BUSINESS roles: - SHAREHOLDER legalName: Investment Fund ABC incorporationDate: '2010-05-20' email: contact@fundabc.com taxId: 99.988.877/0001-66 address: country: USA line1: 123 Wall Street city: New York state: NY postalCode: '10005' ownershipPercentage: 25 AssociatedPartyRepresentativeExample: value: type: INDIVIDUAL roles: - REPRESENTATIVE name: Carlos Mendes birthDate: '1990-03-15' email: carlos.mendes@example.com taxId: 555.666.777-88 address: country: BRA line1: Rua Principal, 100 city: Belo Horizonte state: MG postalCode: 30000-000 AssociatedPartyUBOResponseExample: value: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: INDIVIDUAL roles: - UBO name: Maria Santos taxId: 987.654.321-00 birthDate: '1985-07-10' email: maria.santos@example.com address: country: BRA line1: Rua das Acácias, 456 city: Rio de Janeiro state: RJ postalCode: 20000-000 ownershipPercentage: 40 verification: status: NOT_STARTED level: STANDARD link: https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44 createdAt: '2024-01-15T11:00:00Z' updatedAt: '2024-01-15T11:00:00Z' schemas: AssociatedPartyRequest: oneOf: - $ref: '#/components/schemas/AssociatedPartyIndividualRequest' - $ref: '#/components/schemas/AssociatedPartyBusinessRequest' AssociatedPartyResponse: oneOf: - $ref: '#/components/schemas/AssociatedPartyIndividualResponse' - $ref: '#/components/schemas/AssociatedPartyBusinessResponse' AssociatedPartyIndividualRequest: title: Individual type: object properties: type: type: string enum: - INDIVIDUAL description: >- Associated party type. Must be INDIVIDUAL for UBO and REPRESENTATIVE roles. roles: type: array items: type: string enum: - UBO - SHAREHOLDER - REPRESENTATIVE description: >- Associated party roles. Can have multiple roles (e.g., both UBO and REPRESENTATIVE). UBO and REPRESENTATIVE must be INDIVIDUAL type. name: type: string description: Full name. example: Maria Santos birthDate: type: string format: date description: Birth date (ISO 8601). example: '1985-07-10' email: type: string format: email description: Email address. example: maria.santos@example.com taxId: type: string description: Tax ID (CPF for Brazil). example: 987.654.321-00 address: $ref: '#/components/schemas/Address' ownershipPercentage: type: number minimum: 25 maximum: 100 description: >- Ownership percentage. Required for UBO and SHAREHOLDER roles (25-100%). example: 40 parentId: type: string format: uuid description: >- Parent associated party ID. Used for multi-level corporate structures, allowing you to nest shareholders across 2, 3, or more levels of ownership hierarchy. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 required: - type - roles - name - birthDate - email - taxId - address AssociatedPartyBusinessRequest: title: Business type: object properties: type: type: string enum: - BUSINESS description: Associated party type. Can only be BUSINESS for SHAREHOLDER role. roles: type: array items: type: string enum: - SHAREHOLDER description: >- Associated party roles. BUSINESS type can only have SHAREHOLDER role. legalName: type: string description: Legal name of the company. example: Investment Fund ABC incorporationDate: type: string format: date description: Incorporation date (ISO 8601). example: '2010-05-20' email: type: string format: email description: Email address. example: contact@fundabc.com taxId: type: string description: Tax ID (CNPJ for Brazil). example: 99.988.877/0001-66 address: $ref: '#/components/schemas/Address' ownershipPercentage: type: number minimum: 25 maximum: 100 description: Ownership percentage (25-100%). example: 25 parentId: type: string format: uuid description: >- Parent associated party ID. Used for multi-level corporate structures, allowing you to nest shareholders across 2, 3, or more levels of ownership hierarchy. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 required: - type - roles - legalName - incorporationDate - email - taxId - address - ownershipPercentage AssociatedPartyIndividualResponse: title: Individual type: object properties: id: type: string format: uuid description: Associated party's unique identifier. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: type: string enum: - INDIVIDUAL roles: type: array items: type: string enum: - UBO - SHAREHOLDER - REPRESENTATIVE name: type: string example: Maria Santos taxId: type: string example: 987.654.321-00 birthDate: type: string format: date example: '1985-07-10' email: type: string format: email example: maria.santos@example.com address: $ref: '#/components/schemas/Address' ownershipPercentage: type: number example: 40 parentId: type: string format: uuid description: >- Parent associated party ID. Used for multi-level corporate structures, allowing you to nest shareholders across 2, 3, or more levels of ownership hierarchy. verification: $ref: '#/components/schemas/CustomerVerification' createdAt: type: string format: date-time example: '2024-01-15T11:00:00Z' updatedAt: type: string format: date-time example: '2024-01-15T11:00:00Z' AssociatedPartyBusinessResponse: title: Business type: object properties: id: type: string format: uuid description: Associated party's unique identifier. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: type: string enum: - BUSINESS roles: type: array items: type: string enum: - SHAREHOLDER legalName: type: string example: Investment Fund ABC taxId: type: string example: 99.988.877/0001-66 incorporationDate: type: string format: date example: '2010-05-20' email: type: string format: email example: contact@fundabc.com address: $ref: '#/components/schemas/Address' ownershipPercentage: type: number example: 25 parentId: type: string format: uuid description: >- Parent associated party ID. Used for multi-level corporate structures, allowing you to nest shareholders across 2, 3, or more levels of ownership hierarchy. verification: $ref: '#/components/schemas/CustomerVerification' createdAt: type: string format: date-time example: '2024-01-15T11:00:00Z' updatedAt: type: string format: date-time example: '2024-01-15T11:00:00Z' Address: type: object description: Address information. properties: country: type: string description: Country code (ISO 3166-1 alpha-3). example: BRA line1: type: string description: Street address. example: Rua das Flores, 123 city: type: string description: City name. example: São Paulo state: type: string description: State or province code. example: SP postalCode: type: string description: Postal or ZIP code. example: 01234-567 required: - country - line1 - city - state - postalCode CustomerVerification: type: object description: Customer's verification. properties: status: type: string description: Verification status. enum: - NOT_STARTED - UNDER_VERIFICATION - APPROVED - TEMPORARY_REJECTION - FINAL_REJECTION example: NOT_STARTED level: type: string description: Verification level. enum: - STANDARD example: STANDARD link: type: string description: Verification link. example: https://in.sumsub.com/websdk/p/sbx_aA00bB11cC33dD44 securitySchemes: apiKey: type: http scheme: bearer description: Bearer authentication header on the format `Bearer `. ````