Conference

Once the onboarding part is finished and all data about user is collected, a conference call between user and executive can be established. This section describes endpoints adding a user to the queue so an executive can review the information. Endpoits for establishing video conference between user and executive are described in this section.

Login admin token

POST /executive/log-in

This endpoint is used in the Incode dashboard to login executives and admin users. If the credentials are valid it will return a token with the corresponding permissions of the user.

Request:

• email: String, mandatory.
• password: String, mandatory.

Eg:

    {
    "email": "some@email.com",
    "password": "somePassword"
    }

Response:

• token: String. Access token for next calls. Eg:

  {
  "token": "eyJhbGciOasfasiJ9.eyJleHRl2OTg5NX0.zdbAC-kE-I71"
  }

Add user to queue

PUT /omni/queue/conference/add?queueName=diogenes

When data collection is over, users can be added to the queue for joining conference calls with an executive. The average time for before user joins to conference is given in response.

Request parameter:

• queueName: String, optional. The name of the queue, user is entering in case a conference call will be used. If not set, default queue will be used. Possible values: aristotle, buddha, confucius, diogenes. Same value for queueName needs to be used across all requests in one onboarding session.

Eg:

{
"interviewCode": "PTSFP6"
}

Request:

• interviewCode: String, optional. Interview code received in response of start call.

Response:

• waitingTimeInSeconds: Integer. Average waiting time before user joins conference call.
• success: Boolean. Flag indicating request passed successfully.

Eg:

{
"waitingTimeInSeconds": 203,
"success": true
}

Custom error status:

• 4014: Invalid interview code. For more details about error format see errors section.

Get user's position in queue

GET /omni/queue/conference/index?queueName=diogenes

Use this endpoint to check user's position in waiting queue. Once the index in the reponse is 0, users can connect to the conference call. Use endpoint Get position in queue. Once the index becomes 0, the customer can connect to the interview. Call Connect to fetch connection data.

Request parameter:

• queueName: String, optional. The name of the queue the user is entering in case a conference call will be used. If not set, the default queue will be used. Possible values: aristotle, buddha, confucius, diogenes. Same value for queueName needs to be used across all requests in one onboarding session.

Response:

• index: Integer.

Disconnect user from the queue

POST /omni/queue/conference/disconnect?queueName=diogenes

Users can disconnect themselves while waiting in the queue at any time.

Request parameter:

• queueName: String, optional. The name of the queue the user is entering in case a conference call will be used. If not set, the default queue will be used. Possible values: aristotle, buddha, confucius, diogenes. Same value for queueName needs to be used across all requests in one onboarding session.

Response:

• success: Boolean. Flag indicating if user was successfully removed from the queue. False in the case the user not found in the queue, true otherwise.

Connect to conference call

GET /omni/get/interviewer-info

Get interviewer name for given interview ID read from token. If the interviewer is not yet assigned to interview, null will be returned. This method also returns credentials for OpenTok session. It is recommended to call this method after Get-user's-position returns 0 in response.

Response:

• sessionId: String. Used for establishing a conference connection via OpenTok.
• interviewToken: String. Used for establishing a conference connection via OpenTok.
• interviewerName: String. The name of the executive who is on a conference call with the user.

Read queue content

GET /omni/queue/conference?queueName=diogenes

An executive can inspect the content of the waiting queue.

Request parameter:

• queueName: String, optional. The name of the queue the user is entering in the case a conference call will be used. If not set, the default queue will be used. Possible values: aristotle, buddha, confucius, diogenes. Same value for queueName needs to be used across all requests in one onboarding session.

Response:

• queue: String array. List of interview ids, waiting in the queue.

Get next customer from the queue

GET /omni/queue/conference/next?queueName=diogenes

Fetch next customer from a conference queue. In case no customer in the queue, and empty body is returned.

Request parameter:

• queueName: String, optional. The name of the queue the user is entering in the case the conference call will be used. If not set, the default queue will be used. Possible values: aristotle, buddha, confucius, diogenes. Same value for queueName needs to be used across all requests in one onboarding session.

Response:

