> ## Documentation Index
> Fetch the complete documentation index at: https://support.amplify.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Api doc

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

<Warning>
  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).
</Warning>

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

```bash theme={null}
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:

```bash theme={null}
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

<CodeGroup>
  ```bash cURL theme={null}
  curl 'https://api.ifaxapp.com/v1/customer/fax-send' \
    -H 'accessToken:YOUR_API_KEY' \
    -H 'Content-Type: application/json'
  ```

  ```python Python theme={null}
  import requests

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

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

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

***

## 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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CodeGroup>
  ```json JSON theme={null}
  {
    "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"]
      }
    ]
  }
  ```

  ```bash cURL theme={null}
  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"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

### Sample Response

```json theme={null}
{
  "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

<CodeGroup>
  ```json JSON theme={null}
  {
    "jobId": 12345
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.ifaxapp.com/v1/customer/fax-cancel \
    -H 'accessToken: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"jobId": 12345}'
  ```
</CodeGroup>

### Sample Response

```json theme={null}
{
  "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

<CodeGroup>
  ```json JSON theme={null}
  {
    "jobId": 12345,
    "faxNumber": "+19876543210"
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.ifaxapp.com/v1/customer/fax-resend \
    -H 'accessToken: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"jobId": 12345}'
  ```
</CodeGroup>

### Sample Response

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```python theme={null}
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

<Info>
  **Always use file URLs over base64 encoding** for better performance and lower bandwidth usage.
</Info>

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

***

## Support

For additional help, contact support at:

* **Email:** [support@ifaxapp.com](mailto:support@ifaxapp.com)
* **Website:** [https://ifaxapp.com/support](https://ifaxapp.com/support)