# Accept or decline an invitation this organization received

`POST https://api.suger.cloud/ai/org/{orgId}/prm/invitation/{invitationId}/respond`

Answer an invitation this organization received: an ISV's invitation to this partner organization, or a company's application to this seller's partner program. Needs partners.edit. `invitationId` is an inbound invitation's id from ListPrmInvitations (inbound rows still in "Sent").

`decision` is required, with no default. ACCEPT links the partnership: for an invitation both organizations' rows are accepted and the partnership is created or updated on both sides in one transaction, visible to the sender at once; for an application the applicant becomes a partner. DECLINE is final: no partnership is created and the invitation cannot be accepted later. An optional `reason` (DECLINE only, up to 4000 characters) is kept on the invitation and sent in the decline email.

Only an inbound invitation still awaiting an answer can be answered: an unknown id, or another organization's, is 404; this organization's own outbound invitation is 400 (withdraw it with CancelPrmInvitation instead); one already answered or expired is 409.

## Parameters

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

## Request Body

Required.

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

**`RespondToPrmInvitationRequest`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | string | yes | ACCEPT links the partnership; DECLINE is final. Required, with no default. |
| `reason` | string | no | DECLINE only, optional, up to 4000 characters. It is kept on the invitation and included in the decline email. |

## Responses

### 200 — OK

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

**`RespondToPrmInvitationResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inbound` | PartnerInvitation | yes |  |
| `outbound` | PartnerInvitation | yes |  |
| `recipientPartnership` | Partnership | yes |  |
| `senderPartnership` | Partnership | yes |  |

**`PartnerInvitation`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `createTime` | string | no | Creation timestamp |
| `createdBy` | string | no | ISV user ID who sent the invitation (outbound), null for inbound |
| `direction` | string | no | OUTBOUND (ISV invites partner) or INBOUND (partner applies via public URL) |
| `engagementId` | string | no | Shared identifier that pairs an outbound invitation with its inbound counterpart (Case A paired send, Cases B/C accept-synthesized). Null for non-paired rows. |
| `expiresAt` | string | no | When the invitation expires. Defaults at the DB to 15 days after insert (CURRENT_TIMESTAMP + 15 days); past this it can no longer be accepted/declined and the daily cron marks it Expired. |
| `id` | string | no | ID of the ent. Unique invitation identifier (UUID) |
| `info` | PartnerInvitationInfo | no |  |
| `lastUpdateTime` | string | no | Last update timestamp |
| `organizationId` | string | no | The ISV organization that owns this invitation |
| `partnerOrganizationId` | string | no | The partner's Fours org ID, set on acceptance after org provisioning |
| `partnershipId` | string | no | Target partnership. Nullable for inbound invitations before a partner record exists. |
| `purpose` | string | no | Invitation purpose: network, account_overlap, deal_collaboration |
| `respondedAt` | string | no | When the recipient responded (accepted or declined) |
| `sentAt` | string | no | When the invitation was sent (outbound) or submitted (inbound) |
| `status` | string | no | Invitation status: Sent, Accepted, Declined, Expired |
| `trackingToken` | string | no | UUID token for accept/decline links (outbound) or form URL (inbound) |

**`Partnership`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `companyId` | string | no | The partner's company ID from identity.buyer.company_id, used to group buyers across channels |
| `createTime` | string | no | Creation timestamp |
| `domain` | string | no | Lowercased email domain of the partner (the OTHER side of the relationship). Used for dedup/lookup when provisioning partnerships from inbound flows where the partner has no Fours org and no engagement_id pairing exists. |
| `globalCompanyId` | string | no | Links partnership to canonical company record for firmographic data |
| `id` | string | no | ID of the ent. Unique partnership identifier (UUID) |
| `info` | PartnershipInfo | no |  |
| `lastActivityTime` | string | no | Most recent activity timestamp (e.g., latest CPPO transaction), updated by sync job |
| `lastUpdateTime` | string | no | Last update timestamp |
| `organizationId` | string | no | The org that owns this partnership record (seller) |
| `partnerManager` | string | no |  |
| `partnerOrgId` | string | no | The partner's own Fours org ID (nullable if partner is not a Fours org) |
| `partnerTypes` | array<string> | no | Types of partner: RESELLER, SI (System Integrator), ISV, OTHER |
| `partnershipSince` | string | no | When the partnership was established (e.g., first CPPO transaction date) |
| `status` | AiStatus | no |  |