• interviewId: String. ID of fetched interview.
• interviewToken: String. OpenTok token used for connection to video call.
• sessionId: String. OpenTok session id used for connection to video call.

Save user consent

POST /omni/add/conference-consent?interviewId=lkgaoghao

Save information indicating that user has accepted terms and conditions and other checks on conference.

Request parameter:

• interviewId: String, mandatory. ID of interview for which consent needs to be given.

Request:

• conferenceTermAndConditionsAccepted: Boolean, optional. User accepts terms and conditions.

• creditBureauConsentGiven: Boolean, optional. User accepts credit bureau check.

• applicantDataConfirmed: Boolean, optional. Executive has verified user data. Eg:

  {
  "conferenceTermAndConditionsAccepted": true,
  "creditBureauConsentGiven": true,
  "applicantDataConfirmed": true
  }

Response:

• success: Boolean. Flag indicating request passed successfully.

Start recording

POST /omni/record-start

Start recording of the interview.

Request parameter:

• interviewId: String, mandatory. ID of interview for which recording is started.

Response:

• opentokArchiveId: String. ID of created OpenTok archive.

Stop recording

POST /omni/record-stop

Stop recording the interview.

Request parameter:

• opentokArchiveId: String, optional. ID of OpenTok archive for which recording stop is requested. In case omitted, last created archive on given interview will be stopped.

Response:

• success: Boolean. Flag indicating request passed successfully.

Verify face

POST /omni/verifyFace

A bank executive can ask the customer to additionally capture his face during an interview and do face recognition. A face can be captured from selfie or ID that a customer places in front of camera.

Request parameter:

• base64Image: String, mandatory. Base64 string representation of the image.
• interviewId: String, mandatory. ID of interview.
• compareWith: String, mandatory. This parameter indicates which template should be used for the comparison with the image sent. Possible values are selfie, id.

Eg:

{
"base64Image": "/9j/4AAQSkZJRgABAQABLn0kvWaa6Dxv7Kk9Z89nveU+mjuQKB29EWOavLyBDr7nL...",
"interviewId": "5c10c728c7a29d001536ad13",
"compareWith": "selfie"
}

Response:

• confidence: Float. Confidence value of comparing. Number between 0 and 1.

Custom error statuses:

• 4019: Face not found
• 1003: Face cropping failure

For more details about error format see errors section.

Store conference photos

POST /omni/conference/photo

A bank executive can ask the customer to additionally capture his face or document. These will be stored in DB.

Request parameter:

• base64Image: String, mandatory. Base64 string representation of the image.
• interviewId: String, mandatory. ID of interview.
• origin: String, mandatory. This parameter indicates which type of photo is taken Possible values are selfie, front, back, poa.

Eg:

{
"base64Image": "/9j/4AAQSkZJRgABAQABLn0kvWaa6Dxv7Kk9Z89nveU+mjuQKB29EWOavLyBDr7nL...",
"interviewId": "5c10c728c7a29d001536ad13",
"origin": "selfie"
}

Response:

For more details about error format see errors section.

Get connection details

/omni/queue/conference/connection-details?uuid=kqehgqioghoqih

An executive can invite the user to join a conference if the connection is lost by sending uuid ID to user. Using this uuid connection details for that session can be fetched.

Request parameter:

• uuid: String, mandatory.

Response:

• sessionId: String. Used for establishing conference connection via OpenTok.
• interviewToken: String. Used for establishing conference connection via OpenTok.
• accessToken: String. Access token which needs to be forwarded in header X-Incode-Hardware-Id for future calls. Same purpose as token from start
• interviewerName: String. The name of the executive who is on conference call with the user.

Send conference chat

POST /omni/chat

Store conference chat. The executive should send the whole chat at the end of conference call (just before finish is called).

Request:

• interviewId String, mandatory. Interview id.

• chat: Array of chat objects, mandatory.

  • date: Long, mandatory. UTC timestamp.
  • body: String, mandatory. Single message in chat.
  • author: String, mandatory. Author of the message. Possible values user or interviewer.

  Eg:

          {
      "interviewId": "5ec3e2f99bc2710011fba979",
      "chat": [
          {
          "date": 1576621394233,
          "body": "chat1",
          "author": "user"
          },
          {
          "date": 1576621394233,
          "body": "chat2",
          "author": "interviewer"
          },
          {
          "date": 1576621394233,
          "body": "chat3",
          "author": "user"
          }
      ]
      }

