API v2

Introduction

The API is REST based. We use common HTTP features such as HTTP verbs and HTTP status codes.

Requests must be made via HTTPS. Calls over plain HTTP will fail. We support cross-origin resource sharing (CORS) so that requests can be sent from any domain via the browser.

Responses are in JSON.

Authentication

Authorization: Bearer <api_key>

Authentication is done by passing the api key via the Authorization header.

Parameters / Content-Type

Parameters should be JSON encoded and passed in the request body (with the Content-Type header set to application/json).

IDs are always UUIDv4. Timestamps are in the ISO8601 format and in UTC.

Request ID

Each response has a X-Request-Id identifier in the HTTP header. If you have any issues and need to contact support, specifying the matching Request ID will help us track down the issue.

Errors

Example error response 

{
  "errors": [
    {
      "id": "not_found",
      "message": "Resource not found. Are you using the right HTTP verb?",
    },
    ...
  ]
}

We use HTTP response codes to indicate specific error classes (2xx range is success, 4xx failed based on the provided parameters, 5xx are server errors). Each error has a machine readable id, and a human readable explanation.

Status codes

Code Description
200 The request was a success.
401 Request failed because user is not authenticated.
402 Request failed because user does not have sufficient balance.
403 Request failed because user does not have authorization to access a specific resource.
404 Resource doesn’t exist.
409 The request conflicts with another request.
412 Precondition failed. Check the documentation and contact support.
422 Your request was understood, but contained invalid parameters.
500 Something went wrong on the server, check status site and/or report the issue.
503 Service is temporarily unavailable. Generally this is temporary and the requests should be retried.

Error types

Type Description
unauthenticated Request failed because the user is authenticated.
unauthorized User does not have access to the specified resource.
not_found Resource was not found.
server_error Internal server error.
invalid_params Parameters were not valid.

Versioning

When we make backwards-incompatible changes to the API, we release a new dated version.

Your API calls will always use the version specified on your API key settings (that way we never break your compatibility). Alternatively, you can override the version per-request, by specifying an X-API-Version header:

X-API-Version: 2017-08-31

Once you’re ready, to upgrade, you can bump your API version in the account settings.

You can see the API changelog here.

API v2 Routes

Get DID

GET /dids/:number

Returns information about the did (currently SMS and MMS configuration only).

To get information for 12342341234: 

curl -n https://api.preview.tsgglobal.world/dids/12342341234 \
-H "Authorization: Bearer <api_key>"

Response Fields

Name Type Description Example
number string The number that was looked up 12342341234
sms_enabled boolean Whether or not SMS is enabled on the number true
sms_status string The activation state of the number’s sms “ACTIVE”
sms_post_ver string Affects http delivery, if the sms_uri has a http or https scheme this value applies “postv2”
sms_uri string Where inbound messages should be delivered, if blank, then it’s assumed that an SMPP connection is used “https://example.com”
mms_enabled boolean Whether or not MMS is enabled on the number true
mms_uri string Where inbound mms messages should be delivered, can have a scheme of http, https, mm4, mm4+s or mm4s “mm4://example.com:2525”

Response (Success)

HTTP 200

{
  "number": "12342341234",
  "sms_enabled": true,
  "sms_status": "ACTIVE",
  "sms_post_ver": "postv2",
  "sms_uri": "https://example.com",
  "mms_enabled": true,
  "mms_uri": "mm4://example.com:2525"
}

Update DID

PATCH|PUT /dids/:number

Updates the did (currently MMS configuration only).

To update 12342341234: 

curl -n -X PATCH https://api.preview.tsgglobal.world/dids/12342341234 \
  -H "Authorization: Bearer <api_key>"
  -H "Content-Type: application/json" -d '{
    "mms_uri": "https://example.com/my_webhook/"
  }'

Parameters

(* is a required field)

Name Description Example
mms_uri string A URI pointing to the destination at which you want to receive the messages. Can either be HTTP(S) or an MMS server. "https://example.com/my_webhook", "mm4://mmsc.example.com:2525"

Lookup SMS Carrier

GET /dids/:number/sms_carrier_lookup

Lookup Carrier details for specified number.

Note Requests to this endpoint will incur API charges to the account. Note An account must have LRN dip enabled in order to complete the request.

