Skip to content

CRM and sales

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.

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 (it starts with key_test_).
  • The document you send, at a URL on a supported host, or uploaded to SignatureAPI 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).

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. 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 and Salesforce’s guide. 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 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.

SettingValue
Method POST
URL /v1/envelopes

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

Sample request (JSON)The JSON below.
Sample request (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.

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

2

Run the flow for each waiting opportunity

Create a schedule-triggered 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.

SettingValue
Method GET
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. If your account uses authenticated deliverable URLs, send your API key with the download.