Response:

• success: Boolean. Flag indicating the request passed successfully.

Add notes

POST /omni/add/notes

This endpoint is used for adding notes for interview/session.

Request:

• notes: String, mandatory. Notes to save

Response:

• success: Boolean. Flag indicating request passed successfully.

Add notes

POST /omni/add/conference/notes

Same as add-notes

This endpoint is used for adding notes for interview/session.

Request:

• notes:String, mandatory. Notes to save

Response:

• success: Boolean. Flag indicating request passed successfully.

Fetch notes

GET /omni/get/conference/notes

This endpoint is used for fetching conference notes for interview/session.

Request:

• id:String, optional. ID of interview. If omitted, the interview ID from teh token is used (current session)

Response:

• notes: String. Notes saved for interview.

Add conference feedback

POST /omni/add/conference/feedback

This endpoint is used for adding conference feedback for the interview/session.

Request:

• feedback:String, mandatory. Feedback to save

Response:

• success: Boolean. Flag indicating request passed successfully.

Fetch conference feedback

GET /omni/get/conference/feedback

This endpoint is used for fetching conference feedback for the interview/session.

Request:

• id:String, optional. ID of interview. If omitted the interview ID from token is used (current session)

Response:

• conferenceFeedback: String. Feedback saved for interview.

Add conference event

POST /omni/conference/add/event

Send (OpenTok) conference event. Any connection issue caught by webapp could be reported using this call.

Request:

• interviewId String, mandatory. Interview ID for which event is reported.
• opentokSessionId String, mandatory. Opentok session ID of current video conference.
• eventType String, mandatory. Opentok event type. Could be anything that Opentok sends, e.g. StreamDisconnected, StreamReconnected, VideoDisabled, VideoEnabled...
• details String, optional. Any description that Opentok sends.
• eventSource String, mandatory. Indicate event caught on customer or executive side. Possible values: customer, executive

Eg:

{
    "interviewId": "5ec3e2f99bc2710011fba979",
    "opentokSessionId": "T1==cGFydG5lcl9pZD00NjEzNTg2MiZzaWc9ZjBkMzE5N2I2Y2NkMjFmMmFhNWYzZGQ1OWQ0ZTEzYmQzYTAxYzM2MjpzZXNzaW9",
    "eventType": "StreamDisconnected",
    "details": "Subscriber's stream has been interrupted",
    "eventSource": "executive",
}

Response:

• success: Boolean. Flag indicating request passed successfully.

Fetch conference events

GET /omni/conference/get/events?interviewId=5ec3e2f99bc2710011fba979

Fetch conference events for given 'interviewId'.

Request parameters:

• interviewId: String, mandatory. Interview id.

Response:

• events: Array of event objects
  • interviewId String. Interview id.
  • _createdAt Long. UTC timestamp when event happened.
  • opentokSessionId String. Opentok session id.
  • eventType String. Opentok event type
  • details String. Any description that Opentok sends.
  • eventSource String. Indicate event caught on customer or executive side. Possible values: customer, executive

Report conference issue

POST /omni/conference/report-issue

An executive can report any issue by this call.

Request:

• interviewId String, mandatory. Interview ID for which issue is reported.
• opentokSessionId String, mandatory. Opentok session ID of current video conference.
• details String, mandatory. Any description that Opentok sends.

Eg:

    {
    "interviewId": "5ec3e2f99bc2710011fba979",
    "opentokSessionId": "T1==cGFydG5lcl9pZD00NjEzNTg2MiZzaWc9ZjBkMzE5N2I2Y2NkMjFmMmFhNWYzZGQ1OWQ0ZTEzYmQzYTAxYzM2MjpzZXNzaW9",
    "details": "Subscriber's stream has been interrupted"
    }

Response:

• success: Boolean. Flag indicating request passed successfully.

Finish interview

