---
title: "Request new onboarding for integrations"
url: "https://developer.incode.com/api-reference/b2b-onboarding-request-new/"
section: "api-reference"
group: "Interview"
version: "v1.1"
status: "live"
endpoint: "POST /omni/b2b/onboarding/request-new"
---
# 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `integrationReference` | string | yes | Integration reference for the onboarding request. |
| `loginHint` | string |  | User login hint. |
| `applicantId` | string |  | Existing applicant id. |
| `externalCustomerId` | string |  | Id that identifies user in clients external system. |
| `name` | string |  | Applicant name. |
| `meetingLink` | string |  | Meeting link. |
| `linkValidityInMinutes` | integer (int32) |  | Link validity in minutes. |
| `notification` | NotificationDelivery | 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 |

## 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 POST https://demo-api.incodesmile.com/omni/b2b/onboarding/request-new \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "api-version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationReference": "",
    "loginHint": "",
    "applicantId": "",
    "externalCustomerId": "",
    "name": "",
    "meetingLink": "",
    "linkValidityInMinutes": 0,
    "notification": "",
    "notification.type": "",
    "notification.email": "",
    "notification.phone": ""
  }'
```

### Node

```js
const res = await fetch("https://demo-api.incodesmile.com/omni/b2b/onboarding/request-new", {
  method: "POST",
  headers: {
      "x-api-key": "<YOUR_API_KEY>",
      "api-version": "1.0",
      "Content-Type": "application/json",
  },
    body: JSON.stringify({
      "integrationReference": "",
      "loginHint": "",
      "applicantId": "",
      "externalCustomerId": "",
      "name": "",
      "meetingLink": "",
      "linkValidityInMinutes": 0,
      "notification": "",
      "notification.type": "",
      "notification.email": "",
      "notification.phone": ""
    }),
});
const data = await res.json();
```

### Python

```python
import requests

headers = {
    "x-api-key": "<YOUR_API_KEY>",
    "api-version": "1.0",
    "Content-Type": "application/json",
}
res = requests.post("https://demo-api.incodesmile.com/omni/b2b/onboarding/request-new", headers=headers, json={
  "integrationReference": "",
  "loginHint": "",
  "applicantId": "",
  "externalCustomerId": "",
  "name": "",
  "meetingLink": "",
  "linkValidityInMinutes": 0,
  "notification": "",
  "notification.type": "",
  "notification.email": "",
  "notification.phone": ""
})
data = res.json()
```

### Java

```java
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://demo-api.incodesmile.com/omni/b2b/onboarding/request-new"))
    .header("x-api-key", "<YOUR_API_KEY>")
    .header("api-version", "1.0")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"integrationReference\": \"\",\n  \"loginHint\": \"\",\n  \"applicantId\": \"\",\n  \"externalCustomerId\": \"\",\n  \"name\": \"\",\n  \"meetingLink\": \"\",\n  \"linkValidityInMinutes\": 0,\n  \"notification\": \"\",\n  \"notification.type\": \"\",\n  \"notification.email\": \"\",\n  \"notification.phone\": \"\"\n}"))
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
```

### Example response

```json
{
  "success": true,
  "status": "OK"
}
```