Create a Referral via API

Build and submit an outbound co-sell referral to AWS, Microsoft (Azure), or Google Cloud (GCP) directly through the Suger API.

Overview

This page is the developer companion to the Outbound Referral UI walkthrough. It documents the request payload for one endpoint:

POST /org/{orgId}/cosell/referral

• Auth: API key (Authorization header). See Authentication.
• Query param: forceCreate (boolean, optional). When true, the referral is saved in Suger even if it fails validation or the partner rejects it, so you can fix and resubmit later. Default false.
• Response: 200 with an OperationExecutionDetails object (contains the workflowID of the submission). On validation failure you get 400 with an info array of per-field errors (see Validate first).

One endpoint serves all three clouds. The cloud is chosen by the top-level partner field, and the partner-specific opportunity goes in a matching slot under info. Submission is automatic — the create workflow fires immediately and pushes the referral to the partner. Do not call a sync afterwards for the initial submit. The resulting status is PENDING_CREATE on success or CREATE_FAILED if the partner API rejects it (resubmit by calling this endpoint again).

The envelope

Every request body has the same outer shape, regardless of cloud:

{
  "partner": "AWS",                        // "AWS" | "AZURE" | "GCP"
  "salesforceOpportunityId": "0065g...",   // optional: link to a CRM opportunity
  "salesforceAccountId": "0015g...",       // optional: link to the CRM account
  "info": {
    // exactly one slot, matching `partner` — see table below
  },
  "metaInfo": { /* optional */ },
  "approvalInfo": { /* optional, for the approval workflow */ }
}

The partner-specific opportunity lives in a different info slot for each cloud:

Two tiers of “required”

Throughout this page, required fields fall into two groups:

• Required by Suger — missing/invalid values return a 400 before anything reaches the cloud partner. These are the hard blockers.
• Required by the cloud partner — Suger may accept the payload, but AWS/Microsoft/Google will reject it. Suger’s auto-enrich and auto-fix features try to fill some of these; the authoritative list is each cloud’s own API reference, linked per section.

Validate first

Before creating, dry-run the payload against the partner schema:

POST /org/{orgId}/cosell/referral/validate

Send the same envelope you would POST to /referral. A failing response returns the field-level errors so you can correct the payload without creating a CREATE_FAILED record:

{
  "code": "BAD_REQUEST",
  "message": "failed to validate ...",
  "info": [
    { "field": "customer.account.industry", "message": "'Industry vertical' is required" },
    { "field": "relatedEntityIdentifiers.solutions", "message": "'Solutions' is required" }
  ]
}

AWS

Send the opportunity under info.aceOpportunityV2. Field keys use PascalCase (e.g. Customer, LifeCycle), matching the AWS Partner Central Selling API.

Required by Suger

Also required by AWS (Suger does not block these)

Suger’s validator passes without these, but they are flagged requiredForCreation in the AWS ACE schema — AWS rejects the submission without them, so Suger accepts the payload and the AWS step then fails as CREATE_FAILED. The example below includes all of them:

So beyond Suger’s hard-blocked list, the fields you must supply for AWS to accept are Origin, OpportunityType, Project.Title, Project.CustomerBusinessProblem, Project.CustomerUseCase, Project.DeliveryModels, and Project.ExpectedCustomerSpend.Amount. The create path runs ValidateAndAIFix, which only repairs fields that are present but invalid within a fixed allowlist — it does not invent missing ones, and Solutions / TargetCloseDate aren’t auto-fixable at all. The authoritative list is the AWS CreateOpportunity reference.

Auto-filled / normalized by Suger

• Catalog — set from your connected AWS integration (AWS or Sandbox). Don’t send it.
• Project.ExpectedCustomerSpend[0] — the first entry’s Frequency→Monthly, CurrencyCode→USD, TargetCompany→AWS are always overwritten (AWS only accepts these for this object). You supply Amount.
• Marketing.Source defaults to "None"; Project.SalesActivities defaults if empty.
• NationalSecurity is forced to "Yes" when Industry is "Government".
• Contacts/team without a valid email are dropped; the first OpportunityTeam member defaults to BusinessTitle: "PartnerAccountManager".

