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

# Pipefy as a destination

> Send your data from Nekt to Pipefy.

Pipefy is a workflow management platform that helps teams automate and optimize business processes using customizable pipes, cards, and phases. With the Pipefy destination, you can create new cards, update existing ones, or perform bulk field updates directly from your Nekt data.

## 1. Add your Pipefy access

1. In the [Destinations](https://app.nekt.ai/destinations) tab, click on the "Add destination" button located on the top right of your screen. Then, select the Pipefy option from the list of connectors.

2. Click **Next** and you'll be prompted to add your access:

   * **Access Token**: Your Pipefy authentication token. You can use either a Personal Access Token (PAT) or a Service Account token.
   * **Endpoint**: The operation to perform. See the details for each endpoint below:
     * `CreateCard` creates new cards in the pipe.
     * `UpdateCard` updates existing cards (metadata and custom fields).
     * `BatchUpdateCardField` performs bulk updates on custom fields across many cards in a single request. Recommended for high-volume scenarios (e.g. updating a lead score on 100k+ cards).
   * **Pipe ID**: The ID of the Pipefy pipe where cards will be created or updated. You can find this in the pipe URL (e.g. `https://app.pipefy.com/pipes/305737084` means the Pipe ID is `305737084`).
   * **Batch Size** *(advanced, BatchUpdateCardField only)*: The number of field updates to include in each API request. Default is `100`. Higher values reduce the total number of requests but increase payload size.
   * **Enable partial success**: Whether the connector should continue trying to sync records after one fails. Recommended for large batch operations.

   <Note>
     To generate a Personal Access Token, go to your Pipefy account settings, navigate to **Personal access tokens**, and create a new token. For production integrations, Pipefy recommends using Service Accounts instead.
   </Note>

3. Click **Next**.

## 2. Select your data to send

1. The next step is letting us know which data you want to send. Select the layer and then the desired table.

   <Tip>The table can be found more easily by typing its name.</Tip>

2. Click **Next**.

## 3. Map your data fields

Configure how the fields from your source table should be mapped to the fields in the selected endpoint. Below you can find the supported fields for each endpoint.

### Understanding Pipefy field types

Pipefy cards have two categories of fields:

* **Card-level fields**: Built-in fields like `title`, `due_date`, `assignee_ids`, `label_ids`, and `phase_id`. These are common to all pipes.
* **Custom fields**: Fields defined in the pipe's configuration (e.g. "Nome completo", "CPF", "Renda mensal"). Each custom field has an internal **field ID** (e.g. `nome_completo`, `valor_do_cr_dito`) that you must use as the destination field name in the mapping.

<Note>
  To find a custom field's internal ID, go to the pipe settings in Pipefy and check the field configuration. The ID is displayed under the field name. Alternatively, you can use the Pipefy GraphQL API to query the pipe's `start_form_fields` or phase `fields`.
</Note>

<AccordionGroup>
  <Accordion title="CreateCard">
    Creates a new card in the specified pipe. Card-level fields are set directly on the card, and custom fields are set via the `fields_attributes` parameter in a single API call.

    **Card-level fields**

    | Field          | Type             | Required | Description                                                                                  |
    | :------------- | :--------------- | :------- | :------------------------------------------------------------------------------------------- |
    | `title`        | String           | No       | The title of the card.                                                                       |
    | `due_date`     | DateTime         | No       | The due date for the card.                                                                   |
    | `phase_id`     | String           | No       | The ID of the phase to place the card in. If omitted, the card is placed in the first phase. |
    | `assignee_ids` | Array of Strings | No       | The IDs of users to assign to the card.                                                      |
    | `label_ids`    | Array of Strings | No       | The IDs of labels to apply to the card.                                                      |

    **Custom fields**

    Any destination field name that is not a card-level field is treated as a custom field ID. For example, if your pipe has a field called "Nome completo" with internal ID `nome_completo`, map your source column to destination field `nome_completo`.

    | Destination field | Type   | Description                                                 |
    | :---------------- | :----- | :---------------------------------------------------------- |
    | *Any field ID*    | String | Maps to a custom pipe field. The value is sent as a string. |

    <Warning>
      The pipe may have required fields configured in Pipefy. If you omit a required field, the API will reject the card creation. Check your pipe's form settings to identify which fields are mandatory.
    </Warning>

    <Note>
      **Connector fields** (fields that link to cards in another pipe) require special formatting. The value must reference valid connected card IDs or labels as expected by the Pipefy API. Check the connected pipe for valid values.
    </Note>
  </Accordion>

  <Accordion title="UpdateCard">
    Updates an existing card. Card-level fields (title, due date, assignees, labels) are updated in a single API request via the `updateCard` mutation. Custom fields are updated individually via the `updateCardField` mutation (one API call per field).

    **Card-level fields**

    | Field          | Type             | Required | Description                                                                                          |
    | :------------- | :--------------- | :------- | :--------------------------------------------------------------------------------------------------- |
    | `id`           | String           | **Yes**  | The Pipefy card ID to update. You can obtain this from the Pipefy source connector or the Pipefy UI. |
    | `title`        | String           | No       | The new title of the card.                                                                           |
    | `due_date`     | DateTime         | No       | The new due date for the card.                                                                       |
    | `assignee_ids` | Array of Strings | No       | The new list of assignee IDs.                                                                        |
    | `label_ids`    | Array of Strings | No       | The new list of label IDs.                                                                           |

    **Custom fields**

    Any destination field name that is not a card-level field (and not `id`) is treated as a custom field ID and updated via the `updateCardField` mutation.

    | Destination field | Type   | Description                                                     |
    | :---------------- | :----- | :-------------------------------------------------------------- |
    | *Any field ID*    | String | Maps to a custom pipe field. Updated one at a time via the API. |

    <Note>
      Since each custom field requires a separate API call, updating many fields on many cards can be slow. If you only need to update a single field across many cards, consider using `BatchUpdateCardField` instead.
    </Note>
  </Accordion>

  <Accordion title="BatchUpdateCardField">
    Performs bulk updates on a single custom field across many cards. Instead of sending one API call per card, this endpoint batches multiple `updateCardField` mutations into a single GraphQL request using aliases.

    This is the recommended endpoint for high-volume operations like updating a lead score, status, or any computed field across thousands of cards.

    **Performance comparison**

    | Scenario (100,000 cards) | UpdateCard | BatchUpdateCardField         |
    | :----------------------- | :--------- | :--------------------------- |
    | API requests             | 100,000    | \~1,000 (at batch\_size=100) |
    | Estimated time           | Hours      | Minutes                      |

    **Required fields**

    | Field       | Type   | Required | Description                                                          |
    | :---------- | :----- | :------- | :------------------------------------------------------------------- |
    | `card_id`   | String | **Yes**  | The Pipefy card ID to update.                                        |
    | `field_id`  | String | **Yes**  | The internal ID of the custom field to update (e.g. `renda_mensal`). |
    | `new_value` | String | **Yes**  | The new value for the field.                                         |

    **Source table format**

    Your source table should have **one row per field update**. For example, to update the `lead_score` field on three cards:

    | card\_id | field\_id   | new\_value |
    | :------- | :---------- | :--------- |
    | 301234   | lead\_score | 85         |
    | 301235   | lead\_score | 42         |
    | 301236   | lead\_score | 97         |

    <Tip>
      If all rows update the same field, you can use a **default value** in the mapping to avoid storing the field ID in your source table. Map the `field_id` destination to an empty origin field with `lead_score` as the default value. Then your source table only needs `card_id` and the score value.
    </Tip>

    To update **multiple fields per card**, include one row per card-field combination:

    | card\_id | field\_id     | new\_value |
    | :------- | :------------ | :--------- |
    | 301234   | lead\_score   | 85         |
    | 301234   | renda\_mensal | 25.000,00  |
    | 301235   | lead\_score   | 42         |
    | 301235   | renda\_mensal | 10.000,00  |
  </Accordion>
</AccordionGroup>

### Common Pipefy field types and value formats

When mapping values to Pipefy custom fields, use the format that Pipefy expects for each field type:

| Pipefy field type    | Expected value format                            | Example            |
| :------------------- | :----------------------------------------------- | :----------------- |
| `short_text`         | Plain string                                     | `John Doe`         |
| `email`              | Valid email string                               | `john@example.com` |
| `phone`              | Digits only (no formatting)                      | `11999999999`      |
| `cpf`                | Formatted CPF                                    | `529.982.247-25`   |
| `number`             | Numeric string                                   | `42`               |
| `currency`           | Brazilian format with comma as decimal separator | `25.000,00`        |
| `date`               | `DD/MM/YYYY`                                     | `15/03/1990`       |
| `select`             | One of the allowed option values                 | `Sim`              |
| `radio_vertical`     | One of the allowed option values                 | `Sim`              |
| `checklist_vertical` | Comma-separated values                           | `Banco A, Banco B` |

## 4. Configure your Pipefy data destination

1. Describe your destination for easy identification within your organization. You can inform things like what data it brings, to which team it belongs, etc.

2. To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how frequently you need to have the data updated on the destination (every day, once a week, only at specific times, etc.).

3. Click **Done**.

### Check your new destination!

1. Once completed, you'll receive confirmation that your new destination is set up!

2. You can view your new destination on the [Destinations](https://app.nekt.ai/destinations) page. Now, for you to be able to see it on Pipefy, you have to wait for the pipeline to run. You can monitor it on the [Destinations](https://app.nekt.ai/destinations) page to see its execution and completion. If needed, manually trigger the pipeline by clicking on the refresh icon. Once executed, your data should be seen on Pipefy.

> If you encounter any issues, reach out to us via Slack, and we'll gladly assist you!