To lookup 12342341234 

curl -n https://api.preview.tsgglobal.world/dids/12342341234/sms_carrier_lookup \
  -H "Authorization: Bearer <api_key>"

Response (Success)

HTTP 200

{
  "enabled": true,
  "number": "12342341234",
  "operator" "An operating company"
}

Response (Inactive Account)

HTTP 403 Forbidden

{
  "errors" => [
    {
      "code" => "account_inactive",
      "detail" => "The associated account is inactive, please contact support if you think this is an error."
    }
  ]
}

Response (LRN DIP Disabled)

HTTP 403 Forbidden

{
  "errors" => [
    {
      "code" => "lrn_dip_disabled",
      "detail" => "The associated account has lrn_dips disabled, please contact support if you think this is an error."
    }
  ]
}

Response (Insufficient Balance)

HTTP 402 Payment Required

{
  "errors" => [
    {
      "code" => "insufficient_balance",
      "detail" => "The associated account has an insufficient balance to complete this request."
    }
  ]
}

MMS Enable

POST /dids/:number/mms/enable

As a prerequisite, the number must already be SMS enabled, and the account must have MMS access enabled.

To enable MMS for 12342341234: 

curl -n -XPOST https://api.preview.tsgglobal.world/dids/12342341234/mms/enable \
-H "Authorization: Bearer <api_key>" \
-H "Content-Type: application/json" -d '{
  "uri": "https://example.com/my_webhook/"
}'

Parameters

(* is a required field)

Name Description Example
uri* string A URI pointing to the destination at which you want to receive the messages. Can either be HTTP(S) or an MMS server. "https://example.com/my_webhook", "mm4://mmsc.example.com:2525"

Response

Example response

MMS was enabled for 12342341234. (sms_uri: null means SMPP) 

{
  "mms_enabled": true,
  "mms_uri": "http://example.com",
  "number": "12342341234",
  "sms_enabled": true,
  "sms_uri": null
}

MMS Disable

POST /dids/:number/mms/disable

As a prerequisite, the number must already be MMS enabled.

To disable MMS for 12342341234: 

curl -n -XPOST https://api.preview.tsgglobal.world/dids/12342341234/mms/disable \
-H "Authorization: Bearer <api_key>"

API v1

API v1 Routes

Standalone SMS Only API Usage and Codes

Example (Add)

Request 

POST https://api.preview.tsgglobal.world/sms_enablement.php?api_key=00000000-0000-4000-0000-000000000000&did=12022011234&action=add

Response 

Success

Example (Delete)

Request 

POST https://api.preview.tsgglobal.world/sms_enablement.php?api_key=00000000-0000-4000-0000-000000000000&did=12022011234&action=delete

Response 

Success

GET|POST https://api.preview.tsgglobal.world/sms_enablement.php?api_key=<API_KEY>&did=<1NPANXXXXXX>&action=(add | delete)

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG, 00000000-0000-4000-0000-000000000000
did * 1NPANXXXXXX, 12022011234
action * add, delete

Error Codes

SMS PostURL Update API Usage and Codes

Example

Request 

POST https://api.preview.tsgglobal.world/sms_posturl_update.php?api_key=00000000-0000-4000-0000-000000000000&number=12022011234&posturl=http://sms.example.com/messages

Response

GET|POST https://api.preview.tsgglobal.world/sms_posturl_update.php?api_key=<API_KEY>&did=<1NPANXXXXXX>&posturl=<ROUTING_URL>

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG, 00000000-0000-4000-0000-000000000000
number * 1NPANXXXXXX, 12022011234
posturl http://sms.example.com/messages

Notes

Errors Codes

LRN / LERG DATA LOOKUP API USAGE AND CODES

Example (Only Number)

Request 

POST https://api.preview.tsgglobal.world/lerg_via_lrn.php?api_key=00000000-0000-4000-0000-000000000000&number=12022011234

Response

Example (LRN E164)

Request 

POST https://api.preview.tsgglobal.world/lerg_via_lrn.php?api_key=00000000-0000-4000-0000-000000000000&number=12022011234&lrn=e164

Response

Example (LRN E164 + Carrier Name)

Request 

POST https://api.preview.tsgglobal.world/lerg_via_lrn.php?api_key=00000000-0000-4000-0000-000000000000&number=12022011234&lrn=e164&carrier_name=yes