PrimaryNeedsFromAws values: Co-Sell - Architectural Validation, Co-Sell - Business Presentation, Co-Sell - Competitive Information, Co-Sell - Pricing Assistance, Co-Sell - Technical Consultation, Co-Sell - Total Cost of Ownership Evaluation, Co-Sell - Deal Support, Co-Sell - Support for Public Tender / RFx, or Do Not Need Support from AWS Sales Rep.

For the full list of valid Industry, CountryCode, CustomerUseCase, and DeliveryModels values, see the AWS CreateOpportunity API reference.

Example payload (AWS)

This mirrors the field set the Suger Console submits (the Share with AWS form), so it includes the Suger-required fields, the fields AWS needs to accept the referral, and the common optional fields. It is not the bare validator minimum (see the two lists above). Comments mark // required, // optional, and which fields Suger fills. Treat the AWS reference as the source of truth for what AWS will accept.

{
  "partner": "AWS",
  "salesforceOpportunityId": "0065g00000XXXXXAAA",   // optional: link to the CRM opportunity
  "salesforceAccountId": "0015g00000YYYYYAAA",        // optional: auto-derived from the opportunity if omitted
  "info": {
    "aceOpportunityV2": {
      "Origin": "Partner Referral",          // required (only valid value for Catalog: AWS)
      "OpportunityType": "Net New Business",  // required: Net New Business | Flat Renewal | Expansion
      "NationalSecurity": "No",               // optional ("Yes"/"No"); forced "Yes" when Industry = "Government"

      "Customer": {
        "Account": {
          "CompanyName": "Acme Robotics Inc",            // required
          "Industry": "Software and Internet",            // required (valid Industry value)
          "WebsiteUrl": "https://www.acmerobotics.com",   // required (waived only if NationalSecurity = "Yes")
          "Duns": "123456789",                            // optional (9 digits)
          "AwsAccountId": "123456789012",                 // optional (12 digits)
          "Address": {
            "CountryCode": "US",                           // required (ISO 3166-1 alpha-2)
            "StateOrRegion": "California",                 // required when CountryCode = "US"
            "City": "San Francisco",                       // optional
            "PostalCode": "94105",                         // required
            "StreetAddress": "123 Market St"               // optional
          }
        },
        "Contacts": [                                       // customer contact(s)
          { "FirstName": "Dana", "LastName": "Cruz", "Email": "dana.cruz@acmerobotics.com", "Phone": "+14155550123", "BusinessTitle": "VP Engineering" }
        ]
      },

      "PrimaryNeedsFromAws": ["Co-Sell - Deal Support"],  // required, >= 1

      "Project": {
        "Title": "Acme migration to AWS",                  // required
        "CustomerBusinessProblem": "Acme needs to migrate its on-prem fleet platform to AWS to cut latency and scale globally.", // required, 20-2000 chars
        "CustomerUseCase": "Migration / Database Migration", // required (valid use-case value)
        "DeliveryModels": ["SaaS or PaaS"],                // required: SaaS or PaaS | BYOL or AMI | Managed Services | Professional Services | Resell | Other
        "SalesActivities": ["Initialized discussions with customer"], // Suger defaults this if omitted
        "ExpectedCustomerSpend": [
          { "Amount": "5000" }                             // required; Suger sets CurrencyCode=USD, Frequency=Monthly, TargetCompany=AWS
        ],
        "CompetitorName": "",                              // optional
        "ApnPrograms": [],                                 // optional
        "AdditionalComments": "Joint GTM with the AWS account team." // optional (<= 255 chars)
      },

      "LifeCycle": {
        "TargetCloseDate": "2026-09-30",                   // required; future date, YYYY-MM-DD
        "NextSteps": "Schedule joint architecture review"  // optional (<= 255 chars)
      },

      "RelatedEntityIdentifiers": {
        "Solutions": ["S-0123456"],                        // required, >= 1 (your AWS Solution IDs)
        "AwsProducts": ["AmazonBedrock"]                   // optional (values from the AWS products list)
      },

      "OpportunityTeam": [                                  // your team (partner side); members without an email are dropped
        { "FirstName": "Sam", "LastName": "Patel", "Email": "sam.patel@yourcompany.com", "Phone": "+14155550100", "BusinessTitle": "PartnerAccountManager" },
        { "FirstName": "Jordan", "LastName": "Lee", "Email": "jordan.lee@yourcompany.com", "Phone": "+14155550101", "BusinessTitle": "OpportunityOwner" }
      ],

      "Marketing": { "Source": "None" }                    // Suger fills "None"; if set to a real source, also provide CampaignName / Channels / UseCases / AwsFundingUsed
    }
  }
}

