# Create a task on a partnership

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

Create a task on one partnership. `partnershipId` (from ListPrmPartnerships), `title` and `direction` are required. Send `direction` OUTBOUND: the task is this organization's and is shared with the partner, who sees it as INBOUND. INBOUND records a task received from the partner, on which this organization can then change only the assignees and resources. `assignedSide` says who does the work: OUTBOUND (this organization), INBOUND (the partner) or BOTH (the default); only that side can later change the task's status. The partner sees the task only when it is a Fours organization (its `partnerOrgId` in ListPrmPartnerships is set); for any other partner use OUTBOUND or BOTH, or nobody can move the task.

Optional: `description`, `priority` (URGENT, HIGH, NORMAL by default, LOW), `dueAt` (RFC 3339), `assigneeUserIds` (users of this organization), `tags`, `subtasks`, `resources`, and a `referralId` (one of this organization's co-sell referrals) or `cppoOfferId` (one of its CPPO offers); one that is not found answers 409. The task starts OPEN at version 1.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |

## Request Body

Required.

Content-Type: `application/json` · Schema: `CreatePartnershipTaskRequest`

**`CreatePartnershipTaskRequest`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `assignedSide` | string | no | AssignedSide picks who does the work. Empty defaults to BOTH. |
| `assigneeContactType` | string | no | Assign by role: PARTNER_MANAGER (this organization's manager for the partnership) or CHAMPION_CONTACT (the partner's champion contact), resolved against the partnership's contacts when the task is created. A role that resolves to no one leaves that side unassigned and sets info.autoAssignUnresolved; assigneeUserIds still apply. |
| `assigneeUserIds` | array<string> | no | AssigneeUserIDs is the list of org-local users assigned to the task on the source side. Empty = unassigned. Per-side: the mirror row starts with an empty list; the partner org can set its own assignees later. |
| `category` | string | no |  |
| `cppoOfferId` | string | no |  |
| `description` | string | no |  |
| `direction` | string | no |  |
| `dueAt` | string | no |  |
| `partnershipId` | string | no |  |
| `priority` | string | no |  |
| `referralId` | string | no |  |
| `resources` | array<PartnershipTaskResource> | no |  |
| `subtasks` | array<PartnershipSubtask> | no |  |
| `tags` | array<string> | no |  |
| `templateId` | string | no |  |
| `title` | string | no |  |

**`PartnershipTaskResource`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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 |  |

**`PartnershipTaskResourceFile`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `available` | boolean | no |  |
| `name` | string | no |  |
| `sizeBytes` | integer | no |  |
| `type` | string | no |  |

## Responses

### 201 — Created task

Content-Type: `application/json` · Schema: `PartnershipTask`

**`PartnershipTask`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activityTypeId` | string | no |  |
| `activityName` | string | no |  |
| `points` | integer | no |  |
| `activityDate` | string | no |  |
| `journeyAssignmentId` | string | no |  |
| `journeyStepId` | string | no |  |

**`PartnershipTaskResourceFile`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `available` | boolean | no |  |
| `name` | string | no |  |
| `sizeBytes` | integer | no |  |
| `type` | string | no |  |

### 400 — Validation error

Content-Type: `application/json`

### 403 — A marketing points request from the seller side, on an inactive partnership, or to a program that is not active

Content-Type: `application/json` · Schema: `PrmTierErrorMessage`

**`PrmTierErrorMessage`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | no |  |

### 404 — A marketing points request on a partnership that is not this organization's

Content-Type: `application/json` · Schema: `PrmTierErrorMessage`

**`PrmTierErrorMessage`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | string | no |  |

### 409 — Referral or CPPO offer not found in this organization

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](https://doc.fours.com/settings/oauth-app/)._

### Request

```bash
curl -X POST 'https://api.suger.cloud/ai/org/{orgId}/prm/partnershipTask' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "partnershipId": "6f1c3a9e-0b2d-4c7e-8a15-3d9b0e2f4c61",
  "title": "Send the co-sell playbook",
  "direction": "OUTBOUND",
  "priority": "HIGH",
  "dueAt": "2026-12-04T17:00:00Z"
}'
```

### Response — 201

```json
{
  "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

```json
"string"
```

---

API reference: https://doc.fours.com/api/
