Invite a contact to a partnership or a new partner
POST https://api.suger.cloud/ai/org/{orgId}/prm/invitation
Send a partner invitation: an email to a named recipient, and an invitation record in "Sent" state. Needs partners.create. The body names exactly one target: `partnershipId` (the partnership id from ListPrmPartnerships) brings another person at an existing partner onto the partnership; `newPartner` (with its `partnerCompanyName`) invites a company that is not a partner yet, whose domain is classified and for which a partnership is created. Both, or neither, is refused with 400 before anything is sent. Sends real email to someone outside this organization. Confirm the recipient address before calling. Use ListPrmInvitations first to check whether that person already has an invitation pending, and CancelPrmInvitation to call one back. To edit and resend an invitation (a wrong recipient, a changed email), find it with ListPrmInvitations and call this with its id in `cancelInvitationId` and the same `partnershipId`, plus the full new message (copy what should stay the same from the old invitation's info.outbound). In one step the old invitation, if still Sent, is cancelled and its link stops working, and the new one is sent on the same partnership, to any recipient. An old invitation already Expired or Cancelled is left as it is; one Accepted or Declined refuses the call with 409 and nothing is sent. If the new invitation cannot be created, the old one is not cancelled. The email goes out after that step: if it cannot be delivered, the new invitation still exists with info.outbound.emailDelivery.status FAILED, the old one stays cancelled, and ResendPrmInvitation sends the new one again. Replacing needs partners.edit, and `cancelInvitationId` is not taken with `newPartner` (400). Safe to retry. A second call naming a recipient who already has an invitation in Sent state in this organization is refused with 409 and sends no second email; the guard matches the recipient address case-insensitively, so the same person cannot accumulate duplicate invitations. This is a uniqueness constraint on the pending invitation, NOT an idempotency key: it holds for as long as the first invitation is pending, and it does not return the existing invitation. The same 409 also reports a new partner already linked to a Fours partner organization; the response body says which case it is. Retry a call whose outcome you did not observe; treat 409 as "the invitation is already out", and call ListPrmInvitations to fetch it.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes | Organization ID |
Request Body
Required. Content-Type: application/json · Schema: CreateInvitationRequest
CreateInvitationRequest fields:
| Field | Type | Required | Description |
|---|---|---|---|
aiContext | string | no | |
cancelInvitationId | string | no | Optional, with partnershipId only. The id of an invitation on this same partnership that the new one replaces. If it is still Sent it is cancelled in the same step, so its link stops working; Expired or Cancelled ones are left as they are; an Accepted or Declined one refuses the call with 409. Needs partners.edit. Omit it to send an extra invitation. |
ccEmails | array<string> | no | |
contextMessage | string | no | |
createdBy | string | no | |
emailProvider | string | no | EmailProvider specifies which integration to use: "GOOGLE" (Gmail), "MICROSOFT" (Outlook), or "DNS" (the org's verified custom domain, org-level). If empty, tries Gmail first then Outlook as fallback. |
emailScope | string | no | EmailScope selects the sender identity: "user" (default) uses the sender's own connected Gmail/Outlook; "org" uses the org-level Gmail integration (shared service-account mailbox). Org scope is Gmail-only. |
messageBody | string | yes | |
messageSubject | string | yes | |
newPartner | NewPartnerDetails | no | A company that is not a partner yet. Send exactly one of newPartner and partnershipId. |
partnershipId | string | no | An existing partnership, from ListPrmPartnerships. Send exactly one of partnershipId and newPartner. |
purpose | string | yes | |
recipientEmail | string | yes | |
recipientName | string | no | |
referencedDocuments | array<InvitationReferencedDocument> | no | ReferencedDocuments are the partner agreements / shared files the sender chose to link from this invitation. The body carries a literal token per document; the server swaps each one for a real anchor when it renders the email, so the link is built from server data and never from anything the composer or the AI typed. |
tone | string | yes |
NewPartnerDetails fields:
| Field | Type | Required | Description |
|---|---|---|---|
crmObjectId | string | no | CrmObjectID links this new-partner invite to a CRM account (Salesforce Account Id) when sent from the "From your CRM" tab. Threaded onto the created partnership's info.crmAccountInfo at acceptance so CRM document sync can find it. Empty for non-CRM invites. |
intendedChannels | array<string> | no | |
partnerCompanyName | string | yes |
InvitationReferencedDocument fields:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | no | ID is the PartnerFile id. |
name | string | no | Name is the link text shown to the recipient. |
url | string | no | URL is the resolved link. Server-built at send time; never stored. |
Responses
200 — OK
Content-Type: application/json · Schema: PartnerInvitation
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) |
PartnerInvitationInfo fields:
| Field | Type | Required | Description |
|---|---|---|---|
inbound | InboundInvitationInfo | no | |
outbound | OutboundInvitationInfo | no |
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. |
InvitationEmailDelivery fields:
| Field | Type | Required | Description |
|---|---|---|---|
attemptedAt | string | no | AttemptedAt is the RFC3339 time of this attempt. |
provider | string | no | Provider is the identity the email actually left from: GOOGLE / MICROSOFT (the inviter's connected mailbox), DNS (the org's verified custom domain) or SUGER (the Fours SES sender, used when every configured mailbox was unavailable). Empty when Status is FAILED. |
reason | string | no | Reason is a curated failure code, present only when Status is FAILED: sender_unavailable (no mailbox could send and the Fours fallback failed too), send_failed (a mailbox rejected the message after dispatch, so the Fours fallback was not attempted to avoid a duplicate) or paired_inbound_missing (Case A: the recipient org's paired row could not be resolved, so no deep-link email was sent). The raw error stays in the server log — it carries internal ids. |
status | InvitationEmailDeliveryStatus | no |
InvitationReferencedDocument fields:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | no | ID is the PartnerFile id. |
name | string | no | Name is the link text shown to the recipient. |
url | string | no | URL is the resolved link. Server-built at send time; never stored. |
400 — Bad request error, or both or neither of partnershipId and newPartner
Content-Type: application/json
404 — No such partnership in this organization
Content-Type: application/json
409 — An invitation to this recipient is already pending (no second email was sent), or the new partner is already linked
Content-Type: application/json · Schema: PendingInvitationConflictPayload
PendingInvitationConflictPayload fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | string | no | |
message | string | no | |
recipientEmail | string | no |
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' \
-H "Authorization: Bearer $SUGER_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"partnershipId": "6f1c2a9e-3b7d-4e2a-9c1f-2d8e5a7b4c30",
"purpose": "network",
"tone": "alliance",
"recipientEmail": "dana.reyes@example.com",
"recipientName": "Dana Reyes",
"messageSubject": "Let's grow together",
"messageBody": "Hi Dana, we would like to bring you onto our partner program."
}' Response — 200
{
"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"
} 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.