# Create a co-sell referral (outbound)

`POST https://api.suger.cloud/org/{orgId}/cosell/referral`

Create a new outbound co-sell referral to share a sales opportunity with a cloud partner (AWS / AZURE / GCP). Can also resubmit a previously failed referral.

Request body is `orm.CosellReferral` with `partner` set and the partner-specific opportunity nested under `info` (NOT flat top-level fields). Required nested paths by partner:
- AWS:   `info.aceOpportunityV2.customer.account.companyName`, `.account.industry`, `.account.websiteUrl`, `.account.address.countryCode`, `info.aceOpportunityV2.project.title`, `.project.customerUseCase`, `info.aceOpportunityV2.lifeCycle.targetCloseDate`.
- AZURE: `info.microsoftReferralSet.self.name` (Deal Name), `.customerProfile.address.country`, at least one `.team[]` entry with `email`/`firstName`/`lastName`/`phoneNumber`, and `.details.closingDateTime`.
- GCP:   `info.gcpOpportunityV2.customerInfo.customerDetails.organizationName`, `.domain`, `.address.regionCode`, `.industry`, `.employeeCount`, and `info.gcpOpportunityV2.customerInfo.contact.{givenName,familyName,email}`.

Call ValidateReferral first to surface missing fields.

Submission is automatic: the create workflow fires immediately and submits to the partner — DO NOT call SyncSingleReferral afterwards for the initial submit. Resulting status is PENDING_CREATE on success, or CREATE_FAILED if the partner API rejects (resubmit by re-calling this endpoint).

Exception: if the org has the referral approval process enabled AND the referral's `approvalInfo.status` is not "Approved" (and this is a brand-new referral, not a resubmit), the referral is saved as DRAFT and the workflow does NOT fire. The user must approve via the Suger Console before the workflow runs.

Note that PATCH UpdateCosellReferral accepts business-field edits but the unified `status` is recomputed server-side from partner-specific fields (e.g. AWS uses `info.aceOpportunityV2.lifeCycle`), so passing a top-level `status` is not how you change state.

NOTE: `partner=SUGER` (Suger PRM peer-to-peer referrals) is not exposed through this MCP tool — use the Suger console for that flow.

Use this when: user wants to share a sales opportunity with a cloud partner.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |
| `forceCreate` | query | boolean | no | Force creation in DB regardless of cloud partner submission result |

## Request Body

Required.

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

## Responses

### 200 — OK

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

### 400 — Bad request error

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

### 500 — Internal server error

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

---

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