# Invite a contact to an existing partnership

`POST https://api.suger.cloud/org/{orgId}/prm/partner/{partnerId}/invitation`

Send a partner invitation for a partnership that already exists in this organization, addressed to a named recipient. This sends an email to that person and creates an invitation record in "Sent" state.

Use it to bring another person at a partner company onto an established partnership. It requires a partnerId, so it cannot start a relationship with a company that is not a partner yet.

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.

## Parameters

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

## Request Body

Required.

Content-Type: `application/json` · Schema: `partner.CreateInvitationRequest`

**`partner.CreateInvitationRequest`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aiContext` | string | no |  |
| `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` | partner.NewPartnerDetails | no |  |
| `partnershipId` | string | no |  |
| `purpose` | string | yes |  |
| `recipientEmail` | string | yes |  |
| `recipientName` | string | no |  |
| `tone` | string | yes |  |

**`partner.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 |  |

## Responses

### 200 — OK

Content-Type: `application/json` · Schema: `orm.PartnerInvitation`

**`orm.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 Suger 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 |
| --- | --- | --- | --- |
| `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. |
| `senderOrgId` | string | no | SenderOrgID is the resolved Suger 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 Suger 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 (PE-10710). |
| `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 (PE-11397 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 (PE-10264/PE-10431). 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. |
| `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. |
| `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. |
| `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. |

### 400 — Bad request error

Content-Type: `application/json`

---

Interactive API reference: https://doc.suger.io/api/