Response

GET|POST https://api.preview.tsgglobal.world/lerg_via_lrn.php?api_key=<API_KEY>&did=<1NPANXXXXXX>

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG, 00000000-0000-4000-0000-000000000000
number * 1NPANXXXXXX, 12022011234
lrn 10digit will return LRN value in 10 digit format NPANXXXXXX 10digit
11digit will return value in 11digit format 1NPANXXXXXX 11digit
e164 will return value in e164 format +1NPANXXXXXX e164
carrier_name This will return the current carrier that the DN is routed to via LRN yes, no
ocn This will return the OCN of the LRN number yes, no
lata This will return the LATA of the LRN number yes, no
ratecenter This will return the Rate Center of the LRN number yes, no
switchname This will return the Switch Name of the LRN number yes, no

Carrier Type (e.g. WIRELESS, RBOC, CLEC, ect)

Error Codes

LRN API USAGE AND CODES

Example

Request 

POST https://api.preview.tsgglobal.world/lrn_api.php?api_key=00000000-0000-4000-0000-000000000000&number=12022011234

Response 

12022011238

GET|POST https://api.preview.tsgglobal.world/lrn_api.php?api_key=<API_KEY>&number=<1NPANXXXXXX>

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG, 00000000-0000-4000-0000-000000000000
number * 1NPANXXXXXX, 12022011234

Error Codes

DID Priority Add API Usage and Codes

Example (PSTN)

Request 

POST https://api.preview.tsgglobal.world/did_priority_add_api.php?api_key=00000000-0000-4000-0000-000000000000&did=12022011234&destination=16352321233&call_type=PSTN&call_option=NP

Response

Example (VOIP)

Request 

POST https://api.preview.tsgglobal.world/did_priority_add_api.php?api_key=00000000-0000-4000-0000-000000000000&did=12022011234&destination=192.168.1.1&call_type=VOIP&call_option=NP

Response

GET|POST https://api.preview.tsgglobal.world/did_priority_add_api.php?api_key=<API_KEY>&did=<1NPANXXXXXX>&priority=<NUMBER>&destination=<SIP IP ADDRESS | PHONE NUMBER>&call_type=(VOIP|PSTN)&call_option=(NP|WP)

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG, 00000000-0000-4000-0000-000000000000
did * 1NPANXXXXXX, 12022011234
priority * 2
destination * 192.168.1.1 (for VOIP), 16352321233 (for PSTN)
call_type * VOIP, PSTN
call_option * WP, NP

Notes

Error Codes

DID Priority Delete API Usage and Codes

Example

Request 

POST https://api.preview.tsgglobal.world/did_priority_delete_api.php?api_key=00000000-0000-4000-0000-000000000000&number=12022011234&priority=2

Response

GET|POST https://api.preview.tsgglobal.world/did_priority_delete_api.php?api_key=<API_KEY>&number=<1NPANXXXXXX>&priority=<NUMBER>

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG, 00000000-0000-4000-0000-000000000000
number * 1NPANXXXXXX, 12022011234
priority 2

Error Codes

DID Priority Update API Usage and Codes

Example (PSTN)

Request 

POST https://api.preview.tsgglobal.world/did_priority_update_api.php?api_key=00000000-0000-4000-0000-000000000000&did=12022011234&destination=16352321233&call_type=PSTN&call_option=NP

Response

Example (VOIP)

Request 

POST https://api.preview.tsgglobal.world/did_priority_update_api.php?api_key=00000000-0000-4000-0000-000000000000&did=12022011234&destination=192.168.1.1&call_type=VOIP&call_option=NP

Response

GET|POST https://api.preview.tsgglobal.world/did_priority_update_api.php?api_key=<API_KEY>&did=<1NPANXXXXXX>&priority=<NUMBER>&destination=<SIP-ADDRESS | PSTN-NUMBER>&call_type=(VOIP|PSTN)&call_option=(NP|WP)

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG, 00000000-0000-4000-0000-000000000000
did * 1NPANXXXXXX, 12022011234
priority * 2
destination * Either an SIP IP Address (call_type=VOIP) or a Phone Number (call_type=PSTN) 192.168.1.1, 12003004001
call_type * VOIP, PSTN
call_option * NP, WP
dnis Number for TSG to send to your switch as a Diled Number ID e.g. DID == 13605551212 but you want TSG to send you 3605551212 or 14085551212 instead of the DID number

