Start Onboarding Session

Introduction

Batch process onboardings begin with a call to the Start onboarding endpoint. This call creates a new Incode onboarding session (sometimes called an interview), and returns a JSON response that contains metadata about the newly created session.

Check the start onboarding documentation for a complete reference of the endpoint's inputs and output.

Requirements

This request uses the following header values and body key/value pairs:

Headers

Header	Value
`api-version`	"1.0"
`x-api-key`	The API Key provided to you by Incode

JSON Request Body

Key	Value
`configurationId`	Required: The Incode Flow identifier, also referred to as the Flow ID, for your new sessions. If you don't know the Flow ID, open Dashboard > Flows, locate the Flow you want to reference, and click Copy Flow ID in the Actions column.
`externalCustomerId`	Optional: ID that links the new onboarding session to a specific ID you provide. You can query all the sessions related to this ID on the Incode Dashboard. For example, you may have assigned an ID to the customer in another system and want to be able to find all sessions related to that customer ID.

Handling the JSON response

The metadata returned in the response includes the Session Token. Store this value. It will be needed in subsequent endpoint calls.

Sample code

curl --location 'https://demo-api.incodesmile.com/omni/start' \
--header 'Content-Type: application/json' \
--header 'api-version: 1.0' \
--header 'x-api-key: <your_api_key>' \
--data '{
  "countryCode": "ALL",
  "configurationId": "<your_configuration_id>",
  "externalCustomerId" : "<your_user_id>"
}
'

const axios = require('axios');

const data = JSON.stringify({
  countryCode: "ALL",
  configurationId: "<your_configuration_id>",
  externalCustomerId: "<your_user_id>
});

const config = {
  method: 'post',
  url: 'https://demo-api.incodesmile.com/omni/start',
  headers: { 
    'Content-Type': 'application/json', 
    'api-version': '1.0', 
    'x-api-key': '<your_api_key>'
  },
  data : data
};

axios(config).then(function (response) {
  const token = response.data.token;
  console.log(token);
}).catch(function (error) {
  console.log(error);
});

var client = HttpClient.newHttpClient();

var request = HttpRequest.newBuilder()
  .uri(URI.create("https://demo-api.incodesmile.com/omni/start"))
  .header("Content-Type", "application/json")
  .header("api-version", "1.0")
  .header("x-api-key", "<your_api_key>")
  .POST(BodyPublishers.ofString("{\"countryCode\":\"ALL\",\"configurationId\":\"<your_configuration_id>\", \"externalCustomerId\": \"<your_user_id>\"}"))
  .build();

var response = client.send(request, BodyHandlers.ofString());
var jsonResponse = new JSONObject(response.body());
var token = jsonResponse.getString("token");
System.out.println(token);

using var client = new HttpClient();

var json = "{\"countryCode\":\"ALL\",\"configurationId\":\"<your_configuration_id>\", \"externalCustomerId\": \"<your_user_id>\"}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
client.DefaultRequestHeaders.Add("api-version", "1.0");
client.DefaultRequestHeaders.Add("x-api-key", "<your_api_key>");

var response = await client.PostAsync("https://demo-api.incodesmile.com/omni/start", content);
var responseString = await response.Content.ReadAsStringAsync();
var token = JObject.Parse(responseString)["token"].ToString();
Console.WriteLine(token);

import requests

url = "https://demo-api.incodesmile.com/omni/start"

payload = {
    "countryCode": "ALL",
    "configurationId": "<your_configuration_id>",
    "externalCustomerId": "<your_user_id>"
}
headers = {
    'Content-Type': 'application/json',
    'api-version': '1.0',
    'x-api-key': '<your_api_key>'
}

response = requests.post(url, json=payload, headers=headers)
token = response.json()['token']
print(token)

❗️
Do not use these versions unless otherwise stated
These versions contain variants, beta features and configurations specific for certain use cases. If you have any questions, please contact your CSM.