Messaging Carrier 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.


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


Please note that dips for Canadian numbers are restricted and require additional permissions. Please contact for additional information.

Supported Output Types

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



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

Headers marked with * are mandatory

Parameter Default Description Example
Accept 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


Accept: application/json
Authorization: Bearer YOUR_API_KEY_HERE

Response Codes

Code Description Further Comments and possible 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 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
402 Payment Required Your account has either an insufficient balance or you have exceeded your credit limit in the request. Please contact 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 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 have failed validation or contain invalid values. The response body will contain specific details for the request failure. Correct the request parameters based on this response.
500 Internal Server Error The request has not been fulfilled due to a server error.

Please report this error and contact for further assistance.

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.

Response Format


HTTP/1.1 200 OK

Content-Type: application/json
  "data": {
    "number": "12003004000",
    "messaging": {
      "enabled": true,
      "provider": "Provider Name",
      "country": "Country",
      "country_code": "ISO-code"

Parameters marked with * are mandatory in all requests.

Parameter Type Default Description
data* Data A top-level map containing dip data.
errors* List<Error> A top-level map containing any request errors.
number* String The number used in the request.
messaging * Messaging The messaging data which contains carrier information.
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.

cURL Examples

JSON Example

curl \
  -H "Authorization: Bearer KEY" \
  "data": {
    "messaging": {
      "country": "Country",
      "country_code": "ISO",
      "enabled": true,
      "provider": "Provider Name"
    "number": "12003004000"
  "errors": []