Total Expert Public API
The Total Expert REST API allows you to programmatically create, retrieve, update, and delete information through various endpoints.
Documentation Layout
Each section of this documentation describes a collection of related endpoints that affect a given resource.
Where applicable, at the top of a section you will find a table listing the attributes for the resource and a second showing its relationships with other resources.
NOTE: If an attribute is marked as 'Assignable', its value can be set via a POST/PATCH. You can also modify the data for an 'Assignable' relationship.
Authentication in the TE API
Interaction with the TE API is protected with OAuth 2.0. A client ID/secret pair is required to use the API.
The ID/secret pair is used to request an access token from the '/token' endpoint. This token will need to be present within the header on all calls to the API.
NOTE: See the 'Authentication' endpoint collection for more information. See the 'Heartbeats' endpoint collection for more information on how to test your authentication.
Endpoint Standards
Each endpoint provides interaction with two aspects of an entity:
'Attributes' - Attributes of the entity itself. Includes things like first name, phone number, or birthday of the contact.
E.g. A 'Contact'
'Relationships' - Describe a relationship between that entity and another entity.
E.g. A contact that has an owner in the TE System OR a set of contact groups (separate entities with their own endpoint).
Attributes
Each endpoint returns a JSON object with a set of attributes. Each endpoint collection should describe the names and types of attributes available in each endpoint.
Data Types
Each attribute has a type. There are four data types in the TE API - Numeric, String, Boolean, and Date.
Data Types
Phone Numbers
Phone numbers are accepted in any format. For deduplication, any non-numeric symbols will be stripped out and the numeric phone number will be stored separately. If a numerically identical phone number is used in a different format later, the records are compared using the numeric value only. This applies only to phone numbers with at least 7 digits.
All phone numbers will also be converted into E164 for use in external services (e.g. Twilio). If a phone number cannot be converted into E164, the number will be marked 'Invalid', and external services that rely on phone numbers will not function.
Uniqueness in the TE API
Each type of entity in the TE API can be uniquely identified by a set of attributes. In some cases, multiple options are available to uniquely identify an entity. See each section below for details. These sets of attributes are used to deduplicate entries on creation and to uniquely identify the target in a relationship.
Relationships
Relationships in the TE API are very flexible.
'GET'ing
When GETing an entity, a relationship will be returned with only a partial set of attributes that make sense in the context of that endpoint - e.g. the 'contact_groups' relationship on the '/contacts' endpoint will display only the group name of the target contact_group.
POST and PATCH Requests
When setting a relationship (by POST or PATCH), the target entity is specified using one or more attributes that uniquely identify the entity.
The allowed attributes are listed in the 'Settable Fields' column of each Relationships table. For example, when POSTing to the '/contact-groups' endpoint, either of the following are allowed:
- {
"group_name": "Hot Leads",
"owner":{"username": "alfred"}
}
OR - {
"group_name": "Hot Leads",
"owner":{"id": "123589"}
}
In cases where an endpoint's relationship supports multiple Settable Fields be aware that the request examples may only make use of one of the attributes though any could be used in its place.
Interacting with the API
Admin Calls vs User Calls
You'll notice that many sections of the documentation have samples for POSTs and GETs that are labeled "As Admin" or "As User".
When using client credentials to access the API, you'll use the "As Admin" examples. For Authorization Code access, you'll use the "As User" examples.
'GET'ing
There are two types of GETable endpoints in the TE API: Paging and Individual. Paging endpoints provide lists of entities. E.g. '/contacts' returns a list of contacts.
Getting Individual Entities
Individual endpoints return specific individual entities, specified by TE ID. E.g. '/contacts/51151' returns the contact with the 'id' attribute '51151' (the TE internal identifier).
Getting Multiple Entities (Paging)
Paging endpoints will return an object with two properties: 'objects' and 'links'. The 'objects' property will be an array of entities in 'pages'. Each page will have a number of entities along with a set of links. The page size and page number can be specified using the '?page' GET parameter. Setting '?page[number]=5' will return the fifth page. Setting '?page[size]=100' will make each page consist of 100 items, instead of the default of 10. Both attributes can be set together. E.g. setting '?page[size]=100&page[number]=6' will return items 501-600.
Paging Links
The 'links' attribute on a page object will have four attributes, specifying metadata about the number of entities available to page.
- 'first' will be the page number of the first page of entities (always '1').
- 'last' will be the page number of the last page of entities.
- 'next' will be the page number of the next page after the currently requested one. 'next' may be null if there are no subsequent pages.
- 'prev' will be the page number of the page immediately preceding the current one. 'prev' may be null if there are no preceding pages.
'POST'ing
Entities can be created in the TE system by POSTing to paging endpoints. E.g. sending a POST to '/contacts' will create a contact.
Deduplication
When POSTing an entity, the TE API will attempt to 'Deduplicate' by searching for existing entities with similar attributes. If such a duplicate does exist, the TE API will treat the POST as a PATCH to that entity instead. See each section for details on what attributes will be used to search for duplicates.
'PATCH'ing
Entities can be updated in the TE system by PATCHing to individual endpoints. E.g. sending a PATCH to '/contacts/51151' will update the attributes of the contact with TE 'id' of '51151'.
'DELETE'ing
Entities can be deleted only by TE ID. Send a DELETE request to the appropriate individual entity endpoint to delete it.
Return Codes
Where applicable, the API will respond with an HTTP status code that indicates what happened during the request. Possible values include: