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:

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

  2. Import PamFax_SDK_iOS.h or PamFax_SDK_OSX.h header to link with SDK classes.

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

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

  5. 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]);
    	}
    				
  6. 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 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
			

Sign up for a free PamFax API account and access the full sample code.