NAV
cURL HTTP NodeJS

Getting Started

Vicodo uses API keys to allow access to its API. By default access through API is disabled. You need to enable API access in your account settings and generate API keys first. To do this go to Dashboard > Settings > API Settings and select Enable API. Now you should see something that looks like the following:

These are your account's appId and appSecret. Right after enabling API you should have both API keys generated. They are visible only for admin account, operators cannot see them.

If you forgot, lost or want to invalidate current API keys you have two options:

  1. First option is to generate new appSecret key using GENERATE NEW button on the right. This will result in overwriting current appSecret key and thus invalidating it.

  2. Second option is to disable API access and then re-enable it again. This will result in creating new appId and appSecret keys and invalidating previous ones.

Authentication

Example request with authorization header:

# With shell, you can just pass the correct header with each request
curl "https://api.vicodo.com/api/sample_api_endpoint_here" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/sample_api_endpoint_here HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/sample_api_endpoint_here",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

Make sure to replace "YXBwSWQ6YXBwU2VjcmV0" with your API key.

Vicodo expects API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Basic <apiKey>

To acquire apiKey do the following:

  1. Combine your appId and appSecret with a colon like this: appId:appSecret.
  2. Encode result using base64: appId:appSecret -> YXBwSWQ6YXBwU2VjcmV0.
  3. YXBwSWQ6YXBwU2VjcmV0 is your apiKey.

Cases

Create Case

curl -X POST \
  https://api.vicodo.com/api/cases/new \
  -H 'Authorization: Basic YXBwSWQ6YXBwU2VjcmV0' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "William C. Bates",
  "userInfo": {
    "email": "william.bates@vicodo.com",
    "phone": "+17402847134"
  },
  "note": "Call after 5 pm",
  "startsAt": "2018-09-27T08:45:25.754Z",
  "defaultLang": "en",
  "customFields": {
    "custom_field_1": "some value",
    "custom_field_2": true
  }
}'
POST /api/cases/new HTTP/1.1
Host: api.vicodo.com
Content-Type: application/json
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0

{
  "name": "William C. Bates",
  "userInfo": {
    "email": "william.bates@vicodo.com",
    "phone": "+17402847134"
  },
  "note": "Call after 5 pm",
  "startsAt": "2018-09-27T08:45:25.754Z",
  "defaultLang": "en",
  "customFields": {
    "custom_field_1": "some value",
    "custom_field_2": true
  }
}
const https = require("https");

const postData = JSON.stringify({
  name: "William C. Bates",
  userInfo: {
    email: "william.bates@vicodo.com",
    phone: "+17402847134",
  },
  note: "Call after 5 pm",
  startsAt: "2018-09-27T08:45:25.754Z",
  defaultLang: "en",
  customFields: {
    custom_field_1: "some value",
    custom_field_2: true,
  },
});

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/new",
  method: "POST",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
    "Content-Type": "application/json",
    "Content-Length": postData.length,
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(postData);
req.end();

The above command returns JSON structured like this:

{
  "_id": "5ba0d9aff3e4944f9ef0c94d",
  "ownerId": "5b3f7e7280e54e3bd6cebd6d",
  "userInfo": {
    "email": "william.bates@vicodo.com",
    "phone": "+17402847134"
  },
  "createdAt": "2018-09-18T10:55:43.730Z",
  "createdVia": "api",
  "name": "William C. Bates",
  "note": "Call after 5 pm",
  "state": "active",
  "refNo": "#000000006",
  "feedback": [],
  "customFields": {
    "custom_field_1": "some value",
    "custom_field_2": true
  },
  "defaultLang": "en",
  "operatorHistory": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "operators": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "host": {
    "operatorId": "5b3f7e7280e54e3bd6cebd6d",
    "username": "alan.johns@vicodo.com",
    "email": "alan.johns@vicodo.com",
    "name": "Alan Johns"
  },
  "isPasswordProtected": false,
  "attachments": [],
  "calendarEvents": [
    {
      "_id": "5fce0d7eae9be44cc40fa7f0",
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "ownerId": "5b3f7e7280e54e3bd6cebd6d",
      "startDate": "2018-09-27T08:45:25.754Z",
      "endDate": "2018-09-27T09:15:25.754Z",
      "status": "valid"
    }
  ]
}

This endpoint creates a new case.

HTTP Request

POST https://api.vicodo.com/api/cases/new

Body Parameters

Parameter Type Required Description
name string Case name
userInfo object Contact information about client associated with case
startsAt string (ISO 8601) Appointment starting day and time
endsAt string (ISO 8601) Appointment finish day and time (by default startsAt + 30 minutes)
customFields object Custom fields object. Only fields defined by admin in settings panel are allowed.
note string Case notes for operators
defaultLang string Set case language. If not provided, default customer language from global settings will be used
options object Additional request options (see below)
operatorIds array (string) An array containing valid operator IDs. Pass valid operator IDs to assign provided operators to the case. Pass an empty list [] to create case without assigned operators. By default admin ID is provided.

Additional Options

You can pass additional options for this request:

