> This page is for SWML.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# send_fax

> Send a fax.

[statuscallbacks]: #statuscallbacks

Send a fax.

## **Properties**

**`send_fax`** `object` — required

An object that accepts the following properties.

---

**`send_fax.document`** `string` — required

URL to the PDF document to fax

---

**`send_fax.header_info`** `string`

Text to add to the fax header

---

**`send_fax.identity`** `string` — default: Calling party's caller ID number

Station identity to report

---

**`send_fax.status_url`** `string`

HTTP or HTTPS URL to deliver send fax status events. Learn more about [status callbacks][statuscallbacks].

---

## **Variables**

Set by the method:

* **send\_fax\_document:** (out) URL of sent document.
* **send\_fax\_identity:** (out) identity of this fax station.
* **send\_fax\_remote\_identity:** (out) identity of the receiving fax station.
* **send\_fax\_pages:** (out) number of pages sent.
* **send\_fax\_result\_code:** (out) fax status code.
* **send\_fax\_result\_text:** (out) description of fax status code.
* **send\_fax\_result:** (out) `success` | `failed`.

## **StatusCallbacks**

> **Status callbacks are advisory**
>
> Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don't gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see [Status callback reliability](/docs/platform/webhooks#status-callback-reliability).

A POST request will be sent to `status_url` with a JSON payload like the following:

**`event_type`** `string`

The type of event. Always `calling.call.fax` for this method.

---

**`event_channel`** `string`

The channel for the event, includes the SWML session ID.

---

**`timestamp`** `number`

Unix timestamp (float) when the event was generated.

---

**`project_id`** `string`

The project ID associated with the call.

---

**`space_id`** `string`

The Space ID associated with the call.

---

**`params`** `object`

An object containing fax-specific parameters.

---

**`params.call_id`** `string`

The call ID.

---

**`params.node_id`** `string`

The node handling the call.

---

**`params.control_id`** `string`

The control ID for this fax operation.

---

**`params.fax`** `object`

Fax result details.

---

**`fax.type`** `string`

The type of fax operation. Always `finished`.

---

**`fax.params.direction`** `string`

The direction of the fax (`send`).

---

**`fax.params.identity`** `string`

The identity of this fax station.

---

**`fax.params.remote_identity`** `string`

The identity of the receiving fax station.

---

**`fax.params.document`** `string`

URL of the sent fax document.

---

**`fax.params.pages`** `number`

Number of pages sent.

---

**`fax.params.success`** `boolean`

Whether the fax was sent successfully.

---

**`fax.params.result`** `number`

The numeric result code of the fax operation (e.g., `0` for success).

---

**`fax.params.result_text`** `string`

A description of the fax result (e.g., `OK`).

---

**`fax.params.format`** `string`

The format of the fax document. Always `"pdf"`.

---

#### Page progress events

A separate callback is sent for each page as the fax progresses:

**`fax.type`** `string`

Always `"page"` for page progress events.

---

**`fax.params.direction`** `string`

The direction of the fax.

---

**`fax.params.number`** `number`

The page number that was just processed.

---

### Raw JSON example

```json
{
  "event_type": "calling.call.fax",
  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp": 1640000000.123,
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "params": {
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "fax": {
      "type": "finished",
      "params": {
        "direction": "send",
        "identity": "+15551231234",
        "remote_identity": "+15553214321",
        "document": "https://example.com/fax_to_send.pdf",
        "pages": 3,
        "success": true,
        "result": 0,
        "result_text": "OK",
        "format": "pdf"
      }
    }
  }
}
```

---

## **Examples**

### Send a fax and post a result to a webhook

#### YAML

```yaml
version: 1.0.0
sections:
  main:
    - send_fax:
        document: https://example.com/fax_to_send.pdf
    - execute:
        dest: 'https://example.com/handle_outgoing_fax_result'
```

#### JSON

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "send_fax": {
          "document": "https://example.com/fax_to_send.pdf"
        }
      },
      {
        "execute": {
          "dest": "https://example.com/handle_outgoing_fax_result"
        }
      }
    ]
  }
}
```