List co-sell referrals (inbound + outbound)

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

List co-sell referrals under the organization with pagination, filters, and sort. Covers both inbound (received from a partner) and outbound (shared by us). Use the `q` filter expression to scope by `partner` (AWS / AZURE / GCP), `status`, `stage`, time range, etc. Legal Suger unified status values (DB enum, UPPER_SNAKE_CASE): DRAFT, PENDING_CREATE, CREATE_FAILED, UPDATE_FAILED, IN_REVIEW, PENDING_ACCEPTANCE, ACTION_REQUIRED, ACTIVE, EXPIRED, CLOSED_WON, CLOSED_LOST, CLOSED_ERROR, REJECTED. (DELETED rows are filtered out server-side.) Filter example (qs=lisp, the default): `q=(and (eq partner "AWS") (eq status "IN_REVIEW"))`. Use this when: user wants to browse, search, or filter existing co-sell referrals.

Parameters

Name	In	Type	Required	Description
`orgId`	path	string	yes	Organization ID
`page_size`	query	integer	no	Number of items per page (default 20, max 100)
`page_number`	query	integer	no	Page number (default 1)
`qs`	query	string	no	Query style: 'json' or 'lisp' (default 'lisp')
`q`	query	string	no	Filter expression in the format specified by qs param
`ss`	query	string	no	Sort style: 'json' or 'simple' (default 'simple')
`s`	query	string	no	Sort expression in the format specified by ss param

Responses

200 — OK

Content-Type: application/json · Schema: ListCosellReferralsResponse

ListCosellReferralsResponse fields:

Field	Type	Required
`data`	array<orm.CosellReferral>	no
`engagementPartners`	object	no
`page_number`	integer	no
`page_size`	integer	no
`total_count`	integer	no

orm.CosellReferral fields:

Field	Type	Required	Description
`approvalInfo`	ApprovalInfo	no
`contactIDs`	array<string>	no	ContactIds holds the value of the "contact_ids" field.
`creationRetryCount`	integer	no	CreationRetryCount holds the value of the "creation_retry_count" field.
`creationTime`	string	no	CreationTime holds the value of the "creation_time" field.
`direction`	cosellreferral.Direction	no
`dynamics365OpportunityId`	string	no	Dynamics365OpportunityID holds the value of the "dynamics365_opportunity_id" field.
`errorMessages`	array<string>	no	ErrorMessages holds the value of the "error_messages" field.
`externalCreationTime`	string	no	ExternalCreationTime holds the value of the "external_creation_time" field.
`externalId`	string	no	ExternalID holds the value of the "external_id" field.
`externalLastUpdateTime`	string	no	ExternalLastUpdateTime holds the value of the "external_last_update_time" field.
`hubspotDealId`	string	no	HubspotDealID holds the value of the "hubspot_deal_id" field.
`id`	string	no	ID of the ent.
`info`	ReferralInfo	no
`lastUpdateTime`	string	no	LastUpdateTime holds the value of the "last_update_time" field.
`metaInfo`	ReferralMetaInfo	no
`name`	string	no	Name holds the value of the "name" field.
`organizationId`	string	no	OrganizationID holds the value of the "organization_id" field.
`partner`	cosellreferral.Partner	no
`partnerId`	string	no	PartnerID holds the value of the "partner_id" field.
`partnerStatus`	string	no	PartnerStatus holds the value of the "partner_status" field.
`salesforceAccountId`	string	no	SalesforceAccountID holds the value of the "salesforce_account_id" field.
`salesforceOpportunityId`	string	no	SalesforceOpportunityID holds the value of the "salesforce_opportunity_id" field.
`salesforceReferralId`	string	no	SalesforceReferralID holds the value of the "salesforce_referral_id" field.
`stage`	string	no	Stage holds the value of the "stage" field.
`status`	string	no	Status holds the value of the "status" field.

ApprovalInfo fields:

Field	Type	Required	Description
`approvalStatus`	ApprovalStatus	no
`decisionDate`	string	no	DecisionDate is when the final approval/decline happened (nil when pending) Latest DecisionDate
`message`	string	no	Message is the reason or explanation provided when the approval status is set to Declined or Action Required. It always stores the latest message for the current status transition. Historical messages are stored in notification events.
`requestDate`	string	no	Latest RequestDate