Parameter Type Description
notify string Notify operators (which are active) about created case.

notify values

Parameter Description
me Notifies only the admin who makes the request (creating a case)
joined Notifies all operators/admin who are assigned to the case
all Notifies all operators/admin in your organization

Get Case list

curl "https://api.vicodo.com/api/cases" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

[
  {
    "_id": "5ba0d9aff3e4944f9ef0c94d",
    "ownerId": "5b3f7e7280e54e3bd6cebd6d",
    "userInfo": {
      "email": "william.bates@vicodo.com",
      "phone": "+17402847134"
    },
    "createdAt": "2018-09-18T10:55:43.730Z",
    "createdVia": "api",
    "name": "William C. Bates",
    "note": "Call after 5 pm",
    "state": "active",
    "refNo": "#000000006",
    "feedback": [],
    "customFields": {
      "custom_field_1": "some value",
      "custom_field_2": true
    },
    "defaultLang": "en",
    "operatorHistory": [
      {
        "operatorId": "5b3f7e7280e54e3bd6cebd6d",
        "username": "alan.johns@vicodo.com",
        "email": "alan.johns@vicodo.com",
        "name": "Alan Johns"
      }
    ],
    "operators": [
      {
        "operatorId": "5b3f7e7280e54e3bd6cebd6d",
        "username": "alan.johns@vicodo.com",
        "email": "alan.johns@vicodo.com",
        "name": "Alan Johns"
      }
    ],
    "host": {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    },
    "isPasswordProtected": false,
    "attachments": [],
    "calendarEvents": [
      {
        "_id": "5fce0d7eae9be44cc40fa7f0",
        "caseId": "5ba0d9aff3e4944f9ef0c94d",
        "ownerId": "5b3f7e7280e54e3bd6cebd6d",
        "startDate": "2018-09-27T08:45:25.754Z",
        "endDate": "2018-09-27T09:15:25.754Z",
        "status": "valid"
      }
    ]
  }
]

This endpoint retrieves all cases.

Cases are sorted by date (newest first).

HTTP Request

GET https://api.vicodo.com/api/cases

Query Parameters

This endpoint lets you filter the results of your queries by using the parameters listed below:

Pagination parameters

By using pagination parameters you can control how many results are returned and which part of them is displayed.

Parameter Type Default Description
page number 1 Page number
pageSize number 30 Page size (max 100)

AND parameters

If you use AND parameters, your query will only show cases that fulfill all of the parameters’ requirements.

Parameter Type Default Description
filter[state] string Get cases in specified states (active or completed)
filter[operators][operatorid] string Filter by operators with id equal to the specified value
filter[isAssigned] boolean false If true, get cases with at least one operator assigned. If false, get cases that have no operators assigned.
filter[neverAssigned] boolean false If true, get cases that never had any operators assigned. If false, get cases that are assigned or were assigned to at least one operator in the past.

OR parameters

If you use OR parameters, your query will show all the cases that fulfill at least one of the parameters’ requirements.

Parameter Type Default Description
filter[name] string Filter by cases with name matching the specified pattern
filter[refNo] string Filter by reference number matching the specified pattern
filter[internalReference] string Filter by internal reference matching the specified pattern
filter[operators][email] string Filter by operators with email matching the specified pattern
filter[operators][name] string Filter by operators with name matching the specified pattern
filter[userInfo][email] string Filter by users with email matching the specified pattern
filter[userInfo][phone] string Filter by users with phone matching the specified pattern

If you use both AND and OR parameters, your query will only show cases that fulfill all the ALL parameters’ requirements and at least one OR parameter requirement.

sortOrder parameter

Parameter Type Default Value Description
sortOrder string asc asc, ascending, 1 List cases in ascending order
sortOrder string asc desc, descending, -1 List cases in descending order

The usage of 'sortOrder' parameter is optional. By default, the cases are sorted in ascending order.

Examples

GET https://api.vicodo.com/api/cases?filter[name]=Bates - Find cases with name containing substring Bates

GET https://api.vicodo.com/api/cases?filter[userInfo][email]=william.bates@vicodo.com - Find cases that have client with email william.bates@vicodo.com

GET https://api.vicodo.com/api/cases?filter[userInfo][email]=william.bates@vicodo.com&sortOrder=1 - Find cases that have client with email william.bates@vicodo.com and sort them in ascending order

GET https://api.vicodo.com/api/cases?filter[internalReference]=006&filter[refNo]=006 - Find cases that internal reference contains substring 006 OR reference number contains substring 006

GET https://api.vicodo.com/api/cases?filter[state]=active&filter[operators][operatorId]=5b3f7e7280e54e3bd6cebd6d - Find cases that are active AND belongs to / have operator with id 5b3f7e7280e54e3bd6cebd6d

GET https://api.vicodo.com/api/cases?filter[state]=active&filter[operators][operatorId]=5b3f7e7280e54e3bd6cebd6d&sortOrder=desc - Find cases that are active AND belongs to / have operator with id 5b3f7e7280e54e3bd6cebd6d and sort them in descending order

