> ## Documentation Index > Fetch the complete documentation index at: https://docs.capa.fi/llms.txt > Use this file to discover all available pages before exploring further. # Request Beneficial Owner Signatures > Idempotent: an owner with an outstanding or completed cédula is left untouched and their existing state returned, so calling this again never produces a second link for the same owner. A failure for one owner does not affect the others — each carries its own status. Capa sends no email, so delivering each signingUrl to its owner is the caller's responsibility. Requests a cédula (beneficial owner declaration) signing link for every `UBO`-role associated person on record for a business user who doesn't already have one. See [Associated Person Signature](/docs/associated-person-signature) for the full flow. *** ## Important Notes * **MX only.** `country` must be `MX` — the cédula's legal basis (art. 95 Bis LGOAAC) is Mexico-specific. * **Idempotent.** An owner with an outstanding (`PENDING`) or completed (`SIGNED`) cédula is left untouched; their existing state is returned rather than a new link being issued. Calling this repeatedly never produces a second link for the same owner. * **Partial failure is per-owner.** A failure for one owner (e.g. missing email) doesn't block the others — each result carries its own `status`/`error`. * **Capa sends no email.** Delivering each `signingUrl` to its owner is the caller's responsibility. Treat `signingUrl` as sensitive — anyone holding it can sign as that owner. * The business must be KYB-verified for `MX` and have at least one `UBO`-role associated person on record, and at most 25. * Every `UBO` must have an `email` set — otherwise that owner's entry in the response carries an `error`/`errorCode` instead of a `signingUrl`. * Supports an optional `Idempotency-Key` header (16–128 printable ASCII characters) to protect against duplicate submissions from client-side retries. *** ## Error Codes ### Common Errors | HTTP Status | Code | Message | | ----------- | ---------------------- | ---------------------------------- | | 401 | `UNAUTHORIZED` | "API Key is missing" | | 401 | `UNAUTHORIZED` | "Invalid API Key format" | | 401 | `UNAUTHORIZED` | "Invalid API Key" | | 403 | `INVALID_PARTNER_FLOW` | "The partner has an invalid flow." | ### User Ownership Errors | HTTP Status | Code | Message | | ----------- | -------------- | ---------------------------------------------------- | | 401 | `UNAUTHORIZED` | "Partner information is required for this operation" | | 401 | `UNAUTHORIZED` | "User is not associated with the partner" | ### Endpoint-Specific Errors | HTTP Status | Code | Message | | ----------- | -------------------------- | ---------------------------------------------------------------------------------- | | 400 | `INVALID_USER_INPUT_ERROR` | "Invalid User Input" | | 403 | `USER_NOT_VERIFIED_ERROR` | "Business KYB verification is not verified for this country" | | 404 | `NOT_FOUND_ERROR` | "No business identity found for user" | | 422 | `UNPROCESSABLE_ENTITY` | "Business has no beneficial owners on record" | | 422 | `UNPROCESSABLE_ENTITY` | "Business reports more than 25 beneficial owners" | | 422 | `UNPROCESSABLE_ENTITY` | "The beneficial-owner cédula is only available for MX; {country} is not supported" | | 500 | `INTERNAL_SERVER_ERROR` | "Internal server error" | ## OpenAPI ````yaml reference/openapi/AssociatedPersonPartnerControllerV2_requestUboFormSignatures.json POST /api/partner/v2/users/{userId}/associated-persons/signatures openapi: 3.0.0 info: title: Capa Partner API - V2 description: >- Partner API for integrating cryptocurrency on-ramp and off-ramp services using Capa's infrastructure. Enable your users to seamlessly convert between fiat and crypto. version: v2 contact: {} servers: - url: https://api.sandbox.capa.fi - url: https://production-api.capa.fi security: [] paths: /api/partner/v2/users/{userId}/associated-persons/signatures: post: tags: - users summary: >- Request a signature link for each beneficial owner who does not already have one description: >- Idempotent: an owner with an outstanding or completed cédula is left untouched and their existing state returned, so calling this again never produces a second link for the same owner. A failure for one owner does not affect the others — each carries its own status. Capa sends no email, so delivering each signingUrl to its owner is the caller's responsibility. operationId: AssociatedPersonPartnerControllerV2_requestUboFormSignatures parameters: - name: userId required: true in: path description: The user's Capa ID schema: type: string format: uuid - name: Idempotency-Key required: false in: header description: >- Optional. 16–128 printable ASCII characters. A repeated request with the same key and body replays the original response instead of processing twice. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: country: type: string description: >- The regime requiring the cédula — the country the business's KYB was verified under. Only MX is currently supported (the cédula's legal basis, art. 95 Bis LGOAAC, is Mexico-specific). example: MX required: - country x-readme-ref-name: RequestUboFormSignaturesBody responses: '201': description: >- One result per beneficial owner: newly requested, already outstanding/complete, or failed. content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: count: type: number description: Number of beneficial owners matching the query total: type: number description: Number of beneficial owners on record data: type: array items: type: object properties: associatedPersonId: type: string format: uuid description: >- The beneficial owner this cédula belongs to — the same id returned by GET /users/{userId}/associated-persons name: type: string description: The beneficial owner's full name status: type: string enum: - PENDING - SIGNED - EXPIRED - DELETED description: >- Absent when no cédula has been requested for this owner, or when requesting one failed — see error. PENDING means requested and awaiting their signature; SIGNED means complete. signingUrl: type: string description: >- Where the owner completes and signs the form. Present only while PENDING, and withheld once SIGNED. Capa sends no email, so delivering this to the owner is entirely the caller's responsibility — and anyone holding it can sign as that owner, so it should not be logged or shared beyond them. signedAt: type: string format: date-time description: When the owner signed. error: type: string description: >- Why this owner has no cédula on record, when requesting one failed — for example no email address on file. errorCode: type: string description: >- A stable code for the same failure, so it can be handled without matching on the message. required: - associatedPersonId - name x-readme-ref-name: AssociatedPersonSignatureHttpResponse required: - count - total - data x-readme-ref-name: ListAssociatedPersonSignaturesHttpResponse '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: INVALID_USER_INPUT_ERROR: value: success: false code: INVALID_USER_INPUT_ERROR message: Invalid User Input '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: UNAUTHORIZED: value: success: false code: UNAUTHORIZED message: API Key is missing UNAUTHORIZED_2: value: success: false code: UNAUTHORIZED message: Invalid API Key format UNAUTHORIZED_3: value: success: false code: UNAUTHORIZED message: Invalid API Key UNAUTHORIZED_4: value: success: false code: UNAUTHORIZED message: Partner information is required for this operation UNAUTHORIZED_5: value: success: false code: UNAUTHORIZED message: User is not associated with the partner '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false code: USER_NOT_VERIFIED_ERROR message: Business KYB verification is not verified for this country '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false code: NOT_FOUND_ERROR message: No business identity found for user '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: UNPROCESSABLE_ENTITY: value: success: false code: UNPROCESSABLE_ENTITY message: Business has no beneficial owners on record UNPROCESSABLE_ENTITY_2: value: success: false code: UNPROCESSABLE_ENTITY message: Business reports more than 25 beneficial owners UNPROCESSABLE_ENTITY_3: value: success: false code: UNPROCESSABLE_ENTITY message: >- The beneficial-owner cédula is only available for MX; {country} is not supported '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false code: INTERNAL_SERVER_ERROR message: Internal server error security: - PartnerApiKey: [] components: schemas: ErrorResponse: type: object properties: success: type: boolean example: false code: type: string description: Machine-readable error code. message: type: string description: Human-readable error message. errors: type: array description: Optional per-field validation details. items: type: object properties: field: type: string message: type: string required: - success - code - message securitySchemes: PartnerApiKey: type: apiKey in: header name: partner-api-key description: API key for the affiliated partner performing the request. ````