PUT /omni/finish?queueName=buddha

Finish the interview and remove customer from the queue.

Request parameter:

• queueName: String, optional. The name of the queue the user is entering in case a conference call will be used. If not set, default queue will be used. Possible values: aristotle, buddha, confucius, diogenes. Same value for queueName needs to be used across all requests in one onboarding session.

Request:

• interviewId String, mandatory. Interview id.
• status String, optional. Status of finished interview. Possible values: APPROVED, REJECTED, ABANDONED, NEEDS_REVIEW. If omitted it will be defaulted to NEEDS_REVIEW.

Response:

• success: Boolean. Flag indicating request passed successfully.
• urls: String array. List of urls to archived video calls (usually single url).
• uuid: String, optional. ID of newly created customer (if onboarding was approved).

Fetch video archive urls

GET /omni/get/archives?since=123456789&interviewId=5ea568d3jjhhd7f0016fbe824

Fetch URLs of video archives from given 'interviewId' or if omitted for given 'since' timestamp. If not provided, 'since' will be defaulted to time of first created archive. The maximum fetch size is 1000. In case maximum fetch size is reached, a new fetch should be triggered, using 'startTime' of last record from previous fetch as 'since'. URLs returned are temporary URLs, which expire in 5 days.

Request parameters:

• interviewId: String, optional. In case this parameter is provided, 'since' is ignored, and response will contain single interview requested.
• since: Long, optional. Timestamp — beginning of export. If omitted, it will be defaulted to time of first created archive.

Response:

• archives: Array of archive objects
  • interviewId: String. ID of interview.
  • name: String. Name of the user in conference call.
  • url: String. URL of archive file.
  • startTime: Long. Timestamp of archive creation.

Fetch conference chat

GET /omni/get/chat?interviewId=5ec3e2f99bc2710011fba979

Fetch conference chat for given 'interviewId'.

Request parameters:

• interviewId: String, mandatory. Interview id.

Response:

• chat: Array of chat objects
  • date: Long. UTC timestamp.
  • body: String. Single message in chat.
  • author: String. Author of the message. Possible values user or interviewer.

Fetch conference status

GET /omni/get/conference-status?id=4390u032r

Returns data about conference session for given ID.

Request parameters:

• id: String, optional. ID of onboarding for which data is requested. If not present, it will be extracted from the token.

Response:

• conferenceStatus: String. Expected value is one of the following:

  • APPROVED
  • REJECTED
  • ABANDONED
  • NEEDS_REVIEW
  • NO_CONFERENCE

• executiveId: String, optional.

• conferenceStartTime: Long, optional. UTC timestamp

• conferenceEndTime: Long, optional. UTC timestamp

• conferenceDuration: Long, optional. Conference duration in milliseconds.

• conferenceTermAndConditionsAccepted: Boolean, optional.

• creditBureauConsentGiven: Boolean, optional.

• applicantDataConfirmed: Boolean, optional.

Add conference module

POST /omni/add/conference-module

Add conference module with name, url and icon (base64).

Request parameters:

• name: String, mandatory.
• url: String, mandatory.
• iconBase64: String, mandatory.
• index: String, mandatory.

Eg:

    {
    "name": "Conference module name",
    "url": "https://example.com",
    "iconBase64": "IMAGE BASE64",
    "index": "1"
    }

Response:

• success: Boolean. Flag indicating request passed successfully.

Update conference module index

POST /omni/update/conference-module

Update conference module index with module ID.

Request parameters:

• moduleId: String, mandatory.
• index: String, mandatory.

Response:

• success: Boolean. Flag indicating request passed successfully.

Fetch conference module

GET /omni/get/conference-modules

Fetch all conference modules for customer (apiKey) with moduleId, name, url and icon (base64).

Response:

• conferenceModules: Array of:
  • moduleId: String.
  • name: String.
  • url: String.
  • iconBase64: String.

Delete conference module

DELETE /omni/delete/conference-module?id=5fc7c818585dae001456dfd6

Delete conference module with module ID.

Request parameters:

• id: String, mandatory.

Response:

• success: Boolean. Flag indicating request passed successfully.