GET https://api.vicodo.com/api/cases?filter[state]=completed&filter[userInfo][email]=alan.johns@vicodo.com&filter[operators][email]=alan.johns@vicodo.com - Find cases that are completed AND either have client with email alan.johns@vicodo.com OR have operator with email alan.johns@vicodo.com

Get a specific Case

curl "https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/5ba0d9aff3e4944f9ef0c94d HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

{
  "_id": "5ba0d9aff3e4944f9ef0c94d",
  "ownerId": "5b3f7e7280e54e3bd6cebd6d",
  "userInfo": {
    "email": "william.bates@vicodo.com",
    "phone": "+17402847134"
  },
  "createdAt": "2018-09-18T10:55:43.730Z",
  "createdVia": "api",
  "name": "William C. Bates",
  "note": "Call after 5 pm",
  "state": "active",
  "refNo": "#000000006",
  "feedback": [],
  "customFields": {
    "custom_field_1": "some value",
    "custom_field_2": true
  },
  "defaultLang": "en",
  "operatorHistory": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "operators": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "host": {
    "operatorId": "5b3f7e7280e54e3bd6cebd6d",
    "username": "alan.johns@vicodo.com",
    "email": "alan.johns@vicodo.com",
    "name": "Alan Johns"
  },
  "isPasswordProtected": false,
  "attachments": [],
  "calendarEvents": [
    {
      "_id": "5fce0d7eae9be44cc40fa7f0",
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "ownerId": "5b3f7e7280e54e3bd6cebd6d",
      "startDate": "2018-09-27T08:45:25.754Z",
      "endDate": "2018-09-27T09:15:25.754Z",
      "status": "valid"
    }
  ]
}

This endpoint retrieves a specific case.

HTTP Request

GET https://api.vicodo.com/api/cases/<caseId>

URL Parameters

Parameter Description
caseId The ID of the case to retrieve

Update Case

curl -X PUT \
  https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d \
  -H 'Authorization: Basic YXBwSWQ6YXBwU2VjcmV0' \
  -H 'Content-Type: application/json' \
  -d '{
  "state": "completed",
  "userInfo": {
    "phone": "+17033977090"
  },
  "customFields": {
    "custom_field_1": "some other value"
  }
}'
PUT /api/cases/5ba0d9aff3e4944f9ef0c94d HTTP/1.1
Host: api.vicodo.com
Content-Type: application/json
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0

{
  "state": "completed",
  "userInfo": {
    "phone": "+17033977090"
  },
  "customFields": {
    "custom_field_1": "some other value"
  }
}
const https = require("https");

const putData = JSON.stringify({
  state: "completed",
  userInfo: {
    phone: "+17033977090",
  },
  customFields: {
    custom_field_1: "some other value",
  },
});

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d",
  method: "PUT",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
    "Content-Type": "application/json",
    "Content-Length": putData.length,
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(putData);
req.end();

The above command returns JSON structured like this:

{
  "_id": "5ba0d9aff3e4944f9ef0c94d",
  "ownerId": "5b3f7e7280e54e3bd6cebd6d",
  "userInfo": {
    "email": "william.bates@vicodo.com",
    "phone": "+17033977090"
  },
  "createdAt": "2018-09-18T10:55:43.730Z",
  "createdVia": "api",
  "name": "William C. Bates",
  "note": "Call after 5 pm",
  "state": "completed",
  "refNo": "#000000006",
  "feedback": [],
  "customFields": {
    "custom_field_1": "some other value",
    "custom_field_2": true
  },
  "defaultLang": "en",
  "location": {
    "latitude": 50.368648,
    "longitude": 7.00538
  },
  "operatorHistory": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "operators": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "host": {
    "operatorId": "5b3f7e7280e54e3bd6cebd6d",
    "username": "alan.johns@vicodo.com",
    "email": "alan.johns@vicodo.com",
    "name": "Alan Johns"
  },
  "isPasswordProtected": false,
  "attachments": [],
  "calendarEvents": [
    {
      "_id": "5fce0d7eae9be44cc40fa7f0",
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "ownerId": "5b3f7e7280e54e3bd6cebd6d",
      "startDate": "2018-09-27T08:45:25.754Z",
      "endDate": "2018-09-27T09:15:25.754Z",
      "status": "valid"
    }
  ]
}

This endpoint updates a specific case.

If the request is successful, the endpoint returns an updated case object.

HTTP Request

PUT https://api.vicodo.com/api/cases/<caseId>

URL Parameters

Parameter Description
caseId The ID of the case to update

Body Parameters

Please note that you don't need to necessarily pass whole case object. You can pass only fields that you want to update.

Parameter Type Description
name string Case name
state string Case state (active or completed)
userInfo object Contact information about client associated with case
customFields object Custom fields object. Only fields defined by admin in settings panel are allowed.
note string Case notes for operators
location object (Location) Object containing location coordinates. To remove coordinates, pass this parameter with null value.

Location

Parameter Type Required Description
latitude number Location latitude
longitude number Location longitude