Catalog and SoftwareRevenue are intentionally omitted — Suger sets Catalog from your AWS integration and controls SoftwareRevenue based on your partner program. PartnerOpportunityIdentifier is set to the referral ID for you.

Azure (Microsoft)

Send the opportunity under info.createMicrosoftReferralRequest. Field keys use camelCase.

Required by Suger

Co-sell vs. independent

A referral is treated as a co-sell (Microsoft is asked to help) when it carries an invitation with organizationId: "msft" and an assistanceRequestCode other than NoHelpRequired. For co-sell referrals you must also provide a customer contact: at least one customerProfile.team[] entry with email, firstName, lastName, phoneNumber (and its email domain must differ from your partner team’s domains).

dealType values: Private (no Microsoft help), IPCosell (default when Microsoft help is requested), ServicesCosell. assistanceRequestCode values: NoHelpRequired, WorkloadSpecificValueProposition, CustomerTechnicalArchitecture, ProofOfConceptOrDemo, QuotesOrLicensing, PostSalesCustomerSuccess, GeneralOrOther. Suger auto-sets type, status, substatus, and dealType, and auto-fixes missing phone numbers.

For the valid SolutionArea/SolutionPlay combinations, currency and country lists, see the Microsoft “Create a referral” reference.

Example payload (Azure, independent / no Microsoft help)

This mirrors the field set the Suger Console submits. Comments mark // required / // optional and which fields Suger fills.

{
  "partner": "AZURE",
  "salesforceOpportunityId": "0065g00000XXXXXAAA",   // optional: link to the CRM opportunity
  "salesforceAccountId": "0015g00000YYYYYAAA",        // optional: auto-derived from the opportunity if omitted
  "info": {
    "createMicrosoftReferralRequest": {
      "name": "Acme – Azure migration",                // required (deal name)
      "externalReferenceId": "0065g00000XXXXXAAA",      // optional: your CRM record id
      "team": [                                         // required: >= 1 partner contact, each with email/firstName/lastName/phoneNumber
        { "firstName": "Sam", "lastName": "Patel", "email": "sam.patel@yourcompany.com", "phoneNumber": "+14155550100", "title": "Partner Account Manager" }
      ],
      "customerProfile": {
        "name": "Acme Robotics Inc",                    // optional
        "address": {
          "country": "US",                               // required (ISO 3166-1 alpha-2; Suger defaults "US")
          "city": "San Francisco",                       // optional
          "region": "CA",                                // optional
          "postalCode": "94105"                          // optional
        }
      },
      "details": {
        "closingDateTime": "2026-09-30T23:59:59Z",       // required (UTC; today or future)
        "currency": "USD",                               // required (ISO 4217; Suger defaults "USD")
        "dealValue": 50000,                              // required (> 0)
        "notes": "Joint migration opportunity.",         // optional
        "requirements": {
          "solutions": [{ "id": "your-solution-id" }],   // required (>= 1) for Private / IPCosell deals
          "additionalRequirements": {
            "attributes": [                               // required
              { "type": "SolutionArea", "id": "Cloud and AI Platforms" },
              { "type": "SolutionPlay", "id": "Migrate and Modernize Your Estate" },
              { "type": "CustomerMarketplaceIntent", "id": "HaveNotDecided" }
            ]
          }
        }
      }
    }
  }
}

