Free PamFax API
The PamFax API is completely free. Add fax functionality to your app quickly with our sample SDKs.Samples
We currently have sample SDK libraries available for the following languages:
PHP
C# .NET for XP/Win7
C# .NET for Win8
Java
Python
Ruby
Bash
Objective-C
You will be able to download the full samples after creating an account (below).
If you need help integrating PamFax with a different language, please contact us.
PHP SDK Samples
Our PHP reference implementation is required to run the following samples. Login to the PamFax API Frontend and download the code. Unpack into your server root. Then include the pamfax_api.php file and if you want to use the wrapper classes: call pamfax_use_static() or pamfax_use_instance()
Sample 1: Including the PamFax API lib, setting the credentials and verify a user.
// include the PamFax API Client and set your credentials
require_once('pamfax_api.php');
$GLOBALS['PAMFAX_API_URL'] = "https://api.pamfax.biz/";
$GLOBALS['PAMFAX_API_APPLICATION'] = "your API key here";
$GLOBALS['PAMFAX_API_SECRET_WORD'] = "your API secret word here";
// Tell the API Client to create objects from returned XML automatically
$GLOBALS['PAMFAX_API_MODE'] = ApiClient::API_MODE_OBJECT;
// Tell the API Client to use static wrapper classes
pamfax_use_static();
// verify the PamFax User Name (this is the PamFax account used to also login at https://portal.pamfax.biz):
$result = SessionApi::VerifyUser('test_user','test_users_password');
if( ($result instanceof ApiError) // explicit error
|| !isset($result['UserToken']) || !isset($result['User']) ) // implicit error
die("Unable to login");
// Set the global usertoken
$GLOBALS['PAMFAX_API_USERTOKEN'] = $result['UserToken']->token;
// Optionally remember the user for later use
$currentUser = $result['User'];
Sample 2: Send a fax with cover page only to a single recipient.
// do everything from sample 1
require_once('sample_001.php');
// Create a new fax and give the users IP, UserAgent and an origin
FaxJobApi::Create($_SERVER['REMOTE_ADDR'],$_SERVER['HTTP_USER_AGENT'],'API Samples');
// Add a recipient to the fax (change sample fax number to a real one)
FaxJobApi::AddRecipient('+15752087007','Optional name of recipient');
// Set the cover to template 1 and the text to a random value
FaxJobApi::SetCover(1,'This is my test fax using the PamFax API');
// Wait for the API to prepare the fax
do
{
sleep(5);
$test = FaxJobApi::GetFaxState();
if( ($test instanceof ApiError) // explicit error
|| !isset($test['FaxContainer']) ) // implicit error
die("Error preparing the fax");
}while( $test['FaxContainer']->state != "ready_to_send" );
// Send the fax
FaxJobApi::Send();
Sample 3: Send a fax with a single file and without cover page to multiple recipients.
require_once('sample_001.php');
// Create a new fax and give the users IP, UserAgent and an origin
FaxJobApi::Create($_SERVER['REMOTE_ADDR'],$_SERVER['HTTP_USER_AGENT'],'API Samples');
// Add 3 recipients to the fax (change sample fax numbers to a real ones)
FaxJobApi::AddRecipient('+15752088795','Recipient 1');
FaxJobApi::AddRecipient('+493059878787','Recipient 2');
FaxJobApi::AddRecipient('+313087989898','Recipient 3');
// Use the prefix '@' with the $full_path_to_local_file to tell the API Client it needs to upload a file
$postdata = array(
'file' => "@".$full_path_to_local_file,
'filename' => $name_of_file
);
FaxJobApi::AddFile($postdata);
// Wait for the API to prepare the fax
do
{
sleep(5);
$test = FaxJobApi::GetFaxState();
if( ($test instanceof ApiError) // explicit error
|| !isset($test['FaxContainer']) ) // implicit error
die("Error preparing the fax");
}while( $test['FaxContainer']->state != "ready_to_send" );
// Send the fax
FaxJobApi::Send();
C# SDK Sample
Below you can see sample code to send a fax via our C# .NET library.
//Call init to set the API key, secret and URL (they are all preset)
ApiClient.Init(ApiKey, ApiSecret, ApiUrl);
ApiResult verifyUserResult = null;
//loop until the user successfully logged in
while (verifyUserResult == null || verifyUserResult.State == ApiResultState.Failure)
{
//Login PamFax user
verifyUserResult = SessionApi.VerifyUser(Username, Password);
if (verifyUserResult.State == ApiResultState.Failure)
{
Console.WriteLine("Result: {0}", verifyUserResult.State.ToString());
Console.WriteLine("Code: {0}", verifyUserResult.ErrorCode);
Console.WriteLine("ErrorMessage: {0}", verifyUserResult.ErrorMessage);
Console.WriteLine("Logging in failed, please retry, press any key to continue");
Console.ReadLine();
Console.Clear();
}
}
//Retrieve the usertoken from the xml result using Indexers
string usertoken = verifyUserResult["UserToken", "token"];
//Or use the helper methods
ApiResponse userTokenNode = verifyUserResult.Get("UserToken");
usertoken = userTokenNode.Get("token", "");
//after retrieving the usertoken, don't forget to set it via:
ApiClient.SetApiUserToken(usertoken);
//Create a new fax
//FaxJobApi.Create("127.0.0.1", "test_user_agent", "API Sample");
ApiResult result = FaxJobApi.Create("127.0.0.1", "test_user_agent", "API Sample");
if (result.State != ApiResultState.Success)
return;
//Add fax recipient
result = FaxJobApi.AddRecipient("+1 23 34567890", "Test");
if (result.State != ApiResultState.Success)
return;
//List all covers to retrieve the uuid used to set a cover via FaxJobApi.SetCover
ApiResult listCoversResult = FaxJobApi.ListAvailableCovers(true);
//Get the list names "Covers"
ApiList covers = listCoversResult.GetList("Covers");
string templateId = "";
string templateUuid = "";
//Get the values needed to set the cover
if (covers.Count > 0)
{
templateId = covers[0,"id"];
templateUuid = covers[0 , "template_id"];
}
//Set the cover
FaxJobApi.SetCover(templateId, "Some sample cover text", templateUuid, null);
//Add a file to the fax
string filePath = TestFile;
FileInfo fi = new FileInfo(filePath);
string fileName = fi.Name;
string fileSizeInBytes = fi.Length.ToString();
byte[] pdfBytes = File.ReadAllBytes(filePath);
string pdfBase64 = Convert.ToBase64String(pdfBytes);
//using (var md5 = MD5.Create())
//{
// string contentMD5 = BitConverter.ToString(md5.ComputeHash(File.ReadAllBytes(filePath))).Replace("-", "");
// FaxJobApi.AddFile("9465544x.pdf", "API Sample", fileSizeInBytes, contentMD5, filePath);
//}
FaxJobApi.AddFile(Path.GetFileName(fileName), filePath);
ApiResult faxStateResult = null;
do
{
faxStateResult = FaxJobApi.GetFaxState();
if ((faxStateResult != null) &&
((faxStateResult.State == ApiResultState.Failure)
|| (faxStateResult["FaxContainer", "state"] == "ready_to_send")
|| (faxStateResult["FaxContainer", "state"] == "not_enough_credit")))
break;
else
Thread.Sleep(3000);
}
while (true);
//send the fax
ApiResult sendResult = FaxJobApi.Send("","");
Java SDK Sample
Below you can see sample code to send a fax via our Java library. This sample doesn’t include a UI implementation, because it is dependant on the target platform.
All main API classes are present in the library, their names starts with ‘API’ prefix. In these classes, you may find all needed methods to work with the API. Each method may be used as stand-alone static call with specifiedrequestListener (instance of SessionListener) parameter that uses to handle request response:
// Pre-define a request listener for post-request work
SessionListener requestListener = new SessionListener()
public void onRequestComplete( RequestType requestType, int resultCode, ResponseData responseData ) {
// Checking for successful request result
if ( resultCode == ResultCode.SUCCESS )
...
else
...
// To do some additional things depending on request type
switch ( requestType ) {
case SESSION_VERIFY_USER:
...
UserInfo userInfo = responseData.getUserInfo();
...
break;
default:
break;
}
}
};
// Verifying the user using static call
APISession.verifyUser( "userName", "password", requestListener );
Also there are some classes to do your work easier:
SessionHelper that may be used to handle of a API session and an user session.
FaxJobHelper to semiautomated processing of APIFaxJob requests.
Here is an example how to use these classes in your program code:
// Pre-define a session listener for post-requests work
SessionListener sessionListener = new SessionListener() {
public void onRequestComplete( RequestType requestType, int resultCode, ResponseData responseData ) {
// Checking for successful request result
if ( resultCode == ResultCode.SUCCESS )
...
else
...
// To do some additional things depending on request type
switch ( requestType ) {
case FAXJOB_ADD_FILE:
...
FaxFileContainer fileContainer = responseData.getFaxFileContainer();
...
break;
case FAXJOB_ADD_RECIPIENT:
...
FaxRecipient recipient = responseData.getFaxRecipient();
...
break;
case FAXJOB_CREATE_FAX:
...
FaxContainer faxContainer = responseData.getFaxContainer();
...
break;
case FAXJOB_SEND_FAX:
...
break;
case SESSION_VERIFY_USER:
...
UserInfo userInfo = responseData.getUserInfo();
...
break;
default:
break;
}
}
};
// Creating SessionHelper object to automate some API session work
SessionHelper sessionHelper = new SessionHelper( API_KEY, API_SECRET, sessionListener );
// Starting API user session
sessionHelper.startSession( "userAccount", "userPassword", true );
// Creating FaxJobHelper object to automate some fax job tasks
FaxJobHelper faxJobHelper = new FaxJobHelper( sessionListener, SEND_REPEAT_TIMEOUT, SEND_REPEATS_COUNT );
// Creating new fax container
faxJobHelper.createFax();
// Adding fax recipient
faxJobHelper.addRecipient( "+1991234567", "John Doe" );
// Adding file which one of supported formats
File faxFile = new File( "path/to/my/file.docx" );
faxJobHelper.addFile( "myFileToFax.docx", faxFile );
// Sending fax. If fax yet not ready, FaxJobHelper will retry sending
// with specified SEND_REPEAT_TIMEOUT and SEND_REPEATS_COUNT
faxJobHelper.sendFax();
PaxFax SDK for Mac OS X or iOS
PaxFax SDK consists from two types of classes according to their role:
Core classes.
Core classes is main package of the SDK that contains most of SDK logic. They have 'PFSDK' prefix and should not be used by end-user directly, excluding special data types which used for representation of API responses.
API representation (interface) classes.
API interface classes analogs of web API classes with 'PFAPI' prefix in their names. These classes provides analogs of API functions to make API requests.
Run-up
First you need to do is integrate PamFax SDK sources into your project following next simple steps:
Add PamFax SDK files to your project using menu File->Add files to YOUR_PROJECT_NAME or just Drag-n-Drop them from Finder to the Project navigator.
Import PamFax_SDK_iOS.h or PamFax_SDK_OSX.h header to link with SDK classes.
By default SDK uses sandbox API server, to set it open your AppDelegate implementation file and call PFSDKDefines::setAPIServer with one of next values:
API_SERVER_LIVE
API_SERVER_SANDBOX
API_SERVER_BETA
somewhere in (BOOL) application: (UIApplication *) application didFinishLaunchingWithOptions: (NSDictionary *) launchOptions method.
Next you need PFSDKSession instance to work with SDK, to get em call PFSDKSession::initSessionWithAPIKey:withAPISecret: specifying your API key and API secret values ('_Session' in next example).
Implement PFSDKRequestListener interface to handle API responses ('_Listener' in next example) like below:
- (void)request:(PFSDK_REQUEST_ID)requestID completeWithCode:(int)code andData:(NSDictionary *)responseData { NSLog(@"API response: %@", [responseData description]); } - (void)request:(PFSDK_REQUEST_ID)requestType failedWithError:(NSError *)error { NSLog(@"ERROR: %@", [error description]); }Using initialized Session instance call needed API functions using PFAPI interface classes like below:
// Verify user [PFAPISession session:_Session verifyUser: USERNAME withPassword:PASSWORD andRemember:YES forLifeTime:0 withListener:_Listener]; // Create fax [PFAPIFaxJob session:_Session createFaxForIP:@"0" withAgent:@"PamFax SDK agent" origin:@"PamFax SDK Test App" withListener:_Listener]; // Add recipient [PFAPIFaxJob session:_Session addRecipient:RECIPIENT withListener:_Listener]; // Add file [PFAPIFaxJob session:_Session addFile:filePath withName:@"MyCustomFileName" withListener:_Listener]; // Send the fax [PFAPIFaxJob session:_Session sendFaxWithListener:_Listener];
Python-3 SDK Sample
You can use the a1pamfax package to access the PamFax API from Python 3.6+.
The pip command can be used to install the package.
On Ubuntu, pip can be installed via sudo apt-get install python-pip To install the package, use: sudo pip install a1pamfax
Further information on the Python package is available from PamFax Python library
GitHub (bufemc/a1pamfax)
Python 3 implementation of the PamFax API - a rewrite of the dynaptico Python 2 implementation - dynaptico/pamfaxp
Example: send a fax with a cover text
#!/usr/bin/python3
import os
import time
from pamfax import PamFax
# Either configure it manually or by using an external config.py file
if os.path.isfile('./config.py'):
from config import HOST, USERNAME, PASSWORD, APIKEY, APISECRET
else:
HOST = 'api.pamfax.biz'
USERNAME = 'your PamFax User Name here'
PASSWORD = 'your PamFax password here'
APIKEY = 'your API key here'
APISECRET = 'your API secret word here'
pamfax = PamFax(USERNAME, PASSWORD, host=HOST, apikey=APIKEY, apisecret=APISECRET)
pamfax.create()
response = pamfax.list_available_covers()
pamfax.set_cover(response['Covers']['content'][1]['id'], 'My test fax with PamFax using Python')
pamfax.add_recipient('+15752088795')
while True:
fax_state = pamfax.get_state()
if fax_state['FaxContainer']['state'] == 'ready_to_send':
break
time.sleep(2)
print("\n\nFax setup done, sending...\n")
response = pamfax.send()
print(response)
Python-2 SDK Sample
You can use the dynaptio-pamfax package to access the PamFax API from Python. The pip command can be used to install the package. On Ubuntu, pip can be installed via sudo apt-get install python-pip. To install dynaptico-pamfax use: sudo pip install dynaptico-pamfax Further information on the Python package is available from http://github.com/dynaptico/pamfaxp.
Example: send a fax with a cover text
#!/usr/bin/env python
import time
from pamfax import PamFax
HOST = 'api.pamfax.biz'
USERNAME = 'your PamFax User Name here'
PASSWORD = 'your PamFax password here'
APIKEY = 'your API key here'
APISECRET = 'your API secret word here'
pamfax = PamFax(USERNAME, PASSWORD, host=HOST, apikey=APIKEY, apisecret=APISECRET)
pamfax.create()
response = pamfax.list_available_covers()
pamfax.set_cover(response['Covers']['content'][1]['id'], 'My test fax with PamFax using Python')
pamfax.add_recipient('+15752088795')
while True:
fax_state = pamfax.get_state()
if fax_state['FaxContainer']['state'] == 'ready_to_send':
break
time.sleep(2)
pamfax.send()
Ruby SDK Sample
This sample is taken from the PamFax Ruby library, developed by Tropo.
Sample: Send a fax with a cover sheet and a file to multiple recipients.
require 'rubygems'
require 'lib/pamfaxr'
require 'awesome_print'
PAMFAX_URI = 'https://api.pamfax.biz/'
PAMFAX_USERNAME = 'your PamFax User Name here'
PAMFAX_PASSWORD = 'your PamFax password here'
# You may also specify a custom :api_key and :api_secret, or it uses the default
pamfaxr = PamFaxr.new :base_uri => PAMFAX_URI,
:username => PAMFAX_USERNAME,
:password => PAMFAX_PASSWORD
# Create a faxjob
faxjob = pamfaxr.create_fax_job
ap 'Creating a fax job'
ap '*'*10
ap faxjob
# Add a cover
covers = pamfaxr.list_available_covers
ap 'Listing available covers'
ap '*'*10
ap covers
ap 'Adding a cover'
ap '*'*10
ap pamfaxr.set_cover(covers['Covers']['content'][1]['id'], 'Foobar is here!')
ap 'Adding a remote file'
ap '*'*10
ap pamfaxr.add_remote_file('***place a HTTP address here to a document***')
ap 'Adding a local file'
ap '*'*10
file = pamfaxr.add_file('examples/Tropo.pdf')
ap file
ap 'Removing a file'
ap '*'*10
ap pamfaxr.remove_file(file['FaxContainerFile']['file_uuid'])
ap 'Adding a recipient'
ap '*'*10
ap pamfaxr.add_recipient('+15752088972')
ap 'Adding a second recipient'
ap '*'*10
recipient = pamfaxr.add_recipient('+493089766442')
ap recipient
ap 'Removing a recipient'
ap '*'*10
ap pamfaxr.remove_recipient(recipient['FaxRecipient']['number'])
ap 'Listing a recipient'
ap '*'*10
ap pamfaxr.list_recipients
ap 'Listing associated fax files'
ap '*'*10
ap pamfaxr.list_fax_files
ap 'Checking state'
ap '*'*10
time = 0
loop do
fax_state = pamfaxr.get_state
ap fax_state
converting = true
break if fax_state['FaxContainer']['state'] == 'ready_to_send'
sleep 2
time += 2
ap "#{time.to_s} seconds elapsed..."
end
ap 'Preview the fax'
ap '*'*10
ap pamfaxr.get_preview(faxjob['FaxContainer']['uuid'])
ap 'Send the fax'
ap '*'*10
ap pamfaxr.send_fax
ap 'Send the fax later'
ap '*'*10
ap pamfaxr.send_fax_later
ap 'Clone the fax'
ap '*'*10
ap pamfaxr.clone_fax(faxjob['FaxContainer']['uuid'])
BASH SDK Sample
Save the code to a file named sendpamfax.sh and then call this script via command line like: ./sendpamfax.sh apikey apisecret username password faxnumber faxcontent
Sample: Send a fax with a bash script using a CURL library
#!/bin/bash
# Send a fax using bash, curl, sed and the PamFax API
# Check the number of arguments
if [ $# -ne 7 ]
then
echo "USAGE: $0 apikey apisecret username password faxnumber faxcontent filename"
exit 1
fi
# Protocol and server
export url_start="https://api.pamfax.biz/"
# Common parameters used in all API calls, taken from commandline
export url_params="/?apikey=$1&apisecret=$2"
# Create a session
export xml_result=`curl -k --silent "$url_start/Session/VerifyUser$url_params&username=$3&password=$4"`
# Todo: error handling / check for success
# Extract the user token from the XML response
export usertoken=`echo $xml_result | sed '/UserToken/!d;s/.*token="\([^"]*\)".*/\1/'`
if [ "$usertoken" == "" ]
then
echo "Session/VerifyUser failed"
exit 1
fi
# Add usertoken to common url parameters for this session
export session_params="$url_params&usertoken=$usertoken"
# Create a new fax job
export user_ip=`hostname -i`
export xml_result=`curl -k --silent "$url_start/FaxJob/Create$session_params&user_ip=$user_ip&user_agent=pamfax_send.sh&origin=shell"`
# Todo: error handling / check for success
# Add the recipient
export xml_result=`curl -k --silent "$url_start/FaxJob/AddRecipient$session_params&number=$5"`
# Todo: error handling / check for success
# Use Basic template for the cover page
# Available templates can be listed using FaxJob/ListAvailableCovers
export template_id=1
# Add the cover page using the text provided on the command line
export xml_result=`curl -k --silent "$url_start/FaxJob/SetCover$session_params&template_id=$template_id&text=$6"`
# Todo: error handling / check for success
# Upload the given file
export xml_result=`curl -k --silent --form file=@$7 --form filename=$7 "$url_start/FaxJob/AddFile$session_params"`
# Loop until the fax is ready
export ready=1
while [ $ready -ne 0 ]
do
# Wait for 5 seconds
sleep 5
# Query the fax state
export xml_result=`curl -k --silent "$url_start/FaxJob/GetFaxState$session_params"`
# Note that the response will also contain pricing information
# Look for state="ready_to_send"
echo $xml_result | grep 'state="ready_to_send"'
export ready="$?"
done
#Send the fax
export xml_result=`curl -k --silent "$url_start/FaxJob/Send$session_params"`
echo $xml_result