ReferralInfo fields:

Field	Type	Required	Description
`aceEngagementInvitation`	types.EngagementInvitation	no
`aceOpportunity`	AceOpportunity	no
`aceOpportunityV2`	types.AceOpportunityV2	no
`aceOutboundEngagementInvitations`	array<types.EngagementInvitation>	no	AceOutboundEngagementInvitations stores all outbound engagement invitations sent to partners.
`createMicrosoftReferralRequest`	CreateReferralRequest	no
`gcpOpportunity`	GCPOpportunity	no
`gcpOpportunityV2`	types.Opportunity	no
`microsoftReferralSet`	MicrosoftReferralSet	no
`sugerOpportunity`	SugerOpportunity	no

ReferralMetaInfo fields:

Field	Type	Required	Description
`archivedAt`	string	no	ArchivedAt is the time when the referral was deleted. It is set to indicate that the referral has been archived; otherwise, the referral is considered active.
`autoConnectedManagedAccount`	boolean	no	AutoConnectedManagedAccount is true when Suger's Auto Share auto-picked the Microsoft Managed Account for this referral's customer (vs CRM-mapped or user-selected). Azure-only. Set at submission time and never cleared.
`awsInvitePartnerRequests`	array<SendEngagementInvitationRequest>	no	AwsInvitePartnerRequests stores the list of partners to invite when creating this referral. Each entry is passed to SendEngagementInvitation() after engagement creation completes. This field is never cleared — it serves as a permanent record of invitation intent and allows retry via the standalone SendEngagementInvitation endpoint. Max 9 partners per opportunity (AWS API limit).
`azureDealRegIsEligible`	boolean	no	AzureDealRegIsEligible indicates whether the referral is eligible for Azure deal registration. This is pre-computed by a daily cron workflow and cached here.
`createdByEmail`	string	no	The email address of the user who created the referral. This field is immutable after creation. Especially useful for referrals created from Salesforce/HubSpot integrations where the creator may not have a Suger account yet.
`createdBySource`	CreatedBySource	no
`creationFailureMessage`	string	no
`creationStatus`	string	no
`crmOpportunityId`	string	no
`crmPartner`	string	no
`hubspotDealId`	string	no
`isTesting`	boolean	no	IsTesting is a flag to indicate if the referral is for testing purpose. E.g., customer doing a POC without a real ACE connection.
`lastSyncMessage`	string	no
`lastSyncStatus`	string	no
`lastSyncTime`	string	no
`predictedQualityScore`	structs.PredictedQualityScoreSnapshot	no
`salesforceReferralId`	string	no
`syncDisabled`	boolean	no
`updateFailureMessage`	string	no
`updateStatus`	string	no

types.EngagementInvitation fields:

Field	Type	Required
`Arn`	string	no
`Catalog`	string	no
`EngagementDescription`	string	no
`EngagementId`	string	no
`EngagementTitle`	string	no
`ExistingMembers`	array<github_com_sugerio_marketplace-service_pkg_integration_ace_types.EngagementMember>	no
`ExpirationDate`	string	no
`Id`	string	no
`InvitationDate`	string	no
`InvitationMessage`	string	no
`Payload`	types.EngagementInvitationPayload	no
`PayloadType`	string	no
`Receiver`	github_com_sugerio_marketplace-service_pkg_integration_ace_types.Receiver	no
`RejectionReason`	string	no
`SenderAwsAccountId`	string	no
`SenderCompanyName`	string	no
`Status`	string	no

AceOpportunity fields:

