CompleteTrack API

Current Version ¶

By default, all requests to https://api.completetrack.io receive the v1 version of the REST API. We encourage you to explicitly request this version via the Accept header.

Accept: application/vnd.completetrack.v1+json

Schema ¶

All API access is over HTTPS, and accessed from the https://api.completetrack.io. All data is sent and received as JSON.

Blank fields are included as null instead of being omitted.

All timestamps return in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Summary Representations ¶

When you fetch a list of resources, the response includes a subset of the attributes for that resource. This is the “summary” representation of the resource.

Detailed Representations ¶

When you fetch an individual resource, the response typically includes all attributes for that resource. This is the “detailed” representation of the resource. (Note that authorization sometimes influences the amount of detail included in the representation.)

Parameters ¶

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter.

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’.

Client Errors ¶

There are three possible types of client errors on API calls that receive request bodies:

1. Sending invalid JSON will result in a 400 Bad Request response.

2. Sending the wrong type of JSON values will result in a 400 Bad Request response.

3. Sending invalid fields will result in a 422 Unprocessable Entity response.

Errors will always have a message field describing the error and may enumerate the specific errors via the error array.

HTTP Verbs ¶

Where possible, the API strives to use appropriate HTTP verbs for each action.

Authentication ¶

There are two ways to authenticate through the API. Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private information to unauthorized users.

1. Basic Authentication

2. OAuth2 Token (sent in the Authorization header)

3. OAuth2 Token (sent via the access_token parameter)

Tokens for OAuth Apps can be obtained by issuing a POST to https://api.completetrack.io/oauth/token. Currently the only supported workflow is server-to-server (i.e. client_credentials):

curl -X POST http://api.completetrack.io/oauth/token?
  grant_type=client_credentials
  &client_id=CLIENT_ID
  &client_secret=CLIENT_SECRET

Pagination ¶

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter.

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

User Agent Required ¶

All API requests MUST include a valid User-Agent header. Requests with no User-Agent header will be rejected. We request that you use your account, organization, or the name of your application, for the User-Agent header value. This allows us to contact you if there are problems.

Cross Origin Resource Sharing ¶

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation, or this intro from the HTML 5 Security Guide.

Content-Type: application/json

[
  {
    "id": "5225667016f2f72d21000003",
    "labels": [
      "presidential"
    ],
    "first_name": "George",
    "last_name": "Washington",
    "phone_one": "4567890123",
    "email": "george@washington.gov",
    "address": "1 Apple Tree Ln.",
    "city": "Richmond",
    "region": "Virginia",
    "postal_code": "34569"
  }
]

Content-Type: application/json

{
  "first_name": "Gilbert",
  "last_name": "Sullivan",
  "phone_one": "3457890123",
  "company": "Music & More"
}

Content-Type: application/json
Location: https://api.completetrack.io/accounts/test-account/contacts/52b3cc3f4d61637653100000

{
  "id": "52b3cc3f4d61637653100000",
  "first_name": "Gilbert",
  "last_name": "Sullivan",
  "phone_one": "3457890123",
  "company": "Music & More",
  "created_at": "2013-12-20T04:49:03.606Z",
  "updated_at": "2013-12-20T04:49:03.606Z"
}

Content-Type: application/json

{
  "id": "52b3cc3f4d61637653100000",
  "first_name": "Gilbert",
  "last_name": "Sullivan",
  "phone_one": "3457890123",
  "company": "Music & More",
  "created_at": "2013-12-20T04:49:03.606Z",
  "updated_at": "2013-12-20T04:49:03.606Z"
}

Content-Type: application/json

{
  "labels": [
    "musical"
  ]
}

Content-Type: application/json

{
  "id": "52b3cc3f4d61637653100000",
  "labels": [
    "musical"
  ],
  "first_name": "Gilbert",
  "last_name": "Sullivan",
  "phone_one": "3457890123",
  "company": "Music & More",
  "created_at": "2013-12-20T04:49:03.606Z",
  "updated_at": "2014-11-12T01:12:41.101Z"
}

Content-Type: application/json

[
  {
    "id": "1234",
    "description": "Unable to access account",
    "status": "open",
    "labels": [
      "referral"
    ],
    "disposition": [
      "Support",
      "Account"
    ],
    "channel": "phone",
    "contact": {
      "id": "5963c55acda6ce6f84cf20d3",
      "first_name": "Mary",
      "last_name": "Sunshine",
      "phone_one": "1234567890"
    },
    "fields": {
      "qid.model": "ABC-123"
    },
    "created_at": "2014-11-11T08:40:51.620Z",
    "updated_at": "2014-11-11T08:40:51.620Z"
  }
]

Content-Type: application/json

