# Request new onboarding for integrations

`POST /omni/b2b/onboarding/request-new`

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

This endpoint starts new onboarding session for integration and generates onboarding link.

## Path & query parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `api-version` | header | string | yes |  |

## Request body

Content-Type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `integrationReference` | string | yes | Integration reference for the onboarding request. |
| `loginHint` | string |  | User login hint. |
| `applicantId` | string |  | Existing applicant id. |
| `name` | string |  | Applicant name. |
| `meetingLink` | string |  | Meeting link. |
| `linkValidityInMinutes` | integer (int32) |  | Link validity in minutes. |
| `notification` | object | yes | Notification configuration |
| `notification.type` | string | yes | Notification type, can be SMS, EMAIL or URL. Enum: `SMS`, `EMAIL`, `URL` |
| `notification.email` | string |  | Applicant email. Required for notification type EMAIL. |
| `notification.phone` | string |  | Applicant phone. Required for notification type SMS. |

## Responses

### 200

OK

Response body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string |  | Generated onboarding URL. |
| `interviewId` | string |  | Interview identifier. |

### 400

Custom error statuses:
- 4300: Integration not found by id
- 4301: Employee by login factor cannot be found

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 |