Field	Type	Required	Description
`IsOppFromMarketingActivity`	string	no	Note that the JSON field's first letter must be uppercase.
`aWSAccountOwnerEmail`	string	no
`aWSAccountOwnerName`	string	no
`aWSCloseDate`	string	no
`aWSClosedLostReason`	string	no
`aWSISVSuccessManagerEmail`	string	no
`aWSISVSuccessManagerName`	string	no
`aWSPartnerSuccessManagerEmail`	string	no
`aWSPartnerSuccessManagerName`	string	no
`aWSSalesRepEmail`	string	no
`aWSSalesRepName`	string	no
`aWSStage`	string	no
`acceptBy`	string	no
`additionalComments`	string	no
`apnCrmLeadUniqueIdentifier`	string	no
`apnCrmUniqueIdentifier`	string	no
`apnReviewerComments`	string	no
`awsAccountId`	string	no
`awsProducts`	array<string>	no
`awsSFCampaignName`	string	no
`backwardsCompatibilityChanges`	string	no
`campaignName`	string	no
`city`	string	no
`closedLostReason`	string	no
`competitiveTracking`	string	no
`competitiveTrackingOther`	string	no
`contractEndDate`	string	no
`contractStartDate`	string	no
`cosellConvertReason`	string	no
`country`	string	no
`createdBy`	string	no
`createdDate`	string	no
`customerCompanyName`	string	no
`customerDuns`	string	no
`customerEmail`	string	no
`customerFirstName`	string	no
`customerLastName`	string	no
`customerPhone`	string	no
`customerSoftwareValue`	number	no
`customerSoftwareValueCurrency`	string	no
`customerTitle`	string	no
`customerWebsite`	string	no
`deliveryModel`	string	no
`doesOppBelongToNatSec`	string	no
`engagementInvitationArn`	string	no	For Partner Central API inbound opportunity
`engagementScore`	string	no
`expectedMonthlyAwsRevenue`	integer	no
`industry`	string	no
`industryOther`	string	no
`isMarketingDevelopmentFunded`	string	no
`lastModifiedBy`	string	no
`lastModifiedDate`	string	no
`marketingActivityChannel`	string	no
`marketingActivityUsecase`	string	no
`nextStep`	string	no
`nextStepHistory`	string	no
`offers`	array<string>	no
`opportunityOwnerEmail`	string	no
`opportunityOwnerName`	string	no
`opportunityOwnership`	string	no
`opportunityType`	string	no
`otherSolutionOffered`	string	no
`parentOppId`	string	no	When Opportunity Type is set to "Flat Renewal". Mandatory when partner needs to send updates to existing opportunities.
`partnerAcceptanceDate`	string	no
`partnerAcceptanceStatus`	string	no
`partnerCrmUniqueIdentifier`	string	no
`partnerDeveloperManager`	string	no
`partnerDeveloperManagerEmail`	string	no
`partnerPrimaryNeedFromAws`	string	no
`partnerProjectTitle`	string	no
`postalCode`	string	no
`primaryContactEmail`	string	no
`primaryContactFirstName`	string	no
`primaryContactLastName`	string	no
`primaryContactPhone`	string	no
`primaryContactTitle`	string	no
`procurementType`	string	no
`projectDescription`	string	no
`recommendedNextBestActions`	string	no
`rejectionReason`	string	no
`salesActivities`	string	no
`solutionOffered`	array<string>	no
`stage`	string	no
`state`	string	no
`status`	string	no
`streetAddress`	string	no
`sugerRequestId`	string	no	Suger-internal field to store the request id.
`targetCloseDate`	string	no
`useCase`	string	no
`wWPSPDM`	string	no
`wWPSPDMEmail`	string	no

types.AceOpportunityV2 fields:

