API documentation

MCL API

This document provides in-depth instructions retrieving carrier information with Tychron's Messaging Carrier Lookup (MCL) API. Manage your messaging traffic more effectively and with precision. Build a better messaging strategy today with MCL.

Authorization

Please use your API Key's HTTP Token for authorization.

Restrictions

Please note that dips for Canadian numbers are restricted and require additional permissions. Please contact ([email protected]) for additional information.

Query results are licensed for the immediate transaction that generated the query. Under Tychron's Acceptable Use Policy, results may not be cached, stored, or reused for later transactions or used to build any dataset or directory, and may not be used for eligibility decisions regulated by the Fair Credit Reporting Act — query fresh, every time.

Supported Output Types

The MCL API only supports JSON as an output type. Please see the examples below.

Request Endpoint

GET /api/v1/messaging_carrier/:number HTTP/1.1
Host: api.atlas.tychron.online

Request Path Parameters

Parameters marked with * are mandatory in all requests.

Parameter	Type	Default	Description
number *	String		An 11 digit, valid North American Numbering Plan (NANP) number.

Request Headers

Parameters marked with * are mandatory in all requests.

Header	Default	Description	Example
Accept	application/json	Determines what output format should be returned on the response. Currently only application/json is supported.	`Accept: application/json`
Authorization *	Authorization: Bearer KEY	Please use your API Key's HTTP Token for authorization.	`Authorization: Bearer Rb2VRMSsm0VxHOIcniw6hCJhUqRExQk2`

Request Format

GET /api/messaging_carrier/:number?output=text|json HTTP/1.1
Host: api.atlas.tychron.online
Accept: application/json
Authorization: Bearer YOUR_API_KEY_HERE

Query Parameters

Parameter	Type	Default	Description
enable_cdr_export	Boolean	false	Should CDRs generated by this request be forwarded to any configured CDR Webhooks?

Response Codes

Code	Description	Solutions
200 OK	The request was successful and should contain the requested data.
400 Bad Request	The payload body of the request is malformed or the request contains invalid parameters.	Check your JSON payload for invalid or missing parameters, or run it through a JSON linter.
401 Unauthorized	The request may be deemed unauthorized due to a number of factors. The Authorization header is not set. The provided API HTTP token is invalid, expired, or not active. The requesting account may be unauthorized from making requests.	This error typically results from using an incorrect API token in requests. Check your API token for typos. If the error persists, please contact support. ([email protected])
402 Payment Required	Your account has either an insufficient balance or you have exceeded your credit limit in the request.	Please contact ([email protected]) to purchase more credits.
403 Forbidden	The user is not permitted to make the specified request(s). This error currently only applies to Canadian dips, as additional permissions are required for Canadian numbers.	If you require Canadian dips, please contact ([email protected]) for additional details.
415 Unsupported Media Type	The content-type used to make the request is not supported.	This endpoint only requires a GET request with query parameters. Please remove the Content-Type header from your request.
422 Unprocessable Entity	The parameters of the request body failed validation or contain invalid values.	The response body will contain specific details for the request failure. Correct the request parameters based on these details.
500 Internal Server Error	The request has not been fulfilled due to a server error.	Please report this error and contact support for further assistance. ([email protected])

Response Headers

Name	Description	Example
X-Request-ID	An ID used to identify the HTTP request.	`X-Request-ID: wGvPFqerkrPGm3T0`
X-CDR-ID	An ID used to identify the CDR (Call Detail Record) generated by the request. Please provide this ID for any billing questions when contacting support.	`X-CDR-ID: 01EYVS5A5G7MAJVM25VWZCYKVY`

Response Format

JSON

HTTP/1.1 200 OK
Content-Type: application/json
X-CDR-ID: AN_ID

{
  "data": {
    "number": "12003004000",
    "messaging": {
      "enabled": true,
      "provider": "Provider Name",
      "country": "Country",
      "country_code": "ISO-code",
      "reference_id": "us_acme"
    }
  }
}

Text

HTTP/1.1 200 OK
Content-Type: text/plain

true ACME Corp

Response Parameters

Parameters marked with * are mandatory in all queries.

Parameter	Type	Description
Root
data *	Data	A top-level map containing dip data.
errors *	List<Error>	A top-level map containing any request errors.
Data
number *	String	The number used in the request.
messaging *	Messaging	The messaging data which contains carrier information.
Messaging
enabled *	Boolean	Denotes whether the queried number is capable of Messaging.
provider *	String	The name of the messaging provider of the queried number if Messaging enabled, or the just the voice provider if the number is not messaging enabled.
country *	String	The origin country of the queried number's provider.
country_code *	String	The ISO country code of the queried number's provider.
reference_id	String	Tychron issued internal ID that groups the Service Provider.

cURL Examples

JSON

curl \
  -H "Authorization: Bearer KEY" \
  https://api.atlas.tychron.online/api/v1/messaging_carrier/12003004000

{"data":{"messaging":{"country":"Country","country_code":"ISO","enabled":true,"provider":"ACME Corp","reference_id":"us_acme"},"number":"12003004000"},"errors":[]}

Text

curl \
  -H "Authorization: Bearer KEY" \
  https://api.atlas.tychron.online/api/v1/messaging_carrier/12003004000?output=text

true ACME Corp