Creating Your First Tracking Number
The goal of this quick start guide is to provide a high level overview of how to order a Tracking Number and retrieve basic reporting information.
We’ll take a step by step approach for creating a tracking number by walking through each of the following steps:
Advanced topics can be found in the broader documentation. If you have any questions or require additional support, feel free to contact our customer support at: https://telmetrics.com/support .
1. Acquiring Credentials
Before getting started, you'll first need to retrieve your API access token. This token will be used for all requests to the Telmetrics v3 API.
For details on generating an API token, please refer to our Authentication documentation.
You will need the token you have generated in the next steps of this guide.
2. Creating a Number Group
Telmetrics uses Groups to provide you with the ability to logically organize your numbers in a way that makes sense for your business. For more details, please refer to our documentation on Groups.
To create your first group, you'll need to come up with a descriptive name, and the Time Zone that would like your reporting to be in. In the example below, we're creating a Number Group for Acme Paving Company. This company is located on the east coast, so we're setting the time zone for this group to "Eastern" (click here for a complete list of time zones).
Submit your create Group request using: POST https://api.telmetrics.com/v3/api/groups
Below is a sample cURL request:
curl -H "x-organization-token: {authentication_token}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "Acme Paving Company Inc.",
"time_zone_id": "Eastern"
}' https://api.telmetrics.com/v3/api/groups
If the request is handled successfully, the following JSON response will be returned:
{
"id": 11623287,
"name": "Acme Paving Company Inc.",
"time_zone_id": "Eastern",
"rich_data_type": "Basic",
"billing_group_id": 4455,
"tracking_javascript": "<script type=\"text/javascript\" src=\"#{dni-api-url}/sdk?identifier=197cba2b-e5dd-449d-8054-6bd3226090a1\" async></script>",
"status": "active",
"created_datetime": "2018-04-16T17:38:26.420779Z",
"modified_datetime": "2018-04-16T17:38:26.420779Z"
}
The id that was returned in the JSON response will be used in Step 2 when creating a Tracking Number (11623287 in the example above).
3. Creating a Tracking Number
Once you have created a Number Group, you can order your first Tracking Number. Tracking Numbers are where you'll have the ability to configure call features such as: Call Record, Voice Transcriptions, Call Scoring, Call Verify, Whisper, Stop Call, and SMS Routing Capabilities.
In this example, we'll be using automatic number selection to create a toll-free tracking number that will route phone calls to Acme Paving Company's main telephone number.
To create your first Tracking Number, you'll need to provide:
- A unique label for the number - helpful for reporting purposes
- The type of number you'd like - in the example below we're looking for a number that's local to Acme Paving Company's main telephone number. For a full list of possible ways to find a number, please refer to the Number Searching portion of this documentation
- Routing settings - in the example below, we'll be using the Basic routing option that will forward calls directly to Acme Paving Company's primary office line. We'll also enable the call record feature so we can listen to calls made to our Tracking Number.
Submit your create Tracking Number request using:
POST https://api.telmetrics.com/v3/api/groups/{groupid}/numbers
Note that you will need to populate the {groupid} value with the group id generated in Step 2 of this guide.
Below is a sample cURL request:
curl -H "x-organization-token: {authentication_token}" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"name": "Acme Paving Company Inc - primary office line",
"phone_number_request": {
"match_type": "localtonumber",
"local_to_number": "4043033433"
},
"call_routes": {
"route_type": "Basic",
"route": {
"termination_number": "4045553433",
"features": {
"call_record": {
"enabled": true,
"notification_text": "this call may be recorded for quality control purposes"
}
}
}
}
}' https://api.telmetrics.com/v3/api/groups/11623287/numbers
A successful post will result in the creation of a tracking number:
{
"id": 8660503,
"name": "Acme Paving Company Inc - primary office line",
"group_id": 11623287,
"status": "Active",
"phone_number": "4045550064",
"created_datetime": "2018-04-16T00:00:00Z",
"call_routes": {
"route_type": "Basic",
"route": {
"id": 30474127,
"termination_number": "4045553433",
"features": {
"call_record": {
"enabled": true,
"authenticate_call_record_access": false,
"notification_text": "this call may be recorded for quality control purposes"
}
}
}
}
}
In the resulting response, you will be able to find your tracking number in the phone_number field. This request resulted in the generation of the tracking number: (404) 555-0064.
4. Retrieving Reporting Details
When you have successfully created a Tracking Number, you will be able to start collecting reporting details on your calls. The Telmetrics v3 API will return the following details:
- Details about the call - Date/Time of the call, Answer Status, and how long the call lasted
- Details about the caller - when avaialble, we will return details about the caller (Name, Address, Demographic Data)
- Voice Links - a link to the call recording that can be embedded within your applications
To retrieve calls, submit requests to the endpoint:
GET https://api.telmetrics.com/v3/api/calls
Submit a request similar to the following to retrieve a set of Call Detail Records:
curl -H "x-organization-token: {authorization_token}" \
-X GET \
"https://api.telmetrics.com/v3/api/calls?pagesize=2&startdateutc=2018-01-01-00:00
If successful, the following response will be returned:
{
"results": [
{
"id": 1926683604,
"call_type_id": 1,
"call_type": "Standard",
"number_id": 8498568,
"group_id": 11435857,
"caller_identity": 237277497,
"organization_id": 4455,
"answer_status_id": 1,
"answer_status": "answered",
"ring_duration": 2,
"call_duration": 34,
"registered_DNC": false,
"tracking_number": "8003147859",
"caller_number": "6283335467",
"termination_number": "9052198255",
"caller_details": {
"name": "",
"address": "",
"city": "SAN FRANCISCO",
"state": "CA",
"zip_code": "94105",
"country": "US",
"latitude": 37.7844,
"longitude": -122.3947
},
"conversation_analytics": {
"call_record_file": "b81384ea-93a3-442a-9f42-6ac4de5da88f",
"voice_link": "https://webservice.telmetrics.com/d4b5b465-ad50-4e0b-b967-ff54107505de/123sjh2131a.mp3"
},
"routing_keypress": "1",
"start_time": "2017-12-08T08:55:31",
"answer_time": "2017-12-08T08:55:39",
"end_time": "2017-12-08T08:56:13",
"start_time_utc": "2017-12-08T15:55:31.363",
"answer_time_utc": "2017-12-08T15:55:38.717",
"end_time_utc": "2017-12-08T15:56:12.597",
"status": "complete"
},
"paging": {
"pageNumber": 1,
"pageSize": 10000,
"total": 4636
}
}
To listen to the call record, use the Voice Link returned in the voice_link field in the response.
For a full explanation of all fields, please refer to the Retrieving Phone Call Details section of this documentation.
Updated over 3 years ago