FAQ

Fax API — Integration Guide

IXICA · Developer FAQ

Fax API — Integration Guide

Send PDF faxes, check outbound delivery status and process inbound fax webhooks using the IXICA mysms API.

Base URL: https://api.mysms.ca
Fax is different from SMS: Use 10-digit North American numbers without +1. A 202 / FAX QUEUED response means the fax was queued; confirm delivery using the outbound status endpoint.

All numbers, IDs, file paths and download URLs in the examples are illustrative. Replace them with your own values before use. Keep real API keys and signed download links private.

API endpoints at a glance

Method Endpoint Purpose
POST https://api.mysms.ca/fax/send Submit a fax.
GET https://api.mysms.ca/fax/{fax_id} Read an outbound fax’s delivery status.
POST customer_fax_webhook_url IXICA posts inbound events to your configured URL.

1. How do I authenticate?

Include the API key issued to your account in the Authorization header. View and manage your key in the portal under Account Settings. Requests with a missing or invalid key are rejected.

Authorization: Bearer YOUR_API_KEY

2. What is required to send a fax?

Field Requirement
from Required. 10-digit North American sending number; no +1.
to Required. 10-digit North American destination number; no +1.
subject Optional. Up to 255 characters.
file / file_url Required: upload a PDF using multipart form data, or provide a PDF URL using JSON.

PDF only. The documented maximum is approximately 10 MB, configurable. Confirm your active limit with IXICA.

3. How do I upload a PDF?

POST https://api.mysms.ca/fax/send
Content-Type: multipart/form-data

Multipart fields

from=5145551212
to=5145550000
subject=Test fax
file=@/path/to/file.pdf;type=application/pdf

cURL

curl -X POST "https://api.mysms.ca/fax/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "from=5145551212" \
  -F "to=5145550000" \
  -F "subject=Test fax" \
  -F "file=@/path/to/file.pdf;type=application/pdf"

Replace the file path with your PDF’s local path. In this cURL example, -F creates the multipart request; let cURL set the Content-Type boundary.

4. How do I send a PDF by URL?

POST https://api.mysms.ca/fax/send
Content-Type: application/json

{
  "from": "5145551212",
  "to": "5145550000",
  "subject": "Test fax",
  "file_url": "https://example.com/sample.pdf"
}

cURL

curl -X POST "https://api.mysms.ca/fax/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "5145551212",
  "to": "5145550000",
  "subject": "Test fax",
  "file_url": "https://example.com/sample.pdf"
}'

The file_url must point to a PDF with content type application/pdf. The service must be able to retrieve the file.

5. What does the send response mean?

Queued — HTTP 202

{
  "success": true,
  "code": "202",
  "message": "FAX QUEUED",
  "data": {
    "fax_id": "12345",
    "from": "5145551212",
    "to": "5145550000",
    "pages": 1,
    "status": "pending"
  }
}

Store data.fax_id and use it to check status. The initial pending state is not a delivery confirmation.

Example error — HTTP 500

{
  "success": false,
  "code": "500",
  "message": "file_url must point to a PDF (application/pdf)"
}
Send code Meaning
500 Invalid API key, DID not assigned, API functionality not enabled on this DID, or a documented file-validation error. Read the response message to distinguish the cause.
202 FAX QUEUED — accepted for processing; check status for the final result.

6. How do I check outbound delivery status?

GET https://api.mysms.ca/fax/{fax_id}

Replace {fax_id} with data.fax_id returned by Send Fax. Use the same Bearer API key. Only outbound jobs are available; inbound history IDs return 404.

curl -X GET "https://api.mysms.ca/fax/12345" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Success — HTTP 200

{
  "success": true,
  "code": "200",
  "message": "OK",
  "data": {
    "fax_id": 12345,
    "direction": "outbound",
    "status": "pending",
    "from": "5145551212",
    "to": "5145550000",
    "subject": "Test fax",
    "pages": 1,
    "created_at": "2026-05-08T12:00:00+00:00",
    "updated_at": "2026-05-08T12:00:05+00:00",
    "completed_at": null
  }
}
Status Meaning
pending Queued or sent to the fax gateway; waiting for provider confirmation.
sent Provider reported success. Terminal state.
failed Provider reported failure. Terminal state.

completed_at is an ISO 8601 timestamp when the status becomes terminal (sent or failed). It remains null while in progress. Poll until a terminal state; the supplied documentation does not specify a polling interval or rate limit.

Status endpoint errors

HTTP When
401 Missing or invalid API key.
403 Valid key, but the fax belongs to another account.
404 Unknown fax_id, inbound/non-outbound fax, or invalid ID.
{
  "success": false,
  "code": "401",
  "message": "INVALID API KEY"
}
Send Fax and Fax Status use different documented error conventions. Do not assume an authentication error from /fax/send uses the status endpoint’s 401 code.

7. How do inbound fax webhooks work?

If a DID has customer_fax_webhook_url configured, an event is forwarded after a fax is successfully received. The request uses POST with Content-Type: application/json.

{
  "type": "fax.received",
  "fax_id": 12345,
  "from": "5145550000",
  "to": "5145551212",
  "pages": 2,
  "status": "received",
  "received_at": "2025-08-22T12:34:56Z",
  "media_url": "https://s3.amazonaws.com/bucket/faxes/2025/08/22/fax_12345.pdf?X-Amz-Signature=..."
}
Field Type Description
type string Always fax.received for inbound faxes.
fax_id integer Unique fax identifier.
from string Sender’s fax number, 10 digits.
to string Recipient’s fax number, 10 digits.
pages integer Number of pages.
status string received.
received_at string ISO 8601 receipt timestamp.
media_url string Signed AWS S3 download URL, valid for 24 hours.
Download within 24 hours. The media_url is a temporary signed AWS S3 URL that expires after 24 hours. Download or process the PDF promptly. The example URL is a placeholder, not a working download.

Failures to forward an event are logged; acknowledgement of the upstream webhook is not blocked. The supplied specification does not define customer-event retries or guaranteed redelivery.

8. How do I set customer_fax_webhook_url?

The specification states that this setting is configured per DID, but does not provide a configuration endpoint or portal procedure. Confirm the setup method with IXICA. Do not assume the SMS /webhook endpoint configures fax webhooks.

Troubleshooting checklist

  • Use 10-digit numbers, without +1, for both from and to.
  • Verify that the sending DID is assigned to your account and API functionality is enabled.
  • Check the Authorization Bearer key.
  • Send a PDF only and confirm the configured upload-size limit.
  • Save the returned fax ID; check sent or failed rather than relying on 202 alone.
  • For inbound fax, confirm the per-DID webhook URL and process the signed PDF link before expiry.
Source: fax API documentation supplied by IXICA for this FAQ. JSON examples checked for syntax and consistency. No live fax or API requests were sent. Webhook signatures, retry schedules and customer acknowledgement requirements are not specified in the supplied reference.

Share

Back to all FAQ answers