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

• search
• reserve
• reverselookup (beta)
• numspell (beta)

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). 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