Skip to content

CRM and sales

Send Agreements From Zoho Creator and Flow

Create SignatureAPI envelopes from a Zoho Deluge invokeurl call, and receive signing events with a Zoho Flow webhook trigger.

Zoho’s Deluge scripting language calls the SignatureAPI REST API with its own invokeurl task, so a Creator form or a Flow custom function can send an envelope. A Webhook trigger in Zoho Flow receives the result. No SignatureAPI app is needed.

Before you start

Send the envelope

1

Store the key in a connection

In Creator, open the Microservices tab, click +Create New, choose Connection and then Create New Custom Connector. Choose the API Key authentication type, set the Parameter Key to X-API-Key and the Parameter Location to Header. Zoho sends the stored key with each invokeurl call that uses the connection, so the key stays out of your script.

2

Run the script when a record is saved

Add a Deluge script to the On success action of a form, with Successful form submission as the trigger (Zoho Creator help). Set a criteria so the script runs once per record.

3

Call invokeurl

Set type to POST, send the JSON text in body, and set the Content-Type header to match it. Zoho requires the header to match the body format, and you can’t set both parameters and body in one call (Deluge reference). Replace signatureapi with the link name of your connection.

// payload: a map with the request body below, filled from your form fields
headers = Map();
headers.put("Content-Type", "application/json");
response = invokeurl
[
    url: "https://api.signatureapi.com/v1/envelopes"
    type: POST
    body: payload.toString()
    headers: headers
    connection: "signatureapi"
];
info response.get("id");

Zoho HTTP request step

Settings for the "Service agreement" request.

SettingValue
Method POST
URL https://api.signatureapi.com/v1/envelopes

The API key comes from the setup in the steps above, so the step needs no header row for it.

Header Content-Type: application/json
Body (raw JSON)The JSON below.
Body (raw JSON)
{
  "title": "Service Agreement - Jane Doe",
  "message": "Please review and sign the service agreement.",
  "metadata": {
    "source": "zoho",
    "record_id": "4876876000000123001"
  },
  "topics": [
    "no_code",
    "zoho"
  ],
  "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"
    }
  ]
}

data.envelope_metadata.record_id comes back in every webhook event for this envelope, and the zoho topic lets an endpoint receive only these envelopes. Zoho stops an invokeurl call that takes more than 40 seconds.

Zoho shares Flow custom functions with everyone in the organization, so never write the key into one. Use a connection for it, as in Creator.

Get the result back

1

Create a webhook trigger

In My Flows, click Create Flow, select Webhook as the trigger, choose JSON as the payload format, and copy the URL Zoho Flow generates (Zoho Flow help).

2

Register the URL in SignatureAPI

In the Dashboard, add a webhook endpoint in test mode with that URL. Subscribe to deliverable.generated, which fires when the signed PDF is ready, and add the zoho topic. The envelope.completed event comes earlier, while the PDF may still be generating, so use it only to update a status. Zoho Flow waits for a sample request to show the payload, so complete a test envelope to send one.

3

Read the envelope before you act

Anyone who knows the webhook URL can call it, so read the envelope with your key before you update a record. Add a custom function that calls invokeurl with type: GET, a connection that holds the key, and data.envelope_id from the event in the URL:

Zoho HTTP request step

Settings for the "Completed envelope" request.

SettingValue
Method GET
URL https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56

The API key comes from the setup in the steps above, so the step needs no header row for it.

Act on the response: deliverable.status is generated, metadata.record_id names your record, and deliverable.url downloads the signed PDF. That link expires after an hour. If your account uses authenticated deliverable URLs, send your API key with the download.

Under Advanced settings, Enable webhook acknowledgement lets you set the reply. SignatureAPI expects a 2XX answer and retries a failed delivery for up to 48 hours. The same event can arrive twice, so skip a record that already shows as signed. See Webhooks.