Table of contents
- What is an API?
- Why should you use an API?
- Best practices for API implementation
- How to create an API key in CallRail
- Data accessible via CallRail’s API
- Basic API troubleshooting
What is an API?
API stands for Application Programming Interface. It is a method of connecting two or more software applications so that data can be sent from one to another. Typically, these actions happen without a user having to interact with the API post-connection (there is no user interface).
Here are some terms used when talking about an API. These terms will be used throughout this document.
- Destination: The application you are connecting with CallRail via CallRail’s API
- Request: an attempt made by an application to access CallRail’s API
- Call: a successful request that transmits data from CallRail to your destination.
- Endpoint: the location in the API where the data lives.
- Key: a security token that is required to connect to an API. Each CallRail user can create their own unique API keys.
CallRail’s REST API supports 4 request types:
- GET: Retrieve data from a target resource.
- POST: Submits data to create a resource.
- PUT: Submits data to update a target resource.
- DELETE: Deletes data from the target resource or the target resource.
Why should you use an API?
Software developers building an integration will use CallRail’s API to request data specific to their own software. As a CallRail customer, you might also use the API to integrate with custom/in-house software and/or data warehouses.
Another use case would be customizing a native CallRail integration. For example, CallRail can connect with Salesforce, but depending on your Salesforce environment setup, you might need to customize the integration to suit your needs.
It is important to note that using an API might require access to a software’s backend, and depending on the data needed, some developer knowledge. In addition, CallRail can only assist with questions pertaining to available data, creating API keys, and other pre-call actions. We cannot provide support for actions taken after the data has been successfully retrieved from our API.
Best practices for API implementation
Consolidate the types of API requests you make
Instead of retrieving the data for a single call multiple times, you can use a “list all” request to get a list of calls and their data at one time.
Track your number of calls made per day
CallRail can provide an update on your number of calls made. Reach out to your Account Manager, or use our Contact Us form to make this request. You will receive a response with your past 30 days of API call data.
Use webhooks for real-time notifications instead of an API call
Depending on the type of data you are requesting, webhooks might be an alternative to our API. Webhooks are real-time data pushes to your desired endpoint, occurring when specific actions are taken (for example, data being sent once a phone call ends). If you find yourself making frequent requests for the same type of data, switching to a webhook might be a more efficient solution. Learn more about webhooks here.
Consider caching/storing data
Consider storing or caching the data from API calls to avoid repeated, ad-hoc requests..
Reduce request frequency
If you are making frequent requests in order to update your data, consider increasing your API request interval. For example, instead of making the request every 20 minutes, it could be every 2 hours.
Reduce the time window for requested data
Data related to existing calls is updated most frequently within the first 24 hours, and then only rarely (in the event of manual updates to tags, qualified score, value, and notes). If you are requesting updates and unable to transition to webhooks, consider shortening the time window you are requesting to reduce the pages of results you'll receive. For example, instead of looking at the prior 30 days of data every day, you could request the prior 2 or 3 days and likely receive the most relevant updates.
Filter and search
Use query filters and/or searching to cap the data returned in each request.
How to create an API key in CallRail
- Select the Integrations icon on the left navigation bar.
- Select API Keys from the integrations library or the Data Access header on the left.
- Select Create New API v3 Key to create a new API key (if you haven't created a key before). This key will only be shown in its entirety for 15 minutes; store this key somewhere secure.
- Your active API keys are listed in the table (if you have created a key before). You can delete any API key by clicking the Delete icon on the right.
Things to know about API keys
- API keys are user-specific. You can only view your own created API keys, even at the Admin level.
- API keys do not expire. The only way to remove a key is for the user to delete it from their account. This can be done by navigating to Integrations > Data access > API keys.
- Treat your API key with the same security as a password. The key will only be visible in its entirety for 15 minutes once it has been created. Store it somewhere secure (such as a password manager) and do not share it with anyone outside of when it is required for integrations.
Data accessible via CallRail’s API
There is a significant amount of data that can be accessed with our API, depending on the request type and endpoint category. Below are the categories of endpoints available. Each category has a link to a larger endpoint list. Within each endpoint, you might be able to access, create, update, and/or delete data. The API can even be used to create outbound calls, send SMS messages, and submit forms.
- Accounts
- Calls
- Tags
- Companies
- Form Submissions
- Integrations
- Integration Filters
- Notifications
- Outbound Caller IDs
- Page Views
- Summary Emails
- Text Messages
- Trackers
- Users
Basic API troubleshooting
API error codes
Any API request will return a status code. A code other than 200, 201, or 204 means there was an error in the API call. This list contains common error codes you might encounter when using our API.
| Error code | Code description |
| 400 | Bad Request - The server cannot or will not process the request due to an error in how it is configured (e.g., missing fields). |
| 401 | Unauthorized – The request has not been processed because it lacks a valid API key for the target resource. |
| 403 | Forbidden – The server understood the request but refuses to authorize it. This can be due to the requester not being in the right account, or having a user role below what is required |
| 404 | Not Found – The server did not find the target resource or endpoint. This is typically due to the endpoint being incorrect or missing a correct account ID. |
| 405 | Method Not Allowed – The HTTP method received in the request is known by the origin server but not supported by the target resource. |
| 406 | Not Acceptable – Request parameters were supplied in an unacceptable format. For GET requests, verify that parameters are sent as part of the URL. For other requests, verify that parameters are sent as JSON. |
| 422 | Unprocessable Entity – The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, or invalid request parameters) |
| 429 | Unprocessable Entity – The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, or invalid request parameters) |
| 500 | Internal Server Error – The server encountered an unexpected condition that prevented it from fulfilling the request. If this error persists, please contact support; there might be an outage or issue on CallRail’s end. |
| 503 | Service Unavailable – The CallRail API is temporarily offline for maintenance, or the server is overloaded. If this error persists, please contact support; there might be an outage or issue on CallRail’s end. |
Inactive user keys
An API key for an inactive user will result in errors when attempting to call our API. Once a user is removed from an account, any API keys that were associated with that specific user can no longer be used for that account’s API requests. If the user is still on other accounts, they can still use their keys for the accounts they belong to..
International calling
At this time, CallRail’s API does not support international calls.
Time zones
The CallRail API aligns all dates to the time zone specified within the account. If you need to adjust this time zone to a different one, you can include the time_zone parameter within your API request.