> ## 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. # List ultimate payors > List your ultimate payors, newest first, each with its screening `status`. The list pages by offset — see [Pagination](/reference/pagination#an-offset-object). An empty filter, such as `status=`, is read as if you had left it out. ## OpenAPI ````yaml /openapi/kira-api.2026-06-01.json get /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: get: tags: - Ultimate Payors summary: List ultimate payors description: >- List your ultimate payors, newest first, each with its screening `status`. The list pages by offset — see [Pagination](/reference/pagination#an-offset-object). An empty filter, such as `status=`, is read as if you had left it out. operationId: get_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' - in: query name: limit required: false description: >- How many payors to return. Between `1` and `100`, and `10` when you omit it. A value outside that range is rejected with a `400`. schema: type: integer minimum: 1 maximum: 100 default: 10 - in: query name: offset required: false description: >- How many payors to skip before the first row returned. Use it with `limit` to walk the list: `offset=0`, then `offset=10`, and so on. `0` when you omit it. schema: type: integer minimum: 0 default: 0 - in: query name: sub_client_id required: false description: |- Return only the payors of this sub-client. A sub-client that is not yours returns an empty list, not an error. schema: type: string format: uuid example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee - in: query name: status required: false description: >- Return only the payors whose screening has this status — see [Values](/reference/ultimate-payors/values#status). schema: type: string enum: - created - verifying - verified - failed - rejected - in: query name: search required: false description: >- Return only the payors whose legal name contains this text, in any case. schema: type: string maxLength: 100 responses: '200': description: A page of your payors. content: application/json: schema: $ref: '#/components/schemas/UltimatePayorListResponse' example: data: - id: b6f1c1a4-0c57-4a51-9d0f-6d2b3c1e9a10 legal_name: Acme Holdings LLC city: New York country: USA sub_client_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee status: verified created_at: '2026-10-08T12:00:00.000Z' updated_at: '2026-10-08T12:00:00.000Z' pagination: total: 23 limit: 10 offset: 0 has_more: true '400': description: >- A query parameter is out of range. `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: - limit must be at least 1 - >- status must be one of created, verifying, verified, failed, rejected '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 . '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: UltimatePayorListResponse: type: object properties: data: type: array description: The payors on this page, newest first. items: $ref: '#/components/schemas/UltimatePayor' pagination: type: object properties: total: type: integer description: How many payors match your filters, across every page. limit: type: integer description: The page size used. offset: type: integer description: How many payors were skipped. has_more: type: boolean description: '`true` while another page follows.' 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 UltimatePayor: type: object description: >- A business one of your sub-clients pays on behalf of — see [The ultimate payor object](/reference/ultimate-payors/the-ultimate-payor-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. legal_name: type: string description: The payor's legal name. city: type: string description: The city the payor is based in. country: type: string description: The payor's country, as an upper-case ISO 3166-1 alpha-3 code. sub_client_id: type: string format: uuid description: The `user_id` of the sub-client that pays on this payor's behalf. status: type: - string - 'null' description: >- The status of the payor's screening, which decides whether a payout can go out on its behalf — see [Values](/reference/ultimate-payors/values#status). Available options: `verifying`, `verified`, `failed`, `rejected`. `null` when the payor has no screening. created_at: type: string format: date-time description: When the payor was registered, ISO 8601. updated_at: type: string format: date-time description: >- When the payor itself last changed, ISO 8601. A new screening status does not change it. 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.