> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger workflows from Pipedrive

> Fire an OpenCX workflow from a Pipedrive automation — typed payload, outbound phone calls, lead-by-lead branching.

Pipedrive automations can POST a new lead into an OpenCX workflow the moment it appears in the pipeline. The workflow can then place an outbound AI call, branch on custom fields, or enrich the lead with data from another system.

<Tip>
  Use a **Form Submit** trigger in OpenCX, not a generic webhook. Form Submit triggers validate the payload against a schema you define — the workflow builder then shows typed suggestions (`trigger.formData.phone`, `trigger.formData.name`) instead of a free-form blob.
</Tip>

## How it flows

```mermaid theme={"dark"}
flowchart LR
    A[New lead in Pipedrive] --> B[Pipedrive automation]
    B --> C[HTTP Request step]
    C --> D[OpenCX Form Submit trigger]
    D --> E[Outbound AI call or lead update]
```

## Build the OpenCX side first

<Steps>
  <Step title="Create a workflow with a Form Submit trigger">
    In your [OpenCX dashboard](https://platform.open.cx), start a new workflow and pick **Form Submit** as the trigger type.
  </Step>

  <Step title="Define the form schema">
    Add one field per value Pipedrive will send. Typical set for an outbound-call flow: `name`, `email`, `phone_number`, plus any custom fields (`booking_code`, `van_model`, `lead_id`). The field names here become the keys in `formData` on the Pipedrive side — keep them identical.
  </Step>

  <Step title="Copy the form ID">
    The trigger node exposes a **Form ID** (a ULID like `01K9SYWVMSJF5PT4AH4ACHV3F3`). Copy it — Pipedrive will send it alongside the payload.
  </Step>

  <Step title="Finish the flow">
    After the trigger, add whatever nodes you need. Common chains: `Make Outbound Call` for phone follow-up, or `Update PipeDrive Lead` to enrich the lead after a downstream action lands.
  </Step>
</Steps>

## Wire Pipedrive's automation

<Steps>
  <Step title="Open Pipedrive Automations">
    Go to [Pipedrive Automations](https://app.pipedrive.com/automations) and create a new workflow.
  </Step>

  <Step title="Pick your trigger">
    For outbound calls on new leads, use **Lead created**. For updates on stage changes, use **Lead updated → Stage**. Any Pipedrive trigger works.
  </Step>

  <Step title="Add an HTTP Request action">
    Pipedrive's automation builder has a built-in **HTTP Request** step. Configure it as:

    * **Method:** `POST`
    * **URL:** `https://api.open.cx/backend/workflow/form-submission`
    * **Headers:** `Content-Type: application/json`
    * **Body:**

    ```json theme={"dark"}
    {
      "formId": "01K9SYWVMSJF5PT4AH4ACHV3F3",
      "formData": {
        "name": "{{Lead.person_name}}",
        "email": "{{Lead.person_email}}",
        "phone_number": "{{Lead.person_phone}}",
        "lead_id": "{{Lead.id}}"
      }
    }
    ```

    Replace `formId` with the ID you copied from OpenCX, and swap the merge tags for the Pipedrive fields you want to send.
  </Step>

  <Step title="Save and test">
    Create a test lead in Pipedrive. Your OpenCX workflow should fire within seconds — check the run viewer in the dashboard to confirm the payload arrived typed.
  </Step>
</Steps>

## Outbound call payloads need E.164 phone numbers

If the next step is an outbound AI call, the phone number has to be in <Tooltip tip="The international phone-number format. Starts with +, then the country code, then the subscriber number. Example: +15551234567.">E.164</Tooltip> format before the call action runs. Pipedrive often stores phone numbers without a leading `+`, which the call provider rejects with `customer.number must be a valid phone number in the E.164 format`.

Two places to fix it:

* **In Pipedrive's HTTP Request body** — concatenate a `+` if the number doesn't start with one. If Pipedrive's automation builder doesn't support string manipulation for your layout, fix it upstream.
* **In the OpenCX workflow** — add a transformation node between the trigger and the call action that prefixes `+` when missing.

<Warning>
  Don't skip this. A missing `+` is the single most common reason calls fire from Pipedrive but never ring through — see [Troubleshooting](/integrations/pipedrive/troubleshooting).
</Warning>

## Form Submit vs generic webhook

You can also start a workflow from a generic **Webhook** trigger. It works — but the payload comes through as an untyped object, and the flow builder can't suggest fields. For anything beyond a proof of concept, use Form Submit.

|                     | Form Submit                                    | Generic Webhook    |
| ------------------- | ---------------------------------------------- | ------------------ |
| Payload shape       | Enforced against your schema                   | Free-form JSON     |
| Builder suggestions | Typed (`trigger.formData.phone`)               | Untyped            |
| URL                 | `api.open.cx/backend/workflow/form-submission` | Unique per trigger |
| Body wrapper        | `{ formId, formData }`                         | Whatever you send  |

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Update Lead Action" icon="user-round-pen" href="/integrations/pipedrive/update-lead-action">
    Pair a Pipedrive-triggered workflow with a write-back to the same lead.
  </Card>

  <Card title="Connect" icon="plug" href="/integrations/pipedrive/connect">
    Credentials for the write-back side.
  </Card>

  <Card title="Overview" icon="users-viewfinder" href="/integrations/pipedrive/overview">
    Capabilities and patterns at a glance.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/pipedrive/troubleshooting">
    Payload untyped, phone-format errors, workflow not firing.
  </Card>
</CardGroup>