Field	Type	Required	Description
`AWSLifeCycle`	github_com_sugerio_marketplace-service_pkg_integration_ace_types.LifeCycle	no
`AWSOpportunityTeam`	array<github_com_sugerio_marketplace-service_pkg_integration_ace_types.Contact>	no	AWSOpportunityTeam details the AWS opportunity team, including members involved. This information helps partners know who from AWS is engaged and what their role is.
`Arn`	string	no	Arn, The Amazon Resource Name (ARN) that uniquely identifies the opportunity. Type: String Pattern: ^arn:.*$
`Catalog`	string	no	Specifies the catalog associated with the request. This field takes a string value from a predefined list: AWS or Sandbox. The catalog determines which environment the opportunity is created in. Use AWS to create opportunities in the AWS catalog, and Sandbox to test in a secure and isolated environment. Type: String Pattern: ^[a-zA-Z]+$ Required: Yes
`CosellMotion`	string	no	CosellMotion classifies how AWS is engaging with this opportunity. Operational classification produced by AWS's routing model — not an analytical insight. Populated asynchronously after submission; empty string until classified. Values are extensible — new motions may be added without notice. Type: String Known Values: AWS Field-engaged \| Agent-engaged \| Partner-led
`CreatedDate`	string	no	DateTime when the Opportunity was last created.
`Customer`	github_com_sugerio_marketplace-service_pkg_integration_ace_types.Customer	no
`Id`	string	no	ID Read-only, system generated Opportunity unique identifier. Type: String Pattern: ^O[0-9]{1,19}$
`Insights`	types.Insights	no
`InvolvementType`	string	no	InvolvementType specifies the type of involvement AWS has in the opportunity, such as direct cosell or advisory support. This field helps partners understand the role AWS plays in advancing the opportunity. Type: String Valid Values: For Visibility Only \| Co-Sell
`InvolvementTypeChangeReason`	string	no	InvolvementTypeChangeReason provides a reason for any changes in the involvement type of AWS in the opportunity. This field is used to track why the level of AWS engagement has changed from For Visibility Only to Co-sell offering transparency into the partnership dynamics. Type: String Valid Values: Expansion Opportunity \| Change in Deal Information \| Customer Requested \| Technical Complexity \| Risk Mitigation
`LastModifiedDate`	string	no	DateTime when the opportunity was last modified.
`LifeCycle`	github_com_sugerio_marketplace-service_pkg_integration_ace_types.LifeCycle	no
`Marketing`	github_com_sugerio_marketplace-service_pkg_integration_ace_types.Marketing	no
`NationalSecurity`	string	no	Indicates whether the Opportunity pertains to a national security project. This field must be set to true only when the customer's industry is Government. Additional privacy and security measures apply during the review and management process for opportunities marked as NationalSecurity. Type: String Valid Values: Yes \| No Required: No
`OpportunityTeam`	array<github_com_sugerio_marketplace-service_pkg_integration_ace_types.Contact>	no	Represents the internal team handling the opportunity. Specify the members involved in collaborating on this opportunity within the partner's organization. Type: Array of Contact objects Array Members: Minimum number of 0 items. Maximum number of 1 item. Required: No
`OpportunityType`	string	no	Specifies the opportunity type as a renewal, new, or expansion. Opportunity types: New opportunity: Represents a new business opportunity with a potential customer that's not previously engaged with your solutions or services. Renewal opportunity: Represents an opportunity to renew an existing contract or subscription with a current customer, ensuring continuity of service. Expansion opportunity: Represents an opportunity to expand the scope of an existing contract or subscription, either by adding new services or increasing the volume of existing services for a current customer. Type: String Valid Values: Net New Business \| Flat Renewal \| Expansion Required: No
`Origin`	string	no	Specifies the origin of the opportunity, indicating if it was sourced from AWS or the partner. For all opportunities created with Catalog: AWS, this field must only be Partner Referral. However, when using Catalog: Sandbox, you can set this field to AWS Referral to simulate AWS referral creation. This allows AWS-originated flows testing in the sandbox catalog. Type: String Valid Values: AWS Referral \| Partner Referral Required: No
`PartnerOpportunityIdentifier`	string	no	Specifies the opportunity's unique identifier in the partner's CRM system. This value is essential to track and reconcile because it's included in the outbound payload sent back to the partner. This field allows partners to link an opportunity to their CRM, to ensure seamless integration and accurate synchronization between the Partner Central API and the partner's internal systems. Type: String Length Constraints: Minimum length of 0. Maximum length of 64. Required: No
`PrimaryNeedsFromAws`	array<string>	no	Identifies the type of support the partner needs from AWS. Valid values: Co-Sell - Architectural Validation: Confirmation from AWS that the partner's proposed solution architecture is aligned with AWS best practices and poses minimal architectural risks. Co-Sell - Business Presentation: Request AWS seller's participation in a joint customer presentation. Co-Sell - Competitive Information: Access to AWS competitive resources and support for the partner's proposed solution. Co-Sell - Pricing Assistance: Connect with an AWS seller for support situations where a partner may be receiving an upfront discount on a service (for example: EDP deals). Co-Sell - Technical Consultation: Connect with an AWS Solutions Architect to address the partner's questions about the proposed solution. Co-Sell - Total Cost of Ownership Evaluation: Assistance with quoting different cost savings of proposed solutions on AWS versus on-premises or a traditional hosting environment. Co-Sell - Deal Support: Request AWS seller's support to progress the opportunity (for example: joint customer call, strategic positioning). Co-Sell - Support for Public Tender / RFx: Opportunity related to the public sector where the partner needs AWS RFx support. Do Not Need Support from AWS Sales Rep: Indicates that a partner doesn't need support from an AWS sales representative, and the partner solely manages the opportunity. It's possible to request co-selling support on these opportunities at any stage during their lifecycle. Also known as, for-visibility-only (FVO) opportunity. Type: Array of strings Valid 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 Required: No
`Project`	github_com_sugerio_marketplace-service_pkg_integration_ace_types.Project	no
`RelatedEntityIdentifiers`	github_com_sugerio_marketplace-service_pkg_integration_ace_types.RelatedEntityIdentifiers	no
`SoftwareRevenue`	github_com_sugerio_marketplace-service_pkg_integration_ace_types.SoftwareRevenue	no
`Visibility`	string	no	Visibility defines the visibility level for the AWS Opportunity. Use Full visibility for most cases, while Limited visibility is reserved for special programs or sensitive opportunities. Type: String Valid Values: Full \| Limited

