***

id: 594d3f6e-f2a7-4b09-9060-026d7287f01d
title: receive\_fax
slug: /reference/receive-fax
description: Receive a fax being delivered to this call.
max-toc-depth: 3
----------------

[statuscallbacks]: #statuscallbacks

Receive a fax being delivered to this call.

## **Properties**

<ParamField path="receive_fax" type="object" required={true} toc={true}>
  An object that accepts the following properties.
</ParamField>

<Indent>
  <ParamField path="receive_fax.status_url" type="string" toc={true}>
    HTTP or HTTPS URL to deliver receive fax status events. Learn more about [status callbacks][statuscallbacks].
  </ParamField>
</Indent>

## **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**

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

<ParamField path="event_type" type="string" toc={true}>
  The type of event. Always `calling.call.fax` for this method.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing fax-specific parameters.
</ParamField>

<Indent>
  <ParamField path="params.call_id" type="string" toc={true}>
    The call ID.
  </ParamField>

  <ParamField path="params.node_id" type="string" toc={true}>
    The node handling the call.
  </ParamField>

  <ParamField path="params.control_id" type="string" toc={true}>
    The control ID for this fax operation.
  </ParamField>

  <ParamField path="params.fax" type="object" toc={true}>
    Fax result details.
  </ParamField>

  <Indent>
    <ParamField path="fax.type" type="string" toc={true}>
      The type of fax operation. Always `finished`.
    </ParamField>

    <ParamField path="fax.params.direction" type="string" toc={true}>
      The direction of the fax (`receive`).
    </ParamField>

    <ParamField path="fax.params.identity" type="string" toc={true}>
      The identity of this fax station.
    </ParamField>

    <ParamField path="fax.params.remote_identity" type="string" toc={true}>
      The identity of the sending fax station.
    </ParamField>

    <ParamField path="fax.params.document" type="string" toc={true}>
      URL of the received fax document.
    </ParamField>

    <ParamField path="fax.params.pages" type="number" toc={true}>
      Number of pages received.
    </ParamField>

    <ParamField path="fax.params.success" type="boolean" toc={true}>
      Whether the fax was received successfully.
    </ParamField>

    <ParamField path="fax.params.result" type="number" toc={true}>
      The numeric result code of the fax operation (e.g., `0` for success).
    </ParamField>

    <ParamField path="fax.params.result_text" type="string" toc={true}>
      A description of the fax result (e.g., `OK`).
    </ParamField>

    <ParamField path="fax.params.format" type="string" toc={true}>
      The format of the fax document. Always `"pdf"`.
    </ParamField>
  </Indent>
</Indent>

#### Page progress events

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

<ParamField path="fax.type" type="string" toc={true}>
  Always `"page"` for page progress events.
</ParamField>

<ParamField path="fax.params.direction" type="string" toc={true}>
  The direction of the fax.
</ParamField>

<ParamField path="fax.params.number" type="number" toc={true}>
  The page number that was just processed.
</ParamField>

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

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

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

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/execute) statement's documentation for more details on this behavior.