Exports API

Data Compliance

Omilia OCP® Data Warehouse and Export API comply with General Data Protection Regulation (GDPR) requirements. For any data type exported from OCP, through Export API, the OCP users are responsible to ensure that their exported data are handled accordingly and meet necessary regulations.

Overview

Exports API is organized around HTTP REST. Our API allows you to request CDRs as exports for specific time range. The maximum date range supported is two days. The smallest requested date range is one hour (for example, 2023-01-12T12:00:00.000Z to 2023-01-12T13:00:00.000Z).

Minutes/seconds/milliseconds will not change the export (example, 2023-01-12T12:00:00.000Z to 2023-01-12T13:00:00.000Z is equal to 2023-01-12T12:10:00.000Z to 2023-01-12T13:20:00.000Z).

Each group can run one export at a time. After the successful creation of the export, the exported data is stored for one day, after this period the data is deleted from the API and the status of the export is updated to expired.

We use built-in HTTP authentication to validate users based on groups/roles stored in IAM.

Sequence Diagram

Exports access token creation

The access token is a random string generated by IAM and exports-api will use to validate the user against IAM server and check user’s whitelist of groups.

Whitelisted groups should be added as attributes assigned to the user or to a group which the user belongs to.

Access token creation

After creating the user, the client should obtain access token from IAM deployment via its API.

cURL Example Request

curl --location --request POST 'https://us1-m.ocp.ai/auth/realms/master/protocol/openid-connect/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=ocp' \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'username=<your username>' \
    --data-urlencode 'password=<your password>'

BASH

Response

A successful request returns the HTTP 200 status code and a JSON response body that contains the access token to use with exports-api.

HTTP code responses

Omilia uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the 5xx range indicate an error with Omilia’s servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however. To understand the source of the error please refer to the list of codes in the documentation.

The Omilia API uses the following error codes:

HTTP Error Codes

Error Code	Meaning
200	OK Everything worked as expected
400	Bad Request The request was unacceptable, often due to missing a required parameter
401	Unauthorized No valid API key provided
402	Request Failed The parameters were valid but the request failed
404	Not Found The requested resource doesn’t exist
403	Forbidden Most common example is "No available licenses"
409	Conflict The request conflicts with another request (perhaps due to using the same idempotent key)
429	Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
500, 502, 503, 504	Server Errors Something went wrong on Omilia’s end

API Reference

{{baseUrl}} depends on the user's environment.

For us1 it is us1-a.ocp.ai

Create Export

Request

POST {{baseUrl}}/exports-api/v1/groups/{group}/jobs

CODE

{
  "from_date": "2023-01-12T13:02:09.941Z",
  "to_date": "2023-01-12T13:02:09.941Z",
  "types": [
    "Dialog Data"
  ],
  "export_name": "DMxKBlbbhtRi-J8AOX3SeB4vDW"
}

JSON

Path Parameters

Property	Type	Required	Description
group	string	Yes	The group (organization) the export requested belong to.

Body Parameters

Property	Type	Required	Description
export_name	string	Yes	Name of specific export (^[a-zA-Z0-9-][a-zA-Z0-9-\\s]+$)
from_date	DateTime(UTC)	Yes	Timestamp before `to_date` (ISO-8601 format)
to_date	DateTime(UTC)	Yes	`to_date` must be at least two hours before export request time. `from_date`-`to_date` should be equal or less than two days. (ISO-8601 format)
types	array(string)	Yes	The types of data needed for export Possible values: [“Dialog Data”] {Dialog Step + Dialog Start + Dialog End} ["Dialog Step","Dialog End",“Dialog Start”] (Each one of these can be given independently)

Response

A successful request returns the HTTP 200 status code and a JSON response body that shows the export id created (UUID) and a description field (String) with success.

Example

{
"description": "Task Submitted",
"export_id": "73bd903e-e5c5-4b87-a9a9-6a35e45af48f"
}

JSON

List Exports

Request