Delete Case

curl -X DELETE \
  https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
DELETE /api/cases/5ba0d9aff3e4944f9ef0c94d HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d",
  method: "DELETE",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

{
  "_id": "5ba0d9aff3e4944f9ef0c94d",
  "ownerId": "5b3f7e7280e54e3bd6cebd6d",
  "userInfo": {
    "email": "william.bates@vicodo.com",
    "phone": "+17402847134"
  },
  "createdAt": "2018-09-18T10:55:43.730Z",
  "createdVia": "api",
  "name": "William C. Bates",
  "note": "Call after 5 pm",
  "state": "active",
  "refNo": "#000000006",
  "feedback": [],j
  "customFields": {
    "custom_field_1": "some value",
    "custom_field_2": true
  },
  "defaultLang": "en",
  "operatorHistory": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "operators": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "host": {
    "operatorId": "5b3f7e7280e54e3bd6cebd6d",
    "username": "alan.johns@vicodo.com",
    "email": "alan.johns@vicodo.com",
    "name": "Alan Johns"
  },
  "isPasswordProtected": false,
  "attachments": []
}

This endpoint removes a specific case.

If the request is successful, the endpoint returns a case that was removed.

HTTP Request

DELETE https://api.vicodo.com/api/cases/<caseId>

URL Parameters

Parameter Description
caseId The ID of the case to remove
curl "https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/invitation_url" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/5ba0d9aff3e4944f9ef0c94d/invitation_url HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/invitation_url",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns an url like this:

https://vico.do/A89zX

This endpoint retrieves an invitation link for the client. By default a shortened url is returned.

HTTP Request

GET https://api.vicodo.com/api/cases/<caseId>/invitation_url

URL Parameters

Parameter Description
caseId The ID of the case to retrieve

Query Parameters

This endpoint exposes available query params listed below.

Parameter Type Default Description
fullUrl boolean false Return full invitation url instead of shortened url

Assign operators

curl -X PUT \
  https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/assign_operators \
  -H 'Authorization: Basic YXBwSWQ6YXBwU2VjcmV0' \
  -H 'Content-Type: application/json' \
  -d '{
  "operatorIds": ["5b3f7e7280e54e3bd6cebd6d"]
}'
PUT /api/cases/5ba0d9aff3e4944f9ef0c94d/assign_operators HTTP/1.1
Host: api.vicodo.com
Content-Type: application/json
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0

{
  "operatorIds": ["5b3f7e7280e54e3bd6cebd6d"]
}
const https = require("https");

const putData = JSON.stringify({
  operatorIds: ["5b3f7e7280e54e3bd6cebd6d"],
});

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/assign_operators",
  method: "PUT",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
    "Content-Type": "application/json",
    "Content-Length": putData.length,
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(putData);
req.end();

The above command returns JSON structured like this:

{
  "_id": "5ba0d9aff3e4944f9ef0c94d",
  "ownerId": "5b3f7e7280e54e3bd6cebd6d",
  "createdAt": "2018-09-18T10:55:43.730Z",
  "createdVia": "api",
  "name": "William C. Bates",
  "state": "active",
  "refNo": "#000000006",
  "feedback": [],
  "operatorHistory": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "operators": [
    {
      "operatorId": "5b3f7e7280e54e3bd6cebd6d",
      "username": "alan.johns@vicodo.com",
      "email": "alan.johns@vicodo.com",
      "name": "Alan Johns"
    }
  ],
  "host": {
    "operatorId": "5b3f7e7280e54e3bd6cebd6d",
    "username": "alan.johns@vicodo.com",
    "email": "alan.johns@vicodo.com",
    "name": "Alan Johns"
  },
  "isPasswordProtected": false,
  "attachments": [],
  "calendarEvents": [
    {
      "_id": "5fce0d7eae9be44cc40fa7f0",
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "ownerId": "5b3f7e7280e54e3bd6cebd6d",
      "startDate": "2018-09-27T08:45:25.754Z",
      "endDate": "2018-09-27T09:15:25.754Z",
      "status": "valid"
    }
  ]
}

This endpoint allows to assign/unassign operators to/from given case.

Calling this endpoint will result in assigning all provided operators to the case. If there are already assigned operators to the case that are not provided in request, they will be automatically unassigned from the case. To unassign all operators from the case, pass an empty list [] in the body.

If the request is successful, the endpoint returns an updated case object with assigned operators.

If some of the operator IDs are not valid or not found, the endpoint will return a 400 BAD REQUEST response.

HTTP Request

PUT https://api.vicodo.com/api/cases/<caseId>/assign_operators

URL Parameters

Parameter Description
caseId The ID of the case to update

Body Parameters

Parameter Type Required Description
operatorIds array (string) An array containing valid operator IDs

Create Case password

curl -X POST \
  https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/password \
  -H 'Authorization: Basic YXBwSWQ6YXBwU2VjcmV0'
POST /api/cases/5ba0d9aff3e4944f9ef0c94d/password HTTP/1.1
Host: api.vicodo.com
Content-Type: application/json
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/password",
  method: "POST",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

