Introduction

All calls to the iFax API should be made to https://api.ifaxapp.com/v1, which remains current with the latest minor updates. For most calls, you will need to pass in your API key as parameters. You can find your API key on the “Settings” page of your dashboard. In iFax, there are two types of credentials: Live and Test.

If you make an API call with a Live key, your balance will decrease if you perform operations that cost money (e.g. you send a fax). However, if you make calls with test keys, the iFax system will simulate faxes being sent or received and your balance will not be affected.

All iFax API responses are formatted in JSON. Need an XML response? Too bad. JSON is awesome! Click here to learn more about it.

HTTP Methods

Since our API is RESTful, each API call requires a specific HTTP method to indicate the type of operation to be performed. The method only has to be specified when interacting with the iFax API at the HTTP level, such as when using curl:

			
	            	curl -X POST https://api.ifaxapp.com/v1/customer/fax-send \
-H 'accessToken:API_KEY'

Method Simulation

Some HTTP clients don’t support all HTTP methods. In such cases, the POST method can be used, with the method for the API call passed in the _method parameter:

	              curl https://api.ifaxapp.com/v1/customer/fax-send
-F '_method=POST' \
-H 'accessToken:API_KEY'

Authentication

Most API calls require authentication. The client libraries have built-in authentication handling, which will automatically authenticate each request when properly initialized.

HTTP Authentication

HTTP authentication may be used simply by using the API key. For example:

	              		cURL
curl 'https://api.ifaxapp.com/v1/customer/fax-send' \
-H 'accessToken:API_KEY'

Formats

By default, all API calls return a JSON response. Click here to learn more about it.

Objects

Fax Object

The fax object is a JSON object returned by the iFax API and represents a fax job in the system. Its properties are described in the table below.

Name	Description
jobId	A unique ID generated for each fax sent through the API. This can be used to retrieve the fax’s status, cancel a fax or resend a failed fax.
fromNumber	The number (in E.164 format) the fax was sent from.
toNumber	The number (in E.164 format) that received the fax.
faxCallLength	The total time spent (in seconds) from when the API call was made until the fax processing ended.
faxCallStart	A timestamp (in Unix time) indicating when the initial API call was made.
faxCallEnd	A timestamp (in Unix time) indicating when the fax processing ended.
faxTotalPages	The total number of pages in the fax being sent.
faxTransferredPages	The total number of pages in the fax that were successfully sent and received by the recipient.
faxStatus	The status of the fax. Can be any of the following: ‘sending’, ‘delivered’, ‘canceled’, or ‘failed’. Click here for more information.
message	A detailed description of the fax status or error, if any.
code	A numeric code that indicates a more accurate representation of the fax status or error, if any.

Example Fax Object

	          		{
	          	   		"jobId": 12345,
	          	   		"fromNumber": "+441224515014",
	          	   		"toNumber": "+15065001844",
	          	   		"faxCallLength": 173,
	          	   		"faxCallStart": 1610966603 (UTC timestamp),
	          	   		"faxCallEnd": 1610966723 (UTC timestamp),
	          	   		"faxTotalPages": 20,
	          	   		"faxTransferredPages": 20,
	          	   		"faxStatus": "delivered",
	          	   		"message": "NORMAL_CLEARING",
	          	   		"code": 0
	          	   	}

Webhooks

Webhooks allow iFax to update you in real-time about the status of your faxes. Webhooks are triggered by events such as the completion of a fax, and transmit information about the state of that fax to you via HTTP(S).

Specifying Webhook URLs

The first thing we need to send you a webhook is a destination URL. This should be a valid URI with a http, https scheme that points to a destination that you control. An example of a valid webhook URL is https://www.example.com/ifax_webhook

For sent and received faxes, you can set global webhook URLs on your webhook settings page. These apply to all faxes on your iFax Acount.

Specifying a Webhook Version

Coming Soon

Enabling Inflight Webhooks

