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.
Request
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
{
"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
"string" View as Markdown · API reference overview
Spotted something wrong or out of date on this page? Tell us and we'll correct it.