We provide a web-based API to check your account balance, get calling rate(s) to a specified phone number, call history, DID minutes information and to initiate a web callback to the specified phone number (Click to call). With this, you can give your web site visitors a free way to contact you. All APIs use HTTP(S) POST or GET method to submit request data. Do not use the API usage examples in the production environment because key parameter will be visible to everybody in html source code. Use PHP/Perl/Ruby, etc. scripts instead to invoke the API. To try the examples, copy/paste the HTML code to a local file, set value for key parameter and open the file in a web browser. The key parameter value is shown on "Account info" when you log into your account.

Get account balance
Get calling rates
Web callback
Get call history
Get DID usage
Send SMS
LRN lookup
CNAM lookup

Get account balance.

URI: https://api.callwithus.com/api/account/

Parameters:

• key

Usage example:

<form method="post" action="https://api.callwithus.com/api/account/">
<input type="hidden" name="key" value="apikey">
<input type="submit">
</form>

Return value: string credit=value in USD.

Errors:

• -1000 - invalid API key.

Get calling rates.

URI: https://api.callwithus.com/api/getrate/

Parameters:

• key
• number
• trunk - optional, return pairs "trunk number" "rate", one pair per line.

Usage example:

<form method="post" action="https://api.callwithus.com/api/getrate/">
<input type="hidden" name="key" value="apikey">
<input type="text" name="number">
<input type="submit">
</form>

Return value: string rate=value1 value2 value3
returns a space-separated list of rates in USD for each available route according to your service plan.

Errors:

• -1000 - invalid API key.
• -1001 - number is not specified in the request
• -1002 - number is not valid

Web callback.

URI: https://www.callwithus.com/api/callback/

Parameters:

• key
• called - first call leg number
• calling - second call leg number
• timeout - (optional) first call leg timeout (seconds)
• reverse - (optional) call "calling" number first
• maxtime - (optional, >= 60) limit call duration to maxtime seconds

Usage example:

<form method="post" action="https://www.callwithus.com/api/callback/">
<input type="hidden" name="key" value="apikey">
<input type="text" name="called"> <!-- user enters his phone number here -->
<input type="hidden" name="calling" value="your phone number">
<input type="hidden" name="timeout" value="20">
<input type="hidden" name="maxtime" value="300">
<input type="submit">
</form>

Return value: phone number entered by user, API returns when the user answers incoming call.


Errors:

• -1000 - invalid API key.
• -1001 - called number is not specified in the request
• -1002 - calling number is not specified in the request
• -1003 - called number is not valid
• -1004 - call to user number failed
• -1005 - callback is blocked because you have low balance on your account

Note: both numbers must start with country code, it is your web software responsibility to check the number entered by user and to block calls to the destinations you do not want to allow.

Get call history.

URI: https://api.callwithus.com/api/callhistory/

Parameters:

• key
• start
• end
• html - (optional) format the result as html table instead of csv

"Start" and "end" parameters format is "YYYY-MM-DD[ HH:MM:SS]". If "start" or "end" parameters are missed or the value is not provided, the parameter defaults to the current day. The API takes into account your time zone setting.

Usage example:

<form method="post" action="https://api.callwithus.com/api/callhistory/">
<input type="hidden" name="key" value="apikey">
<input type="text" name="start">
<input type="text" name="end">
<input type="hidden" name="html" value="yes">
<input type="submit">
</form>

Return value: new line separated CDR records in format
"call date/time","call lenght","call from", "call to", "destination name", "terminate cause", "rate", "price", "IP address", "Trunk"
or html table if "html" parameter is set to "yes".

Errors:

• -1000 - invalid API key.
• -1001 - there are no calls in the specified time period.
• -1002 - date range is more than 1 month.

Get DID usage.

URI: https://www.callwithus.com/api/getdidminutes/

Parameters:

• key
• did

Usage example:

<form method="post" action="https://www.callwithus.com/api/getdidminutes/">
<input type="hidden" name="key" value="apikey">
<input type="text" name="did">
<input type="submit">
</form>

Return value: line with the following values:
"DID","free minutes","used minutes","minute price","monthly price","DID setup date"

Errors:

• -1000 - invalid API key.
• -1001 - the DID "did" has not been set up on your account.

Send SMS.

URI: https://www.callwithus.com/api/sms/

Parameters:

• key
• to - phone number to send SMS to
• from - your phone number (will not be delivered correctly if you send SMS to US number)
• text - message text, up to 160 characters

Usage example:

<form method="post" action="https://www.callwithus.com/api/sms/">
<input type="hidden" name="key" value="apikey">
To: <input type="text" name="to">
From: <input type="text" name="from">
Text: <input type="text" name="text">
<input type="submit">
</form>

Return value: String "OK" if message has been accepted for delivery by SMS gateway.

Errors:

• -1000 - invalid API key.
• -1001 - "to" number is not specified in the request
• -1002 - "from" number is not specified in the request
• -1003 - "to" number is not valid
• -1004 - SMS delivery failed
• -1005 - SMS is blocked because you have low balance on your account

Note: both numbers must start with country code.

LRN lookup.

LRN lookup service is not free. Your account will be charged $0.0003 per query. If the requested number is a not valid US/Canada number (-1003 error code), your account will be charged $0.0001.

URI: http://lrn.callwithus.com/api/lrn/index.php

Parameters:

• key
• number - 10 or 11 digits US or Canada number
• ei (optional) - return extra information about the number.

Usage example:

<form method="post" action="http://lrn.callwithus.com/api/lrn/index.php">
<input type="hidden" name="key" value="apikey">
<input type="hidden" name="ei">
<input type="text" name="number">
<input type="submit">
</form>

Return value: the LRN of the queried number. If the number has not been ported, the API will return the queried number. If extra number info was requested, the return value is comma separated string in the following format:
LRN,State,Ratecenter,LATA,OCN,Company,Prefix_Type

Errors:

• -1000 - invalid API key.
• -1003 - the queried number is not a valid US/Canada number.
• -1004 - lookup error.
• -1005 - Your account balance is low.

CNAM lookup.

CNAM lookup service is not free. Your account will be charged $0.006 per query.

URI: http://lrn.callwithus.com/api/cnam/index.php

Parameters:

• key
• number - 10 or 11 digits North American number

Usage example:

<form method="post" action="http://lrn.callwithus.com/api/cnam/index.php">
<input type="hidden" name="key" value="apikey">
<input type="text" name="number">
<input type="submit">
</form>

Return value: the caller id name of the queried number.

Errors:

• -1000 - invalid API key.
• -1003 - the queried number is not a valid North America number.
• -1004 - lookup error.
• -1005 - Your account balance is low.

If you use FreePBX, you can do CNAM lookups with Caller ID Source module, please see the instructions.