**`PartnerInvitationInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `inbound` | InboundInvitationInfo | no |  |
| `outbound` | OutboundInvitationInfo | no |  |

**`PartnershipInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aiOverview` | PartnershipAiOverview | no |  |
| `buyerIds` | array<string> | no | BuyerIDs lists the Fours internal buyer IDs grouped under this partnership. Used by frontend to query CPPO offers via the existing offer API. |
| `channels` | array<string> | no | Channels lists the cloud marketplaces this partner operates on (e.g., ["AWS", "AZURE"]). |
| `crmAccountInfo` | CrmAccountInfo | no |  |
| `crmPartnerChampion` | AiPartnerChampionContact | no |  |
| `crmPartnerManager` | CrmPartnerManager | no |  |
| `customCommissionPlanId` | string | no | Empty/unset means "use Standard Defaults". The share-cosell flow uses this to prepopulate Revenue Share fields per commission type at deal-create time. |
| `description` | string | no | Description is a brief partner summary |
| `displayName` | string | no | DisplayName is the name the ISV chose to show for this partner. Written only by the partner PATCH: discovery sync and the partner org's Company Name propagation write Name and never touch it. When it has text the console shows it instead of Name (see ShownName). |
| `employees` | string | no | Employees is the partner's employee count as a string, derived from enriched company info. |
| `engagementType` | EngagementType | no |  |
| `founded` | string | no | Founded is the partner's founding year, derived from enriched company info. |
| `globalCompanyContactIds` | array<string> | no |  |
| `location` | string | no | Location is the partner's location (e.g., "Dover, Delaware"), derived from buyer company info. |
| `matchingAccounts` | array<MatchingCrmAccount> | no | MatchingAccounts lists the CRM accounts whose domain matches the partner's managed accounts. Only populated for partnerships with SUGGESTED status. |
| `name` | string | no | Name is the partner's display name, derived from the buyer with the most complete data. |
| `ourTier` | PartnerTier | no |  |
| `ourTierActivityTypes` | array<TierActivityType> | no | , read time only, beside ourTier. The partner org's marketing activity list, what Earn points offers in its program. Left out when it has none. |
| `ourTierSince` | string | no | , read time only, beside ourTier. When the partner org set ourTier (its own row's partnerTierSince). |
| `partnerBrand` | PartnerBrand | no |  |
| `partnerChampionContact` | AiPartnerChampionContact | no |  |
| `partnerTier` | string | no | PartnerTier is the ID of the tier this partner is assigned in the owning org's ISV-defined tier hierarchy. References a PartnerTier.ID in the org's PartnershipConfigInfo.Tiers. Set to the default tier when the partnership is created. Empty means "fall back to the org's default tier" at read time (e.g. a tier was deleted). |
| `partnerTierSince` | string | no | . When partnerTier last changed. |
| `partnerViewTemplateId` | string | no | Empty/unset means "fall back to the org's Default Template" at render time. |
| `potentialRevenue` | number | no | PotentialRevenue is the total opportunity amount from matching CRM accounts. Only populated for partnerships with SUGGESTED status. |
| `recommendationReason` | string | no | RecommendationReason is an AI-generated human-readable explanation of why this partner is recommended. Only populated for partnerships with SUGGESTED status. |
| `recommendationScore` | number | no | RecommendationScore is a normalized score (0.0–1.0) indicating how good a match this partner is for the ISV. Only populated for partnerships with SUGGESTED status. |
| `relationshipType` | RelationshipType | no |  |
| `revenueByChannel` | object | no | RevenueByChannel is revenue broken down by cloud channel and YYYY-MM period. Example: {"AWS": {"2026-01": 50000}, "AZURE": {"2026-02": 30000}}. |
| `scoreBreakdown` | RecommendationScoreBreakdown | no |  |
| `sellerIds` | object | no | SellerIDs maps cloud partner to the partner's cloud-specific account ID. AWS -> AWS Account ID (12-digit), AZURE -> Azure MPO Seller ID. Used by frontend to pre-populate the reseller account field when creating CPPOs. |
| `slackChannelId` | string | no | SlackChannelID is the Slack channel this partner's broadcasts / co-sell activity post to. Empty/unset ⇒ no channel configured. |
| `slackChannelName` | string | no | SlackChannelName caches the channel's display name (e.g. "partner-cloudsync-suger"). |
| `sugerCosellMetrics` | PartnershipSugerCosellMetrics | no |  |
| `suggestedRelationshipType` | RelationshipType | no |  |
| `totalDeals` | integer | no | TotalDeals is the total count of CPPO-related offers for this partner. |
| `totalRevenue` | number | no | TotalRevenue is the sum of disbursed CPPO-attributed revenue for this partner. |
| `upcomingRevenue` | number | no | UpcomingRevenue is the total CommitAmount from active CPPO_OUT offers minus disbursed revenue. |

**`InboundInvitationInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `declineReason` | string | no | DeclineReason is what the ISV wrote when it declined this application. Kept on the record and sent in the decline email. |
| `formData` | object | no | FormData holds the submitted form field values. |
| `formId` | string | no | FormID is the ID of the form configuration used for this submission. |
| `responseMessage` | string | no | ResponseMessage explains how this application reached its current status when something other than a human on the Applications surface decided it. Today that is one case: the ISV accepted the applicant's co-sell, which provisions them as a partner and therefore settles the application too — including reversing an earlier Declined or Expired, because a provisioned partner with a live deal cannot also be a rejected applicant. Without the note the Applications tab would show a reversal with no cause. Distinct from OutboundInvitationInfo.ResponseMessage, which carries the RECIPIENT's own words when they answer an invitation the ISV sent. These are inbound rows: nobody replied, the system reconciled them. |
| `senderOrgId` | string | no | SenderOrgID is the resolved Fours org of the applicant who submitted this inbound application (the sender / partner side). Optional: set at submit time only when the work-email domain matches exactly ONE production, PRM-enabled-or-PARTNER Fours org; empty when zero or multiple matched. Read at accept time to link the ISV-side partnership to this org and create the reciprocal partnership record on the sender side. |
| `submitterEmail` | string | no | SubmitterEmail is the email of the partner who submitted the form. |
| `submitterName` | string | no | SubmitterName is the name of the partner who submitted the form. |

