Update Phase Jumps

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: You must be able to manage the pipe the phase belongs to (pipe admin).
3. Phase IDs: The ID of the source phase, and the IDs of the phases cards may jump to from it.

Step 1: Find Your Phase IDs

1. Via Pipefy UI:
   1. Click on the gear button that appears when you hover over the phase title and a modal will open over the Kanban area.
   2. The URL will include the Phase ID: https://app.pipefy.com/pipes/1234/settings/phases/123456.
   3. Phase ID = 123456 (the number after /phases/).
2. Via GraphQL Query
   1. Check on our Get resource IDs page.

Step 2: Execute the Mutation

Use the updatePhaseJumps mutation to replace the jump targets of the phase:

mutation {
  updatePhaseJumps(input: {
    phaseId: 123456,
    targetPhaseIds: [123457, 123460]
  }) {
    success
  }
}

Arguments Breakdown

• phaseId: the ID of the phase whose jump targets you want to set.
• targetPhaseIds: the full list of phases cards can be moved to from this phase. The list replaces the current targets; send an empty list to remove every target. The argument is optional in the schema, but a call without it is rejected with INVALID_INPUT.

Example Response

{
  "data": {
    "updatePhaseJumps": {
      "success": true
    }
  }
}

Key Notes

• The list replaces every connection. When a phase is created, Pipefy connects it to its neighbouring phases. A call that sends only the new target removes those neighbour connections. To add or remove one connection, first read the current targets (next_phase_ids and previous_phase_ids on phase), then send the full list.
• Invalid IDs are rejected. IDs of phases from another pipe, of the start form, or of phases that do not exist return an INVALID_INPUT error naming them, for example Invalid input: targetPhaseIds (987654). Nothing is saved.
• targetPhaseIds must be sent. Omitting it, or sending null, returns Invalid input: targetPhaseIds (null) with INVALID_INPUT, and the current targets are kept.
• A phase cannot target itself. Including phaseId in targetPhaseIds returns a RECORD_INVALID error and keeps the current targets.
• Setting transitions with updatePhase. The jumpTargetIds argument of updatePhase replaces the same set of transitions while you update other phase settings, and createPhase can skip the neighbor links with connectNeighbors: false. See Set phase transitions. Unlike targetPhaseIds here, omitting jumpTargetIds leaves the transitions unchanged.
• Permissions: a user who cannot manage the pipe receives a PERMISSION_DENIED error.
• Unknown phase: a phaseId that does not exist, or that is the start form, returns Phase not found with id: <id> with RESOURCE_NOT_FOUND.