NewsPricingSystem StatusBook DemoFree Trial

Track APIs

APIs to configure policies and manage cases in Track

In addition to utilizing the create case block for case creation in Track, you can leverage the power of Track APIs to effectively manage cases within your company.

Authentication

All of Proto's RESTful APIs calls must be authenticated. Instead of passing the full credentials on every REST API call, Proto uses a personal access token. The Proto AICX platform users can find their personal access token in the profile page.

👍

Best Practice

For PAT, use an Admin account that is not linked to any user's personal email address to avoid lock-out when the user is no longer employed by the company.

To create your Personal Access Token (PAT)

  1. On the top-right corner, click on your avatar
  2. Select "Profile"
  3. On the horizontal menu, select "API"
  4. If you never created a PAT before, click "Issue new token"
  5. Save the token safe somewhere. Anyone with this token could gain access to your account.

To use the RESTful APIs, authenticate it with your PAT by passing it in X-PROTO-TOKEN header. For example,

curl --header "X-PROTO-TOKEN: <PERSONAL ACCESS TOKEN>" "https://gw.proto.cx/track/v1/<CASE_GROUP_ID>"

To utilize the Track APIs, it is necessary to first enable the API settings within Track. Here's how to get started:

  1. In Track, select the Case Group.
  2. Go to Settings.
  3. Click on the API tab.
  4. Check the "Enable" and press "Save"

Take note of your Case Group ID and Case Group Secret, you will need to pass this information in all API calls.

📘

Base URL for all Track API endpoints

https://gw.proto.cx/track/v1/<CASE_GROUP_ID>

Case APIs

The following shows a list of APIs you can use to manage the cases in a case group:

Get Cases API

Get the list of cases in a case group

GET Endpoint:

https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/cases

Path VariableDescription
<CASE_GROUP_ID>Case group ID that can be found in Track > select a Case Group > Settings > API

Request Header

KeyValueDescription
X-PROTO-TOKEN<PERSONAL_ACCESS_TOKEN>Proto's platform user's personal access token that can be found on the Profile page.
X-CASE-GROUP-SECRET<CASE_GROUP_SECRET>Case Group Secret that can be found in Track > select a Case Group > Settings > API

Query Parameter

We support the following query parameters:

ParameterData TypeDescription
pageintegerThe number of page of the result. It must be a positive integer. Default 1
perPageintegerThe number of cases per page. It must be an integer between 1 and 100. Default 50
orderBydateOne of createdAt, updatedAt (default), receiveAt, dueAt
emaillistList of emails address of the complainant/representative

Sample Request

curl --location 'https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/[email protected]' \
--header 'X-PROTO-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--header 'X-CASE-GROUP-SECRET: <CASE_GROUP_SECRET>'

Sample Response

{
    "result": [
        {
            "id": "case_j9vzjj37wj54m0efeuw88203434",
            "shortId": "VWQ749VV9X1H",
            "title": "New Complaint",
            "description": "",
            "category": {
                "id": "062d2298-c800-00dc-e7a7-a6146fdebb68",
                "name": "Technical"
            },
            "customFields": null,
            "status": "RESOLVED",
            "human": {
                "id": "0639e797-e800-00b9-5d9c-001c111f41f6",
                "fullName": "Allyson",
                "firstName": null,
                "lastName": null,
                "phone": null,
                "email": "[email protected]"
            },
            "respondent": {
                "id": "062d22a2-2d00-0016-1494-d9e4e927aa39",
                "name": "CS team"
            },
            "representative": null,
            "createdAt": "2023-06-23T01:20:28.228150+00:00",
            "updatedAt": "2023-06-23T01:21:13.947859+00:00",
            "receivedAt": "2023-06-23T01:20:00+00:00",
            "dueAt": null
        }
    ]
}

Get Case API

Get the information of a given Case Id

GET Endpoint:

https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case/<CASE_ID>

Path VariableDescription
<CASE_GROUP_ID>Case group ID that can be found in Track > select a Case Group > Settings > API
<CASE_ID>Case id or shortId

Request Header

KeyValueDescription
X-PROTO-TOKEN<PERSONAL_ACCESS_TOKEN>Proto's platform user's personal access token that can be found on the Profile page.
X-CASE-GROUP-SECRET<CASE_GROUP_SECRET>Case Group Secret that can be found in Track > select a Case Group > Settings > API

Sample Request

curl --location 'https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case/<CASE_ID>' \
--header 'X-PROTO-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--header 'X-CASE-GROUP-SECRET: <CASE_GROUP_SECRET>'