Suger sets type, status, substatus, and dealType for you and auto-fixes missing phone numbers — don’t send those.

To request Microsoft co-sell help, add an invitations entry and a customer contact (the customer contact is required once Microsoft help is requested):

"invitations": [
  { "organizationId": "msft", "organizationName": "Microsoft", "assistanceRequestCode": "ProofOfConceptOrDemo" }
],
"customerProfile": {
  "address": { "country": "US" },
  "team": [                                              // required for co-sell: >= 1 customer contact
    { "firstName": "Dana", "lastName": "Cruz", "email": "dana.cruz@acmerobotics.com", "phoneNumber": "+14155550200" }
  ]
}

GCP (Google Cloud)

Send the opportunity under info.gcpOpportunityV2. Field keys use camelCase.

GCP has two opportunity types, selected by the top-level opportunityType field:

• Regular — opportunityType is REGULAR (or omitted / TWO_TIER). A standard resell/services opportunity.
• ISV Solution Connect — opportunityType is ISV_SOLUTION_CONNECT. An ISV solution deal, with its own isvSolutionConnectInfo block.

The two types share a customer block but differ in which qualification and product fields are required.

Required for both types

Required for Regular only

Required for ISV Solution Connect only

For the full industry, productCategory, currency, and region lists, see the Google Cloud opportunities API reference.

Example payload (GCP — Regular)

{
  "partner": "GCP",
  "salesforceOpportunityId": "0065g00000XXXXXAAA",   // optional: link to the CRM opportunity
  "salesforceAccountId": "0015g00000YYYYYAAA",        // optional: auto-derived from the opportunity if omitted
  "info": {
    "gcpOpportunityV2": {
      "opportunityType": "REGULAR",                    // REGULAR | TWO_TIER | ISV_SOLUTION_CONNECT
      "opportunityInfo": {
        "partnerEntity": "partners/123456",            // required (partners/{id})
        "productCategory": ["GCP_COMPUTE"],            // required (>= 1; e.g. GCP_AI, GCP_ANALYTICS, GCP_DATABASES)
        "displayName": "Acme Corp – GCP Compute",      // optional (auto-generated if omitted)
        "confidential": false                          // optional
      },
      "customerInfo": {
        "customerDetails": {
          "organizationName": "Acme Corporation",      // required
          "domain": "acme.com",                        // required
          "industry": "SOFTWARE",                      // required (GCP industry value)
          "employeeCount": 500,                        // required (> 0)
          "address": { "regionCode": "US", "postalCode": "94043" }  // required (regionCode; postalCode for most countries)
        },
        "contact": {
          "givenName": "John", "familyName": "Doe", "email": "john.doe@acme.com",  // required
          "phone": { "e164Number": "+14155550123" }    // optional
        },
        "region": "NORTH_AMERICA"                       // required (GCP sales region)
      },
      "qualificationInfo": {
        "operationType": "NEW",                         // required: NEW | RENEWAL | ADD_ON | EXPANSION
        "quantity": 1,                                  // required (>= 1)
        "contractLengthMonths": 12,                     // required (1–96)
        "dealSize": { "currencyCode": "USD", "units": "50000" },        // required (USD for GCP; units as a string)
        "estimatedCloseDate": { "year": 2026, "month": 9, "day": 30 },  // required (future)
        "budget": "EXACT_BUDGET_GIVEN",                 // required
        "authority": "CLEARLY_IDENTIFIED_PROCESS",      // required
        "need": "CLEAR_NEED",                           // required
        "timeline": "SPECIFIC_DECISION_DATES_GIVEN",    // required
        "decisionPhase": "FINAL_DECISION",              // required
        "legalLanguageAccepted": true,                  // required (must be true)
        "publicSector": false,                          // optional
        "msspDeal": false                               // optional
      }
    }
  }
}