**`OutboundInvitationInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `acceptInitiatedAt` | string | no | AcceptInitiatedAt (RFC3339) is stamped when the recipient submits the public accept form (records intent + ResponseMessage) BEFORE signing in via Auth0. The authenticated finalize step requires it before verifying the Auth0 email against RecipientEmail and provisioning ( two-step accept flow). |
| `aiContext` | string | no | AIContext is additional context provided for AI email generation. |
| `ccEmails` | array<string> | no | CcEmails is the list of CC email addresses. |
| `contextMessage` | string | no | ContextMessage is the user-provided engagement context. |
| `crmObjectId` | string | no | CrmObjectID is the CRM account record id (Salesforce Account Id) this invite was created from in the "From your CRM" flow (/). Threaded to acceptance so the created ISV-side partnership is linked to its CRM account (info.crmAccountInfo.accountId) — which the CRM document sync relies on. Empty for non-CRM invites. Salesforce-only today. |
| `emailDelivery` | InvitationEmailDelivery | no |  |
| `emailProvider` | string | no | EmailProvider is the sender integration the original send resolved to: "GOOGLE", "MICROSOFT" or "DNS" (the org's verified custom domain). Empty on legacy rows and when the sender did not pin one. Persisted so a RESEND re-uses the same identity — without it a resend silently falls back to the user-scope Gmail/Outlook path, which changes the From address (and DMARC alignment) for an org that deliberately sent over DNS or org-scope Gmail. |
| `emailScope` | string | no | EmailScope is "user" (the sender's own mailbox, the default) or "org" (the org-level Gmail service account). Persisted for the same reason as EmailProvider — see above. |
| `intendedChannels` | array<string> | no | IntendedChannels is the marketplace channel classification computed at send time from the recipient email's domain: ["Direct"] for Case B, the matched marketplace(s) for Case C, and the matched org's inferred channels (or ["Direct"]) for Case A. Used at acceptance to populate the ISV-side partnership's info.channels when an ISV-side partnership must be created from the invitation. |
| `kind` | string | no | Kind is "member" for an invitation to join a partner's existing Fours workspace: the partnership is already active on both sides, so accepting only seats the person in that workspace. Empty for an invitation to become a partner. |
| `messageBody` | string | no | MessageBody is the final email body (HTML). |
| `messageSubject` | string | no | MessageSubject is the final email subject line. |
| `partnerCompanyName` | string | no | PartnerCompanyName is the free-text partner company name entered by the sender in "Invite a new partner" mode. Unset when the invitation is for a pre-existing partnership (Select Recommended Partner mode). |
| `recipientEmail` | string | no | RecipientEmail is the partner contact email the invitation was sent to. |
| `recipientName` | string | no | RecipientName is the partner contact name. |
| `referencedDocuments` | array<InvitationReferencedDocument> | no | ReferencedDocuments are the agreements / shared files this invitation linked. Doubles as the allow-list the public document route checks — see InvitationReferencedDocument. |
| `responseMessage` | string | no | ResponseMessage is the partner's response when accepting or declining the invitation. Mandatory for Accepted invitations, optional for Declined. |
| `tone` | string | no | Tone is the selected email tone: executive, sales, technical, alliance, tactical. |

**`PartnershipAiOverview`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cloudTier` | string | no | CloudTier is the partner's cloud marketplace tier level. |
| `description` | string | no | Description is a brief AI-generated summary of the partner company. |
| `employeeRange` | string | no | EmployeeRange is the approximate employee count range (e.g., "100-500"). |
| `error` | string | no | Error holds the error message if generation failed. |
| `foundedYear` | string | no | FoundedYear is the year the company was founded. |
| `headquarters` | string | no | Headquarters is the company's headquarters location (e.g., "San Francisco, CA, USA"). |
| `keyProducts` | array<string> | no | KeyProducts lists the partner's key products or services. |
| `knownCustomers` | array<string> | no | KnownCustomers lists notable customers of the partner. |
| `lastScraped` | string | no | LastScraped is the timestamp of the last AI overview generation (RFC3339). |
| `retryCount` | integer | no | RetryCount is the number of consecutive failed generation attempts for this partnership. The daily Sync Partnerships workflow caps retries at 3 and only retries after a 14-day backoff (see). |
| `specializations` | array<string> | no | Specializations lists the partner's technical specializations. |
| `status` | string | no | Status indicates the generation result: empty for success, "failed" or "empty" on error. |
| `targetIndustries` | array<string> | no | TargetIndustries lists the industries the partner focuses on. |
| `website` | string | no | Website is the partner's website URL as reported by AI. |

