---
title: "Send Contracts From Salesforce Flow"
description: "Send a SignatureAPI contract when an opportunity reaches a stage with a Flow HTTP Callout, and read the result back with a scheduled flow."
canonical: "https://signatureapi.com/docs/integrations/salesforce"
source: "https://signatureapi.com/docs/integrations/salesforce.md"
last_verified_api_version: "1.18.0"
---

# Send Contracts From Salesforce Flow

Send a SignatureAPI contract when an opportunity reaches a stage with a Flow HTTP Callout, and read the result back with a scheduled flow.

_Last verified against API version 1.18.0._

Salesforce Flow calls the SignatureAPI REST API with its own **HTTP Callout** action. An external credential holds the key, a named credential holds the URL, a record-triggered flow sends the envelope when an opportunity reaches a stage, and a scheduled flow reads the result. No Apex and no SignatureAPI package are needed.

## Before you start

- A SignatureAPI [test API key](https://signatureapi.com/docs/api/test-mode) (it starts with `key_test_`).
- The document you send, at a URL on a [supported host](https://signatureapi.com/docs/api/resources/documents/url#external-store), or [uploaded to SignatureAPI](https://signatureapi.com/docs/api/resources/uploads/create) first. The examples use a sample PDF.
- Two custom fields on **Opportunity**: a text field for the envelope id and a text field for the signing status.

## Send the envelope

1. **Create the external credential**

   In Setup, create an external credential named `SignatureAPI` and set its **Authentication Protocol** to **Custom**. Under **Principals**, add a principal with an authentication parameter named `ApiKey` whose value is your key. Salesforce stores authentication parameters encrypted and recommends keeping API keys there ([Use API Keys in Custom Headers](https://help.salesforce.com/s/articleView?id=xcloud.nc_custom_headers_and_api_keys.htm\&type=5)).

2. **Give users access to the principal**

   Open a permission set, and under **External Credential Principal Access** add the principal you created, as in Salesforce's [Trailhead project](https://trailhead.salesforce.com/content/learn/projects/quick-start-create-http-callouts-with-flow-builder/create-the-credentials). Assign the permission set to the users that run the flows. The schedule-triggered flow below runs as the Default Workflow User, so include that user.

3. **Send the key in a custom header**

   On the external credential, under **Custom Headers**, add a header named `X-API-Key` with the value `{!$Credential.SignatureAPI.ApiKey}`. The formula reads the encrypted parameter at callout time, so the key never appears in the header settings.

4. **Create the named credential**

   Create a named credential with the URL `https://api.signatureapi.com` and select your external credential. Turn on **Allow Formulas in HTTP Header** so the header formula is evaluated, and turn off **Generate Authorization Header**, as Salesforce's article does, so the callout sends your custom header instead of a generated one.

5. **Create the HTTP Callout action**

   In Flow Builder, add an **Action** element and click **Create HTTP Callout**. Select your named credential, set the method to **POST** and the URL path to `/v1/envelopes`. Paste the request body below as the sample request and provide a sample response, as in the [Trailhead walkthrough](https://trailhead.salesforce.com/content/learn/projects/quick-start-create-http-callouts-with-flow-builder/build-the-http-callout-flow) and [Salesforce's guide](https://admin.salesforce.com/blog/2023/integrations-are-easier-than-ever-with-flow-http-callouts). Flow turns both into a data structure.

6. **Call it from a record-triggered flow**

   Create a record-triggered flow on **Opportunity** that runs when the stage changes to your contract stage. A record-triggered flow can't call out on its immediate path, so [include a Run Asynchronously path](https://admin.salesforce.com/blog/2023/automate-this-how-to-build-well-architected-automation) and put the action there. Map the signer's name and email and the opportunity id into the request, then store the response `id` in the envelope id field.

Salesforce HTTP request step settings for the "Opportunity contract" request:

1. **Method**: POST
2. **URL**: `/v1/envelopes`

   Relative to `https://api.signatureapi.com`. The base URL and the API key come from the setup in the steps above.
3. **Sample request (JSON)**:

   ```json
   {
     "title": "Service Agreement - Acme Corp",
     "message": "Please review and sign the service agreement for your order.",
     "metadata": {
       "source": "salesforce",
       "opportunity_id": "006Dn00000A1b2CIAR"
     },
     "topics": [
       "no_code",
       "salesforce"
     ],
     "documents": [
       {
         "key": "service_agreement",
         "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
         "format": "pdf",
         "fixed_positions": [
           {
             "place_key": "signer_signature",
             "page": 1,
             "top": 172,
             "left": 210
           }
         ],
         "places": [
           {
             "key": "signer_signature",
             "type": "signature",
             "recipient_key": "signer"
           }
         ]
       }
     ],
     "recipients": [
       {
         "type": "signer",
         "key": "signer",
         "name": "Jane Doe",
         "email": "jane.doe@example.com"
       }
     ]
   }
   ```

Setting names as in the [Salesforce documentation](https://trailhead.salesforce.com/content/learn/projects/quick-start-create-http-callouts-with-flow-builder/build-the-http-callout-flow).

The opportunity's envelope id field links it to the envelope, and `metadata.opportunity_id` links the envelope back to the opportunity.

## Get the result back

Flow has no trigger for an incoming webhook, so check the open opportunities on a schedule instead. Each run reads the envelope of every opportunity that is still waiting, so no envelope is missed however many are open.

1. **Create a GET callout**

   Create a second HTTP Callout on the same named credential with the method **GET** and the URL path `/v1/envelopes/{envelope_id}`. Salesforce turns a name in curly brackets into a path variable that the flow fills in each time it calls the action ([Configure an HTTP Callout Action](https://help.salesforce.com/s/articleView?id=sf.flow_http_callout_configure.htm\&type=5)).

2. **Run the flow for each waiting opportunity**

   Create a [schedule-triggered flow](https://trailhead.salesforce.com/content/learn/modules/autolaunched-scheduled-flows/schedule-a-flow) with a start date, a start time and a daily or weekly frequency. In its Start element, click **Choose Object**, select **Opportunity**, and set criteria: the envelope id field is not blank, and the signing status field is not `completed`, `canceled` or `failed`. The flow finds every matching opportunity on each run and makes it available as `$Record`. A schedule-triggered flow needs a Default Workflow User, set under **Process Automation Settings** in Setup.

3. **Read the envelope**

   Call the GET action with `envelope_id` set to the opportunity's envelope id field:

   Salesforce HTTP request step settings for the "Completed envelope" request:

   1. **Method**: GET
   2. **URL**: `/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`

      Relative to `https://api.signatureapi.com`. The base URL and the API key come from the setup in the steps above.

   The flow reads with your key, so it can only read envelopes in your account.

4. **Update the opportunity**

   Set the signing status field to the envelope's `status`. When `status` is `completed`, check `deliverable.status`: when it is `generated`, `deliverable.url` downloads the signed PDF and expires after an hour, so fetch it in the same run. If it is still `pending` or `processing`, leave the status field unchanged, and the next run reads the envelope again. See the [deliverable lifecycle](https://signatureapi.com/docs/api/resources/deliverables/lifecycle). If your account uses [authenticated deliverable URLs](https://signatureapi.com/docs/api/resources/deliverables/object#url), send your API key with the download.

## Related

- [Create an envelope](https://signatureapi.com/docs/api/resources/envelopes/create): every field of the request body.
- [Organize with topics and metadata](https://signatureapi.com/docs/api/guides/how-to/organize-topics-metadata).
- [Make](https://signatureapi.com/docs/integrations/make), [Zapier](https://signatureapi.com/docs/integrations/zapier/http-recipe) and [n8n](https://signatureapi.com/docs/integrations/n8n) can receive webhooks if you want events in real time.

### Example: Opportunity contract

Sent from a Salesforce flow for one opportunity.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement - Acme Corp",
  "message": "Please review and sign the service agreement for your order.",
  "metadata": {
    "source": "salesforce",
    "opportunity_id": "006Dn00000A1b2CIAR"
  },
  "topics": [
    "no_code",
    "salesforce"
  ],
  "documents": [
    {
      "key": "service_agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "signer_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "signer",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Service Agreement - Acme Corp",
  "label": null,
  "message": "Please review and sign the service agreement for your order.",
  "status": "processing",
  "attestation": "none",
  "language": "en",
  "mode": "test",
  "routing": "sequential",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "snapshot_url": null,
  "branding": {
    "logo": null,
    "accent_color": "#2463EB",
    "email": {
      "footer": null,
      "logo_position": "left",
      "from": "noreply@signatureapi.com"
    }
  },
  "deliverable": {
    "id": "del_6FF89lKNyTNamOJCJd1tLL",
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "name": null,
    "status": "pending",
    "type": "standard",
    "url": null,
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null,
    "timezone": "UTC",
    "language": "en",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "service_agreement"
    ]
  },
  "metadata": {
    "source": "salesforce",
    "opportunity_id": "006Dn00000A1b2CIAR"
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "captures": {},
  "documents": [
    {
      "id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "service_agreement",
      "title": null,
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "page": 1,
          "top": 172,
          "left": 210,
          "place_key": "signer_signature"
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_49r1R2jpPDz8hSpP75ZkPp",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "signer",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "redirect_delay": 3,
        "url": null,
        "url_variant": "standard"
      },
      "ceremony_creation": "automatic",
      "delivery_type": "email",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "status": "pending",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    }
  ],
  "topics": [
    "no_code",
    "salesforce"
  ],
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "errors": [
    "recipients[0].email must be a valid email address."
  ]
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