Sample Response

{
    "result": {
        "id": "case_j9vzjj37wj54m0efeuw88203434",
        "shortId": "VWQ749VV9X1H",
        "title": "New Complaint",
        "description": "",
        "category": {
            "id": "062d2298-c800-00dc-e7a7-a6146fdebb68",
            "name": "Technical"
        },
        "customFields": [],
        "status": "RESOLVED",
        "human": {
            "id": "0639e797-e800-00b9-5d9c-001c111f41f6",
            "fullName": "Allyson",
            "firstName": null,
            "lastName": null,
            "phone": null,
            "email": "[email protected]"
        },
        "respondent": {
            "id": "062d22a2-2d00-0016-1494-d9e4e927aa39",
            "name": "CS team"
        },
        "representative": null,
        "createdAt": "2023-06-23T01:20:28.228150+00:00",
        "updatedAt": "2023-06-23T01:21:13.947859+00:00",
        "receivedAt": "2023-06-23T01:20:00+00:00",
        "dueAt": null
    }
}

Create Person API

To create new case via this API endpoint, you'll first need to use the Person API endpoint to create the complainant or representative ID. Person can be used as Complainant or Representative of a Case.

  • Complainant: The person that wants to submit the case, the applicant of a case
  • Representative: The person who is delegated by Complainant to deal with the case

POST Endpoint:

https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/person

Path VariableDescription
<CASE_GROUP_ID>Case group ID that can be found in Track > select a Case Group > Settings > API

Request Header

KeyValueDescription
X-PROTO-TOKEN<PERSONAL_ACCESS_TOKEN>Proto's platform user's personal access token that can be found on the Profile page.
X-CASE-GROUP-SECRET<CASE_GROUP_SECRET>Case Group Secret that can be found in Track > select a Case Group > Settings > API

Request Body

ParameterRequiredData TypeDescription
fullNametruestringComplainant/Representative's full name
firstNamefalsestringComplainant/Representative's first name
lastNamefalsestringComplainant/Representative's last name
phonefalsestringComplainant/Representative's phone number
emailfalsestringComplainant/Representative's email address

Sample Request

curl --location 'https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/person' \
--header 'X-PROTO-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--header 'X-CASE-GROUP-SECRET: <CASE_GROUP_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fullName": "Allyson",
    "firstName": "Allyson",
    "lastName": "",
    "phone": "+60123456789",
    "email": "[email protected]"
}'

Sample Response

{
    "result": {
        "id": "063cbbea-7200-0033-5511-a8017d91b98a",
        "fullName": "Allyson",
        "firstName": "Allyson",
        "lastName": "",
        "phone": "+60123456789",
        "email": "[email protected]"
    }
}

Create Case API

Please note that to create new case via this API endpoint, you'll first need to use the PERSONS API endpoint (at bottom of page) to create a human - which provides you with the human id - which you then use in the body snippet as below.

POST Endpoint:

https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case

Path VariableDescription
<CASE_GROUP_ID>Case group ID that can be found in Track > select a Case Group > Settings > API

Request Header

KeyValueDescription
X-PROTO-TOKEN<PERSONAL_ACCESS_TOKEN>Proto's platform user's personal access token that can be found on the Profile page.
X-CASE-GROUP-SECRET<CASE_GROUP_SECRET>Case Group Secret that can be found in Track > select a Case Group > Settings > API

Request Body

ParameterRequiredData TypeDescription
categorytruestringThe ID of the category found in Track > select a Case Group > Settings > Categories
respondenttruestringThe ID of the respondent found in Track > select a Case Group > Settings > Respondents
humantruestringThe Complainant ID generated from the preceding Person API.
representativefalsestringThe Representative ID generated from the preceding Person API.
customFieldsfalselistThe custom fields ID and values found in Track > select a Case Group > Settings > Custom Fields
{ "id": "cf_XXXXXXXX", "value": "Bank" }
titletruestringThe title of the case
descriptionfalsestringThe description of the case
statustruestringThe status of the case: NEW | OPEN | OVERDUE | CLOSED | RESOLVED
receivedAtfalsestringDatetime of the case received at "2022-01-23T12:34:56.332Z"
dueAtfalsestringDatetime of the case due at "2022-01-23T12:34:56.332Z"

Sample Request