**`CrmAccountInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | string | no | AccountID is the CRM account/company record ID. |
| `accountName` | string | no | AccountName is the display name of the CRM account. |
| `provider` | string | no | Provider identifies which CRM the account belongs to ("SALESFORCE" or "HUBSPOT"). |

**`AiPartnerChampionContact`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contactId` | string | no | ContactID is the CRM contact record ID. |
| `email` | string | no | Email is the contact's email address. |
| `name` | string | no | Name is the contact's full name. |
| `title` | string | no | Title is the contact's job title. |

**`CrmPartnerManager`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | no | Email is the CRM user's email, lowercased. |
| `name` | string | no | Name is the CRM user's full name. |
| `status` | CrmPartnerManagerStatus | no |  |

**`MatchingCrmAccount`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accountId` | string | no | AccountID is the CRM account record ID. |
| `accountName` | string | no | AccountName is the display name of the CRM account. |
| `domain` | string | no | Domain is the normalized domain of the CRM account's website. |
| `opportunityAmount` | number | no | OpportunityAmount is the total opportunity revenue from this account. |
| `opportunityCount` | integer | no | OpportunityCount is the number of opportunities on this account. |

### 400 — No or an unknown decision, a reason with ACCEPT, an over-long reason, or this organization's own outbound invitation

Content-Type: `application/json`

### 404 — No such inbound invitation in this organization

Content-Type: `application/json`

### 409 — Already answered, or expired

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/invitation/{invitationId}/respond' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "decision": "DECLINE",
  "reason": "Not this quarter"
}'
```

