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

# The ultimate payor object

> The business a sub-client pays on behalf of, and the screening that decides whether it can be paid for.

An ultimate payor is the business one of your sub-clients pays on behalf of. You register it once for that sub-client. Kira screens it against anti-money-laundering lists, and you name it on every payout the sub-client makes on its behalf.

A sub-client has to hold the `pobo` capability before it can have an ultimate payor. [Request a capability](https://docs.kirafin.ai/api-reference/capabilities/request-a-capability.md) is how it gets one.

## Example

```json theme={null}
{
  "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"
}
```

## Fields

| Field | Type | Description |
| - | - | - |
| `id` | string, uuid | The payor's identifier. Send it as `ultimate_payor_id` on a payout made on its behalf. |
| `legal_name` | string | The payor's legal name. |
| `city` | string | The city the payor is based in. |
| `country` | string | The payor's country, as an upper-case ISO 3166-1 alpha-3 code. |
| `sub_client_id` | string, uuid | The `user_id` of the sub-client that pays on this payor's behalf. |
| `status` | string or `null` | The status of the payor's screening. `null` when the payor has no screening. [Values](https://docs.kirafin.ai/reference/ultimate-payors/values.md#status) |
| `created_at` | string, date-time | When the payor was registered, ISO 8601. |
| `updated_at` | string, date-time | When the payor itself last changed, ISO 8601. A new screening status does not change it. |

## How a payor clears

The screening starts when you create the payor, and it finishes after that call has returned.

1. [Create an ultimate payor](https://docs.kirafin.ai/api-reference/ultimate-payors/create-an-ultimate-payor.md). The answer carries the payor's `id` and its first `status`: `verifying` when the check started, `failed` when it could not start.
2. Read `status` with [Get an ultimate payor](https://docs.kirafin.ai/api-reference/ultimate-payors/get-an-ultimate-payor.md) until it reaches a verdict. No webhook reports the screening.
3. Make the payout on the payor's behalf once `status` is `verified`. While it holds any other value, a payout naming the payor is refused.

A `verified` payor can still become `rejected` later, so a payor that cleared once is not cleared for good. Payouts naming it are refused from then on.


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