• logo

    Good news! Custom Toll Free is currently upgrading toll free number search to show even more vanity number results. During this upgrade, you may not see all of the toll free numbers that are available. Let us provide a customized search for you!

    *Include keywords, business or product names to receive additional number results.

Search API Architecture

API Calls

All API calls will be GET requests with the parameters included in the URL. Each call will be of the following format:

https://api.www.customtollfree.com/api/command?key=xxx&param1=xxx&param2=xxx

As can be seen, the command is a direct part of the URL and every command will require the unique key provided to each user. This key is used to identify the user and which numbers they will be allowed to search.

Valid Commands


Find Numbers Containing a Vanity

Command: search

Parameters

  1. key: Unique user key for identification purposes.
  2. vanity: 3 – 12 character string of alpha-numeric only characters to be mapped to numbers and those numbers searched in the database.
  3. source (optional): Database(s) to search. Options include: “spare”. If this option is not included, the API defaults to “spare” numbers.
  4. prefix (optional): The area codes to search (800, 888, 877, 866, 855, 844). A semi- colon separates multiple values. If missing, assume all area codes.
  5. quantity (optional): Maximum number of results to return. This must be a positive integer.
  6. trailing (optional): Maximum number of trailing digits to consider. This must be 0-5. Default is 5.
  7. adult (optional): Filter out phrases containing adult words. This must be 0 (off) or 1 (on). Default is 1 (on).
  8. numeric (optional): Do not suggest additional words, instead ranking numbers by their numerical quality. This must be 0 (off) or 1 (on). Default is 0 (off).

Return Results

The API returns a properly formatted XML response. The first item in the XML is the <status> tag and will have a value of SUCCESS or ERROR. If ERROR, the XML will contain a list of <error> items. If SUCCESS, it will contain a list of <item> objects (within a <results> tag). Each <item> object will contain a number prefix, 7 digit number, the vanity, and an optional list of additional number spellings.

Example Call

/search?key=abc123xyz0&vanity=book&source=spare;rugly&quantity=100

Example Return Results

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>SUCCESS</status>
    <results>
        <item>
            <prefix>800</prefix>
            <number>8432665</number>
            <vanity>800 - THE BOOK</vanity>
        </item>
        <item>
        ...
        </item>
    </results>
</response>


Reserve a Specific Number

Command: reserve

Parameters

  1. key: Unique user key for identification purposes.
  2. number: All 10 digits (includes prefix) of the number to reserve.

Return Results

The API returns a properly formatted XML response. The first item in the XML is the <status> tag and will have a value of SUCCESS or ERROR. If ERROR, the XML will contain a list of <error> items. If SUCCESS, the number reserved will be returned inside the <number> tag (enclosed inside the <results> tag).

Example Call

/reserve?key=abc123xyz0&number=8775551234

Example Return Results

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>SUCCESS</status>
    <results>
        <number>8775551234</number>
    </results>
</response>

OR 

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>ERROR</status>
    <errors>
        <error>
            <code>number_unavailable</code>
            <message>The number is not available for reservation.</message>
        </error>
    <errors>
</response>


Perform a reverse lookup on a toll free number.

Command: reverselookup

Parameters

  1. key: Unique user key for identification purposes.
  2. number: All 10 digits (includes prefix) of the number to lookup.

Return Results

The API returns a properly formatted XML response. The first item in the XML is the <status> tag and will have a value of SUCCESS or ERROR. If ERROR, the XML will contain a list of <error> items. If SUCCESS, the information will be returned inside the <results> tag.

Example Call

/reverselookup?key=abc123xyz0&number=8775551234

Example Return Results

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>SUCCESS</status>
    <results>
        <number>8775551234</number>
        <numberstatus>WORKING</numberstatus>
        <statusdate>01/01/01</statusdate>
        <company>Phone Company, Inc.</company>
        <contactphone>2025551000</contactphone>
        <website>www.example.com</website>
    </results>
</response>

OR 

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>ERROR</status>
    <errors>
        <error>
            <code>number_invalid</code>
            <message>The number is not a valid toll free number.</message>
        </error>
    <errors>
</response>


NumSpellâ„¢ – find out what a number spells.

Command:numspell

Parameters

  1. key: Unique user key for identification purposes.
  2. number: The number to spell. Must contain 2-12 digits.
  3. quantity: The amount of results to return

Return Results

The API returns a properly formatted XML response. The first item in the XML is the <status> tag and will have a value of SUCCESS or ERROR. If ERROR, the XML will contain a list of <error> items. If SUCCESS, the number spellings will be returned inside the <results> tag.

Example Call

/numspell?key=abc123xyz0&number=3926753&quantity=2

Example Return Results

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>SUCCESS</status>
    <results>
        <spelling>example</spelling>
        <spelling>exam-please</spelling>
    </results>
</response>

OR 

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>ERROR</status>
    <errors>
        <error>
            <code>number_invalid</code>
            <message>The number is not a valid number.</message>
        </error>
    <errors>
</response>

Error Codes

request_timeout request has timed out
key_missing user key is missing
key_not_found key not found
key_invalid invalid key (not 24 characters)
vanity_missing vanity not supplied in search call
vanity_invalid vanity is not alphanumeric
invalid_source_format source paramater is invalid
invalid_source source does not exist
prefix_invalid invalid prefix supplied
quantity_invalid quantity not numeric
trailing_invalid invalid trailing digits (must be 0-5)
adult_invalid invalid adult filter parameter, must be 0 or 1
numeric_invalid invalid numeric parameter, must be 0 or 1
number_unavailable the number is not available for reservation
number_invalid the number is not a valid toll free number