FAQ
Fax API — Integration Guide
Fax API — Integration Guide
Send PDF faxes, check outbound delivery status and process inbound fax webhooks using the IXICA mysms API.
https://api.mysms.caAll 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/sendContent-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/sendContent-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"
}
/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. |
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.
Share