{
  "password": "000000"
}

This endpoint allows you to create a password for a case. If the case already has a password, a new password will be created.

If the request is successful, the endpoint returns a new password for the case.

If the case is not found, the endpoint will return a 404 NOT FOUND response.

HTTP Request

POST https://api.vicodo.com/api/cases/<caseId>/password

URL Parameters

Parameter Description
caseId The ID of the case

Get Case password

curl "https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/password" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/5ba0d9aff3e4944f9ef0c94d/password HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/password",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

{
  "password": "000000"
}

This endpoint allows you to get the password of a password-protected case.

If the request is successful, the endpoint returns the case's password.

If the case is not found or it does not have a password, the endpoint will return a 404 NOT FOUND response.

HTTP Request

GET https://api.vicodo.com/api/cases/<caseId>/password

URL Parameters

Parameter Description
caseId The ID of the case

Delete Case password

curl -X DELETE \
  https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/password \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
DELETE /api/cases/5ba0d9aff3e4944f9ef0c94d/password HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/password",
  method: "DELETE",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command does not return anything in body.

This endpoint deletes a password from a password-protected case.

If the request is successful, the endpoint returns an empty 200 OK response.

If the case is not found, the endpoint will return a 404 NOT FOUND response.

HTTP Request

DELETE https://api.vicodo.com/api/cases/<caseId>/password

URL Parameters

Parameter Description
caseId The ID of the case

Customers

Get Customer list

curl "https://api.vicodo.com/api/customers" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/customers HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/customers",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

[
  {
    "_id": "5b3f7e7280e54e3bd6cebd6d",
    "username": "alan.johns@vicodo.com",
    "email": "alan.johns@vicodo.com",
    "phone": "+491555557354",
    "name": "Alan Johns",
    "licence": {},
    "defaultClientLanguage": "en",
    "dashboardLanguage": "en",
    "customFields": [],
    "globalSettings": {},
    "notificationSettings": {},
    "webhooks": [],
    "tags": []
  },
  {
    "_id": "5ba36ffbeff42a5cdcd1043c",
    "username": "daisy.blake@vicodo.com",
    "email": "daisy.blake@vicodo.com",
    "name": "Daisy Blake",
    "adminId": "5b3f7e7280e54e3bd6cebd6d",
    "licence": {},
    "defaultClientLanguage": "en",
    "dashboardLanguage": "en",
    "notificationSettings": {},
    "tags": []
  }
]

This endpoint retrieves a list of all customers being part of one organization.

HTTP Request

GET https://api.vicodo.com/api/customers

Get a specific Customer

curl "https://api.vicodo.com/api/customers/5b3f7e7280e54e3bd6cebd6d" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/customers/5b3f7e7280e54e3bd6cebd6d HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/customers/5b3f7e7280e54e3bd6cebd6d",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

{
  "_id": "5b3f7e7280e54e3bd6cebd6d",
  "username": "alan.johns@vicodo.com",
  "email": "alan.johns@vicodo.com",
  "phone": "+491555557354",
  "name": "Alan Johns",
  "licence": {},
  "defaultClientLanguage": "en",
  "dashboardLanguage": "en",
  "customFields": [],
  "globalSettings": {},
  "notificationSettings": {},
  "webhooks": [],
  "tags": []
}

This endpoint retrieves information about a specific customer. The user must be part of your organization.

HTTP Request

GET https://api.vicodo.com/api/customers/<customerId>

URL Parameters

Parameter Description
customerId The ID of the customer to retrieve

Attachments

Get attachments list

curl "https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/5ba0d9aff3e4944f9ef0c94d/attachments HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

[
  {
    "_id": "5e972497255898e76eb7fd92",
    "caseId": "5ba0d9aff3e4944f9ef0c94d",
    "createdAt": "2020-04-15T15:13:27.000Z",
    "fileName": "notes.txt",
    "fileType": "txt",
    "contentType": "text/plain",
    "tags": ["car"]
  },
  {
    "_id": "5e9724a59b11513c2b9dac26",
    "caseId": "5ba0d9aff3e4944f9ef0c94d",
    "createdAt": "2020-04-15T15:13:41.000Z",
    "fileName": "scan.png",
    "fileType": "png",
    "contentType": "image/png",
    "tags": ["engine", "EZ30"]
  },
  {
    "_id": "5e9724adc7a480e7c830e4b2",
    "caseId": "5ba0d9aff3e4944f9ef0c94d",
    "createdAt": "2020-04-15T15:13:49.000Z",
    "fileName": "screenshot.jpg",
    "fileType": "jpg",
    "contentType": "image/jpeg",
    "tags": ["engine", "EZ30"]
  }
]

This endpoint retrieves all attachments that were added to specific case.

HTTP Request

GET https://api.vicodo.com/api/cases/<caseId>/attachments

URL Parameters

Parameter Description
caseId The ID of the case

Query Parameters

This endpoint exposes filter API with available query params listed below. All params are concatenated in an OR query.