Notes

Error Codes

DID LOOKUP API Usage and Codes

Example

Request 

POST https://api.preview.tsgglobal.world/did_lookup_api.php?api_key

Response 

DID,ROUTING INFO,ACTIVATION DATE,LAST USED DATE,SEC USED,DID RATE,ORDER ID,RATE CENTER,STATE,TIER,PORTED,SMS ENABLED,PROVISIONING DATA

GET|POST https://api.preview.tsgglobal.world/did_lookup_api.php?api_key=<API_KEY>&did=<1NPANXXXXXX>

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG
did * 1NPANXXXXXX, +NPANXXXXXX, 12022011234, +12022011234

Errors Codes

CNAME DATA LOOKUP API USAGE AND CODES

Example 

GET|POST https://api.preview.tsgglobal.world/cnam_api.php?api_key=<API_KEY>&number=<1NPANXXXXXX>

Request 

POST https://api.preview.tsgglobal.world/cnam_api.php?api_key=00000000-0000-4000-0000-000000000000&number=12022011234

Response 

JOHN DOE WA

GET|POST https://api.preview.tsgglobal.world/cnam_api.php

By Default all customers are granted access to this API.

Charges

The default rate is 0.006 USD per CNAME dip, unless otherwise contracted.

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG
number * 1NPANXXXXXX, +NPANXXXXXX, 12022011234, +12022011234

Error Codes

CDR API USAGE AND CODES

GET|POST https://api.preview.tsgglobal.world/cdr_api.php?api_key=<API_KEY>&startdate=<START_DATE>&stopdate=<STOP_DATE>&type=(VOIP | LRN | CNAME | MMS | SMS)

Example (VOIP)

Request 

POST https://api.preview.tsgglobal.world/cdr_api.php?api_key=00000000-0000-4000-0000-000000000000&startdate=2019-05-01&stopdate=2019-05-05&type=VOIP

Response 

Date Time of Call,Call ID,Source ANI,Destination Number,DID Used,Destination,Call Time in Sec,Terminate Cause,Per Min Rate,Call Cost,Call Type,ANI-II

Example (LRN)

Request 

POST https://api.preview.tsgglobal.world/cdr_api.php?api_key=00000000-0000-4000-0000-000000000000&startdate=2019-05-01&stopdate=2019-05-05&type=LRN

Response 

Date Time of Lookup,Orig Number,LRN Number,TerminateCause,API Access Charge,API Type

Example (CNAME)

Request 

POST https://api.preview.tsgglobal.world/cdr_api.php?api_key=00000000-0000-4000-0000-000000000000&startdate=2019-05-01&stopdate=2019-05-05&type=CNAME

Response 

Date Time of Lookup,Requested Number,CNAME,Status,CNAME Access Charge,API Type

Example (SMS)

Request 

POST https://api.preview.tsgglobal.world/cdr_api.php?api_key=00000000-0000-4000-0000-000000000000&startdate=2019-05-01&stopdate=2019-05-05&type=CNAME

Response 

Date Time of SMS,From Number,To Number,Direction,Status,SMS Charge,SMS Type

Example (MMS)

Request 

POST https://api.preview.tsgglobal.world/cdr_api.php?api_key=00000000-0000-4000-0000-000000000000&startdate=2019-05-01&stopdate=2019-05-05&type=CNAME

Response 

Date Time of MMS,From Number,To Number,Direction,Status,MMS Charge,MMS Type

Parameters

Name Description Example
api_key * API_KEY_FROM_TSG, 00000000-0000-4000-0000-000000000000
startdate * YYYY-MM-DD, 2019-05-01
enddate * YYYY-MM-DD, 2019-05-05
type * VOIP, LRN, CNAME, SMS, MMS

Notes

Sample

Sample Download to File via WGET – Output file would be test.csv

wget 'https://api.tsgglobal.net/cdr_api.php?api_key=API_KEY&startdate=2015-05-09&stopdate=2015-05-10&type=VOIP' -O test.csv --no-check-certificate

Errors Codes