Example payload (GCP — ISV Solution Connect)

{
  "partner": "GCP",
  "salesforceOpportunityId": "0065g00000XXXXXAAA",   // optional: link to the CRM opportunity
  "salesforceAccountId": "0015g00000YYYYYAAA",        // optional: auto-derived from the opportunity if omitted
  "info": {
    "gcpOpportunityV2": {
      "opportunityType": "ISV_SOLUTION_CONNECT",       // required for ISV
      "opportunityInfo": {
        "partnerEntity": "partners/123456",            // required (partners/{id})
        "productFamily": ["GOOGLE_CLOUD_PLATFORM"],    // required for ISV: GOOGLE_CLOUD_PLATFORM | GOOGLE_WORKSPACE
        "description": "Deploying our real-time analytics SaaS on GCP for the customer."  // required for ISV
      },
      "customerInfo": {
        "customerDetails": {
          "organizationName": "TechCorp Inc",          // required
          "domain": "techcorp.io",                     // required
          "industry": "FINANCIAL_SERVICES",            // required
          "employeeCount": 2000,                       // required
          "address": { "regionCode": "GB", "postalCode": "SW1A 1AA" }  // required
        },
        "contact": {
          "givenName": "Jane", "familyName": "Smith", "email": "jane.smith@techcorp.io",  // required
          "phone": { "e164Number": "+442071234567" }   // optional
        },
        "region": "UK_AND_I"                            // required (GCP sales region)
      },
      "qualificationInfo": {
        "contractLengthMonths": 24,                     // required (1–96)
        "dealSize": { "currencyCode": "USD", "units": "250000" },       // required
        "estimatedCloseDate": { "year": 2026, "month": 6, "day": 30 },  // required (future)
        "legalLanguageAccepted": true                   // required (must be true)
      },
      "isvSolutionConnectInfo": {
        "isvSolutionConnectDeal": true,                 // required for ISV
        "contractVehicle": "CLOUD_MARKETPLACE",         // required for ISV
        "deliveryModel": "SAAS_ON_GOOGLE_CLOUD",        // required for ISV
        "supportLevel": "TECH",                         // required for ISV
        "customerContactRequested": false               // optional
      }
    }
  }
}

ISV Solution Connect does not require the qualification fields (operationType, budget, authority, need, timeline, decisionPhase, quantity, productCategory) that a Regular opportunity does — Suger’s validator only enforces those for Regular. Google’s API is the final authority; see the reference linked above.

Response & next steps

A successful create returns OperationExecutionDetails, including a workflowID of the form org/{orgId}/cosell/referral/{referralId}/create — the {referralId} segment is the new referral’s ID.

• The referral lands in PENDING_CREATE while the submission workflow runs, then moves to the partner’s accepted state — or CREATE_FAILED if the partner API rejects it. Resubmit by calling POST .../cosell/referral again with the corrected payload.
• Do not call sync for the initial submit — submission is automatic.
• To edit a referral later, use PATCH /org/{orgId}/cosell/referral/{referralId}, then sync the change to the partner.

Call it from Salesforce (Apex)

If you use the Suger Connector managed package for Salesforce, you can create a referral from Apex without writing your own HTTP callout — call the packaged method with the same payload shape described above (note the Suger. namespace prefix):