{
  "description": "Customer interested in upgrading",
  "status": "open",
  "labels": [
    "loyalty",
    "tier-two"
  ],
  "disposition": [
    "Sales",
    "Existing Customer",
    "Upgrade"
  ],
  "channel": "phone",
  "contact_id": "5225667016f2f72d21000003",
  "fields": {
    "qid.products": [
      "Boom",
      "Blam"
    ],
    "qid.warranty": false
  },
  "assignee_id": "522cebd016f2f70114000011"
}

Content-Type: application/json
Location: https://api.completetrack.io/accounts/test-account/tickets/4567

{
  "id": "4567",
  "description": "Customer interested in upgrading",
  "status": "open",
  "labels": [
    "loyalty",
    "tier-two"
  ],
  "disposition": [
    "Sales",
    "Existing Customer",
    "Upgrade"
  ],
  "channel": "phone",
  "contact": {
    "id": "5225667016f2f72d21000003",
    "first_name": "George",
    "last_name": "Washington",
    "phone_one": "4567890123",
    "address": "1 Apple Tree Ln. Richmond, Virginia 34569"
  },
  "fields": {
    "qid.products": [
      "Boom",
      "Blam"
    ],
    "qid.warranty": false
  },
  "assignee": {
    "id": "522cebd016f2f70114000011",
    "display_name": "Luxanna Troi"
  },
  "created_at": "2015-10-17T01:30:11.123Z",
  "updated_at": "2015-10-17T01:30:11.123Z"
}

Content-Type: application/json

{
  "id": "1234",
  "description": "Unable to access account",
  "status": "open",
  "labels": [
    "referral"
  ],
  "disposition": [
    "Support",
    "Account"
  ],
  "channel": "phone",
  "contact": {
    "id": "5963c55acda6ce6f84cf20d3",
    "first_name": "Mary",
    "last_name": "Sunshine",
    "phone_one": "1234567890"
  },
  "fields": {
    "qid.model": "ABC-123"
  },
  "created_at": "2014-11-11T08:40:51.620Z",
  "updated_at": "2014-11-11T08:40:51.620Z"
}

Content-Type: application/json

{
  "description": "Not able to login to access account"
}

Content-Type: application/json

{
  "id": "1234",
  "description": "Not able to login to access account",
  "status": "open",
  "labels": [
    "referral"
  ],
  "disposition": [
    "Support",
    "Account"
  ],
  "channel": "phone",
  "contact": {
    "id": "5963c55acda6ce6f84cf20d3",
    "first_name": "Mary",
    "last_name": "Sunshine",
    "phone_one": "1234567890"
  },
  "fields": {
    "qid.model": "ABC-123"
  },
  "created_at": "2014-11-11T08:40:51.620Z",
  "updated_at": "2015-04-45T11:23:39.593Z"
}

Content-Type: application/json

{
  "assignee": "5226aa1516f2f72eef000003"
}

Content-Type: application/json

[
  {
    "type": "label",
    "value": "Escalations",
    "transitions": 2,
    "total_time": 32382
  }
]

Content-Type: application/json

{
  "template": "{{id}}, {{status}}, {{description}}, {{labels}}"
}

Content-Type: text/plain

Content-Type: application/json

[
  {
    "id": "53a726484d616348cd130000",
    "text": "Unable to access account",
    "author": {
      "id": "522cceab16f2f7ff92000005",
      "display_name": "Agent One"
    },
    "created_at": "2013-12-20T04:45:30.574Z"
  }
]

Content-Type: application/json

{
  "text": "I am *very* **very** important comment"
}

Content-Type: application/json
Location: https://api.completetrack.io/accounts/test-account/tickets/4567/comments/52b3ccbe4d61637653190000

{
"id": "52b3ccbe4d61637653190000",
"text" : "I am *very* **very** important comment"
"author": {
"id": "522cceab16f2f7ff92000005",
"display_name": "Agent One"
},
"created_at": "2013-12-20T04:45:30.574Z"
}

Content-Type: application/json

{
  "total_count": 14,
  "contacts": [
    {
      "id": "52b3cc3f4d61637653100000",
      "labels": [
        "musical"
      ],
      "first_name": "Gilbert",
      "last_name": "Sullivan",
      "phone_one": "3457890123",
      "company": "Music & More",
      "created_at": "2013-12-20T04:49:03.606Z",
      "updated_at": "2014-11-12T01:12:41.101Z"
    }
  ]
}

Content-Type: application/json

{
"total_count": 42,
"tickets": [
  {
  "id": "1234",
  "description": "Not able to login to access account",
  "status": "open",
  "labels": [ "referral" ],
  "disposition": [ "Support", "Account" ],
  "channel": "phone",
  "contact" : {
    "id": "5963c55acda6ce6f84cf20d3",
    "first_name": "Mary",
    "last_name": "Sunshine",
    "phone_one": "1234567890"
  },
  "fields": {
    "qid.model" : "ABC-123"
  },
  "created_at": "2014-11-11T08:40:51.620Z",
  "updated_at": "2015-04-45T11:23:39.593Z"
}
}