# Schemas

> Shared request and response objects of the REST API.

Source: https://docs.okyc.stream/reference/api/schemas

### CreatedSession

| Field          | Type                                                                                                                                                    | Required | Notes |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----- |
| `id`           | `string`                                                                                                                                                | yes      | —     |
| `status`       | `created` \| `started` \| `in_progress` \| `processing` \| `approved` \| `declined` \| `review` \| `resubmission_requested` \| `expired` \| `cancelled` | yes      | —     |
| `url`          | `string`                                                                                                                                                | yes      | —     |
| `client_token` | `string`                                                                                                                                                | yes      | —     |
| `expires_at`   | `string`                                                                                                                                                | yes      | —     |

### Error

| Field              | Type     | Required | Notes |
| ------------------ | -------- | -------- | ----- |
| `error`            | `object` | yes      | —     |
| `error.type`       | `string` | yes      | —     |
| `error.code`       | `string` | yes      | —     |
| `error.message`    | `string` | yes      | —     |
| `error.param`      | `string` |          | —     |
| `error.details`    | any      |          | —     |
| `error.request_id` | `string` |          | —     |

### CreateSession

| Field               | Type         | Required | Notes                                                      |
| ------------------- | ------------ | -------- | ---------------------------------------------------------- |
| `workflow_id`       | `string`     | yes      | —                                                          |
| `reference_id`      | `string`     |          | Your user's id — max length 128                            |
| `country`           | `string`     |          | Applicant's country; defaults to the workflow's — length 2 |
| `prefill`           | `object`     |          | —                                                          |
| `prefill.phone`     | `string`     |          | —                                                          |
| `prefill.email`     | `string`     |          | format `email`                                             |
| `prefill.full_name` | `string`     |          | —                                                          |
| `locale`            | `string`     |          | —                                                          |
| `redirect_url`      | `string`     |          | format `uri`                                               |
| `metadata`          | object (map) |          | —                                                          |
| `expires_in`        | `integer`    |          | Seconds — min 300, max 2592000                             |

### Session

| Field                       | Type                                                                                                                                                    | Required | Notes                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `id`                        | `string`                                                                                                                                                | yes      | —                                                                           |
| `object`                    | `session`                                                                                                                                               | yes      | —                                                                           |
| `mode`                      | `test` \| `live`                                                                                                                                        | yes      | —                                                                           |
| `type`                      | `kyc` \| `kyb`                                                                                                                                          | yes      | —                                                                           |
| `status`                    | `created` \| `started` \| `in_progress` \| `processing` \| `approved` \| `declined` \| `review` \| `resubmission_requested` \| `expired` \| `cancelled` | yes      | —                                                                           |
| `country`                   | `string`                                                                                                                                                | yes      | —                                                                           |
| `workflow_id`               | `string`                                                                                                                                                | yes      | —                                                                           |
| `reference_id`              | `string \| null`                                                                                                                                        | yes      | —                                                                           |
| `parent_session_id`         | `string \| null`                                                                                                                                        | yes      | —                                                                           |
| `decision`                  | `string \| null`                                                                                                                                        | yes      | —                                                                           |
| `decision_source`           | `string \| null`                                                                                                                                        | yes      | —                                                                           |
| `steps`                     | object (map)                                                                                                                                            | yes      | —                                                                           |
| `metadata`                  | object (map)                                                                                                                                            | yes      | —                                                                           |
| `expires_at`                | `string`                                                                                                                                                | yes      | —                                                                           |
| `created_at`                | `string`                                                                                                                                                | yes      | —                                                                           |
| `completed_at`              | `string \| null`                                                                                                                                        | yes      | —                                                                           |
| `checks`                    | [Check](https://docs.okyc.stream/reference/api/schemas.md#check)\[]                                                                                                                |          | —                                                                           |
| `applicant`                 | `object \| null`                                                                                                                                        |          | —                                                                           |
| `business`                  | `object \| null`                                                                                                                                        |          | —                                                                           |
| `related_sessions`          | `object`\[]                                                                                                                                             |          | —                                                                           |
| `related_sessions[].id`     | `string`                                                                                                                                                | yes      | —                                                                           |
| `related_sessions[].role`   | `string \| null`                                                                                                                                        | yes      | —                                                                           |
| `related_sessions[].status` | `string`                                                                                                                                                | yes      | —                                                                           |
| `duplicates`                | `object`\[]                                                                                                                                             | yes      | Earlier sessions in this project that look like the same person or business |
| `duplicates[].session_id`   | `string`                                                                                                                                                | yes      | —                                                                           |
| `duplicates[].signals`      | `string`\[]                                                                                                                                             | yes      | —                                                                           |

### Check

| Field         | Type                             | Required | Notes                                                                                                                                                                                    |
| ------------- | -------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | `string`                         | yes      | —                                                                                                                                                                                        |
| `step`        | `string \| null`                 | yes      | —                                                                                                                                                                                        |
| `capability`  | `string \| null`                 | yes      | —                                                                                                                                                                                        |
| `generic_key` | `string`                         | yes      | —                                                                                                                                                                                        |
| `check_key`   | `string`                         | yes      | —                                                                                                                                                                                        |
| `provider`    | `string \| null`                 | yes      | —                                                                                                                                                                                        |
| `status`      | `string`                         | yes      | —                                                                                                                                                                                        |
| `verified_by` | `source` \| `reviewer` \| `null` | yes      | `source`: the issuing registry or a cryptographic check answered. `reviewer`: provider `manual` — a reviewer compared the uploaded document (no registry call). `null`: not decided yet. |
| `score`       | `number \| null`                 | yes      | —                                                                                                                                                                                        |
| `error_code`  | `string \| null`                 | yes      | —                                                                                                                                                                                        |
| `from_cache`  | `boolean`                        | yes      | —                                                                                                                                                                                        |
| `result`      | `object \| null`                 |          | —                                                                                                                                                                                        |
| `created_at`  | `string`                         | yes      | —                                                                                                                                                                                        |
| `finished_at` | `string \| null`                 | yes      | —                                                                                                                                                                                        |

### Decision

| Field         | Type                                                 | Required | Notes                                           |
| ------------- | ---------------------------------------------------- | -------- | ----------------------------------------------- |
| `outcome`     | `approved` \| `declined` \| `resubmission_requested` | yes      | —                                               |
| `reason_code` | `string`                                             | yes      | max length 64                                   |
| `note`        | `string`                                             |          | max length 2000                                 |
| `steps`       | `string`\[]                                          |          | For resubmission: steps the applicant must redo |

### DirectCheckInput

| Field     | Type     | Required | Notes    |
| --------- | -------- | -------- | -------- |
| `country` | `string` |          | length 2 |

### WebhookEndpointCreate

| Field    | Type        | Required | Notes           |
| -------- | ----------- | -------- | --------------- |
| `url`    | `string`    | yes      | format `uri`    |
| `events` | `string`\[] |          | default `["*"]` |