---
title: "KYB form for an onboarding session"
url: "https://developer.incode.com/api-reference/kyb-form/"
section: "api-reference"
group: "eKYB"
version: "v1.1"
status: "live"
endpoint: "GET /omni/kyb/form"
---
# KYB form for an onboarding session

`GET /omni/kyb/form`

Base URL: `https://demo-api.incodesmile.com` — Incode demo environment

Returns the form to collect the business details for the KYB step of an onboarding session.
Render it as is: which modules run for the country, which fields are shown and required, and
their formats are already decided.

Call it first without `country`: the form has only a country field, listing the countries the
organization can run KYB for. Each time the country changes (the field's `refetchOnChange`), call
it again with `country`: the form then has the fields for that country and a `submit` section
for `POST /omni/kyb`. Modules selected for the step that are not supported for the country are
listed in `context.unsupportedModules`; they are still submitted and come back with a
`notSupported` error.

Texts carry a translation `key` and an English `text` fallback.

## Path & query parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `country` | query | string |  | Country of the business, ISO 3166-1 alpha-2. Omit for the first form. |
| `api-version` | header | string | yes | Default: `1.0` |

## Responses

### 200

The form

Response body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemaVersion` | string |  | Version of this form format. |
| `formId` | string |  | Form identifier. |
| `context` | KybFormContext |  | What the form was built for. |
| `context.country` | string |  | Country of the business, ISO 3166-1 alpha-2. Omitted until a country is chosen. |
| `context.modules` | array[string] |  | Modules selected for this onboarding step. Enum: `identity`, `address`, `statusEntityType`, `personAssociation`, `webPresence`, `websiteAnalysis`, `industryInfo`, `financialIntelligence`, `groupStructure` |
| `context.unsupportedModules` | array[KybFormUnsupportedModule] |  | Selected modules that are not supported for the country. They are still submitted and come back with a notSupported error. |
| `context.unsupportedModules.module` | string |  | The module. Enum: `identity`, `address`, `statusEntityType`, `personAssociation`, `webPresence`, `websiteAnalysis`, `industryInfo`, `financialIntelligence`, `groupStructure` |
| `context.unsupportedModules.message` | KybText |  | Why it does not run. |
| `context.unsupportedModules.message.key` | string |  | Translation key. |
| `context.unsupportedModules.message.text` | string |  | English text, to show when key has no translation. |
| `steps` | array[KybFormStep] |  | Steps, in display order. |
| `steps.id` | string |  | Step identifier. |
| `steps.title` | KybText |  | Step title. |
| `steps.title.key` | string |  | Translation key. |
| `steps.title.text` | string |  | English text, to show when key has no translation. |
| `steps.sections` | array[KybFormSection] |  | Sections, in display order. |
| `steps.sections.id` | string |  | Section identifier. |
| `steps.sections.title` | KybText |  | Section title. Omitted for an untitled section. |
| `steps.sections.title.key` | string |  | Translation key. |
| `steps.sections.title.text` | string |  | English text, to show when key has no translation. |
| `steps.sections.fields` | array[KybFormField] |  | Fields, in display order. |
| `steps.sections.fields.name` | string |  | Field identifier. |
| `steps.sections.fields.type` | string |  | Kind of input: text, select, list or phone. |
| `steps.sections.fields.display` | string |  | Whether the user can edit it. |
| `steps.sections.fields.required` | boolean |  | Whether a value is required to submit. |
| `steps.sections.fields.value` | object |  | Initial value: a string, or an array of strings for a list field. |
| `steps.sections.fields.label` | KybText |  | Field label. |
| `steps.sections.fields.label.key` | string |  | Translation key. |
| `steps.sections.fields.label.text` | string |  | English text, to show when key has no translation. |
| `steps.sections.fields.input` | object |  | Keyboard and length hints for text input. |
| `steps.sections.fields.phone` | object |  | Phone input settings, for a phone field. |
| `steps.sections.fields.options` | array[KybFormOption] |  | Allowed values, for a select field. |
| `steps.sections.fields.options.value` | string |  | Value to submit. |
| `steps.sections.fields.options.label` | KybText |  | Text to show for the value. |
| `steps.sections.fields.rules` | array[KybFormRule] |  | Validation rules, checked in order. |
| `steps.sections.fields.rules.kind` | string |  | Rule kind: required, pattern (regex must match) or requireAnyOf (one of fields must be set). |
| `steps.sections.fields.rules.regex` | string |  | Regular expression, for a pattern rule. |
| `steps.sections.fields.rules.flags` | string |  | Regular expression flags, for a pattern rule. |
| `steps.sections.fields.rules.fields` | array[string] |  | Field names, for a rule across fields. |
| `steps.sections.fields.rules.message` | KybText |  | Message to show when the rule fails. |
| `steps.sections.fields.payload` | KybFormPayload |  | Where the value goes in the submitted body. |
| `steps.sections.fields.payload.key` | string |  | Property name in the request body. |
| `steps.sections.fields.payload.transforms` | array[string] |  | Transforms to apply before submitting, in order: trim or e164. |
| `steps.sections.fields.payload.omitWhenEmpty` | boolean |  | Leave the property out when the value is empty. |
| `steps.sections.fields.refetchOnChange` | string |  | When set, fetch the form again with this query parameter set to the new value whenever the field changes. |
| `rules` | array[KybFormRule] |  | Rules across fields, checked on submit. |
| `rules.kind` | string |  | Rule kind: required, pattern (regex must match) or requireAnyOf (one of fields must be set). |
| `rules.regex` | string |  | Regular expression, for a pattern rule. |
| `rules.flags` | string |  | Regular expression flags, for a pattern rule. |
| `rules.fields` | array[string] |  | Field names, for a rule across fields. |
| `rules.message` | KybText |  | Message to show when the rule fails. |
| `rules.message.key` | string |  | Translation key. |
| `rules.message.text` | string |  | English text, to show when key has no translation. |
| `submit` | KybFormSubmit |  | How to submit the form. Omitted until a country is chosen. |
| `submit.endpoint` | string |  | Endpoint to call. |
| `submit.method` | string |  | HTTP method. |
| `submit.static` | object |  | Properties to add to the body as they are. |
| `submit.onSuccess` | object |  | What to do after a successful call. |
| `submit.onFailure` | object |  | What to do after a failed call. |

### 400

Unknown `country`, or no KYB provider configured for it in this organization

Response body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `timestamp` | integer (int64) |  | UTC timestamp in milliseconds |
| `status` | integer (int32) |  | Custom error code or HTTP status code |
| `error` | string |  | HTTP status error |
| `message` | string |  | Custom error message |
| `path` | string |  | Endpoint path |
| `details` | object |  | Custom error details |

### 401

Missing, invalid or expired session token. The response has no body

### 403

Not an onboarding session token, the session is closed, or KYB is not part of the session's flow or workflow

Response body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `timestamp` | integer (int64) |  | UTC timestamp in milliseconds |
| `status` | integer (int32) |  | Custom error code or HTTP status code |
| `error` | string |  | HTTP status error |
| `message` | string |  | Custom error message |
| `path` | string |  | Endpoint path |
| `details` | object |  | Custom error details |

## Code samples

Generated from this endpoint's method, path, and the conventional Incode headers. The base URL is the Incode demo environment; replace `<YOUR_API_KEY>` with a key for your region.

### cURL

```bash
curl -X GET https://demo-api.incodesmile.com/omni/kyb/form?country=%3Ccountry%3E \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "X-Incode-Hardware-Id: <YOUR_INCODE_HARDWARE_ID>" \
  -H "api-version: 1.0"
```

### Node

```js
const res = await fetch("https://demo-api.incodesmile.com/omni/kyb/form?country=%3Ccountry%3E", {
  method: "GET",
  headers: {
      "x-api-key": "<YOUR_API_KEY>",
      "X-Incode-Hardware-Id": "<YOUR_INCODE_HARDWARE_ID>",
      "api-version": "1.0",
  },
});
const data = await res.json();
```

### Python

```python
import requests

headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "X-Incode-Hardware-Id": "<YOUR_INCODE_HARDWARE_ID>",
    "api-version": "1.0",
}
res = requests.get("https://demo-api.incodesmile.com/omni/kyb/form?country=%3Ccountry%3E", headers=headers)
data = res.json()
```

### Java

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://demo-api.incodesmile.com/omni/kyb/form?country=%3Ccountry%3E"))
    .header("x-api-key", "<YOUR_API_KEY>")
    .header("X-Incode-Hardware-Id", "<YOUR_INCODE_HARDWARE_ID>")
    .header("api-version", "1.0")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
```