Map<String, Object> referral = new Map<String, Object>{
  'partner' => 'AWS',
  'salesforceOpportunityId' => opp.Id,         // optional: link to the CRM opportunity
  'salesforceAccountId' => opp.AccountId,       // optional: auto-derived from the opportunity if omitted
  'info' => new Map<String, Object>{
    'aceOpportunityV2' => new Map<String, Object>{
      'Origin'          => 'Partner Referral',   // required
      'OpportunityType' => 'Net New Business',    // required
      'NationalSecurity' => 'No',                 // optional
      'Customer' => new Map<String, Object>{
        'Account' => new Map<String, Object>{
          'CompanyName' => 'Acme Robotics Inc',          // required
          'Industry'    => 'Software and Internet',       // required
          'WebsiteUrl'  => 'https://www.acmerobotics.com',// required
          'Duns'        => '123456789',                   // optional
          'AwsAccountId' => '123456789012',               // optional
          'Address'     => new Map<String, Object>{
            'CountryCode' => 'US',                          // required
            'StateOrRegion' => 'California',                // required for US
            'City' => 'San Francisco',
            'PostalCode' => '94105',                        // required
            'StreetAddress' => '123 Market St'
          }
        },
        'Contacts' => new List<Object>{
          new Map<String, Object>{ 'FirstName' => 'Dana', 'LastName' => 'Cruz', 'Email' => 'dana.cruz@acmerobotics.com', 'Phone' => '+14155550123', 'BusinessTitle' => 'VP Engineering' }
        }
      },
      'PrimaryNeedsFromAws' => new List<String>{ 'Co-Sell - Deal Support' },   // required
      'Project' => new Map<String, Object>{
        'Title' => 'Acme migration to AWS',                // required
        'CustomerBusinessProblem' => 'Acme needs to migrate its on-prem fleet platform to AWS to cut latency and scale globally.',  // required
        'CustomerUseCase' => 'Migration / Database Migration',  // required
        'DeliveryModels'  => new List<String>{ 'SaaS or PaaS' },// required
        'ExpectedCustomerSpend' => new List<Object>{ new Map<String, Object>{ 'Amount' => '5000' } },  // required (Amount)
        'SalesActivities' => new List<String>{ 'Initialized discussions with customer' }, // Suger defaults if omitted
        'AdditionalComments' => 'Joint GTM with the AWS account team.'  // optional
      },
      'LifeCycle' => new Map<String, Object>{
        'TargetCloseDate' => '2026-09-30',                 // required (future, YYYY-MM-DD)
        'NextSteps' => 'Schedule joint architecture review'// optional
      },
      'RelatedEntityIdentifiers' => new Map<String, Object>{
        'Solutions'   => new List<String>{ 'S-0123456' },  // required, >= 1
        'AwsProducts' => new List<String>{ 'AmazonBedrock' }// optional
      },
      'OpportunityTeam' => new List<Object>{                // your team (partner side)
        new Map<String, Object>{ 'FirstName' => 'Sam', 'LastName' => 'Patel', 'Email' => 'sam.patel@yourcompany.com', 'Phone' => '+14155550100', 'BusinessTitle' => 'PartnerAccountManager' },
        new Map<String, Object>{ 'FirstName' => 'Jordan', 'LastName' => 'Lee', 'Email' => 'jordan.lee@yourcompany.com', 'Phone' => '+14155550101', 'BusinessTitle' => 'OpportunityOwner' }
      },
      'Marketing' => new Map<String, Object>{ 'Source' => 'None' }  // Suger fills "None"
    }
  }
};

// forceCreate=false → fail fast on validation errors; true → save even if the partner rejects, to fix & resubmit
Object result = Suger.CosellApi.createCosellReferral(referral, false);
Map<String, Object> operation = (Map<String, Object>) result;
String workflowId = (String) operation.get('workflowID');

• Build info.aceOpportunityV2 / info.createMicrosoftReferralRequest / info.gcpOpportunityV2 as nested Map<String, Object> exactly as the JSON examples above show — the envelope is identical to the REST body.
• The method makes an HTTP callout, so it must run in a callout-allowed context: not after DML in the same transaction, and from a record-triggered Flow or trigger it must run asynchronously (Queueable or @future(callout=true)).
• The caller needs co-sell write permission for the partner; the Suger endpoint and authentication are handled by the package.

Full API reference

For the complete request/response schema and to try the endpoint, see POST /org/{orgId}/cosell/referral in the Suger API reference. The authoritative field definitions for each cloud are the partner references linked above:

• AWS — CreateOpportunity
• Microsoft — Create a referral
• Google Cloud — opportunities