Parameter Type Description
filter[tags] string Filter by tags with matching the specified pattern

Examples

GET http://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments?filter[tags]=car - Find all attachments within 5ba0d9aff3e4944f9ef0c94d case with car tag

GET http://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments?filter[tags]=car&filter[tags]=engine - Find all attachments within 5ba0d9aff3e4944f9ef0c94d case with either car or engine tag

Get a specific attachment information

curl "https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments/5e972497255898e76eb7fd92" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/5ba0d9aff3e4944f9ef0c94d/attachments/5e972497255898e76eb7fd92 HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path:
    "/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments/5e972497255898e76eb7fd92",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

{
  "_id": "5e972497255898e76eb7fd92",
  "caseId": "5ba0d9aff3e4944f9ef0c94d",
  "createdAt": "2020-04-15T15:13:27.000Z",
  "fileName": "notes.txt",
  "fileType": "txt",
  "contentType": "text/plain",
  "tags": ["car"]
}

This endpoint retrieves a specific attachment that was added to case.

HTTP Request

GET https://api.vicodo.com/api/cases/<caseId>/attachments/<attachmentId>

URL Parameters

Parameter Description
caseId The ID of the case
attachmentId The ID of the attachment

Download attachment

curl "https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments/5e972497255898e76eb7fd92/download" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/5ba0d9aff3e4944f9ef0c94d/attachments/5e972497255898e76eb7fd92/download HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path:
    "/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments/5e972497255898e76eb7fd92/download",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns the contents of the file.

This endpoint allows to directly download the attachment file.

HTTP Request

GET https://api.vicodo.com/api/cases/<caseId>/attachments/<attachmentId>/download

URL Parameters

Parameter Description
caseId The ID of the case
attachmentId The ID of the attachment

Delete attachment

curl -X DELETE \
  https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments/5e972497255898e76eb7fd92 \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
DELETE /api/cases/5ba0d9aff3e4944f9ef0c94d/attachments/5e972497255898e76eb7fd92 HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path:
    "/api/cases/5ba0d9aff3e4944f9ef0c94d/attachments/5e972497255898e76eb7fd92",
  method: "DELETE",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command does not return anything in body.

This endpoint removes a specific attachment.

HTTP Request

DELETE https://api.vicodo.com/api/cases/<caseId>/attachments/<attachmentId>

URL Parameters

Parameter Description
caseId The ID of the case
attachmentId The ID of the attachment

Video Calls

Get video calls list

curl "https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

[
  {
    "_id": "63048fd95c68451c5b322c6b",
    "provider": "liveSwitch",
    "caseId": "5ba0d9aff3e4944f9ef0c94d",
    "recordingUrl": "https://url-to-recording-file",
    "thumbnailUrl": "https://url-to-recording-thumbnail-image-file",
    "createdAt": "2022-08-16T10:32:50.425Z",
    "updatedAt": "2022-08-16T10:32:50.425Z"
  },
  {
    "_id": "63048fdfd68dc7ff612e7c81",
    "provider": "liveSwitch",
    "caseId": "5ba0d9aff3e4944f9ef0c94d",
    "recordingUrl": "https://url-to-another-recording-file",
    "thumbnailUrl": "https://url-to-another-recording-thumbnail-image-file",
    "createdAt": "2022-08-16T14:11:53.712Z",
    "updatedAt": "2022-08-16T14:11:53.712Z"
  }
]

This endpoint retrieves all video calls that were recorded for a specific case.

HTTP Request

GET https://api.vicodo.com/api/cases/<caseId>/videocalls

URL Parameters

Parameter Description
caseId The ID of the case

Get a specific video call information

curl "https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls/63048fd95c68451c5b322c6b" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls/63048fd95c68451c5b322c6b HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls/63048fd95c68451c5b322c6b",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

{
  "_id": "63048fd95c68451c5b322c6b",
  "provider": "liveSwitch",
  "caseId": "5ba0d9aff3e4944f9ef0c94d",
  "recordingUrl": "https://url-to-recording-file",
  "thumbnailUrl": "https://url-to-recording-thumbnail-image-file",
  "createdAt": "2022-08-16T10:32:50.425Z",
  "updatedAt": "2022-08-16T10:32:50.425Z"
}

This endpoint retrieves a specific video call that was recorded for a specific case.

HTTP Request

GET https://api.vicodo.com/api/cases/<caseId>/videocalls/<videoId>

URL Parameters

Parameter Description
caseId The ID of the case
videoId The ID of the video call

Download video recording file

curl "https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls/63048fd95c68451c5b322c6b/download" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls/63048fd95c68451c5b322c6b/download HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls/63048fd95c68451c5b322c6b/download",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns the contents of the recording file.

This endpoint allows to directly download the video call file.

Please note that using this endpoint to the download video recording is only possible for recordings recorded by liveSwitch provider.

HTTP Request

GET https://api.vicodo.com/api/cases/<caseId>/videocalls/<videoId>/download

URL Parameters

Parameter Description
caseId The ID of the case
videoId The ID of the video call

