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",
  "startsAt": "2018-09-27T08:45:25.754Z",
  "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"
  },
  "attachments": []
}

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 date and time
customFields object Custom fields object. Only fields defined by admin in settings panel are allowed.
cancelationNote string Appointment's cancellation note (can be from client or from operator)
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",
    "startsAt": "2018-09-27T08:45:25.754Z",
    "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"
    },
    "attachments": []
  }
]

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 exposes filter API with available query params listed below. All params except filter[state] are concatenated in an OR query.

Parameter Type Default Description
page number 1 Page number
pageSize number 30 Page size
filter[state] string Get only cases in specified states (active or completed)
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][operatorid] string Filter by operators with id equal to the specified value
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

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[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]=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",
  "startsAt": "2018-09-27T08:45:25.754Z",
  "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"
  },
  "attachments": []
}

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",
  "startsAt": "2018-09-27T08:45:25.754Z",
  "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"
  },
  "attachments": []
}

This endpoint updates a specific case.

If successful, 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
startsAt string (ISO 8601) Appointment date and time
customFields object Custom fields object. Only fields defined by admin in settings panel are allowed.
cancelationNote string Appointment's cancellation note (can be from client or from operator)
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",
  "startsAt": "2018-09-27T08:45:25.754Z",
  "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"
  },
  "attachments": []
}

This endpoint removes a specific case.

If successful, 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"
  }
}

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 successful, 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

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

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