curl --location 'https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case' \
--header 'X-PROTO-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--header 'X-CASE-GROUP-SECRET: <CASE_GROUP_SECRET>' \
--header 'Content-Type: application/json' \
--data '{
  "category": {  
    "id": "062d2298-c800-00dc-e7a7-a6146fdebb63"
  },
  "customFields": [
    {
      "id": "cf_CF97VbVNkUdPc6m3wGadI",
      "value": "Card"
    }
  ],
  "respondent": {  
    "id": "062d22a2-2d00-0016-1494-d9e4e927aaa39"
  },
  "human": {  
    "id": "063cb9de-ac00-0050-679a-9bd43604a444a"
  },
  "representative": {
    "id": "063cb9de-ac00-0050-679a-9bd4a3604444a"
  },
  "receivedAt": "2023-01-23T12:34:56.332Z",
  "dueAt": "2023-01-23T12:34:56.332Z",
  "status": "NEW", 
  "title": "Test",  
  "description": "Test description"  
}'

Sample Response

{
    "result": {
        "id": "case_1cf4z0qvfn0gjnl68gfksoc",
        "shortId": "L8PTCKEFZ7FA",
        "title": "Test",
        "description": "Test description",
        "category": {
            "id": "062d2298-c800-00dc-e7a7-a6146fdebb6Aaa8",
            "name": "Test"
        },
        "customFields": [
            {
                "id": "cf_CF97VbVNkUdPc6m3waGdI",
                "value": "Card",
                "name": "Payment"
            }
        ],
        "status": "NEW",
        "human": {
            "id": "063cb9de-ac00-0050-679a-9bd43604444aa",
            "fullName": "Allyson",
            "firstName": null,
            "lastName": null,
            "phone": null,
            "email": ""
        },
        "respondent": {
            "id": "062d22a2-2d00-0016-1494-d9e4e9a27aa39",
            "name": "Test1"
        },
        "representative": {
            "id": "063cb9de-ac00-0050-679a-9bd43604a444a",
            "fullName": "Allyson",
            "firstName": null,
            "lastName": null,
            "phone": null,
            "email": ""
        },
        "createdAt": "2023-07-12T10:05:25.455175+00:00",
        "updatedAt": null,
        "receivedAt": "2023-01-23T12:34:56.332000+00:00",
        "dueAt": "2023-01-23T12:34:56.332000+00:00"
    }
}

Update Case API

To update a specific case

PUT Endpoint:

https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case/<CASE_ID>

Path VariableDescription
<CASE_GROUP_ID>Case group ID that can be found in Track > select a Case Group > Settings > API
<CASE_ID>Case id or shortId

Request Header

KeyValueDescription
X-PROTO-TOKEN<PERSONAL_ACCESS_TOKEN>Proto's platform user's personal access token that can be found on the Profile page.
X-CASE-GROUP-SECRET<CASE_GROUP_SECRET>Case Group Secret that can be found in Track > select a Case Group > Settings > API

Request Body

ParameterRequiredData TypeDescription
categorytruestringThe ID of the category found in Track > select a Case Group > Settings > Categories
respondenttruestringThe ID of the respondent found in Track > select a Case Group > Settings > Respondents
humantruestringThe Complainant ID generated from the preceding Person API.
representativefalsestringThe Representative ID generated from the preceding Person API.
customFieldsfalselistThe custom fields ID and values found in Track > select a Case Group > Settings > Custom Fields
{ "id": "cf_XXXXXXXX", "value": "Bank" }
titletruestringThe title of the case
descriptionfalsestringThe description of the case
statustruestringThe status of the case: NEW | OPEN | OVERDUE | CLOSED | RESOLVED
receivedAtfalsestringDatetime of the case received at "2022-01-23T12:34:56.332Z"
dueAtfalsestringDatetime of the case due at "2022-01-23T12:34:56.332Z"

Sample Request

curl --location --request PUT 'https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case/<CASE_ID>' \
--header 'X-PROTO-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--header 'X-CASE-GROUP-SECRET: <CASE_GROUP_SECRET>' \
--header 'Content-Type: application/json' \
--data '{
  "category": {  
    "id": "062d2298-c800-00dc-e7a7-a61a46fdebb68"
  },
  "customFields": [
    {
      "id": "cf_CF97VbVNkUdPc6m3wGadI",
      "value": "Card"
    }
  ],
  "respondent": {  
    "id": "062d22a2-2d00-0016-1494-d9e4e927aaa39"
  },
  "human": {  
    "id": "063cb9de-ac00-0050-679a-9bd43a604444a"
  },
  "representative": {
    "id": "063cb9de-ac00-0050-679a-9bd4360a4444a"
  },
  "receivedAt": "2023-01-23T12:34:56.332Z",
  "dueAt": "2023-01-23T12:34:56.332Z",
  "status": "OPEN", 
  "title": "Test",  
  "description": "Test description"  
}'

