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

# Pipedrive integration

> Connect Voiceflow to Pipedrive for confirmed enquiries, authorized customer records and assigned follow-up.

## Overview

Connect Voiceflow to Pipedrive with API tools to capture confirmed enquiries, use authorized customer records and create assigned follow-up work. The tools call your CRM directly; credentials are stored in Voiceflow Secrets.

- **[Connect Pipedrive](#connecting-pipedrive)** — prepare account access and a tested customer lookup.
- **[Capture an enquiry](#capturing-enquiries)** — save confirmed details for your sales team.
- **[Recognize a customer](#recognizing-customers)** — read the record authorized by your application.
- **[Update customer details](#updating-records)** — change a confirmed phone number and read it back.
- **[Create follow-up](#recording-follow-up)** — save work linked to the customer and approved owner.

#### Studio

Use an editable test project, a CRM administrator and an application developer. The developer prepares trusted customer mappings for protected records and confirmed JSON payloads; the steps below name the values to obtain.

#### Developer

Use Voiceflow APIs or CLI to create, execute and attach the same API tools. Your backend owns CRM authorization, customer identity and JSON construction. Test with records you can inspect before attaching tools to a customer-facing agent.

<a id="connecting-pipedrive"></a>

## Connecting Pipedrive

Prepare direct API access and a protected customer lookup.

For a private account integration, obtain the user's API token from **Personal preferences → API** in Pipedrive. The token belongs to one user and company and has that user's data access. The administrator must approve person/Lead creation, person reads/updates and activity creation, plus the intended owner. Store the token as a restricted Voiceflow Secret and send it in **`x-api-token`**, not in the request URL. See [Pipedrive authentication](https://pipedrive.readme.io/docs/core-api-concepts-authentication).

Use your exact company origin, such as `https://YOUR_COMPANY.pipedrive.com`. This recipe uses v2 Persons and Activities and the still-supported v1 Leads endpoint. A distributed application needs its own OAuth flow; this private-token recipe does not implement a Marketplace app. Rotating the user's token invalidates other integrations sharing it.

For a public capture-only agent, prepare the credential and capture payload variable, then continue to [Capturing sales enquiries](#capturing-enquiries). Skip the customer lookup and Contact mapping. The lookup steps below are for the authenticated customer agent.

### Prepare the lookup and credentials

#### Studio

### 1. Obtain the account and application setup

Ask the CRM administrator and application developer to complete the authorization above. Obtain the fixed CRM origin, restricted Secret **pipedrive_api_token**, the approved owner ID and a test application URL. For a customer lookup, also obtain an authorized test login and Contact ID. Obtain the private token through your approved secret-sharing process, then create **pipedrive_api_token** in **More → Secrets**. Creating its default also writes Main's Published value; use a dedicated test project.

### 2. Create the protected variables

Open [Agent studio](https://creator.voiceflow.com), select the test project and intended Environment, then open **More → Variables**. Create `pipedrive_contact_id`, `pipedrive_capture_payload`, `pipedrive_phone_payload` and `pipedrive_followup_payload` with empty defaults. Also create `pipedrive_lead_payload` for the second capture write and the output variables `pipedrive_created_person_id` and `pipedrive_person_success` with empty defaults. For the authenticated agent, have the developer supply the authorized mapping and prepared payloads on every turn/resume while retaining runtime credentials on the backend. The public capture-only agent supplies confirmed capture payloads without a Contact mapping. Do not accept browser overrides or ask the model to choose a record/owner.

### 3. Configure the customer lookup

In **Agent → Global tools → + → API**, create **Find customer in Pipedrive**. Select **GET** and use `https://example.pipedrive.com/api/v2/persons/{contact_id}`, replacing only the example origin with the approved one. Add `x-api-token: {token}` and `Accept: application/json`.

Native Pipedrive API tool with its configured request — Configure the Pipedrive request and bind its protected inputs before testing.

### 4. Bind credential and customer identity

Save the request and click the attached tool in **Global tools**. Under **Input variables**, click the **token** row, then select `pipedrive_api_token` through **Default value → Secrets**. Open **contact_id** and select `pipedrive_contact_id` through **Default value → Variables**. Click outside to save. Enabling a switch does not bind the input. Reopen each row to verify the selected reference.

### 5. Test the actual record

Open the saved API tool’s editor and click **Run**. In its test-input panel, choose the token Secret and enter the developer-approved test `contact_id`, then click **Run** again. These test values are separate from attached runtime defaults; the proxy does not populate this panel. Inspect `data.id` in the provider body and compare it with the intended CRM record. Use **Capture response** only for approved fields; a saved request or Secret does not verify record access.

#### Developer

Use the administrator-approved private-account token for this recipe. Keep the credential in the restricted `pipedrive_api_token` Secret. No OAuth renewal worker is needed for this API-token method. To stop access, disable the relevant tool and revoke/rotate the provider token deliberately; coordinate every other integration sharing that token.

Use a [Voiceflow bearer credential](/docs/api-reference/authentication) with the required project/Environment permissions. Keep it server-side. Set `VF_TOKEN`, `PROJECT_ID`, `ENVIRONMENT` and `CRM_CONTACT_ID` to your test resources; install the [CLI](/docs/cli/install) if choosing CLI. `CRM_CONTACT_ID` is the authorized Contact/Person ID, not a new Lead ID.

Download and extract the [direct CRM example bundle](/docs/examples/crm/direct-crm-examples.zip). It contains the tool definitions, payload builders, renewal worker and fixture tests. Run `node --test direct-requests.test.mjs` on Node.js 22 or later; these are local fixtures, not authenticated provider tests. Set `CRM_API_ORIGIN` to your approved CRM origin, then prepare the definitions locally:

```sh
node direct-tools.mjs pipedrive "$CRM_API_ORIGIN" > tools.json
jq '.lookup' tools.json > tool.json
```

Each definition fixes the provider host, method and fields. Write definitions use raw JSON body `{payload}`; the backend builder supplies that entire serialized value. No provider credential is embedded in these files.

Create `pipedrive_api_token` as a restricted Secret **without `defaultValue`** through `POST /v2/stable/secret?projectID=$PROJECT_ID` with body `{"name":"pipedrive_api_token","visibility":"restricted"}` and the Voiceflow bearer header, or:

```sh
printf '%s' '{"name":"pipedrive_api_token","visibility":"restricted"}' |
vf secret create --project-id "$PROJECT_ID" --output-format json
```

Save `secret.id` as `SECRET_ID`. The placeholder has no value. Set its explicit test Draft target using [Secret value configuration](/docs/cli/commands/secret/set-value). Use the private Pipedrive API token as the value. Supply `environmentAlias` and `versionVariant`; omitting the target can write Main's Published value.

Create the identity and payload variables before attachment. The API is `POST /v2/stable/variable` with the same project/Environment query and body `{"name":"pipedrive_contact_id","defaultValue":null,"color":"#515A63"}`; repeat with each payload variable name. Through CLI:

```sh
vf variable create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --name pipedrive_contact_id --default-value '' --color-param '#515A63' --output-format json
```

Repeat for `pipedrive_capture_payload`, `pipedrive_phone_payload`, `pipedrive_followup_payload`, `pipedrive_lead_payload`, `pipedrive_created_person_id` and `pipedrive_person_success` with empty defaults. Keep both returned output-variable IDs for the Person-result captures. For protected customer records, your authenticated proxy must use [trustedDirectTurn](/docs/examples/crm/direct-requests.mjs) on every turn and resume, strip browser variables/state and retain the runtime session key. An initial launch mapping alone is insufficient.

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @tool.json
```

#### CLI

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < tool.json
```

Save each returned `apiTool.id` separately. Set `API_TOOL_ID` to the lookup's ID for its test, and retain it as `LOOKUP_TOOL_ID` for later readback. List its inputs with `GET /v2/stable/api-tool-variable?apiToolID=$API_TOOL_ID&projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT`, or `vf api-tool variable list --api-tool-id "$API_TOOL_ID" --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --output-format json`. Match `variables[].name` to `id` for attachment.

Save the lookup inputs:

```sh
jq -n --arg id "$CRM_CONTACT_ID" \
  '{inputs:{token:"{pipedrive_api_token}",contact_id:$id}}' > inputs.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Require `success: true`, `error: null`, `truncated: false`, provider `output.status: 200` and the expected `output.body.data.id`. Standalone execution uses the selected Environment's Draft; it does not attach or publish the tool.

<a id="using-tools-with-agent" />

### Use CRM tools in an agent

Start with an agent that already handles a Draft conversation in the selected test Environment. Keep its existing [Playbooks](/docs/documentation/build/playbooks) or [Workflows](/docs/documentation/build/workflows) registered while adding these tools.

#### Studio

### 1. Open the attached customer lookup

In **Agent → Global tools**, open **Find customer in Pipedrive**. Keep the lookup on the authenticated customer agent. The separate public capture-only agent gets only its create tools; a saved API request in Tools alone is not an agent attachment.

### 2. Set the Trigger and provided inputs

Set **Trigger** to “Find the signed-in customer's contact details when they ask about their profile.” Keep **token** bound to the Secret and **contact_id** to `pipedrive_contact_id`. For writes, bind the complete **payload** from the backend variable named in that capability. The agent collects the customer's request, not credentials, CRM IDs or raw JSON.

### 3. Test the question through your application

Use the authenticated test application and ask “What phone number do you have for me?” Inspect the tool call and the approved returned field before the agent answers. Repeat without a permitted mapping: the backend must stop the private read and the agent must use general help. API-editor **Run** tests the request separately.

#### Developer

Attach the saved lookup to the authenticated agent with `target: {"global":true}`; use `{"playbookID":"YOUR_PLAYBOOK_ID"}` to restrict a read to one Playbook. Set the attachment's `description` to “Find the signed-in customer’s contact details when they ask about their profile,” keeping `token` and `contact_id` as provided defaults. Each write uses its own saved tool ID, input IDs, description and backend-prepared payload binding. The complete attachment commands are in **Attach tested tools to an agent** below.

Compile the Draft, then send “What phone number do you have for me?” through the authenticated application. Inspect the actual tool call, current result and answer. Test a missing/foreign mapping and a later-turn override. For a first enquiry, use `trustedEnquiryTurn` with a separate capture-only agent; protected customer tools use `trustedDirectTurn` on every turn/resume. A Trigger describes selection; the backend enforces access and confirmation.

For API-tool **Capture response**, use `data.id` for the Person, Lead or activity, each in a separate output variable. The path starts in the provider JSON, without the standalone `output.body` prefix. Create any output variables with empty defaults using the variable setup above; keep returned IDs separate from `pipedrive_contact_id`.

Capture paths are relative to the tool's current response, not the standalone `output` envelope. Captures can retain an earlier value after a failure or missing field; a retained ID alone is not a success check. Use the current result and the capability's completion check before answering, and clear retained outputs before a new attempt when your workflow relies on them.

#### Developer

### Attach tested tools to an agent

Bind protected inputs, compile and test a conversation after standalone execution.

Save this attachment as `attachment.json`, replacing the resource and input IDs with those returned above:

```json
{
  "type": "api",
  "apiToolID": "RETURNED_API_TOOL_ID",
  "target": {
    "global": true
  },
  "description": "Read only the customer authorized by the authenticated application.",
  "inputVariables": {
    "token": {
      "apiToolInputVariableID": "TOKEN_INPUT_ID",
      "required": false,
      "defaultValue": "{pipedrive_api_token}"
    },
    "contact_id": {
      "apiToolInputVariableID": "CONTACT_ID_INPUT_ID",
      "required": false,
      "defaultValue": "{pipedrive_contact_id}"
    }
  }
}
```

For a write, add the `payload` input using its returned input ID and `defaultValue: "{pipedrive_capture_payload}"`, `"{pipedrive_phone_payload}"` or `"{pipedrive_followup_payload}"` for that tool; use `"{pipedrive_lead_payload}"` for Pipedrive Lead creation. Include `contact_id` only on tools whose schema declares it. Defaults are protected server-supplied values; do not leave IDs, credentials or full JSON payloads to model selection.

POST the attachment to `/v2/stable/tool` with the project/Environment query and Voiceflow bearer header, or:

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < attachment.json
vf environment compile --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --output-format json
```

Resolve `unresolvedReferences`. Compile, exercise a conversation and inspect the resulting CRM record before [publishing the reviewed Environment](/docs/documentation/deploy/environments/publishing). Compilation does not publish. Verify that your proxy resets protected variables on later turns, including resumes, and that unprepared payloads cannot execute a write.

### Rotate or stop account access

Remove credentials deliberately without deleting CRM records.

Disable affected tools before revoking access. Coordinate token rotation with every integration sharing that user token and update the intended Secret targets. Clear obsolete Secret values only after checking other tools and versions. Revoking authorization does not delete records already created.

<a id="capturing-enquiries"></a>

## Capturing sales enquiries

Save confirmed details for your sales team.

A first enquiry does not require an existing CRM Contact. For public prospects, use a separate capture-only agent with just these create tools and the backend’s `trustedEnquiryTurn` boundary. Keep customer lookup, update and linked follow-up tools on the authenticated agent.

Apply your qualification policy, then ask the customer to confirm the details and follow-up request. The [qualification Guide](/docs/guides/integrations/crms/qualify-and-capture-sales-enquiries) explains that broader journey; a CRM write does not qualify the customer by itself.

Capture uses two deliberate writes: **Create person** saves `name`, `emails` and `owner_id`; **Create lead** saves a `title`, the returned numeric `person_id` and approved `owner_id`. Keep the Person ID even if Lead creation fails. Reuse an already-authorized Person when one exists; this recipe does not discover identity from email. Require provider `success: true` on both results. See [Persons](https://developers.pipedrive.com/docs/api/v1/Persons) and [Leads](https://developers.pipedrive.com/docs/api/v1/Leads).

| Confirmed value | Provider field |
| --- | --- |
| Name | Person `name` |
| Confirmed email | Person `emails: [{value, primary: true}]` |
| Approved owner | Person and Lead `owner_id` |
| Enquiry | Lead `title` |
| Created Person | Lead `person_id` |

**In the conversation:** Set the capture tool’s **Trigger** to recording a confirmed sales enquiry when `pipedrive_capture_payload` is ready. Let the agent gather the enquiry details; the backend validates confirmation, selects the approved owner and supplies the complete payload. Retain the Person ID on the backend, prepare the linked Lead payload for a later conversation turn, then call the Lead tool; acknowledge completion only after both writes succeed. Test Person success followed by Lead failure: retain the Person and reconcile the Lead without creating a second Person or claiming a completed enquiry.

### Save the confirmed enquiry

#### Studio

### 1. Prepare the reviewed request

Have your developer use `capturePayload` in the [request builders](/docs/examples/crm/direct-requests.mjs) to populate `pipedrive_capture_payload` from confirmed, validated fields and the approved owner. Require a recorded confirmation, not a model assertion.

### 2. Add the capture request

Create an API tool with **POST** `https://example.pipedrive.com/api/v2/persons` and the credential header from setup. Add `Content-Type: application/json`. Use **Body → Raw → JSON** with the complete input `{payload}`; do not interpolate customer text into a quoted JSON template.

Native Pipedrive API tool with its configured request — Configure the Pipedrive request and bind its protected inputs before testing.

### 3. Bind and test the write

In the attached tool's **Input variables**, bind **token → Default value → Secrets → pipedrive_api_token**. Open **payload** and bind **Default value → Variables → pipedrive_capture_payload**. Click outside and reopen to check. Open the API tool editor’s **Run** panel. Select the token Secret and paste the developer-prepared complete JSON string in **payload**. Click **Run** and inspect the saved Person. Retain its ID; do not announce success from HTTP status alone.

#### Developer

Select `.capture` from `tools.json` into `tool.json`, then [create it](#connecting-pipedrive) and retain its new `apiTool.id` as `CAPTURE_TOOL_ID`. Set `API_TOOL_ID` to that ID.

Use the [request builders](/docs/examples/crm/direct-requests.mjs) on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as `prepare.mjs` and run `node prepare.mjs` to write `inputs.json`:

```js
import fs from 'node:fs';
import { capturePayload, phonePayload, followUpPayload, pipedriveLeadPayload } from './direct-requests.mjs';
const payload = capturePayload({ provider: 'pipedrive', confirmed: true, firstName: 'Maya', lastName: 'Chen', email: 'maya@example.com', company: 'Example Company', subject: '25-seat demo requested', ownerID: '2147' });
fs.writeFileSync('inputs.json', JSON.stringify({ inputs: { token: '{pipedrive_api_token}', payload } }));
```

The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied [fixture tests](/docs/examples/crm/direct-requests.test.mjs) exercise this boundary.

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Require the Voiceflow execution checks from setup and the provider result described above. Keep `output.body.data.id` with the request.

For conversation use, create `pipedrive_created_person_id` and `pipedrive_person_success` as above. Add `"captureResponse":{"person-result":{"path":"data.id","variableOrEntityID":"RETURNED_PERSON_RESULT_VARIABLE_ID"},"person-success":{"path":"success","variableOrEntityID":"RETURNED_SUCCESS_VARIABLE_ID"}}` to the Person attachment. Both turn helpers reset the ID and success flag before forwarding. After the call, read the same server-owned conversation’s state with [Get conversation state](/docs/cli/commands/conversation/state/get):

```sh
vf conversation state get --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --user-id "$USER_ID" --version-param draft --output-format json > person-state.json
```

`USER_ID` is the application's retained conversation identity, not browser input. The management route is `GET /v1/stable/conversation-state/USER_ID` with `projectID`, `environmentAlias` and `version` query fields; the credential needs conversation-state read permission. Use the actual Draft/Published version.

Parse the management response as `stateResponse`, then call `pipedrivePersonResult(stateResponse.state)`. It requires `pipedrive_person_success === true` and a positive safe-integer Person ID, then converts the ID to the decimal string expected by `pipedriveLeadPayload`. Retain it with this enquiry server-side, prepare `pipedrive_lead_payload`, and supply that payload through `trustedEnquiryTurn` on a later turn. The first call does not automatically populate or invoke the second tool.

### Link the Person to a Lead

Keep the first write's Person ID. Create a separate API tool using **POST** `/api/v1/leads`, the same header and JSON body `{payload}`. Bind its token and `pipedrive_lead_payload` through the same Default value controls. Have the developer construct that payload with `pipedriveLeadPayload` from the confirmed enquiry, saved numeric Person ID and approved owner.

#### Studio

### 1. Retain the current Person result

In the Person tool’s **Capture response**, map `data.id` to `pipedrive_created_person_id` and `success` to `pipedrive_person_success`. The turn helper clears the ID and sets success to false before each attempt. After the call, have the backend read that conversation’s state and require a fresh true flag and valid numeric Person ID.

### 2. Prepare the linked Lead

Have the developer use `pipedriveLeadPayload` to populate `pipedrive_lead_payload` from that saved Person ID, the confirmed enquiry and approved owner. Add a second API tool: **POST** `https://example.pipedrive.com/api/v1/leads`, the token header, JSON content type and raw `{payload}`. Bind its payload to `pipedrive_lead_payload`.

### 3. Continue the enquiry and check both records

Set the Lead tool's Trigger to the pending enquiry when its payload is ready. The backend supplies that value on a later turn; the Person tool does not invoke it automatically. Retain the Lead UUID separately and inspect its Person link. A failed Lead must preserve the existing Person for reconciliation.

#### Developer

Select `.lead` from `tools.json`, create the separate tool and set `API_TOOL_ID` to its new ID. Replace `1042` with the actual Person ID from the first result:

Use the [request builders](/docs/examples/crm/direct-requests.mjs) on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as `prepare.mjs` and run `node prepare.mjs` to write `inputs.json`:

```js
import fs from 'node:fs';
import { capturePayload, phonePayload, followUpPayload, pipedriveLeadPayload } from './direct-requests.mjs';
const payload = pipedriveLeadPayload({ confirmed: true, personID: '1042', title: '25-seat demo requested', ownerID: '2147' });
fs.writeFileSync('inputs.json', JSON.stringify({ inputs: { token: '{pipedrive_api_token}', payload } }));
```

The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied [fixture tests](/docs/examples/crm/direct-requests.test.mjs) exercise this boundary.

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Require `output.body.success: true` and retain the Lead UUID in `output.body.data.id`. This UUID is a different resource from the Person ID.

Inspect the saved CRM record and its owner before confirming completion. A write timeout is ambiguous: reconcile the existing record and execution evidence before retrying. Creation is not an idempotent upsert. It does not send a customer email, book a meeting or create a qualified opportunity.

<a id="recognizing-customers"></a>

## Recognizing returning customers

Use only the customer record authorized by your application.

Customer identity comes from your application sign-in and server-side CRM mapping. A typed email, a CRM ID suggested in chat or provider account authorization is not customer authentication. Use [the tested lookup](#connecting-pipedrive) after the proxy has reset the protected mapping for this turn.

Require provider `success: true` and the expected numeric `data.id`. Pipedrive v2 does not support the old field-selector URL syntax. The direct Person response can contain custom and other fields: use this tool only when the complete returned record is approved for the agent. If fields require redaction, put that filtering on your backend before exposing the result; **Capture response** alone does not redact the original tool output. See [request behavior](https://pipedrive.readme.io/docs/core-api-concepts-requests).

**In the conversation:** Set **Find customer in Pipedrive** to run when the signed-in customer asks about their saved profile. Provide `pipedrive_contact_id` from the authenticated application and the token from Secrets; neither is collected by the agent. Answer from approved fields in the current matching record; failed or empty reads use general help. Test “What phone number do you have for me?” plus a missing mapping and a later-turn override; no private data may escape the permitted record.

### Use the authorized record

#### Studio

### 1. Check the supplied mapping

Have the application developer demonstrate that `pipedrive_contact_id` is rebuilt from the authenticated server-side map on every turn/resume and client runtime credentials stay on that backend. The lookup input must remain bound to that variable.

### 2. Run the customer question

Use the provided authenticated test application with an authorized test customer, then ask for another customer's record and attempt a later-turn variable override. Neither may expose it. Test a missing mapping and fall back to general help.

### 3. Use only the approved result

Inspect the actual response before configuring **Capture response**. Verify `data.id` and the fields approved for this customer. Do not turn a failed lookup into automatic record creation.

#### Developer

Set `API_TOOL_ID` to the saved `LOOKUP_TOOL_ID`. Authorize the customer and record again, prepare `inputs.json` with the server-mapped ID as in setup, then execute that lookup. Check the provider ID and permitted fields before returning an answer.

`trustedDirectTurn` discards browser variables/state and resets the Contact ID and every payload variable; integrate it behind your application authentication on all supported runtime actions. Its allowlist covers launch/text only. Additional actions require their own audited boundary. Missing mappings must fail before the tool executes; never use a shared customer ID as a default.

<a id="updating-records"></a>

## Updating customer details

Save a confirmed phone change and verify persistence.

Confirm the requested number and authorize the same customer before changing it. This recipe accepts international phone strings matching `^\+[1-9][0-9]{7,14}$`; it does not accept free-form text or additional fields.

Use **PATCH** with a `phones` array. The helper requires the freshly retrieved `phones` and preserves secondary numbers/labels while replacing the primary number; it rejects multiple primaries. Review the complete submitted list before writing. The read/update pair is not atomic: if another application changes phone data concurrently, reconcile before retrying. Require provider `success: true`, then read the same Person again and compare the full `phones` list.

**In the conversation:** Call the phone-update tool only after the backend supplies a confirmed `pipedrive_phone_payload`, then run the lookup again. Let the agent collect the proposed number; the application owns validation, customer identity and the complete write payload. Use the current readback to confirm the same record changed; reconcile uncertain writes before retry. Test an unconfirmed change and a confirmed number; the first must not write, and the second must preserve the authorized record.

### Save and read back the change

#### Studio

### 1. Prepare the permitted change

Have the developer populate `pipedrive_phone_payload` using `phonePayload` with the authorized Contact/Person ID and confirmed number. Read the current `phones` first and supply that complete list to the helper.

### 2. Configure the update tool

Create an API tool with **PATCH** `https://example.pipedrive.com/api/v2/persons/{contact_id}`, the setup credential header and `Content-Type: application/json`. Set **Body → Raw → JSON** to `{payload}`. Bind **token** to the Secret, **contact_id** to the protected identity variable and **payload** to `pipedrive_phone_payload` using each row's **Default value**.

### 3. Verify persistence

In the API editor’s **Run** test panel, choose the token Secret, enter the approved `contact_id` and paste the complete prepared **payload**. Run the update, inspect provider errors and repeat the lookup test for that same ID. Then exercise the change through the provided authenticated application and inspect [Transcripts](/docs/documentation/measure/transcripts). Compare `phones` with the confirmed change and open the CRM record. A failed read does not prove the write failed.

#### Developer

Select `.phone` from `tools.json`, create the new API tool and retain its ID as `PHONE_TOOL_ID`. Set `API_TOOL_ID` to it. Use the actual mapped ID in both the prepared payload and execution input:

Use the [request builders](/docs/examples/crm/direct-requests.mjs) on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as `prepare.mjs` and run `node prepare.mjs` to write `inputs.json`:

```js
import fs from 'node:fs';
import { capturePayload, phonePayload, followUpPayload, pipedriveLeadPayload } from './direct-requests.mjs';
const payload = phonePayload({ provider: 'pipedrive', contactID: '1042', confirmed: true, value: '+14165550123', currentPhones: [{ value: '+14165550100', primary: true, label: 'work' }, { value: '+14165550199', primary: false, label: 'other' }] });
fs.writeFileSync('inputs.json', JSON.stringify({ inputs: { token: '{pipedrive_api_token}', contact_id: '1042', payload } }));
```

The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied [fixture tests](/docs/examples/crm/direct-requests.test.mjs) exercise this boundary.

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Check the provider result, then set `API_TOOL_ID` back to `LOOKUP_TOOL_ID`, prepare lookup inputs and re-read that same record. Compare `output.body.data.id` and the saved phone field. On a timeout, reconcile this read before choosing whether to retry the write.

<a id="recording-follow-up"></a>

## Creating assigned follow-up

Link the requested work to the customer and approved owner.

Create a activity only after the customer has requested follow-up. The administrator supplies an active permitted owner ID and verifies assignment permissions. This is a recorded work item, not a live human conversation or a guarantee that someone has contacted the customer.

Create a v2 activity with `subject`, `type: "task"`, approved numeric `owner_id`, `due_date` and `done: false`. Link the customer with `participants: [{person_id: ID, primary: true}]`; the v2 create body does not use a top-level `person_id`. Confirm that `task` is an enabled activity type and agree the calendar due date; this recipe leaves the due time unset. Inspect provider `success: true` and `data.id`, then check the actual owner, participant and due date. See [Activities](https://developers.pipedrive.com/docs/api/v1/Activities).

**In the conversation:** Set the follow-up tool’s **Trigger** to a requested follow-up when `pipedrive_followup_payload` is ready. Let the agent collect the subject and agreed date; the backend supplies the approved customer link, owner and confirmed payload. Use the current work-item ID and saved owner/date before acknowledging the request; a saved task is not a delivered message. Test a confirmed follow-up and a rejected write; only the saved, correctly linked work may be reported as recorded.

### Record the assigned work

#### Studio

### 1. Prepare the linked request

Have the developer call `followUpPayload` with the authorized customer record, approved owner, confirmed subject and agreed due date. Obtain `pipedrive_followup_payload`; the customer/model must not choose a CRM owner ID.

### 2. Configure and bind the follow-up tool

Create an API tool with **POST** `https://example.pipedrive.com/api/v2/activities`, the setup credential header and `Content-Type: application/json`. Set **Body → Raw → JSON** to `{payload}`. Bind the token Secret and the **payload** row to `pipedrive_followup_payload` through **Default value**.

### 3. Check the assigned record

In the API editor’s **Run** panel, select the token Secret and paste the complete confirmed **payload**. Run once and inspect the returned activity ID and open that record in the CRM. Confirm its linked customer, intended owner, due date and request details; retain the customer-to-work-item mapping.

#### Developer

Select `.followup` from `tools.json`, create the tool and retain its ID as `FOLLOWUP_TOOL_ID`. Set `API_TOOL_ID` to it, then prepare:

Use the [request builders](/docs/examples/crm/direct-requests.mjs) on your backend after recording confirmation and authorizing the record/owner. Download that file beside this script. These are fictional test inputs; replace the IDs before execution. Save this as `prepare.mjs` and run `node prepare.mjs` to write `inputs.json`:

```js
import fs from 'node:fs';
import { capturePayload, phonePayload, followUpPayload, pipedriveLeadPayload } from './direct-requests.mjs';
const payload = followUpPayload({ provider: 'pipedrive', confirmed: true, contactID: '1042', ownerID: '2147', subject: 'Demo follow-up requested', dueDate: '2026-12-01' });
fs.writeFileSync('inputs.json', JSON.stringify({ inputs: { token: '{pipedrive_api_token}', payload } }));
```

The helper serializes JSON and rejects braces in customer strings for this recipe. JSON quoting alone does not stop a Secret-shaped token from being interpreted during standalone execution. The supplied [fixture tests](/docs/examples/crm/direct-requests.test.mjs) exercise this boundary.

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

#### CLI

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json < inputs.json
```

Require the Voiceflow execution checks and the provider result described above. Retain `output.body.data.id` and inspect the corresponding CRM record's customer/owner/date before reporting completion. Retry only after reconciling an uncertain create; an authentication failure and a lost successful response need different handling.

### Diagnose a rejected or uncertain request

Separate credential failures, record access and writes whose outcome is unknown.

- **401 / invalid token:** check the Secret target and whether the user token was revoked or rotated.
- **403 / permission failure:** have the administrator inspect object, field, record and assignment access in the selected CRM account. A token or successful read does not establish write access.
- **Validation or duplicate error:** inspect the provider body and administrator-required fields. Do not treat a Voiceflow HTTP 200 as provider success.
- **429:** respect the provider's retry/reset information and review API usage; do not loop writes.
- **Timeout or lost response:** inspect the CRM and retained request/record IDs before retrying. The write may already have completed.
