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

# receive_fax

> Receive a fax being delivered to this call.

[statuscallbacks]: #statuscallbacks

Receive a fax being delivered to this call.

## **Properties**

**`receive_fax`** `object` — required

An object that accepts the following properties.

---

**`receive_fax.status_url`** `string`

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

---

## **Variables**

Set by the method:

* **receive\_fax\_document:** (out) URL of received document.
* **receive\_fax\_identity:** (out) identity of this fax station.
* **receive\_fax\_remote\_identity:** (out) identity of the sending fax station.
* **receive\_fax\_pages:** (out) number of pages received.
* **receive\_fax\_result\_code:** (out) fax status code.
* **receive\_fax\_result\_text:** (out) description of fax status code.
* **receive\_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 (`receive`).

---

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

The identity of this fax station.

---

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

The identity of the sending fax station.

---

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

URL of the received fax document.

---

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

Number of pages received.

---

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

Whether the fax was received 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": "receive",
        "identity": "+15551231234",
        "remote_identity": "+15553214321",
        "document": "https://your-space.signalwire.com/api/v1/faxes/fax-uuid/download",
        "pages": 3,
        "success": true,
        "result": 0,
        "result_text": "OK",
        "format": "pdf"
      }
    }
  }
}
```

---

## **Examples**

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

#### YAML

```yaml
version: 1.0.0
sections:
  main:
    - receive_fax: {}
    - execute:
        dest: 'https://<NGROK UUID>.ngrok-free.app'
```

#### JSON

```json
{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "receive_fax": {}
      },
      {
        "execute": {
          "dest": "https://<NGROK UUID>.ngrok-free.app"
        }
      }
    ]
  }
}
```

In this example, when a fax is received, a POST request will be sent to the URL with all
the fax related variables (like `receive_fax_document`) already set.
Refer to the [`execute`](/docs/swml/reference/calling/execute) statement's documentation for more details on this behavior.

> Receive a fax being delivered to this call.