Sample Response

{
    "result": {
        "id": "case_g3lsdihzam4w10mbhmboqf4r",
        "shortId": "9KVQUH3ARG7R",
        "title": "Test",
        "description": "Test description",
        "category": {
            "id": "062d2298-c800-00adc-e7a7-a6146fdebb68",
            "name": "Test"
        },
        "customFields": [
            {
                "id": "cf_CF97VbVNkUdaPc6m3wGdI",
                "value": "Card",
                "name": "Payment"
            }
        ],
        "status": "OPEN",
        "human": {
            "id": "063cb9de-ac00-0050-679aa-9bd43604444a",
            "fullName": "Allyson",
            "firstName": null,
            "lastName": null,
            "phone": null,
            "email": ""
        },
        "respondent": {
            "id": "062d22a2-2d00-0016-149a4-d9e4e927aa39",
            "name": "Test1"
        },
        "representative": {
            "id": "063cb9de-ac00-0050-679aa-9bd43604444a",
            "fullName": "Allyson",
            "firstName": null,
            "lastName": null,
            "phone": null,
            "email": ""
        },
        "createdAt": "2023-06-28T12:49:39.327788+00:00",
        "updatedAt": "2023-07-12T10:14:29.754557+00:00",
        "receivedAt": "2023-01-23T12:34:56.332000+00:00",
        "dueAt": "2023-01-23T12:34:56.332000+00:00"
    }
}

Note API

A note is a message that serves as a follow-up from a customer, agent, respondent, or any other relevant party. Once created, notes cannot be altered or modified.

Get Notes API

List the Notes of a Case

GET Endpoint:

https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case/<CASE_ID>/notes

Path VariableDescription
<CASE_GROUP_ID>Case group ID that can be found in Track > select a Case Group > Settings > API
<CASE_ID>Case id or shortId

Request Header

KeyValueDescription
X-PROTO-TOKEN<PERSONAL_ACCESS_TOKEN>Proto's platform user's personal access token that can be found on the Profile page.
X-CASE-GROUP-SECRET<CASE_GROUP_SECRET>Case Group Secret that can be found in Track > select a Case Group > Settings > API

Sample Request

curl --location 'https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case/<CASE_ID>/notes' \
--header 'X-PROTO-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--header 'X-CASE-GROUP-SECRET: <CASE_GROUP_SECRET>'

Sample Response

{
    "result": [
        {
            "id": "0643e22b-b000-a0097-479a-f6c838f392e4",
            "content": "<p>test</p>",
            "type": "INTERNAL",
            "author": {
                "id": "user_71M2alkvo",
                "type": "user"
            },
            "recipients": [],
            "createdAt": "2023-05-12T10:23:15.675755"
        }
    ]
}

Create New Note API

Create a new Note of a Case

POST Endpoint:

https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case/<CASE_ID>/note

Path VariableDescription
<CASE_GROUP_ID>Case group ID that can be found in Track > select a Case Group > Settings > API
<CASE_ID>Case id or shortId

Request Header

KeyValueDescription
X-PROTO-TOKEN<PERSONAL_ACCESS_TOKEN>Proto's platform user's personal access token that can be found on the Profile page.
X-CASE-GROUP-SECRET<CASE_GROUP_SECRET>Case Group Secret that can be found in Track > select a Case Group > Settings > API

Request Body

ParameterRequiredData TypeDescription
typetruestringThe type of the note PUBLIC | INTERNAL
contenttruestringThe content of the note
recipientsfalselistThe type of recipient. If provided, it must be one or multiple of the following: human, respondent, representative

Sample Request

curl --location 'https://gw.proto.cx/track/v1/<CASE_GROUP_ID>/case/<CASE_ID>/note' \
--header 'X-PROTO-TOKEN: <PERSONAL_ACCESS_TOKEN>' \
--header 'X-CASE-GROUP-SECRET: <CASE_GROUP_SECRET>' \
--header 'Content-Type: application/json' \
--data '{  
  "type": "PUBLIC",  
  "content": ".....",
  "recipients": [    
    { "type": "human" }
  ]
}'

Sample Response

{
    "result": {
        "id": "0643e35b-f300-00b4-ca49-440754310a5bb",
        "content": ".....",
        "type": "PUBLIC",
        "author": {
            "id": "user_71M2lkavo",
            "type": "user"
        },
        "recipients": [],
        "createdAt": "2023-05-12T10:36:14.590814+00:00"
    }
}

Updated 11 months ago