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 request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.vicodo.com/api/sample_api_endpoint_here',
  headers: {
    Authorization: 'Basic YXBwSWQ6YXBwU2VjcmV0'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

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"
}'
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"
}
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.vicodo.com/api/cases/new',
  headers:
  {
    Authorization: 'Basic YXBwSWQ6YXBwU2VjcmV0',
    'Content-Type': 'application/json'
  },
  body:
  {
    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'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) {
    throw new Error(error);
  }

  console.log(body);
});

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
cancelationNote string Appointment's cancelation 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)

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 All Cases

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

const options = {
  method: 'GET',
  url: 'https://api.vicodo.com/api/cases',
  headers:
  {
    Authorization: 'Basic YXBwSWQ6YXBwU2VjcmV0'
  }
};

request(options, function (error, response, body) {
  if (error) {
    throw new Error(error);
  }

  console.log(body);
});

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 request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d',
  headers:
  {
    Authorization: 'Basic YXBwSWQ6YXBwU2VjcmV0'
  }
};

request(options, function (error, response, body) {
  if (error) {
    throw new Error(error);
  }

  console.log(body);
});

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 request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d',
  headers:
  {
    Authorization: 'Basic YXBwSWQ6YXBwU2VjcmV0',
    'Content-Type': 'application/json'
  },
  body:
  {
    state: "completed",
    userInfo: {
      phone: '+17033977090'
    },
    customFields: {
      custom_field_1: 'some other value'
    }
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) {
    throw new Error(error);
  }

  console.log(body);
});

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",
  "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 in settings are allowed
cancelationNote string Appointment's cancelation note (can be from client or from operator)
note string Case notes for operators

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 request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d',
  headers:
  {
    Authorization: 'Basic YXBwSWQ6YXBwU2VjcmV0'
  }
};

request(options, function (error, response, body) {
  if (error) {
    throw new Error(error);
  }

  console.log(body);
});

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 request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.vicodo.com/api/cases/5ba0d9aff3e4944f9ef0c94d/invitation_url',
  headers:
  {
    Authorization: 'Basic YXBwSWQ6YXBwU2VjcmV0'
  }
};

request(options, function (error, response, body) {
  if (error) {
    throw new Error(error);
  }

  console.log(body);
});

The above command returns an url like this:

https://vico.do/A89zX

This endpoint retrieves a shortened invitation link for client.

HTTP Request

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

URL Parameters

Parameter Description
caseId The ID of the case to retrieve

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