GET {{baseUrl}}/exports-api/v1/groups/{group}/jobs

CODE

Path Parameters

Property	Type	Required	Description
group	string	Yes	The group (organization) that the list export refers to.

Query Parameters

Property

Type

Required

Description

page_number

Integer

No

Integer > 0 , default value = 1

page_size

Integer

No

100 >= Integer > 0 , default value = 50

status

string

No

The types of data needed for export
Possible values:

SUBMITTED, PROCESSING, RUNNING, READY, EXPIRED (Each one of these can be given independently)

Response

A successful request returns the HTTP 200 status code and a JSON response body that shows a list of created exports from the specific group.

Example

{
    "pagination": {
        "pages": 1,
        "page_number": 1,
        "page_size": 2,
        "total_results": 2
    },
    "exports": [
        {
            "name": "KT_dw_qa_2_AwsDev",
            "status": "EXPIRED",
            "group": "dw_qa_2_AwsDev",
            "export_id": "3342d2f8-2279-43a3-b4e9-082ceed19a68",
            "time_submitted": "2023-01-13T09:54:58.192Z",
            "from_date": "2023-01-13T05:00:00Z",
            "finished_date": "2023-01-13T09:55:50.57Z",
            "to_date": "2023-01-13T06:00:00Z",
            "types": [
                "Dialog Step",
                "Dialog Start",
                "Dialog End"
            ]
        },
        {
            "name": "tests",
            "status": "EXPIRED",
            "group": "dw_qa_2_AwsDev",
            "export_id": "b52d8a2c-358f-486d-a464-f89dbf2eaa9b",
            "time_submitted": "2023-01-05T12:19:54.061727Z",
            "from_date": "2022-12-05T00:00:00Z",
            "finished_date": "2023-01-08T18:00:01.784466Z",
            "to_date": "2022-12-05T23:00:00Z",
            "types": [
                "Dialog Step"
            ]
        }
    ]
}

JSON

GET Export Metadata

Request

GET {{baseUrl}}/exports-api/v1/groups/{group}/jobs/{export_id}

CODE

Path Parameters

Property	Type	Required	Description
group	string	Yes	The group (organization) that the list export refers to.
export_id	UUID string	Yes	A valid UUID string referencing a created export.

Response

A successful request returns the HTTP 200 status code and a JSON response body that shows metadata of the specific export.

Example

{
  "export_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "num_of_files": 0,
  "size_of_export": 0
}

JSON

List Export Data

Request

GET {{baseUrl}}/exports-api/v1/groups/{group}/jobs/{export_id}/data/compressed

CODE

Path Parameters

Property	Type	Required	Description
group	string	Yes	The group (organization) that the list export refers to.
export_id	UUID string	Yes	A valid UUID string referencing a created export.

Query Parameters

Property	Type	Required	Description
page_number	Integer	No	Integer > 0, default value 1
page_size	Integer	No	50 >= Integer > 0, default value 50

Response

A successful request returns the HTTP 200 status code with some pagination http headers and starts a streaming response that when finished, a zip file is created and downloaded.

Example

Exports Supported

Currently the API supports only CDR exports. The CDRs have 3 different types: dialog_start, dialog_step, dialog_end.

Rate Limiting

Description

Exports-api has a rate limiting mechanism configured by its configuration file which applies a threshold of requests per group for a specific time window. The algorithm used is a token-bucket applied over a fixed window of time. This means that for a specific window a certain amount of tokens are produced for each group and they’re consumed as requests are landing on each endpoint. One limit per group applies for all endpoints. If the limit is exceeded, the API will respond with an error response of Status Code 429 (Too many requests). The API will again allow requests for this group after the bucket will refill with tokens in the next fixed request window. The status of the buckets are kept in a memory cache. In order to prevent the cache from growing indefinitely, there is a Time To Live (TTL) for each entry. Entries will be evicted if the TTL of the entry is exceeded (The TTL value configured should be more than the request window).

After eviction, a new cache entry will be created if a new request arrives.