iFax API Documentation

All calls to the iFax API should be made to https://api.ifaxapp.com/v1, which remains current with the latest minor updates.

Getting Your API Key

You can find your API key on the Settings page of your dashboard.

If you make an API call with a Live key, your balance will decrease if you perform operations that cost money (e.g., sending a fax).

All iFax API responses are formatted in JSON.

HTTP Methods

Since our API is RESTful, each API call requires a specific HTTP method to indicate the type of operation to be performed.

Standard HTTP Methods

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

Method Simulation

Some HTTP clients don’t support all HTTP methods. Use the POST method with the _method parameter:

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

Authentication

Most API calls require authentication via the accessToken header.

HTTP Authentication

curl 'https://api.ifaxapp.com/v1/customer/fax-send' \
  -H 'accessToken:YOUR_API_KEY' \
  -H 'Content-Type: application/json'

import requests

headers = {
    'accessToken': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.post('https://api.ifaxapp.com/v1/customer/fax-send', headers=headers)

const options = {
  method: 'POST',
  headers: {
    'accessToken': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

fetch('https://api.ifaxapp.com/v1/customer/fax-send', options)
  .then(response => response.json())
  .then(data => console.log(data));

Data Formats

All API calls return JSON responses by default.

API Objects

Fax Object

The fax object represents a fax job in the iFax system.

Field	Type	Description
`jobId`	integer	A unique ID generated for each fax sent through the API
`fromNumber`	string	The number (E.164 format) the fax was sent from
`toNumber`	string	The number (E.164 format) that received the fax
`faxCallLength`	integer	Total time spent in seconds from API call to fax end
`faxCallStart`	integer	Unix timestamp when the initial API call was made
`faxCallEnd`	integer	Unix timestamp when fax processing ended
`faxTotalPages`	integer	Total number of pages in the fax
`faxTransferredPages`	integer	Number of pages successfully sent and received
`faxStatus`	string	Status of fax: `sending`, `delivered`, `canceled`, `failed`
`message`	string	Detailed description of fax status or error
`code`	integer	Numeric code for fax status or error
`direction`	string	Direction of fax: `sent` or `received`

Example Fax Object:

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

Webhooks

Webhooks allow iFax to update you in real-time about the status of your faxes.

Specifying Webhook URLs

Provide a valid webhook URL on your webhook settings page, e.g., https://www.example.com/ifax_webhook.

Postflight Webhooks

Postflight webhooks are triggered when a fax completes, regardless of success.

Webhook Retries

If a webhook fails, it will automatically retry up to 5 times with exponential backoff:

Retry Number	Backoff Time
1	5 minutes
2	10 minutes
3	20 minutes
4	30 minutes
5	60 minutes

Fax Statuses

Status	Description
`sending`	Currently sending/communicating with the recipient machine
`delivered`	Successfully sent and received by recipient machine
`canceled`	Fax has been cancelled successfully
`failed`	System failed to send fax; see error codes for more information

Error Codes & Messages

Error Code	Message
0	Success
-3001	Invalid fax number
-3002	Insufficient account balance
-3003	Image does not exist
-3004	TIFF file is empty
-3005	File size exceeds maximum limit
-3006	Invalid file format
-3007	No permission for this action (user is not Primary)
-3008	Recipient limit exceeded
-3009	Invalid API key
-3010	Rate limit exceeded

Send Fax

Endpoint: POST /customer/fax-send Base URL: https://api.ifaxapp.com/v1

Request Headers

Header	Value	Description
`Content-Type`	`application/json`	Request format (required)
`Accept`	`application/json`	Response format (required)
`accessToken`	Your API Key	Authentication (required)

Request Parameters

Parameter	Type	Required	Description
`faxNumber`	string	Yes	Recipient fax number (E.164 format: +1234567890)
`callerId`	string	No	Caller ID as From number
`templateId`	string	No	Template ID from Webapp
`smartDocumentId`	string	No	Smart document ID from Webapp
`subject`	string	No	Subject on cover page
`from_name`	string	No	Sender Name on cover page
`to_name`	string	No	Recipient Name on cover page
`message`	string	No	Comment on cover page
`send_at`	string	No	UTC date/time to schedule delivery (ISO 8601 format)
`faxQuality`	string	No	Fax quality: `Low`, `Standard` (default), or `HD`
`faxData`	array	Yes	Array of file attachments (at least one required)

Fax Data Array

Each item in faxData should include:

{
  "fileName": "string - File name",
  "fileUrl": "string - HTTP/HTTPS accessible URL (preferred)",
  "fileData": "string - Base64 encoded file data",
  "pages": ["array - Page selection e.g. 1-5, 2, 1-10"]
}

Sample Request

{
  "faxNumber": "+12345678901",
  "callerId": "+12345678901",
  "templateId": "0000",
  "smartDocumentId": "0000",
  "subject": "test subject",
  "from_name": "abc",
  "to_name": "xyz",
  "message": "sample fax",
  "send_at": "2019-11-14T00:55:31.820Z",
  "faxQuality": "Standard",
  "faxData": [
    {
      "fileName": "abc.pdf",
      "fileUrl": "https://example.com/document.pdf",
      "pages": ["1-5", "2", "1-10"]
    },
    {
      "fileName": "xyz.pdf",
      "fileData": "JVBERi0xLjQKJ...base64encodedcontent...",
      "pages": ["1", "2"]
    }
  ]
}

curl -X POST https://api.ifaxapp.com/v1/customer/fax-send \
  -H 'accessToken: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "faxNumber": "+12345678901",
    "callerId": "+12345678901",
    "subject": "test subject",
    "from_name": "abc",
    "to_name": "xyz",
    "message": "sample fax",
    "faxQuality": "Standard",
    "faxData": [
      {
        "fileName": "document.pdf",
        "fileUrl": "https://example.com/document.pdf"
      }
    ]
  }'

import requests
import json

url = 'https://api.ifaxapp.com/v1/customer/fax-send'
headers = {
    'accessToken': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    "faxNumber": "+12345678901",
    "callerId": "+12345678901",
    "subject": "test subject",
    "from_name": "abc",
    "to_name": "xyz",
    "faxQuality": "Standard",
    "faxData": [
        {
            "fileName": "document.pdf",
            "fileUrl": "https://example.com/document.pdf"
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Sample Response

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

Request Restrictions

Limit	Value
Max request size	20MB
Max pages per fax	200
Max files per fax	20
Max recipients per fax	15

Cancel Scheduled Fax

Endpoint: POST /customer/fax-cancel Cancel a fax that has been scheduled for future delivery.

Request Parameters

Parameter	Type	Required	Description
`jobId`	integer	Yes	The unique ID of the fax job to cancel

Sample Request

{
  "jobId": 12345
}

curl -X POST https://api.ifaxapp.com/v1/customer/fax-cancel \
  -H 'accessToken: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"jobId": 12345}'

Sample Response

{
  "status": 1,
  "message": "Fax job 12345 has been cancelled",
  "data": {
    "jobId": 12345,
    "faxStatus": "canceled"
  }
}

Resend Fax

Endpoint: POST /customer/fax-resend Resend a previously sent fax.

Request Parameters

Parameter	Type	Required	Description
`jobId`	integer	Yes	The unique ID of the original fax job
`faxNumber`	string	No	New recipient number (if different)

Sample Request

{
  "jobId": 12345,
  "faxNumber": "+19876543210"
}

curl -X POST https://api.ifaxapp.com/v1/customer/fax-resend \
  -H 'accessToken: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"jobId": 12345}'

Sample Response

{
  "status": 1,
  "message": "Fax resent successfully",
  "data": {
    "jobId": 12346,
    "originalJobId": 12345
  }
}

Fax Webhook Events

Webhook URL: Configured in your dashboard settings

Webhook Payload

When a fax completes, iFax sends a POST request to your webhook URL with the following payload:

{
  "event": "fax.completed",
  "timestamp": 1610966723,
  "data": {
    "jobId": 12345,
    "fromNumber": "+441224515014",
    "toNumber": "+15065001844",
    "faxCallLength": 173,
    "faxCallStart": 1610966603,
    "faxCallEnd": 1610966723,
    "faxTotalPages": 20,
    "faxTransferredPages": 20,
    "faxStatus": "delivered",
    "message": "NORMAL_CLEARING",
    "code": 0
  }
}

Webhook Security

Always verify the webhook signature to ensure the request came from iFax. The signature is sent in the X-iFax-Signature header.

import hmac
import hashlib

def verify_webhook(body, signature, webhook_secret):
    expected_signature = hmac.new(
        webhook_secret.encode(),
        body.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected_signature)

Rate Limiting

iFax API implements rate limiting to ensure fair usage:

Limit	Value
Requests per hour	1000
Concurrent requests	20
Burst capacity	50

If you exceed rate limits, you’ll receive a 429 Too Many Requests response.

Response Codes

Code	Meaning	HTTP Status
1	Success	200 OK
0	Fax processing started	200 OK
-1	General error	400 Bad Request
-2	Invalid parameters	400 Bad Request
-3	Authentication failed	401 Unauthorized
-4	Insufficient balance	402 Payment Required
-5	Resource not found	404 Not Found

Best Practices

Always use file URLs over base64 encoding for better performance and lower bandwidth usage.

Error Handling - Implement proper error handling and retry logic
Webhooks - Always verify webhook signatures before processing
Rate Limiting - Implement backoff strategies when approaching rate limits
Scheduling - Use send_at parameter to batch faxes during off-peak hours
File URLs - Provide publicly accessible HTTP/HTTPS URLs instead of base64 data
Monitoring - Log all API calls for debugging and auditing purposes

Support

For additional help, contact support at:

Email: support@ifaxapp.com
Website: https://ifaxapp.com/support

​iFax API Documentation

​Getting Your API Key

​HTTP Methods

​Standard HTTP Methods

​Method Simulation

​Authentication

​HTTP Authentication

​Data Formats

​API Objects

​Fax Object

​Webhooks

​Specifying Webhook URLs

​Postflight Webhooks

​Webhook Retries

​Fax Statuses

​Error Codes & Messages

​Send Fax

​Request Headers

​Request Parameters

​Fax Data Array

​Sample Request

​Sample Response

​Request Restrictions

​Cancel Scheduled Fax

​Request Parameters

​Sample Request

​Sample Response

​Resend Fax

​Request Parameters

​Sample Request

​Sample Response

​Fax Webhook Events

​Webhook Payload

​Webhook Security

​Rate Limiting

​Response Codes

​Best Practices

​Support

iFax API Documentation

Getting Your API Key

HTTP Methods

Standard HTTP Methods

Method Simulation

Authentication

HTTP Authentication

Data Formats

API Objects

Fax Object

Webhooks

Specifying Webhook URLs

Postflight Webhooks

Webhook Retries

Fax Statuses

Error Codes & Messages

Send Fax

Request Headers

Request Parameters

Fax Data Array

Sample Request

Sample Response

Request Restrictions

Cancel Scheduled Fax

Request Parameters

Sample Request

Sample Response

Resend Fax

Request Parameters

Sample Request

Sample Response

Fax Webhook Events

Webhook Payload

Webhook Security

Rate Limiting

Response Codes

Best Practices

Support