LRN API

This document provides in-depth instructions on how to look up LRN information with Tychron’s LRN API. Retrieve a number’s detailed geographical and carrier information to avoid dropped calls and lower your calling costs with accurate routing. Gain more control over your calling today with LRN.

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 (support@tychron.com) for additional information.

Supported Output Types

The LRN API supports json and text as output types. For reference, see the examples below. If no output is specified, the default output is made in JSON.

Request Endpoint

GET /api/v1/lrn/: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 (unless an output parameter is given)	This header determines what output format should be returned in a response. When this header is given, it will take priority over the default output parameter.	`Accept: application/json`
Authorization *	Authorization: Bearer KEY	Please use your API Key's HTTP Token for authorization.	`Authorization: Bearer Rb2VRMSsm0VxHOIcniw6hCJhUqRExQk2`

Request Format

GET /api/v1/lrn/:number?enhanced=:boolean&messaging_lookup=:boolean&number_format=11digit|10digit|e164&output=json|text HTTP/1.1
Host: api.atlas.tychron.online
Accept: application/json, text/plain
Authorization: Bearer YOUR_API_KEY_HERE

Query Parameters

Parameters marked with * are mandatory in all requests.

Parameter	Type	Default	Description
enhanced	Boolean	false	Specifies whether or not additional block information should be queried for the number (This may incur additional costs).
messaging_lookup	Boolean	false	Specifies whether or not the messaging provider should be included in the query (This may incur additional costs).
number_format	String	11digit	The queried number must be in either 11 digit, e164, or 10 digit format.
output	String	json	Queries must be made in either json or text.

Please note that text output cannot be used in conjunction with messaging_lookup or enhanced parameters.

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.	This error is most likely caused by a text based output with the messaging_lookup or enhanced flags set to true. Either use json as the output, or unset the messaging_lookup or enhanced flags when using a text based output.
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. (support@tychron.com)
402 Payment Required	Your account has either an insufficient balance or you have exceeded your credit limit in the request.	Please contact (support@tychron.com) 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 (support@tychron.com) 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. (support@tychron.com)

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",
    "lrn": "17463334653",
    "enhanced": {
      "carrier": "CARRIER NAME",
      "carrier_type": "OCR",
      "city": "CITY NAME",
      "zip_code": "12345",
      "county": "COUNTY NAME",
      "timezone": "-0500",
      "state": "FL",
      "rate_center": "RATECENTER",
      "lata": "876",
      "ocn": "333"
    },
    "messaging": {
      "enabled": true,
      "provider": "Messaging Provider Name",
      "country": "COUNTRY",
      "country_code": "ISO",
      "reference_id": "us_acme"
    }
  }
}

Text

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

12003004000

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.
lrn	String	The dipped lrn number. This number may be the same as the queried number if the number was not ported.
enhanced	Enhanced	A map containing dip data from the enhanced flag.
messaging	Messaging	A map containing dip data from the messaging flag.
Enhanced
carrier *	String	The name of the carrier that the queried number belongs to.
carrier_type *	String	The the carrier's type of service provider. See carrier types below for a full list of types that may be returned.
state *	String	The state that the queried number belongs to.
city	String	The city that the queried number belongs to.
zip_code	String	The zip code of the queried number's switch. This may be left empty.
county	String	The county of the queried number's switch. This may be left empty.
timezone	String	The timezone of the queried number's switch. This may be left empty.
rate_center*	String	The rate center that the queried number is loaded under.
lata *	String	The local access transport area code (LATA) of the queried number.
ocn *	String	The operating company number (OCN) of the queried number.
Messaging
enabled *	Boolean	Denotes whether the queried number is capable of SMS or MMS.
provider *	String	The name of the messaging provider of the queried number if SMS or MMS 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.

Carrier Types

Acronym	Full Name
ILEC	Incumbent Local Exchange Carrier
ICO	Independent Telephone Company
ULEC	Unbundled Local Exchange Carrier
RBOC	Regional Bell Operating Company
CLEC	Competitive Local Exchange Carrier
CAP	Competitive Access Provider
IXC	Inter-exchange Carrier
WRSL	Wireless Reseller
IPES	Internet Protocol Enabled Services
ETHX	Ethernet Exchange
INTL	International Telecommunications Service Provider
LRSL	Local Reseller
WIRELESS	Wireless
PCS	Personal Communications Service
PCSR	Personal Communications Service Reseller
PAGING	Paging and messaging

cURL Examples

JSON

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

{"data":{"enhanced":null,"lrn":"12003004000","messaging":null,"number":"12003004000"},"errors":[]}

Text

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

12003004000