Table of Contents
URL and domain
The URL for accessing the API will follow this pattern:
<https://api.$>{environment_name}.motocorti.io
With environment_name being the internal naming for that deployment. For more information, contact Corti DevOps department
Authentication
Add a header with your API key. To get an API key, please contact your Customer Experience manager.
x-api-key: XXXX
REST API (v2)
Create Triage Session
Allows creating a triaging session in the Corti system, using the case and user identifiers. Optional yet unique per organization external_id could be provided to assist associating with 3rd party sessions.
- If the external_id already exists, an error will be returned (status 409). No session will be created.
- If either case_id or owner_user_id do not match to an entity within Corti, an error will be returned (status code 400). No session will be created.
// POST /public/api/v2.0/triage-sessions
{
"user_id": "386308075989172225",
"case_id": "1ba8528e-7644-4b1a-95a6-dd2ef14c6dbe",
"external_id": "19-7883374-1" //Optional
}
// Response - 201
{
"data": {
"id": "e0d75d9d-d84d-41d4-8309-fc9c12ffedfa",
"owner_user_id": "386308075989172225",
"case_id": "1ba8528e-7644-4b1a-95a6-dd2ef14c6dbe",
"external_id": "19-7883374-1", //Optional
"started_at": "2020-05-04T14:04:24.427524Z"
}
}
Get Triage Session
Allows fetching Triage Session in Corti system, using the session internal or external identifiers.
- If either session_id or external_session_id does not match to a triage session entity within Corti, no triage session will be returned (status 404).
// GET /public/api/v2.0/triage-sessions/
// GET /public/api/v2.0/triage-sessions/by-external-id/
// Response - 200
{
"data": {
"id": "e0d75d9d-d84d-41d4-8309-fc9c12ffedfa",
"user_id": "386308075989172225",
"case_id": "1ba8528e-7644-4b1a-95a6-dd2ef14c6dbe",
"external_id": "19-7883374-1", //Optional
"started_at": "2020-05-04T14:04:24.427524Z"
}
}
Set Triage Session Flow Fact Values
Corti allows you to modify triage session flow facts by providing a list of fact's id and value pairs.
- If session_id does not match to a triage session entity within Corti, no facts will be updated and status 400 returned.
- Optional query parameter timeout could be provided to control how much seconds to wait (after the request is validated and accepted) for a response about the successful/unsuccessful setting of fact values. The default value is null, which means the waiting is disabled. The maximum timeout value is 10.
- Only facts that are provided will be affected.
- If value is an empty string (""), fact will be set to null/default value in the Corti system.
- Returns HTTP status 204 (if the timeout is provided) or status 202 (if the timeout is not provided) on success and an empty body. If the fact is not set after the provided timeout has passed, the server returns status 504.
// PATCH /public/api/v2.0/triage-sessions//flow-fact-values?&timeout=5
[
{
"id": "breathing",
"value": "true"
},
{
"id": "state",
"value": "Washington"
}
]
// Response - 202
Get Case
Allows fetching Case in Corti system, using the case internal or external identifiers.
- If either case_id or external_case_id does not match to a case entity within Corti, no case will be returned (status 404). by-external-id
// GET /public/api/v2.0/cases/
// GET /public/api/v2.0/cases/by-external-id/
// Response - 200
{
"data": {
"id": "1ba8528e-7644-4b1a-95a6-dd2ef14c6dbe",
"external_id": "19-7883374-1", //Optional
"started_at": "2020-05-04T14:04:24.427524Z"
}
}
Create Case
Corti allows you to create a case. Optional yet unique per organization external_id could be provided to assist associating with 3rd party cases.
- If the external_id already exists, an error will be returned (status 409). Case will not be created.
- Returns HTTP status 201 on success and the newly created case.
// POST /public/api/v2.0/cases
{
"started_at": "2020-04-10T11:20:10.123456Z",
"external_id": "Case-1000-1", //Optional
}
// Response - 201
{
"data": {
"id": "47a6f690-8c0a-4e52-8da6-cc9fc8f7c73e",
"external_id": "Case-1000-1", //Optional
"started_at": "2020-04-10T11:20:10.123456Z"
}
}
Update Case
Corti allows you to modify case properties. Optional yet unique per organization external_id could be provided to assist associating with 3rd party cases.
- If the external_id already exists, an error will be returned (status 409). Case will not be updated.
- Only attributes that are not empty (null) will be updated. For example: if external_id is null, it will not be updated. If external_id is an empty string ("") it will be set to null in the Corti system. Otherwise, it will be set to the string provided.
- If case_id do not match to a case entity within Corti, an error will be returned (status 400). The case will not be updated.
- Returns HTTP status 204 on success and an empty body.
// PATCH /public/api/v2.0/cases/
{
"location": { //Optional
"address": { //Optional
"country": "Sweden",
"state": null,
"county": null,
"region": "Stockholms län",
"locality": "Stockholm",
"sublocality": null,
"neighborhood": null,
"route": null,
"premise": null,
"subpremise": null,
"postal_code": "113 57",
"street_address": "Rådmansgränden",
"street_number": "38",
"floor": null,
"room": null
},
"coordinates": { //Optional
"lat" : 42.10808340000001,
"lng" : -87.735895
},
"formatted_address": "Rådmansgränden 38, 113 57, Stockholm, Sweden" //Optional
},
"external_id": "19-7883374" //Optional
}
// Response - 204
Merge Cases
Corti allows you to merge two cases into one by moving all content (triage-sessions, calls etc.) from the provided (target) case in the request body to the base case (identified in the path by base_case_id), adjusting it's start/end range and eventually removing the target case.
- If case_id or base_case_id do not match to a case entity within Corti, an error will be returned (status 400). The case will not be updated.
- In the event of case direct/custom properties conflict (when base and target case have a different value on the same property) the base case's property value will be chosen.
- Returns HTTP status 201 on success with merge creation date response
// POST /public/api/v2.0/cases//merges
{
"case_id": "1ba8528e-7644-4b1a-95a6-dd2ef14c6dbe"
}
// Response - 201
{
"data": {
"created_at": "2020-05-04T14:04:24.427524Z"
}
}
Update Case Custom Properties
Corti allows you to modify case custom properties.
- Only attributes that are not empty (null) will be updated. For example: if custom_prop_2 is null, it will not be updated. If custom_prop_2 is an empty string ("") it will be set to null in the Corti system. Otherwise, it will be set to the string provided.
- If case_id do not match to a case entity within Corti, an error will be returned (status 400). The case custom properties will not be updated.
- Returns HTTP status 204 on success and an empty body.
// PATCH /public/api/v2.0/cases//custom-properties
{
"custom_prop_2": "custom_prop_1 value",
"custom_prop_3": "custom_prop_3 value"
}
// Response - 204
Update Session
Corti allows you to modify triage-session properties.
- Only attributes that are not empty (null) will be updated. For example: if telephoneNumber is null, it will not be updated. If telephoneNumber is an empty string ("") it will be set to null in the Corti system. Otherwise, it will be set to the string provided.
- If session_id do not match to a triage session entity within Corti, an error will be returned (status 400). The session will not be updated.
- Returns HTTP status 204 on success and an empty body.
// PATCH /public/api/v2.0/triage-sessions/
{
"telephoneNumber": "+46101408000" //Optional
}
// Response - 204
Change Session's owner
Corti allows you to change triage-session's owner.
- If session_id do not match to a triage session entity within Corti, an error will be returned (status 400). The session will not be updated.
- Returns HTTP status 204 on success and an empty body.
// POST /public/api/v2.0/triage-sessions//change-owner
{
"owner_user_id": "386308075989172225"
}
// Response - 204
Get Calls List
Allows fetching Calls in Corti system for a defined period of time.
Query parameters:
- started_from [Date time*,* mandatory] - find calls that started from the specified date and time. Date and time format example: "2020-01-04T14:04:24.427524Z" in accordance to the ISO-8601 standard
- started_before [Date time, optional] - find calls that started up until the specified date and time. If it is not specified, the system will search for calls up until the current date until the limit of records is reached. Date and time format example: "2020-02-04T14:04:24.427524Z" in accordance to the ISO-8601 standard
- user_id [String, optional] - find calls that belong to the specified user
- continuation_token [String, optional] - providing a continuation token, will display the next set of records, after the previous limit of records was reached
- limit [Integer, optional]- limits records to the provided size (default value – 10 records, maximum value – 1000)
// GET /public/api/v2.0/calls?&started_from=&started_before=&user_id=&continuation_token=&limit=
// Response - 200
{
"continuation_token": "1", //Optional
"data": [{
"id": "1ba8528e-7644-4b1a-95a6-dd2ef14c6dbe",
"case_id": "90a90363-3cf7-4ffa-b066-e5be59c87b35",
"active": false,
"user_id": "386308075989172225",
"started_at": "2020-05-04T14:04:24.123Z",
"ended_at": "2020-05-04T14:05:24.123Z", //Optional
"calling_party": "+46215481200" //Optional
},
{
"id": "d2fb30bb-6329-4233-8551-e50fccebf8de",
"case_id": "90a90363-3cf7-4ffa-b066-e5be59c87b35",
"active": true,
"user_id": "386308075989172225",
"started_at": "2020-05-04T15:04:24.008Z",
"ended_at": null, //Optional
"calling_party": "+46215481200" //Optional
}]
}
Get User
Allows fetching User in Corti system, using the user internal or external identifiers.
- If either user_id or external_user_id do not match to a user entity within Corti, no user will be returned (status 404).
// GET /public/api/v2.0/users/
// GET /public/api/v2.0/users/by-external-id/
// Response - 200
{
"data": {
"id": "386308075989172225",
"name": "Admin User",
"email": "admin@company.com",
"role_name": "admin",
"extension": "1234", //Optional
"external_id": "S-1-5-21-453406510-812318184-4183662089" //Optional
}
}
Create User
Allows creating User in Corti system. Optional yet unique per user external_id could be provided to assist associating with 3rd party use.
- If role_name do not match to a role entity within Corti, no user will be returned (status 400).
- If the email or external_id already exists, an error will be returned (status 409). User will not be created.
// POST /public/api/v2.0/users
{
"name": "Admin User",
"email": "admin@company.com",
"role_name": "admin",
"extension": "1234", //Optional
"external_id": "S-1-5-21-453406510-812318184-4183662089" //Optional
}
// Response - 204
{
"data": {
"id": "386308075989172225",
"name": "Admin User",
"email": "admin@company.com",
"role_name": "admin",
"extension": "1234", //Optional
"external_id": "S-1-5-21-453406510-812318184-4183662089" //Optional
}
}
Update User
Allows updating User in Corti system. Optional yet unique per user external_id could be provided to assist associating with 3rd party use.
- If role_name do not match to a role entity within Corti, no user will be returned (status code 400).
- Only attributes that are not empty (null) will be updated. For example: if external_id is null, it will not be updated. If external_id is an empty string ("") it will be set to null in the Corti system. Otherwise, it will be set to the string provided.
- If the email or external_id already exists, an error will be returned (status 409). User will not be created.
- Returns HTTP status 204 on success and an empty body.
// PATCH /public/api/v2.0/users
{
"name": "Simple User", //Optional
"role_name": "user", //Optional
"extension": "4321", //Optional
"external_id": "S-1-5-21-453406510-812318184-4183662089" //Optional
}
// Response - 204
Delete User
Corti allows you to delete a user.
- If the user_id doesn't exist, an error will be returned (status 400).
- Returns HTTP status 204 on success.
// DELETE /public/api/v2.0/users/
// Response - 204
Link User Auth Provider to an User
Corti allows you to link an auth provider for user. This allows the user to be logged in the Corti system with 3rd party authentication provider which implements oauth2 password grant type token generation. The provider must be configured in the Corti application beforehand. More information: https://www.notion.so/cortihome/Core-Authentication-providers-de55be91b85c4ceea71789b0ad4acfe7
- If the user_id or auth_provider_id doesn't exist, an error will be returned (status 400).
- If the auth_provider_user_id already exists for different user, an error (USER_AUTH_PROVIDER_USER_ID_ALREADY_USED) will be returned (status 409).
- Returns HTTP status 201 or 200 (if provider already created for user) on success and the auth provider entity in the response body.
// PUT /public/api/v2.0/users//auth-providers/
{
"auth_provider_user_id": "external-user-id"
}
// Response - 201
{
"data": {
"auth_provider_user_id": "external-user-id"
}
}
Get User Auth Provider
Corti allows you to acquire an auth provider for user.
- If the user_id or auth_provider_id doesn't exist, an error will be returned (status 400).
- Returns HTTP status 200 on success and the auth provider entity in the response body.
// GET /public/api/v2.0/users//auth-providers/
// Response - 200
{
"data": {
"auth_provider_user_id": "external-user-id"
}
}
Delete User Auth Provider
Corti allows you to delete an auth provider for user.
- If the user_id or auth_provider_id doesn't exist, an error will be returned (status 400).
- Returns HTTP status 204 on success.
// DELETE /public/api/v2.0/users//auth-providers/
// Response - 204
Create User Token
Corti allows you to create a user token to access FE app. This allows the user to be logged in the Corti system bypassing the login procedure. The generate-token-api feature must be enabled and users:generate_token_api permission assigned for the user that is calling the endpoint.
- If the user_id doesn't exist, an error will be returned (status 400).
- Returns HTTP status 201 on success and the access token in the response body.
// POST /public/api/v2.0/users//tokens
// Response - 201
{
"data": {
"access_token": "eyJpc3MiOiJ0b3B0YWwuY19tIiwiZShwIjoxNDI2NDIwODAwLCJodHRwOi9vdG9wdGTsLmNvbS9qd3RfY2xhaW1zL2lzX2FkbWluIjp0cnVlLCJjb21wYW55IjoiVG9wdGFsIiwiYXdlc29tZSI6dHJ1ZX0"
}
}
REST API (v1)
Export Case/Event Metadata
⚠️There is no pagination on this API, so it is advised NOT to export data containing more than 3,000 cases.
There are two endpoints you can use to return data. Both take the same request body. This endpoint returns metadata attached to each case/call, including the call-taker's name.
// POST /api/v1.0/exports/cases HTTP/1.1
// POST /api/v1.0/exports/events HTTP/1.1
{
"organization_id": "XXXX",
"filter":{
"junction":"and",
"entities":[{
"id":"case",
"junction":"and",
"predicates":[{
"attributeID":"case.startedAt",
"comparison":"between",
"value":{
"type":"datetime",
"objects":[
"2020-08-15T22:00:00.000Z",
"2020-08-22T21:59:59.999Z"
]
}
}]
}]
}
}
// Response - 200
CSV file
SSE API
This API works as a stream of information, using SSE (server-sent events) technology.
Triage Session Events Stream
Allows listening to triage session events generated in Corti system.
- session_id [String, optional] - filters events that belong to the specified triage session
// GET /public/api/v2.0/triage-session-events-stream
// OR GET /public/api/v2.0/triage-session-events-stream?session_id=e0d75d9d-d84d-41d4-8309-fc9c12ffedfa
// Content-Type:text/event-stream;charset=UTF-8
// Response - 200
event: action-element-clicked
data: {
"name": "action-element-clicked",
"datetime": "2020-03-12T19:17:56.723Z",
"user_id": "386308075989172225",
"session_id": "e0d75d9d-d84d-41d4-8309-fc9c12ffedfa",
"source": {
"custom_properties": [{
"key": "casePriority",
"value": "1B"
}]
}
}
event: grouped-flow-value-collector-elements-updated
data: {
"name": "grouped-flow-value-collector-elements-updated",
"datetime": "2020-03-12T19:17:58.723Z",
"user_id": "386308075989172225",
"session_id": "e0d75d9d-d84d-41d4-8309-fc9c12ffedfa",
"value": {
"collectors": [
{
"id": "c7395a60-5bd6-4dfc-aa52-2f922e5e7264",
"name": "collector 1",
"custom_properties": [{
"key": "casePriority",
"value": "1B"
}],
"custom_values": [{
"label": "Question ?", //Optional
"value": "Answer"
}],
"collected_element_values" : {
"elements": [
{
"id": "1",
"label": "Multi select question?",
"custom_properties": [{
"key": "foo",
"value": "bar"
}]
}
],
"values": [
{
"element_id": "1",
"value": "answer 1",
"custom_properties": [{
"key": "foo",
"value": "bar"
}]
},
{
"element_id": "1",
"value": "answer 2"
}
]
}
}
]
}
}
Call Events Stream
Allows listening to call events generated in Corti system.
- call_id [String, optional] - filters events that belong to the specified call by ID.
// GET /public/api/v2.0/call-events-stream?call_id=e0d75d9d-d84d-41d4-8309-fc9c12ffedfa
// Content-Type:text/event-stream;charset=UTF-8
// Response - 200
event: call-started
data: {
"name": "call-started",
"datetime": datetime,
"call_id": string,
"participants": [{
"address": string, // e.g. extension, IP
}],
}
event: call-stopped
data: {
"name": "call-stopped",
"datetime": datetime,
"call_id": string,
"participants": [{
"address": string, // e.g. extension, IP
}]
}
event: call-annotation-created
data: {
"name": "call-annotation-created",
"datetime": datetime,
"call_id": string,
"annotation": {
"id": string,
"start_datetime": timestamp, // optional
"stop_datetime": timestamp, // optional
"type":{
"objective_name": string, // e.g. 'Critical Illness Detected'
"label_name": string // e.g. 'Cardiac Arrest'
}
}
}