Delete video call

curl -X DELETE \
  https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls/63048fd95c68451c5b322c6b \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
DELETE /api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls/63048fd95c68451c5b322c6b HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/5ba0d9aff3e4944f9ef0c94d/videocalls/63048fd95c68451c5b322c6b",
  method: "DELETE",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command does not return anything in body.

This endpoint removes a specific video call.

HTTP Request

DELETE https://api.vicodo.com/api/cases/<caseId>/videocalls/<videoId>

URL Parameters

Parameter Description
caseId The ID of the case
videoId The ID of the video call

Calendar Events

Get calendar events list

curl "https://api.vicodo.com/api/cases/calendar/events" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/calendar/events HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/calendar/events",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

{
  "events": [
    {
      "_id": "5f33eae83d82f813239a3c32",
      "ownerId": "5b3f7e7280e54e3bd6cebd6d",
      "startDate": "2022-07-20T13:00:00.000Z",
      "endDate": "2022-07-20T14:00:00.000Z",
      "status": "valid",
      "case": {}
    },
    {
      "_id": "6214bcf5ab11a3ed65b17d77",
      "ownerId": "5b3f7e7280e54e3bd6cebd6d",
      "startDate": "2022-07-20T13:30:00.000Z",
      "endDate": "2022-07-20T14:30:00.000Z",
      "status": "cancelled",
      "case": {}
    },
    {
      "_id": "6298c10a0a5350879e64ce10",
      "ownerId": "5b3f7e7280e54e3bd6cebd6d",
      "startDate": "2022-07-20T15:00:00.000Z",
      "endDate": "2022-07-20T16:00:00.000Z",
      "status": "valid",
      "case": {
        "_id": "5ba0d9aff3e4944f9ef0c94d",
        "name": "William C. Bates",
        "refNo": "#000000006",
        "userInfo": {
          "email": "william.bates@vicodo.com",
          "phone": "+17402847134"
        },
        "operatorIds": ["5b3f7e7280e54e3bd6cebd6d"]
      }
    },
    {
      "_id": "62a339c81413f80af0bd47ab",
      "ownerId": "5b3f7e7280e54e3bd6cebd6d",
      "startDate": "2022-07-20T11:00:00.000Z",
      "endDate": "2022-07-20T12:00:00.000Z",
      "recurrence": {
        "rrule": ["RRULE:FREQ=WEEKLY;BYDAY=WE"],
        "timezone": "Europe/Warsaw",
        "until": "2199-12-25T11:00:00.000Z"
      },
      "status": "valid",
      "case": {}
    }
  ],
  "pagination": {
    "page": 0,
    "pageSize": 30,
    "totalElements": 4,
    "totalPages": 1,
    "lastPage": true
  }
}

This endpoint retrieves all calendar events. It accepts query parameters to narrow down the results.

HTTP Request

GET https://api.vicodo.com/api/cases/calendar/events

Query Parameters

This endpoint lets you filter the results of your queries by using the parameters listed below:

Pagination parameters

By using pagination parameters you can control how many results are returned and which part of them is displayed.

Parameter Type Default Description
page number 1 Page number
pageSize number 30 Page size (max 100)

Filter parameters

By using filter parameters, your query will only show calendar events that fulfill all of the parameters’ requirements.

Parameter Type Description
filter[status] string Get calendar events with specified status (valid or cancelled)
filter[caseId] string Show calendar events assigned to specified case
filter[operatorIds] string Show calendar events that have at least one of the provided operators assigned - meaning either a calendar event related to a case with the assigned operator or a calendar event without a related case (e.g. a Blocker event) with the operator being the owner of the event. You can use this filter more than once to include other operators’ IDs (see examples below).
filter[isAssigned] boolean If true, show calendar events with attached cases that have at least one operator assigned. If false, show calendar events with attached cases that have no operators assigned or calendar events without any cases
filter[startDate] string (ISO 8601) Show only calendar events that start after the provided date
filter[endDate] string (ISO 8601) Show only calendar events that end before the provided date

Examples

GET https://api.vicodo.com/api/cases/calendar/events?filter[status]=valid - Find calendar events that have a valid status

GET https://api.vicodo.com/api/cases/calendar/events?filter[startDate]=2022-07-17T22:00:00.000Z&filter[endDate]=2022-07-24T22:00:00.000Z - Find calendar events that start after startDate and end before endDate

GET https://api.vicodo.com/api/cases/calendar/events?filter[operatorIds]=5b3f7e7280e54e3bd6cebd6d&filter[operatorIds]=5ba0d9aff3e4944f9ef0c94d - Find calendar events that have either operator with id 5b3f7e7280e54e3bd6cebd6d or operator with id 5ba0d9aff3e4944f9ef0c94d assigned

Get a specific calendar event

curl "https://api.vicodo.com/api/cases/calendar/events" \
  -H "Authorization: Basic YXBwSWQ6YXBwU2VjcmV0"
GET /api/cases/calendar/events HTTP/1.1
Host: api.vicodo.com
Authorization: Basic YXBwSWQ6YXBwU2VjcmV0
const https = require("https");

