Change a Partnership Task's Status

POST https://api.suger.cloud/ai/org/{orgId}/prm/partnershipTask/{taskId}/transition

Move a task to OPEN, IN_PROGRESS, BLOCKED or COMPLETED, sent as `to`, with the task's current `version` (from GetPartnershipTask). A task can move between any two statuses; asking for the status it already has is refused with 409 TASK_INVALID_TRANSITION, and a stale version with 409 TASK_VERSION_CONFLICT. A task with open subtasks can still be completed. Only the side a task is assigned to can move it: this organization can move a task it shared (`direction` OUTBOUND) when `assignedSide` is OUTBOUND or BOTH, and one received from the partner (INBOUND) when `assignedSide` is INBOUND or BOTH; otherwise the call answers 403 TASK_PARTNER_SIDE_NOT_ALLOWED. `taskId` is the task's `id` from ListPartnershipTasks. Moving a task that a journey step created also moves that step: COMPLETED completes the step, which can complete the journey and change the partner's tier, and any other status sets the step IN_PROGRESS.

Parameters

NameInTypeRequiredDescription
orgId path string yes Organization ID
taskId path string yes Task ID

Request Body

Required. Content-Type: application/json · Schema: TransitionPartnershipTaskRequest

TransitionPartnershipTaskRequest fields:

FieldTypeRequiredDescription
to string no
uiLabel string no
version integer no

Responses

200 — Transitioned task

Content-Type: application/json · Schema: PartnershipTask

PartnershipTask fields:

FieldTypeRequiredDescription
assignedSide string no OUTBOUND, INBOUND, or BOTH — which side does the work. Stored verbatim on both mirror rows (not flipped).
assigneeUserIds array<string> no User IDs assigned to this task on this side.
category string no Set from template.category at materialization; null otherwise
completedAt string no Set when status moves to COMPLETED; cleared on reopen
cppoOfferId string no Optional link to workload.offer.id (must be CPPO-typed and share partnership)
createTime string no Creation timestamp
createdByUserId string no Creator's user id. NULL on mirror rows (partner org has no real creator user).
createdByUserName string no Display name of the creator — both mirror rows carry the same value
description string no Optional free-form description
direction string no OUTBOUND or INBOUND.
dueAt string no Target due date
id string no ID of the ent. Unique partnership task identifier (UUID)
info PartnershipTaskInfo no
lastUpdateTime string no Last update timestamp
organizationId string no ISV org id — tenant isolation
partnershipId string no
priority string no URGENT, HIGH, NORMAL, LOW.
referralId string no Optional link to cosell.referral.id — validated to share partnership at write time
status string no OPEN, IN_PROGRESS, BLOCKED, COMPLETED.
tags array<string> no Free-form tag strings.
taskPairId string no Shared UUID that links the two mirror rows across a partnership
templateId string no Optional provenance link to prm.partnership_task_template.id — snapshot semantics
title string no Task title
version integer no Optimistic-concurrency counter; bumped on every write

PartnershipTaskInfo fields:

FieldTypeRequiredDescription
autoAssignUnresolved boolean no AutoAssignUnresolved is set when a role-based assignee was requested at create time but resolved to no one on either side. The task may still carry fixed assignees from the request; the UI shows the "no matching contact" warning badge only while the row has no assignees. On the partner-side mirror row the flag is set only for external roles; resolution FAILURES (as opposed to a genuine no-match) leave it unset.
journeyAssignmentId string no JourneyAssignmentID / JourneyStepID link a task materialized from a journey CUSTOM_TASK step back to that step. Set only on journey tasks; drives the "Journey task" badge and the bidirectional step↔task completion sync. Stored here (not as columns) to avoid a partnership_task migration.
journeyStepId string no
resources array<PartnershipTaskResource> no
subtasks array<PartnershipSubtask> no
marketingPoints MarketingPointsRequest no

PartnershipTaskResource fields:

FieldTypeRequiredDescription
attachedByOrgId string no AttachedByOrgID records which org's user attached this resource. The PATCH path uses it to enforce per-attacher delete: only the org that attached a resource may remove it. Empty values are treated as source-side-owned by the update validator (legacy rows from before this field existed); only the source org can prune them.
displayName string no
externalUrl string no
file PartnershipTaskResourceFile no
kind string no
partnerFileId string no

PartnershipSubtask fields:

FieldTypeRequiredDescription
assigneeUserId string no AssigneeUserID is the org-local user assigned to this subtask. Per-side: each mirror row carries its own value and it is not synced across the partnership pair.
completedAt string no CompletedAt is stamped by the server when a subtask is saved with status == COMPLETED and CompletedAt is nil, so clients can just flip the status and let the server handle the timestamp.
priority string no
status string no
title string no

MarketingPointsRequest fields:

FieldTypeRequiredDescription
activityTypeId string no
activityName string no
points integer no
activityDate string no
journeyAssignmentId string no
journeyStepId string no

PartnershipTaskResourceFile fields:

FieldTypeRequiredDescription
available boolean no
name string no
sizeBytes integer no
type string no

400 — Validation error

Content-Type: application/json

409 — Status unchanged (TASK_INVALID_TRANSITION) or stale version (TASK_VERSION_CONFLICT)

Content-Type: application/json

500 — Internal server error

Content-Type: application/json

Example

The request bodies are this operation's documented examples; the response and error bodies are generated from its schema. Substitute your own ids, and set SUGER_TOKEN to a bearer token from the OAuth client-credentials exchange.

Request

curl -X POST 'https://api.suger.cloud/ai/org/{orgId}/prm/partnershipTask/{taskId}/transition' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "to": "COMPLETED",
  "version": 4
}'

Response — 200

{
  "assignedSide": "string",
  "assigneeUserIds": [
    "01H0000000000000000000"
  ],
  "category": "string",
  "completedAt": "string",
  "cppoOfferId": "01H0000000000000000000",
  "createTime": "2026-01-31T12:00:00Z",
  "createdByUserId": "01H0000000000000000000",
  "createdByUserName": "Acme Corp",
  "description": "string",
  "direction": "string",
  "dueAt": "string",
  "id": "01H0000000000000000000"
}

Error — 400

"string"

View as Markdown · API reference overview

Spotted something wrong or out of date on this page? Tell us and we'll correct it.