CreateReferralRequest fields:

Field	Type	Required	Description
`attributes`	object	no
`callToAction`	string	no
`campaignId`	string	no
`consent`	MicrosoftPartnerReferralConsent	no
`contract`	MicrosoftPartnerReferralContract	no
`customerProfile`	MicrosoftPartnerReferralProfile	no
`dealType`	DealType	no
`details`	MicrosoftPartnerReferralDetail	no
`engagementId`	string	no
`expirationDateTime`	string	no
`externalReferenceId`	string	no
`invitations`	array<InvitationToPartner>	no	Additional properties from Suger, used to generate connected referrals Details and Team are mandatory for non-msft invitations
`inviteContext`	MicrosoftPartnerReferralInviteContext	no
`mpnId`	string	no
`name`	string	no
`organizationId`	string	no
`organizationName`	string	no
`qualification`	MicrosoftPartnerReferralQualification	no
`status`	MicrosoftPartnerReferralStatus	no
`statusReason`	string	no
`substatus`	MicrosoftPartnerReferralSubStatus	no
`target`	array<MicrosoftPartnerReferralTarget>	no
`team`	array<MicrosoftPartnerReferralPerson>	no
`type`	MicrosoftPartnerReferralType	no

GCPOpportunity fields:

Field	Type	Required
`approvedDate`	string	no
`authority`	string	no
`budget`	string	no
`campaignCode`	string	no
`closeDate`	string	no
`closeDatePushCount`	integer	no
`confidential`	boolean	no
`contractExpiryDate`	string	no
`contractLengthMonths`	integer	no
`contractVehicle`	string	no
`customerAddressAdministrativeArea`	string	no
`customerAddressLanguageCode`	string	no
`customerAddressLines`	array<string>	no
`customerAddressLocality`	string	no
`customerAddressOrganization`	string	no
`customerAddressPostalCode`	string	no
`customerAddressRecipients`	array<string>	no
`customerAddressRegionCode`	string	no
`customerAddressRevision`	integer	no
`customerAddressSortingCode`	string	no
`customerAddressSublocality`	string	no
`customerContactEmail`	string	no
`customerContactFamilyName`	string	no
`customerContactGivenName`	string	no
`customerContactPhone`	object	no
`customerContactRequested`	boolean	no
`customerContacts`	array<object>	no
`customerDisplayName`	string	no
`customerDomain`	string	no
`customerEmployeeCount`	integer	no
`customerIndustry`	string	no
`customerOrganizationName`	string	no
`customerRegion`	string	no
`dealNumber`	string	no
`dealSize`	object	no
`decisionPhase`	string	no
`deliveryModel`	string	no
`distributor`	string	no
`estimatedCloseDate`	string	no
`extensionsCount`	integer	no
`gcpCreatedDate`	string	no
`gcpCreatorEmail`	string	no
`gcpName`	string	no
`gcpOwner`	string	no
`gcpOwnerEmail`	string	no
`gcpProjectNumbers`	array<string>	no
`gcpSource`	string	no
`gcpStage`	string	no
`gcpState`	string	no
`gcpStateDescription`	string	no
`gcpUpdatedDate`	string	no
`gcpWatermark`	number	no
`id`	string	no
`incentiveEligibility`	boolean	no
`incentiveType`	string	no
`indirectPartnerEntity`	string	no
`isvSolutionConnectDeal`	boolean	no
`legalLanguageAccepted`	boolean	no
`lostMainReason`	string	no
`lostReason`	string	no
`lostRejectedReasonDetails`	string	no
`msspDeal`	boolean	no
`need`	string	no
`operationType`	string	no
`opportunityAmount`	object	no
`opportunityDescription`	string	no
`opportunityDisplayName`	string	no
`opportunityLines`	array<object>	no
`opportunityTeamMembers`	array<object>	no
`opportunityType`	string	no
`partnerEntity`	string	no
`partnerReadyToClose`	string	no
`prmSiteDetails`	string	no
`productCategory`	array<string>	no
`productFamily`	array<string>	no
`publicSector`	boolean	no
`rebateExpirationDate`	string	no
`rebateExtensions`	array<object>	no
`subbillingAccountId`	string	no
`submittedDate`	string	no
`supportLevel`	string	no
`timeline`	string	no
`winLossAdditionalContext`	string	no
`winLossProducts`	array<string>	no
`winMainReason`	string	no
`wonReason`	string	no

