> ## Documentation Index > Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an ultimate payor > Register the business one of your sub-clients pays on behalf of, and start its anti-money-laundering screening. The screening finishes after this call returns. [How a payor clears](/reference/ultimate-payors/the-ultimate-payor-object#how-a-payor-clears) says how to follow it. This call takes no idempotency key, and every call registers a new payor. If you never got the answer to one, look for the payor with [List ultimate payors](/api-reference/ultimate-payors/list-ultimate-payors) before you send it again. ## OpenAPI ````yaml /openapi/kira-api.2026-06-01.json post /v1/ultimate-payors openapi: 3.1.0 info: title: Kira API version: '2026-06-01' description: >- REST API for users, KYC/KYB verification, virtual accounts, payouts, recipients, and webhooks. Every request except the token call needs a bearer access token (see Authentication). Pin your account to the recommended version before integrating (see [Versioning](/using-the-api/versioning)). contact: name: Kira API Support email: support@kirafin.ai servers: - url: https://api.balampay.com description: Production - url: https://api.balampay.com/sandbox description: Sandbox security: - bearerAuth: [] tags: - name: Authentication - name: Versioning - name: Users - name: Virtual Accounts - name: Recipients - name: Quotations - name: Payouts - name: Ultimate Payors - name: Capabilities - name: Reference - name: RFIs paths: /v1/ultimate-payors: post: tags: - Ultimate Payors summary: Create an ultimate payor description: >- Register the business one of your sub-clients pays on behalf of, and start its anti-money-laundering screening. The screening finishes after this call returns. [How a payor clears](/reference/ultimate-payors/the-ultimate-payor-object#how-a-payor-clears) says how to follow it. This call takes no idempotency key, and every call registers a new payor. If you never got the answer to one, look for the payor with [List ultimate payors](/api-reference/ultimate-payors/list-ultimate-payors) before you send it again. operationId: post_v1-ultimate-payors parameters: - in: header name: X-Api-Version required: false description: >- Version applied to this request. It wins over your account's pinned version — see [Versioning](/using-the-api/versioning). schema: type: string example: '2026-06-01' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUltimatePayorRequest' example: legal_name: Acme Holdings LLC city: New York country: USA sub_client_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee responses: '201': description: >- The payor is registered. Read `status` to know whether its screening started. content: application/json: schema: $ref: '#/components/schemas/CreateUltimatePayorResponse' examples: verifying: summary: The screening started value: id: b6f1c1a4-0c57-4a51-9d0f-6d2b3c1e9a10 status: verifying failed: summary: The screening could not start value: id: b6f1c1a4-0c57-4a51-9d0f-6d2b3c1e9a10 status: failed '400': description: >- A field is missing or invalid. Nothing is saved. `details` holds one line per problem, every problem at once. content: application/json: schema: $ref: '#/components/schemas/UltimatePayorErrorResponse' example: error: ValidationError message: 'the request is invalid: 2 fields rejected' details: - legal_name should not be empty - country must be a valid ISO31661 Alpha3 code '401': description: >- No valid bearer token came with the request. Get one from [Get access token](/api-reference/authentication/get-access-token) and send it as `Authorization: Bearer `. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: invalid_request message: >- The request was not authenticated. Request a token at POST /auth with your Client ID and your API key, then send it as Authorization: Bearer . '403': description: >- The payor cannot be registered for this sub-client. Nothing is saved. Read `message` for the cause. content: application/json: schema: $ref: '#/components/schemas/UltimatePayorErrorResponse' examples: not_your_sub_client: summary: The sub-client is not yours value: error: ForbiddenError message: sub-client does not belong to the client not_enabled: summary: The sub-client does not hold the `pobo` capability value: error: ForbiddenError message: sub-client does not hold the POBO capability api_key_role: summary: Your API key's role cannot write sub-clients value: error: ForbiddenException message: This API key does not allow this action '500': description: >- Something failed on our side. Retry, and if it keeps happening contact your Kira contact with the time of the call. content: application/json: schema: $ref: '#/components/schemas/UltimatePayorErrorResponse' example: error: InternalError message: an unexpected error occurred security: - bearerAuth: [] apiKeyAuth: [] servers: - url: https://api.balampay.com/sandbox description: Sandbox - url: https://api.balampay.com description: Production components: schemas: CreateUltimatePayorRequest: type: object description: Any other field is ignored. required: - legal_name - city - country - sub_client_id properties: legal_name: type: string minLength: 1 description: >- The payor's legal name, as the screening should check it. Spaces around it are trimmed. example: Acme Holdings LLC city: type: string minLength: 1 description: The city the payor is based in. Spaces around it are trimmed. example: New York country: type: string pattern: ^[A-Za-z]{3}$ description: >- The payor's country, as an ISO 3166-1 alpha-3 code. Any case is accepted, and it is stored upper-cased. example: USA sub_client_id: type: string format: uuid description: >- The `user_id` of the sub-client that pays on this payor's behalf. The sub-client has to hold the `pobo` capability — see [Request a capability](/api-reference/capabilities/request-a-capability). example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee CreateUltimatePayorResponse: type: object properties: id: type: string format: uuid description: >- The payor's identifier. Send it as `ultimate_payor_id` on a payout made on its behalf. status: type: string description: >- How far the screening got before this call returned. Available options: `verifying`, `failed` — see [Values](/reference/ultimate-payors/values#status). UltimatePayorErrorResponse: type: object properties: error: type: string description: The kind of error. message: type: string description: What went wrong, in one sentence. details: type: array description: One line per rejected value. Only on a `400`. items: type: string ErrorResponse: type: object properties: message: type: string code: type: string statusCode: type: number error: type: string timestamp: type: string path: type: string details: {} required: - message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The `data.access_token` value from [Get access token](/api-reference/authentication/get-access-token). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.