Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

TLDCRM Has Robust Ingress and Egress API Endpoints that can be used with a variety of third party automation platforms and reporting tools such as Microsoft BI and other Data lake platforms such as Snowflake.

API Basics

The first step in using the API is Creating and Using an API Key, as well as setting up basic Endpoint Security and IP Address Access Protections to make sure your data is safe.

Creating an API Key

Go to Settings → API to create an API key. You must have Superadmin Privileges or the Manage APIs Ability to see this section.

Click the Green + Icon to create an API.

For most general use cases you will be using a v1 API type until our V2 API is complete.

Make sure when testing to use IP Protection as by default all API’s are Available when you create an API Key.

IP Address Protection allows you to take a CSV List of IP Addresses that are allowed to use the API. Otherwise it is open to anyone with the ID and Key.

You can further protect your API Key by setting Endpoint Permissions. Once you set an Endpoint Permission it locks your API to only be able to access that specific URL or URL Pattern.

Endpoint Protections allow you to limit this API to specific Endpoints, the full domain should not be included in the url. For example /api/egress/leads will allow for access to only that endpoint. You can however use * as well to denote a larger amount of endpoints. If you want someone to only access egress and not ingress, then you can place /api/egress/* or for example of you want someone to only access documentation you can set it to /api/egress/*/docs*. You can give access to all of TLDialer egress by using /api/egress/tldialer/* You can use multiple rules at once, as long as one applies it will let them through. By default no restrictions set will allow all endpoints for this API type.

Using API ID and API Key

The API Key and ID can be passed via almost any GET, POST, PUT, or DELETE as parameters but the preferred and most secure method is via headers using tld-api-id: {api_id} and tld-api-key: {api_key}

You can also send a pair of api and apikey, or api_id` and api_key as alternatives if your third party system has some sort of limitation.

Both API ID and API Key are required with every Request.

Request Body Types

All API Requests support JSON Raw Body Content as long as Content-Type: application/json is passed via headers. JSON is the recommended format to work with the API.

The Egress API supports GET or POST Methods via form-data or x-www-form-urlencoded Body data aside from JSON.

The Ingress API supports POST, PUT & DELETE via form-data or x-www-form-urlencoded Body Data and follow REST Standards related to the specific endpoint if that function is available.

POST is normally used for Adding new Data
PUT is normally used for Updating or Replacing Data as well as for Bulk Modifications of Data.
DELETE is normally used for Removing or Deactivating Data. Most Deletes set a Trashed State.

Return Types

The Egress API supports 3 return types. By Default data is output along with debug data in the response object as an array of objects related to your query. This is the default return type.

The format Parameter can be used to modify this default behavior. It can be provided via the URL or as a Form Parameter

&format=json / &format=stream

This format will stream a flat array of objects as JSON and is useful for very large data requests as it is memory performant. It omits performance metrics.

&format=csv

This format will stream a CSV file instead of JSON and is memory performant.

The Ingress API will return a JSON Result similar to the default behavior of the Egress API and does not support format modification as it is normally informational return data. Return data will vary but they will always be encapsulated in the response object.

Account Selection and API Account Exclusivity

All API’s generated are bound to the account they are created on so for example if you created an API on the Sandbox account the domain that that API key would work is https://sandbox.tldcrm.com there are no multi-account API’s.

API Paths

The two main API Paths that are granted are the Egress /api/egress/ and Ingress /api/ingress API's. Egress is used for pulling data, and Ingress is used for Updating Data. Most Ingress or Egress paths relate to a general table or section in TLD or TLDialer. Some are more complex and involve multiple database for reports and have less standardized parameters than those related to a base table. All TLDialer Egress API endpoints can be found under /api/egress/tldialer

Egress API Endpoints

Egress Endpoints

TQL ( Total Query Language ) - Working with the Egress API

TQL - Total Query Language

Ingress API Endpoints

Ingress API Endpoints

  • No labels