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.
	          		{
	          	   		"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

Post
https://api.ifaxapp.com/v1/customer/fax-send
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
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 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.

	              
	                {
	                  "faxNumber" : "+12345678901",
	                  "faxData" : [{
	                        "fileName" : "abc.pdf",
	                        "fileUrl" : "HTTP url of file"
	                      },
	                      {
	                        "fileName" : "xyz.pdf",
	                        "fileUrl" : "HTTP url of file"
	                  }]
	                }
	              
	            
	              
	                {
	                  "status": 1,
	                  "message": "Fax processed for sending",
	                  "data": {
	                            "jobId": 12345
	                          }
	                }
	              
	            

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

For sent faxes, there are currently three event types:

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

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

Resend a fax

Post
https://api.ifaxapp.com/v1/customer/fax-resend
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
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
	              
	                {
	                  "jobId" : 12345
	                }
	              
	            
	                {
	                  "status": 1,
	                  "message": "Fax processed for sending",
	                  "data": {
	                            "jobId": 12345
	                          }
	                }
	            

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

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

Post
https://api.ifaxapp.com/v1/customer/fax-status
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
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
	              
	                {
	                  "jobId" : "12345",	                  
	                }
	              
	            
	          	{
	          	   "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

Post
https://api.ifaxapp.com/v1/customer/fax-delete
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
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
	              
	                {
	                  "jobId" : "12345",	                  
	                }
	              
	            
	            {
	            	"status": 1,
	            	"message":"Fax deleted successfully"
	            }
	        	

Cancel fax

Post
https://api.ifaxapp.com/v1/customer/fax-cancel
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
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
	                {
	                  "jobId" : "12345",	                  
	                }
	            
	            {
	            	"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.

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