types.Opportunity fields:

Field	Type	Required	Description
`createTime`	string	no	Output only. CreateTime is the time when the Opportunity was created.
`creationDate`	types.GcpCosellDate	no
`creatorEmail`	string	no	Output only. CreatorEmail is the email of the user who created the Opportunity.
`customerContacts`	array<types.CustomerContact>	no	List of Customer contacts for the Opportunity, present after approval. Present only after the Opportunity is approved. Unset otherwise. Cannot be edited. Output only.
`customerDisplayName`	string	no	Output only. CustomerDisplayName is the display name of the customer associated with the Opportunity.
`customerInfo`	types.CustomerInfo	no
`isvSolutionConnectInfo`	types.IsvSolutionConnectInfo	no
`name`	string	no	Name is the identifier for the Opportunity in the format: opportunities/{opportunity_id}.
`opportunityInfo`	types.OpportunityInfo	no
`opportunityLines`	array<types.OpportunityLine>	no	Information about the products added to the Opportunity Present only after the Opportunity is approved. Unset otherwise. Cannot be edited. Output only.
`opportunityTeamMembers`	array<types.OpportunityTeamMember>	no	Information on the Partner users with access to the Opportunity Present only after the Opportunity is approved. Unset otherwise. Cannot be edited. Output only.
`opportunityType`	string	no	Optional. Indicates if the opportunity is a Regular/Independent Software Vendor/2-tier deal. If not specified, it will be treated as a Regular. Can't be edited after the Opportunity is Accepted.
`owner`	string	no	Output only. Owner is the name of the Google FSR (Field Sales Representative) who owns the Opportunity.
`ownerEmail`	string	no	Output only. OwnerEmail is the email of the Google FSR who owns the Opportunity.
`partnerInfo`	types.PartnerInfo	no
`qualificationInfo`	types.QualificationInfo	no
`rebateExtensions`	array<types.RebateExtension>	no	Information about rebate extensions requested on the Opportunity. Present only after the Opportunity is approved. Unset otherwise. Cannot be edited. Output only.
`salesCycle`	types.SalesCycle	no
`source`	string	no	Output only. Source indicates if the Opportunity was created by Google or a Partner.
`stage`	types.GCPOppoStage	no
`state`	types.GCPOppoState	no
`stateDescription`	string	no	Output only. StateDescription contains the reason if the Opportunity was not accepted.
`updateTime`	string	no	Output only. CreateTime is the time when the Opportunity was updated.
`winLossInfo`	types.WinLossInfo	no

MicrosoftReferralSet fields:

Field	Type	Required	Description
`connected`	array<MicrosoftPartnerReferral>	no
`self`	MicrosoftPartnerReferral	no

400 — Bad request error

Content-Type: application/json

500 — Internal server error

Content-Type: application/json

View as Markdown · Interactive API reference

Spotted something wrong or out of date on this page? Tell us and we'll correct it.