const options = {
  hostname: "api.vicodo.com",
  port: 443,
  path: "/api/cases/calendar/events",
  method: "GET",
  headers: {
    Authorization: "Basic YXBwSWQ6YXBwU2VjcmV0",
  },
};

const req = https.request(options, (res) => {
  console.log("statusCode: ", res.statusCode);

  res.on("data", (data) => {
    console.log("data: ", data);
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();

The above command returns JSON structured like this:

{
  "_id": "6298c10a0a5350879e64ce10",
  "ownerId": "5b3f7e7280e54e3bd6cebd6d",
  "startDate": "2022-07-20T15:00:00.000Z",
  "endDate": "2022-07-20T16:00:00.000Z",
  "status": "valid",
  "case": {
    "_id": "5ba0d9aff3e4944f9ef0c94d",
    "name": "William C. Bates",
    "refNo": "#000000006",
    "userInfo": {
      "email": "william.bates@vicodo.com",
      "phone": "+17402847134"
    },
    "operatorIds": ["5b3f7e7280e54e3bd6cebd6d"]
  }
},

This endpoint retrieves a specific calendar event based on id.

HTTP Request

GET https://api.vicodo.com/api/cases/calendar/events/<eventId>

URL Parameters

Parameter Description
eventId The ID of the calendar event

Webhooks

Below is a list of all events responses:

// operator_message_sent

{
  "body": {
    "date": "2020-04-30T13:47:19.463Z",
    "eventType": "operator_message_sent",
    "data": {
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "senderId": "5b3f7e7280e54e3bd6cebd6d",
      "message": "Hello William!"
    }
  }
}
// client_message_sent

{
  "body": {
    "date": "2020-04-30T13:47:19.463Z",
    "eventType": "client_message_sent",
    "data": {
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "senderId": "William C. Bates",
      "message": "Hi Alan"
    }
  }
}
// case_created

{
  "body": {
    "date": "2020-04-30T13:47:19.463Z",
    "eventType": "case_created",
    "data": {
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "senderId": "5b3f7e7280e54e3bd6cebd6d"
    }
  }
}
// case_completed

{
  "body": {
    "date": "2020-04-30T13:47:19.463Z",
    "eventType": "case_completed",
    "data": {
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "senderId": "5b3f7e7280e54e3bd6cebd6d"
    }
  }
}
// case_reopened

{
  "body": {
    "date": "2020-04-30T13:47:19.463Z",
    "eventType": "case_reopened",
    "data": {
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "senderId": "5b3f7e7280e54e3bd6cebd6d"
    }
  }
}
// case_deleted

{
  "body": {
    "date": "2020-04-30T13:47:19.463Z",
    "eventType": "case_deleted",
    "data": {
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "senderId": "5b3f7e7280e54e3bd6cebd6d"
    }
  }
}
// client_appointment_cancelled

{
  "body": {
    "date": "2020-04-30T13:47:19.463Z",
    "eventType": "client_appointment_cancelled",
    "data": {
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "senderId": "William C. Bates"
    }
  }
}
// operator_appointment_cancelled

{
  "body": {
    "date": "2020-04-30T13:47:19.463Z",
    "eventType": "operator_appointment_cancelled",
    "data": {
      "caseId": "5ba0d9aff3e4944f9ef0c94d",
      "senderId": "5b3f7e7280e54e3bd6cebd6d"
    }
  }
}

Webhooks let you send events that occur in Vicodo to any endpoint that is under your control.

To set up a webhook, navigate to Settings -> Integration -> Webhooks tab. Once there, click Add new webhook button.

After you are done with setting up your webhook, it will appear on a webhooks list.

You can test your webhook by clicking Test button next to it.

You can select an event that you want to be sent. Clicking Test button will send the event. Note that the request body will contain example test data.

Every admin account can enable up to 5 webhooks to different endpoints.

Event types

Below is a list of current events in the system:

Webhook Event Meaning
operator_message_sent Event sent when operator sends a chat message to the client.
client_message_sent Event sent when client sends a chat message to the operator.
case_created Event sent when a new case is created.
case_completed Event sent when a case is marked as completed.
case_reopened Event sent when a completed case case is reopened.
case_deleted Event sent when a case is deleted.
client_appointment_cancelled Event sent when client cancels an appointment.
operator_appointment_cancelled Event sent when operator cancels an appointment.

Event data

Depending on event type, data will contain different set of fields:

Field Description
caseId Id of the case.
senderId Id of the user that triggered the event. In case of operator or admin, their id will be returned. In case of a client - a case name will be returned.
message Content of the chat message.

Errors

The Vicodo API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid or has missing fields. Check error message in response for details
401 Unauthorized -- Your API key is invalid
403 Forbidden -- You don't have permissions to access this resource
404 Not Found -- The specified resource could not be found
429 Too Many Requests -- You're requesting too many resources in a short time period. Please try again later
500 Internal Server Error -- We had a problem with our server. Please try again later or contact us if error persists
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later