### Response — 200

```json
{
  "inbound": {
    "createTime": "2026-01-31T12:00:00Z",
    "createdBy": "string",
    "direction": "string",
    "engagementId": "01H0000000000000000000",
    "expiresAt": "string",
    "id": "01H0000000000000000000",
    "info": {
      "inbound": {
        "declineReason": "string",
        "formData": {},
        "formId": "01H0000000000000000000",
        "responseMessage": "string",
        "senderOrgId": "01H0000000000000000000",
        "submitterEmail": "buyer@example.com",
        "submitterName": "Acme Corp"
      },
      "outbound": {
        "acceptInitiatedAt": "string",
        "aiContext": "string",
        "ccEmails": [
          "buyer@example.com"
        ],
        "contextMessage": "string",
        "crmObjectId": "01H0000000000000000000",
        "emailDelivery": {
          "attemptedAt": "string",
          "provider": "string",
          "reason": "string",
          "status": "SENT"
        },
        "emailProvider": "buyer@example.com",
        "emailScope": "buyer@example.com",
        "intendedChannels": [
          "string"
        ],
        "kind": "string",
        "messageBody": "string",
        "messageSubject": "string"
      }
    },
    "lastUpdateTime": "2026-01-31T12:00:00Z",
    "organizationId": "01H0000000000000000000",
    "partnerOrganizationId": "01H0000000000000000000",
    "partnershipId": "01H0000000000000000000",
    "purpose": "string"
  },
  "outbound": {
    "createTime": "2026-01-31T12:00:00Z",
    "createdBy": "string",
    "direction": "string",
    "engagementId": "01H0000000000000000000",
    "expiresAt": "string",
    "id": "01H0000000000000000000",
    "info": {
      "inbound": {
        "declineReason": "string",
        "formData": {},
        "formId": "01H0000000000000000000",
        "responseMessage": "string",
        "senderOrgId": "01H0000000000000000000",
        "submitterEmail": "buyer@example.com",
        "submitterName": "Acme Corp"
      },
      "outbound": {
        "acceptInitiatedAt": "string",
        "aiContext": "string",
        "ccEmails": [
          "buyer@example.com"
        ],
        "contextMessage": "string",
        "crmObjectId": "01H0000000000000000000",
        "emailDelivery": {
          "attemptedAt": "string",
          "provider": "string",
          "reason": "string",
          "status": "SENT"
        },
        "emailProvider": "buyer@example.com",
        "emailScope": "buyer@example.com",
        "intendedChannels": [
          "string"
        ],
        "kind": "string",
        "messageBody": "string",
        "messageSubject": "string"
      }
    },
    "lastUpdateTime": "2026-01-31T12:00:00Z",
    "organizationId": "01H0000000000000000000",
    "partnerOrganizationId": "01H0000000000000000000",
    "partnershipId": "01H0000000000000000000",
    "purpose": "string"
  },
  "recipientPartnership": {
    "companyId": "01H0000000000000000000",
    "createTime": "2026-01-31T12:00:00Z",
    "domain": "string",
    "globalCompanyId": "01H0000000000000000000",
    "id": "01H0000000000000000000",
    "info": {
      "aiOverview": {
        "cloudTier": "string",
        "description": "string",
        "employeeRange": "string",
        "error": "string",
        "foundedYear": "string",
        "headquarters": "string",
        "keyProducts": [
          "string"
        ],
        "knownCustomers": [
          "string"
        ],
        "lastScraped": "string",
        "retryCount": 1,
        "specializations": [
          "string"
        ],
        "status": "string"
      },
      "buyerIds": [
        "01H0000000000000000000"
      ],
      "channels": [
        "string"
      ],
      "crmAccountInfo": {
        "accountId": "01H0000000000000000000",
        "accountName": "Acme Corp",
        "provider": "string"
      },
      "crmPartnerChampion": {
        "contactId": "01H0000000000000000000",
        "email": "buyer@example.com",
        "name": "Acme Corp",
        "title": "string"
      },
      "crmPartnerManager": {
        "email": "buyer@example.com",
        "name": "Acme Corp",
        "status": "MATCHED"
      },
      "customCommissionPlanId": "01H0000000000000000000",
      "description": "string",
      "displayName": "Acme Corp",
      "employees": "string",
      "engagementType": "RESELLER",
      "founded": "string"
    },
    "lastActivityTime": "2026-01-31T12:00:00Z",
    "lastUpdateTime": "2026-01-31T12:00:00Z",
    "organizationId": "01H0000000000000000000",
    "partnerManager": "string",
    "partnerOrgId": "01H0000000000000000000",
    "partnerTypes": [
      "string"
    ]
  },
  "senderPartnership": {
    "companyId": "01H0000000000000000000",
    "createTime": "2026-01-31T12:00:00Z",
    "domain": "string",
    "globalCompanyId": "01H0000000000000000000",
    "id": "01H0000000000000000000",
    "info": {
      "aiOverview": {
        "cloudTier": "string",
        "description": "string",
        "employeeRange": "string",
        "error": "string",
        "foundedYear": "string",
        "headquarters": "string",
        "keyProducts": [
          "string"
        ],
        "knownCustomers": [
          "string"
        ],
        "lastScraped": "string",
        "retryCount": 1,
        "specializations": [
          "string"
        ],
        "status": "string"
      },
      "buyerIds": [
        "01H0000000000000000000"
      ],
      "channels": [
        "string"
      ],
      "crmAccountInfo": {
        "accountId": "01H0000000000000000000",
        "accountName": "Acme Corp",
        "provider": "string"
      },
      "crmPartnerChampion": {
        "contactId": "01H0000000000000000000",
        "email": "buyer@example.com",
        "name": "Acme Corp",
        "title": "string"
      },
      "crmPartnerManager": {
        "email": "buyer@example.com",
        "name": "Acme Corp",
        "status": "MATCHED"
      },
      "customCommissionPlanId": "01H0000000000000000000",
      "description": "string",
      "displayName": "Acme Corp",
      "employees": "string",
      "engagementType": "RESELLER",
      "founded": "string"
    },
    "lastActivityTime": "2026-01-31T12:00:00Z",
    "lastUpdateTime": "2026-01-31T12:00:00Z",
    "organizationId": "01H0000000000000000000",
    "partnerManager": "string",
    "partnerOrgId": "01H0000000000000000000",
    "partnerTypes": [
      "string"
    ]
  }
}
```

### Error — 400

```json
"string"
```

---

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