Currently, iFax supports two categories of webhooks: postflight and inflight. Postflight webhooks are triggered when a fax completes, regardless of success. Inflight webhooks are triggered by events during the transmission of a fax, such as the transfer of individual pages.

Inflight webhooks are disabled by default, but can be enabled on the webhook settings page.

Retries

If a webhook fails, We will automatically retry up to 5 times. There will be a backoff before each retry, which increases as follows:

Retry No.	Backoff
1	5 minutes
2	10 minutes
3	20 minutes
4	30 minutes
5	60 minutes

Fax Statuses

Will receive the following possible status in API responses

Name	Description
sending	The system is currently sending the fax and communicating with the recipient machine.
delivered	The fax has been successfully sent and received by the recipient machine.
canceled	The fax has been cancelled successfully.
failed	The system has failed to send the fax successfully. Refer to the error codes here to know more about the specific error.

Error Messages

Error Code	Message
-3007	No permission for this action (In inbound method GetList, L'Type is set to Account All Messages or Account New Messages, when the username is not a Primary user)
-3004	TIFF file is empty
-3003	Image does not exist
-3001	MESSAGE_TYPE_NONEXIST
-2076	Contact List reached its maximum number of contacts.
-2075	INVALID_NUMBER_FORMAT
-2074	User is not authorized to operate actions on specified contact
-2072	There is not contact list with ListID value which belong to requested userid.
-2057	Invalid DefaultTextFontSize
-2056	Invalid DefaultPageScaling
-2055	Invalid DefaultRetriesInterval
-2041	RECOVERY_ON_TIMER_EXPIRE
-2040	Invalid date range
-2037	No credit
-2036	SERVICE_UNAVAILABLE
-2035	E-mail does not exist
-2034	E-mail already exists
-2033	No numbers available
-2028	There is no country code matching for this number.
-2027	Invalid DefaultRetriesToPerform
-2026	Invalid DefaultRenderingQuality
-2025	Invalid DefaultPageResolution
-2024	Invalid DefaultPageOrientation
-2023	Invalid DefaultPageSize
-2014	Username/password not found in request data.
-2012	Invalid Time zone
-1066	Multiple faxes are chained to the same original transaction
-1063	Total file size is too big
-1062	Wrong session ID
-1020	Too many users for this account. Please contact support@ifaxapp.com for further assistance.
-1011	Image not available (may happen if the delete fax after completion feature is active)
-1008	File count and total file data/name are not equal.
-1005	fax_id not found in this request.
-1004	Fax file not compatible/found.
-311	Transaction does not belong to requested user
-310	Active user not found for this request.
-162	Fax can not be cancel now.
-150	SYSTEM_SHUTDOWN
-123	No valid documents attached
-111	Attempting to fax to a number that is not the designated fax number in a developer account.
-22	Not enough credit for the user
-11	Pre-processing
-3	Fax processed for sending
-3	processed
-3	sent
0	Normal clearing of fax.
0	NORMAL_CLEARING
0	delivered
256	Internal error
261	Busy trunk line detected
263	USER_BUSY
403	Fax canceled.
1111	Manually updated old sent fax records.
3072	Telephony error
3211	Fax machine incompatibility
3230	WRONG_MESSAGE
3912	UNALLOCATED_NUMBER
3931	Busy
3935	No answer (might be out of paper)
3937	Ring busy
6002	NO_ROUTE_TRANSIT_NET
6002	NO_ROUTE_DESTINATION
6021	CALL_REJECTED
6021	WRONG_CALL_STATE
6022	Number changed
6099	DESTINATION_OUT_OF_ORDER
6100	UNSPECIFIED
6100	INCOMPATIBLE_DESTINATION
7200	NORMAL_TEMPORARY_FAILURE
8021	NO_ANSWER
9000	CHANNEL_UNACCEPTABLE
9001	NORMAL_CIRCUIT_CONGESTION
9002	ALLOTTED_TIMEOUT
9005	Problem establishing connection
9006	The Receiving Phone Number Is Not Operational
9007	NETWORK_OUT_OF_ORDER
9008	Problem with remote carrier
9009	There was an error communicating with the far side.
9010	Far end cannot receive at the size of image
9011	NO_USER_RESPONSE
9012	Disconnected after permitted retries
9013	Received no response to DCS or TCF
9014	Timed out waiting for the first message
9015	Timed out waiting for initial communication
9016	Unexpected message received
9023	Insufficient funds to send fax and not able to auto recharge: There was a problem charging your credit card. Please check your payment information and try again.
9024	No answer (The Receiving Machine May Be Out Of Paper)
9028	Far end is not compatible
9030	Fax is already canceled.
9036	Could not send the file to the fax server for spooling
9040	Insufficient funds to send fax and not able to auto recharge.
9042	There was a problem in converting and merging files to the output file format.
11008	missing data
11009	invalid account
11010	invalid amount
11013	Processing error. Please try again later
12001	USER_BLOCKED
12006	No record found
12007	failed
12008	Duplicate email
12009	Invalid parameter
12010	Invalid request method
12012	Not enough credits
12014	Max user logged in
12015	Wrong password
12016	Wrong email
12017	Credit not added
12020	to_number not found in request data.
12021	Fax with this id does not exist
12026	You have successfully logged out from iFax.
12029	Your notifications changes saved successfully.
12032	"Password has been reset successfully and sent to your email address, If you do not receive the email shortly, please check your spam or junk mail box."
12033	USER_NOT_REGISTERED
12034	Your password has been changed successfully.
12035	Please enter valid email address or password.
12036	Fax number list.
12037	Record deleted successfully.
12043	Credit added successfully.
12046	Customer not available
12047	Customer card details not available
12048	FAX cancel request failed.
12049	CALL_AWARDED_DELIVERED
12050	SUBSCRIBER_ABSENT
12051	NUMBER_CHANGED
12052	REDIRECTION_TO_NEW_DESTINATION
12053	EXCHANGE_ROUTING_ERROR
12054	FACILITY_REJECTED
12055	RESPONSE_TO_STATUS_ENQUIRY
12056	NORMAL_UNSPECIFIED
12057	SWITCH_CONGESTION
12058	ACCESS_INFO_DISCARDED
12059	REQUESTED_CHAN_UNAVAIL
12060	PRE_EMPTED
12061	FACILITY_NOT_SUBSCRIBED
12062	OUTGOING_CALL_BARRED
12063	INCOMING_CALL_BARRED
12064	BEARERCAPABILITY_NOTAUTH
12065	BEARERCAPABILITY_NOTAVAIL
12066	CHAN_NOT_IMPLEMENTED
12067	FACILITY_NOT_IMPLEMENTED
12068	SERVICE_NOT_IMPLEMENTED
12069	INVALID_CALL_REFERENCE
12071	MANDATORY_IE_MISSING
12072	IE_NONEXIST
12073	INVALID_IE_CONTENTS
12074	MANDATORY_IE_LENGTH_ERROR
12075	PROTOCOL_ERROR
12076	INTERWORKING
12077	ORIGINATOR_CANCEL
12078	CRASH
12079	LOSE_RACE
12080	MANAGER_REQUEST
12081	BLIND_TRANSFER
12082	ATTENDED_TRANSFER
12083	USER_CHALLENGE
12084	MEDIA_TIMEOUT
12085	PICKED_OFF
12086	PROGRESS_TIMEOUT
12087	GATEWAY_DOWN
204000	Rendering error
205000	Quota exceeded (Prepaid card depleted)
205001	Internal System error (FindRoute)
206001	Internal System Error (LocalSender)
12090	Can not validate number.
12091	Can not find fax.
12092	File not found
12093	Data not found
12094	file not found to resend this fax.
12095	FAX resend request failed.
12096	FAX status request failed.
12097	fax details not found for this request.
12098	fax details not found.
12099	FAX list request failed.
12100	FAX delete request failed.
12101	No data found for supported countries.
12102	FAX list country price request failed.
12089	password not found in request data.
12088	username not found in request data.
12103	Fax status response
12104	Fax supported countries
12105	User credit response
12106	Fax list response
-2075	invalidnumber
-1008	file_count is not valid in request data.
-1005	fax not found for this fax_id.
12107	Can't resend the fax, it's already in sending mode.
12108	country iso not found in request data.
12109	Fax supported areas
12110	Fax number available
12111	Provider Configuration not found.
12112	Fax number purchase successfully
12113	Number was not Purchased Successfully.
12114	Number was not deleted Successfully.
12115	Number deleted Successfully.
12116	Can not find provider.
12117	Can not find area.
12118	Area name not found for this request.
12119	Active provider not found for this request.
12120	Can not find user.
12121	country iso not found in request data.
12122	national_destination_code not found in request data.
12123	id not found in request data.
12124	number not found in request data.
12125	environment not found in request data.
12126	Not valid environment.
12127	Can not find country.
12128	Country iso not found for this request.
12129	Number already exists.
12130	Can not find Fax.
12131	chunk Number not found in request data.
12132	Download Fax Response
12133	Chunk Number should be less than chunk total count.
12134	No any fax number available
12135	Can not find Number.
12136	upfront cost is greater than zero for this number
12137	order_id not found
12138	Purchased number connection not assign.
12139	old_connection_id missing.
12140	old_sip_username missing.
12141	new_connection_id missing.
12142	new_sip_username
12143	new_sip_password missing.
12144	sip_credential updated successfully.

Send faxes

Method: Post

Path: https://api.ifaxapp.com/v1/customer/fax-send

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Request Parameters

Name	Type	Description
faxNumber	String	The receiptent fax number need to pass here. This parameter is required
faxData	Array	Array of attachment will be pass here. Allow pdf & image attachment only Required at least one attachment

Fax content

Fax content may be supplied via one or more files or URLs of supported filetypes.

file
Files may be included in the POST request as multipart/form-data parts

fileUrl
Give us any URL on the Internet (including ones with basic authentication), and we’ll pull it down and make it a fax. This might be useful to you if you’re using a web framework for templating and creating fancy fax files. Please note: If you are passing iFax a secure URL (starting with https://), make sure that your SSL certificate (including your intermediate cert, if you have one) is installed properly, valid, and up-to-date.

Response
A JSON object with status, message, and data attributes. The data attribute contains one element, jobId, which is the ID number of the fax.

Sample Request Postman reference

	              
	                {
	                  "faxNumber" : "+12345678901",
	                  "faxData" : [{
	                        "fileName" : "abc.pdf",
	                        "fileUrl" : "HTTP url of file"
	                      },
	                      {
	                        "fileName" : "xyz.pdf",
	                        "fileUrl" : "HTTP url of file"
	                  }]
	                }

Sample Response

	              
	                {
	                  "status": 1,
	                  "message": "Fax processed for sending",
	                  "data": {
	                            "jobId": 12345
	                          }
	                }

Restrictions

iFax places some restrictions on request files and page length in order to ensure timely processing of your faxes and to ensure a high transmission success rate.

The total request size for sending a fax may not exceed 20MB.
The total number of pages for any fax may not exceed 200 pages.
A maximum of 20 files may be submitted per fax.
A maximum of 15 recipients may be submitted per fax.

Send fax webhooks

This page documents the webhook format for sent faxes. See the webhooks introduction page for background information

Event Types

For sent faxes, there are currently three event types:

Fax Completed: This is a postflight webhook, triggered when the fax completes.

Fax Completed Webhook Parameters

Name	Type	Description
fax	Fax Object	The job's fax object.
event_type	String	fax_completed

Resend a fax

Method: Post

Path: https://api.ifaxapp.com/v1/customer/fax-resend

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Request Parameters

Name	Type	Description
jobId	Integer	It is the unique id generated when sending a fax. You will receive this from the Send Fax API response. This parameter is required

Sample Request Postman reference

	              
	                {
	                  "jobId" : 12345
	                }

Sample Response

	                {
	                  "status": 1,
	                  "message": "Fax processed for sending",
	                  "data": {
	                            "jobId": 12345
	                          }
	                }

Response

A JSON object with status, message, and data attributes. The data attribute contains one element, id, which is the ID number of the fax.

Restrictions

iFax can only resend faxes that have files stored on our platform. The resend operation will fail if you have long term file storage disabled or deleted files for a given fax.

Fax Status

Method: Post

Path: https://api.ifaxapp.com/v1/customer/fax-status

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The parameters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Request Parameters

Name	Type	Description
jobId	Integer	It is a unique id generated when sending a fax. You will receive this from the Send Fax API response. This parameter is required

Sample Request Postman reference

	              
	                {
	                  "jobId" : "12345",	                  
	                }

Sample Response

	          	{
	          	   "status": 1,
	          	   "message": "Fax status response",
	          	   "data": {
	          	   		"jobId": 12345,
	          	   		"fromNumber": "+441224515014",
	          	   		"toNumber": "+15065001844",
	          	   		"faxCallLength": 173,
	          	   		"faxCallStart": 1610966603 (UTC timestamp),
	          	   		"faxCallEnd": 1610966723 (UTC timestamp),
	          	   		"faxTotalPages": 20,
	          	   		"faxTransferredPages": 20,
	          	   		"faxStatus": "delivered",
	          	   		"message": "NORMAL_CLEARING",
	          	   		"code": 0
	          	   		}
	          	}

Delete fax

Method: Post

Path: https://api.ifaxapp.com/v1/customer/fax-delete

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Request Parameters

Name	Type	Description
jobId	Integer	It is a unique id generated when sending a fax. You will receive this from the Send Fax API response. This parameter is required

Sample Request Postman reference

	              
	                {
	                  "jobId" : "12345",	                  
	                }

Sample Response

	            {
	            	"status": 1,
	            	"message":"Fax deleted successfully"
	            }

Cancel fax

Method: Post

Path: https://api.ifaxapp.com/v1/customer/fax-cancel

Request Header

Name	Value	Description
Content-type	application/json	API response will be in json format. This header is required
Accept	application/json	The paramaters value should be passed in json format. This header is required
accessToken	API key	API key will be unique for all users. It is available in the settings page of your dashboard. This header is required

Request Parameters

Name	Type	Description
jobId	Integer	It is a unique id generated when sending a fax. You will receive this from the Send Fax API response. This parameter is required

Sample Request Postman reference

	                {
	                  "jobId" : "12345",	                  
	                }

Sample Response

	            {
	            	"status": 1,
	            	"message":"Fax canceled successfully"
	            }

Receive Faxes

Coming Soon

Billing

We thought it would be useful to let you know how our billing process works at the different stages of your API calls, so you can have more insight as to why and when your funds will be depleted.

Sending Faxes

When you make an API call to send a fax, we check your balance. If it’s too low for the price of the fax, the call results in an error and we stop the process. Otherwise, we queue the fax for sending.
Right before the fax is actually sent over the wire, we again check your balance. If it’s too low for the price of the fax, the call results in an error and we stop the process. Once your balance is high enough, we deduct the price of the fax (factoring in all of the recipients you’re sending to).
When the fax transmission process has ended, we check to see if any recipients did not receive the fax successfully (e.g. line busy, bad connection, etc.). We then credit your account the price of the fax for each recipient that encountered an error.

API Documentation

Introduction

HTTP Methods

Method Simulation

Authentication

HTTP Authentication

Formats

Objects

Fax Object

Webhooks

Specifying Webhook URLs

Specifying a Webhook Version

Enabling Inflight Webhooks

Retries

Fax Statuses

Error Messages

Send faxes

Send fax webhooks

Resend a fax

Fax Status

Delete fax

Cancel fax

Receive Faxes

Coming Soon

Billing