### Ruby

```
require "net/http"
require "json"

uri = URI("https://demo-api.incodesmile.com/omni/kyb/form?country=%3Ccountry%3E")
req = Net::HTTP::Get.new(uri)
req["x-api-key"] = "<YOUR_API_KEY>"
req["X-Incode-Hardware-Id"] = "<YOUR_INCODE_HARDWARE_ID>"
req["api-version"] = "1.0"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
```

### PHP

```
$ch = curl_init("https://demo-api.incodesmile.com/omni/kyb/form?country=%3Ccountry%3E");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: <YOUR_API_KEY>",
    "X-Incode-Hardware-Id: <YOUR_INCODE_HARDWARE_ID>",
    "api-version: 1.0",
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);
```

### Example response

```json
{
  "schemaVersion": 1,
  "formId": "kyb",
  "context": {
    "country": "US",
    "modules": [
      "identity"
    ],
    "unsupportedModules": [
      {
        "module": "identity",
        "message": {
          "key": "kyb.fields.businessName.label",
          "text": "Business name"
        }
      }
    ]
  },
  "steps": [
    {
      "id": "business",
      "title": {
        "key": "kyb.fields.businessName.label",
        "text": "Business name"
      },
      "sections": [
        {
          "id": "address",
          "title": {
            "key": "kyb.fields.businessName.label",
            "text": "Business name"
          },
          "fields": [
            {
              "name": null,
              "type": null,
              "display": null,
              "required": null,
              "value": null,
              "label": null,
              "input": null,
              "phone": null,
              "options": null,
              "rules": null,
              "payload": null,
              "refetchOnChange": null
            }
          ]
        }
      ]
    }
  ],
  "rules": [
    {
      "kind": "pattern",
      "regex": "string",
      "flags": "string",
      "fields": [
        "string"
      ],
      "message": {
        "key": "kyb.fields.businessName.label",
        "text": "Business name"
      }
    }
  ],
  "submit": {
    "endpoint": "/omni/kyb",
    "method": "POST",
    "static": {},
    "onSuccess": {},
    "onFailure": {}
  }
}
```
