> ## 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 user object

A user is the account holder Kira verifies and holds products for — the business you onboard. Every other resource hangs off one: virtual accounts, recipients and payouts all belong to a user.

Elsewhere on this site a user is called a **sub-client**. Same object, two names — see [Sub-client](/overview/model/sub-client).

Which fields come back depends on what the user is and how far verification has got. A field that does not apply is **absent**, not `null` — the two exceptions are called out below.

## Example

```json theme={null}
{
  "id": "e687484f-74ef-43a8-a68a-5bf78aa2e721",
  "type": "business",
  "email": "ops@example.com",
  "status": "CREATED",
  "verification_status": "unverified",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "verification_mode": "automatic",
  "capabilities": { "requested_banks": [] },
  "metadata": {},
  "formation_country": "USA",
  "business_legal_name": "Northwind Trading LLC",
  "registered_address": {
    "street_line_1": "1 Market Street",
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "identifying_information": [ ... ],
  "associated_persons": [ ... ],
  "eligible_products": [ ... ],
  "missing_fields": { ... }
}
```

## Always present

| Field                 | Type              | Description                                                                                                    |
| --------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `id`                  | string, uuid      | The user's identifier. Every other call that touches this user takes it.                                       |
| `type`                | string            | Whether the account holder is a company or a person. [Values](/reference/users/values#type)                    |
| `email`               | string, email     | The account holder's email address.                                                                            |
| `status`              | string            | Where the user sits in its lifecycle. Uppercase. [Values](/reference/users/values#status)                      |
| `verification_status` | string            | The result of the identity or business check. Lowercase. [Values](/reference/users/values#verification_status) |
| `created_at`          | string, date-time | When the user was created, ISO 8601.                                                                           |
| `updated_at`          | string, date-time | When the user last changed, ISO 8601.                                                                          |
| `verification_mode`   | string            | How verification is run for this user. [Values](/reference/users/values#verification_mode)                     |
| `capabilities`        | object            | Which banks the user has said it needs. Always carries `requested_banks`.                                      |
| `metadata`            | object            | The key-value pairs you stored on this user. `{}` when you stored none — see [Metadata](/reference/metadata).  |

<Note>
  Compare `status` and `verification_status` **case-insensitively** rather than matching exact strings.
</Note>

## Verification link

Present only while the user is verified through a hosted link.

| Field                              | Type   | Description                                                                                                |
| ---------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `verification_link`                | string | The hosted verification URL. Absent in automatic mode.                                                     |
| `verification_link_error`          | string | A plain-text note about something the request could not finish.                                            |
| `verification_link_error_severity` | string | Whether that note asks anything of you. [Values](/reference/users/values#verification_link_error_severity) |

## On a business

| Field                 | Type            | Description                                                |
| --------------------- | --------------- | ---------------------------------------------------------- |
| `formation_country`   | string          | Where the business was formed, as an ISO **alpha-3** code. |
| `business_legal_name` | string          | The registered legal name.                                 |
| `registered_address`  | object          | The registered legal address.                              |
| `associated_persons`  | array or `null` | The people tied to the business. `null` on a person.       |

## On a person

| Field                 | Type   | Description                                                                   |
| --------------------- | ------ | ----------------------------------------------------------------------------- |
| `first_name`          | string | Given name.                                                                   |
| `last_name`           | string | Family name.                                                                  |
| `middle_name`         | string | Middle name, when provided.                                                   |
| `phone`               | string | Contact phone in E.164 form.                                                  |
| `birth_date`          | string | Date of birth, `YYYY-MM-DD`.                                                  |
| `nationality`         | string | Nationality, as an ISO **alpha-3** code.                                      |
| `country_of_birth`    | string | Where the person was born, as an ISO **alpha-3** code. Absent when never set. |
| `gender`              | string | `male`, `female` or `other`, when provided.                                   |
| `residential_address` | object | The person's address.                                                         |

## Records and eligibility

| Field                     | Type            | Description                                                                                                                   |
| ------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `identifying_information` | array or `null` | Identity or registration records. `null` when none are stored. [Types](/reference/users/values#identifying_information-types) |
| `eligible_products`       | array           | What the user can already use, product by product. Each entry carries `eligible`, and the gaps when it is `false`.            |
| `missing_fields`          | object          | The gaps that remain, grouped by product code, plus a `general` key holding every token once.                                 |

<Warning>
  `identifying_information` and `associated_persons` are the only two fields that come back as `null`. Both are also **absent** on users whose verification runs through a hosted link — so a client must handle the key being missing, the value being `null`, and the value being a list.
</Warning>