Free PamFax API
The PamFax API is completely free for developers. Deploy fax services easily and at no cost.
Getting started with the PamFax API
It’s easy to get started with PamFax. API access and usage is easy and FREE. Click “Sign up” below and send us a short description on how you plan to use PamFax and we’ll immediately send you your login details to the sandbox API. This environment will provide you with all the documentation and API access so you can start the integration. The sandbox works just like the live, production API. The sandbox will even throw you fax delivery errors randomly so that you can test error handling.
Once you are ready to go live just contact us with a brief explanation of the solutions (and a few screenshots). We will then send you the live production API keys so that you can go live.
You can pay for faxes in two ways. Either you pre-load your PamFax account with enough credit to provide the fax service to your clients as part of your solution or you tell your clients to purchase the required credit themselves. In all cases, the PamFax API will provide you with price and page information so that you can track billing and inform your users of cost.
PamFax API Technical Overview
The PamFax API is made up of the following components:
- PamFax Application Server – The server manages all fax processes and associated data. For now, this means that we host the data in our high availability data center. Part of this environment are the document converter servers which are hosted on a powerful server platform.
- XML API – We’ve designed a highly flexible, standards based XML API which makes integrating with PamFax a snap. The PamFax XML API is an easy way to make programmatic HTTPS requests that result in simple XML responses.
- Common commands
Functions related to global information like system status, supported file types, etc.
- Fax History
Fax history access (inbox, outbox and sent faxes).
- Fax Job
Functions to create, manage and send a fax.
- Number Information
Functions about phone numbers like pricing for a particular number, zone rate information, etc.
Functions related to session handling, links, login/logout, user verification, etc.
Functions to handle shop items, vouchers, invoices, pricing information, etc.
- User Info
Functions to retrieve information about the user, settings, profile, history, etc.
Using the API
You have two possibilities to connect your software to PamFax: either you write the code yourself to communicate with the API via HTTPS XML yourself (see below) or you use one of these libraries:
- PHP client reference implementation
- Python library (kudos to Dynaptio)
- Ruby library (kudos to Tropo)
You can view the sample code on the sample page or after logging in to the PamFax API Frontend (free PamFax API account required, sign up below).
The PamFax API is a HTTPS GET/POST API that returns XML or JSON response. Arguments are passed using the POST method and must be validated with a checksum that is build on the given arguments. Each call must contain an argument that identifies the caller to ensure security. URL for a call is followed by an API processor and a method name. You may specify how return values shall be encoded using the special argument ‘apioutputformat’. It may be ‘API_FORMAT_XML’ or ‘API_FORMAT_JSON’. In this documentation we’ll show only XML formatted responses because this is API default.
<?xml version="1.0" encoding="UTF-8"?> <Session> <result> <code>success</code> </result> <User uuid="ab3549119c0dcb035f12863bdce456b5" username="somepamfaxusername" created="2008-04-30 11:49:33" credit="1.25" free_credit="1.2" inactive_credit="0" reactivated_credit="0" email="firstname.lastname@example.org" is_member="0" name="Eric Smith"/> <UserToken token="ip6d6rdv3t3bsesai2npkkantee1vpm3"/> <UserRights type="list"> <UserRight name="see_credit" allowed="1"/> <UserRight name="buy_credit" allowed="1"/> <UserRight name="buy_number" allowed="1"/> <UserRight name="transfer_credit" allowed="1"/> <UserRight name="receive_messages" allowed="1"/> </UserRights> </Session>
In the example resonse you’ll see a tag named ‘UserToken’. This is very important as it must be submitted with many calls to the API to identify the PamFax user the call shall be executed for. For example the FaxJob/Create call needs a validated PamFax user to work.
Securing API calls
All API calls are secured by a checksum-parameter. This ensures that the call is not changed on the way from your application to the PamFax API. You’ll have to calculate this value, so let’s have a look how to do this:
- data := [associative array of values]
- data := [sort alphabetically by case-insensitve key]
- checksum := [empty string]
- for each key/value pair in data
- checksum := [append value]
- checksum := [append your api secret word]
- checksum := [calculate md5 of checksum]
- [associative array of values] must NOT contain the following arguments: page, event, apikey, apicheck, usertoken
- [associative array of values] must contain the ‘apioutputformat’ argument if specified.
- [concatenate checksum and value] needs to check if the value is a bool take [true] as 1 and [false] as 0
- [concatenate checksum and value] needs to loop if value is an array. values keys needs to be converted to lowercase and value must be sorted alphabetically by it’s key (as in 2) and 3) ).
A reference implementation in PHP can be found in apiclient.php in the API client reference implementation (PHP) (see function CalcApiCheck).
Currencies in the API
Internally PamFax operates in Euro. All prices, credit etc. are kept in EUR. The currency values returned by the API are also always in Euro, except when a user is logged in (via Session::VerifyUser) and this user has a different currency set in his profile. Then all currency values are returned in the user’s currency. I.e. NumberInfo::GetPagePrice will return the cost of the fax (field “priceperpage”) in Euro if no user is logged in or if the logged in user has EUR set as his currency. When a user is logged in who has i.e. USD set as his currency, the “priceperpage” will be returned in USD (converted from EUR to USD with the current currency conversion). If you need a list of currency rates PamFax uses, just call Common::ListCurrencies. User’s credit is also returned in user’s currency. The API converts the internally used EUR values to the correct currency for you. This could lead in user’s credit varying from day to day when there are changes in the conversion rate. But as the prices of sending faxes will also be calculated with the same rate, the user always gets exactly the pages he paid for.
Dates in the API
Date/Time values are always returned in standard 24h date format, i.e. FaxHistory::ListInboxFaxes field “received” could look like “2009-04-24 22:44:11″. The time zone of all time fields is calculated based on the user’s settings or a global time zone set for your api account. I.e. we have set your API account to time zone “Asia/Tokyo” (please contact us so that we can set your time zone in your account). Then a fax is created. It will have the “created” field value in time zone value of “Asia/Tokyo”, and not the time of our servers.
Distribute your solution
Commercialize your integration – Are you ready to ship a commercial integration with PamFax? You can do this without any additional cost – using the PamFax API in your solution is FREE. Once you have completed the integration you submit the solution to us for certification. This is free and after successful certification you will be provided with API credentials to access the production API.