API Documentation - Pharmique Fax

Fax API v1

Programmatic access to send and receive faxes. All endpoints require Bearer token authentication.

Base URL: Loading...

Authentication

All API requests require a Bearer token in the Authorization header.

Tokens are created by an admin from the Admin page.

Request Header

Authorization: Bearer faxapi_your_token_here

Scopes

Scope	Description
`fax:read`	Read access to fax data and files
`fax:send`	Permission to send faxes via the API
`fax:all:read`	Full read access (bypasses scope checks)

Endpoints

GET /api/v1/faxes

List incoming faxes with pagination and filtering.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`from`	string	—	Filter by sender number (partial match)
`status`	string	—	Filter by status (e.g., `received`)
`date_from`	ISO 8601	—	Filter faxes received after this date
`date_to`	ISO 8601	—	Filter faxes received before this date
`downloaded`	string	—	`true` or `false` — filter by download status for your API token

Example Request

curl

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:7000/api/v1/faxes?page=1&limit=10"

Example Response

200 OK

{
  "data": {
    "faxes": [
      {
        "id": "ac62b6e2-2acc-474c-9f5c-ad6f712130e8",
        "from": "+18772333839",
        "to": "+14079747020",
        "pages": "1",
        "status": "received",
        "remote_station_id": "877-233-3839",
        "received_at": "2026-02-10T08:13:48.308Z",
        "file_size": 8952,
        "has_tiff": true,
        "tiff_file_size": 12480,
        "downloaded": false,
        "downloaded_at": null
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "total_pages": 5
  }
}

GET /api/v1/faxes/:id

Get detailed information about a specific fax.

Path Parameters

Parameter	Type	Description
`id`	string	Fax ID (SignalWire FaxSid)

Example Request

curl

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:7000/api/v1/faxes/ac62b6e2-..."

Example Response

200 OK

{
  "data": {
    "id": "ac62b6e2-2acc-474c-9f5c-ad6f712130e8",
    "from": "+18772333839",
    "to": "+14079747020",
    "pages": "1",
    "status": "received",
    "remote_station_id": "877-233-3839",
    "received_at": "2026-02-10T08:13:48.308Z",
    "media_url": "https://files.signalwire.com/...",
    "file_size": 8952,
    "filename": "fax_+18772333839_2026-02-10T08-13-47-802Z.pdf",
    "has_tiff": true,
    "tiff_filename": "fax_+18772333839_2026-02-10T08-13-47-802Z.tiff",
    "tiff_converted_at": "2026-02-10T08:14:02.000Z",
    "tiff_file_size": 12480,
    "downloaded": false,
    "downloaded_at": null
  }
}

GET /api/v1/faxes/:id/download

Download the fax file in PDF (original) or TIFF format. Automatically marks the fax as downloaded for the requesting API token.

Query Parameters

Parameter	Type	Default	Description
`format`	string	`original`	`original` for PDF, `tiff` for converted TIFF

Example Requests

Download PDF

curl -H "Authorization: Bearer YOUR_TOKEN" \
  -o fax.pdf \
  "http://localhost:7000/api/v1/faxes/ID/download"

Download TIFF

curl -H "Authorization: Bearer YOUR_TOKEN" \
  -o fax.tiff \
  "http://localhost:7000/api/v1/faxes/ID/download?format=tiff"

PATCH /api/v1/faxes/:id/downloaded

Mark a fax as downloaded without downloading the file. Useful when a fax was processed through other means. Requires fax:read scope.

Path Parameters

Parameter	Type	Description
`id`	string	Fax ID

Example Request

curl

curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:7000/api/v1/faxes/ac62b6e2-.../downloaded"

Example Response

200 OK

{
  "data": {
    "id": "ac62b6e2-2acc-474c-9f5c-ad6f712130e8",
    "downloaded": true,
    "downloaded_at": "2026-02-15T12:00:00"
  }
}

DELETE /api/v1/faxes/:id/downloaded

Reset the downloaded flag for a fax, allowing it to appear in ?downloaded=false queries again. Requires fax:read scope.

Path Parameters

Parameter	Type	Description
`id`	string	Fax ID

Example Request

curl

curl -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:7000/api/v1/faxes/ac62b6e2-.../downloaded"

Example Response

200 OK

{
  "data": {
    "id": "ac62b6e2-2acc-474c-9f5c-ad6f712130e8",
    "downloaded": false,
    "downloaded_at": null
  }
}

POST /api/v1/faxes/send

Send a fax. Requires fax:send scope.

Request Body (JSON)

Field	Type	Required	Description
`to`	string	Yes	Recipient phone number in E.164 format (e.g., `+14155551234`)
`media_url`	string	*	URL of the PDF to fax. Required if not uploading a file.

Alternative: Send as multipart/form-data with a file field (PDF, max 10 MB) instead of media_url.

Example Request (JSON)

curl

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "media_url": "https://example.com/document.pdf"}' \
  "http://localhost:7000/api/v1/faxes/send"

Example Request (File Upload)

curl

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "to=+14155551234" \
  -F "file=@/path/to/document.pdf" \
  "http://localhost:7000/api/v1/faxes/send"

Example Response

200 OK

{
  "success": true,
  "fax": {
    "sid": "FX1234567890abcdef",
    "to": "+14155551234",
    "media_url": "https://example.com/document.pdf",
    "status": "queued"
  }
}

GET /api/v1/faxes/sent

List sent (outbound) faxes with pagination and filtering.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`to`	string	—	Filter by recipient number (partial match)
`status`	string	—	Filter by status (e.g., `queued`, `delivered`)
`date_from`	ISO 8601	—	Filter faxes sent after this date
`date_to`	ISO 8601	—	Filter faxes sent before this date

Example Request

curl

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "http://localhost:7000/api/v1/faxes/sent?page=1&limit=10"

Example Response

200 OK

{
  "data": {
    "faxes": [
      {
        "sid": "FX1234567890abcdef",
        "to": "+14155551234",
        "media_url": "https://fax.pharmique.net/uploads/abc123",
        "original_filename": "invoice.pdf",
        "status": "delivered",
        "pages": "2",
        "error_code": null,
        "error_message": null,
        "sent_at": "2026-02-10T15:30:00.000Z",
        "updated_at": "2026-02-10T15:32:00.000Z"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "total_pages": 1
  }
}

Download Tracking

The API tracks which faxes have been downloaded, independently per API token. This allows each vendor to manage their own processing workflow.

Behavior	Details
Per-token tracking	Each API token has its own independent download status. Token A marking a fax as downloaded does not affect Token B.
Auto-mark on download	Downloading a fax via `GET /faxes/:id/download` automatically marks it as downloaded for the requesting token.
Poll for new faxes	Use `GET /faxes?downloaded=false` to retrieve only faxes that haven't been downloaded yet.
Manual mark/unmark	Use `PATCH /faxes/:id/downloaded` to mark without downloading. Use `DELETE /faxes/:id/downloaded` to reset the flag.

Pagination

List endpoints return paginated results. Use page and limit query parameters to navigate.

Pagination Object

{
  "pagination": {
    "page": 1,        // Current page number
    "limit": 20,      // Items per page
    "total": 42,      // Total matching items
    "total_pages": 3  // Total number of pages
  }
}

Error Codes

Status	Error	Description
`400`	bad_request	Invalid request parameters
`401`	unauthorized	Missing or invalid Bearer token
`403`	forbidden	Token lacks required scope
`404`	not_found	Fax or file not found
`429`	too_many_requests	Rate limit exceeded (100 req / 15 min)
`500`	internal_error	Server error

Error Response Format

{
  "error": "unauthorized",
  "message": "Bearer token required in Authorization header"
}

Rate Limiting

The API allows 100 requests per 15-minute window per IP address.

Rate limit headers are included in responses:

Header	Description
`RateLimit-Limit`	Maximum requests per window
`RateLimit-Remaining`	Requests remaining in current window
`RateLimit-Reset`	Seconds until the window resets

Try It

Test the API directly from this page.

API Token