Create a referral
This article explains how to create a referral. There are two types of ReferralType:
Independent: Where a referral is visible to one partner.
Shared: Where a referral is visible to two parties that are working together. For example, if Microsoft and a partner are working together in a co-selling deal, a referral can be shared between both parties. For more information, see the section Creating a shared referral.
Note
MACC eligibility and customer matching features aren't available with the use of API integration.
Deal types
There are three types of co-sell opportunities (or deals or referrals) that can be created from Partner Center - Private, Partner-Led, and Co-sell deals. Typically, from the Partner Center user interface, these choices are presented to the user, but while creating these from the API, there are certain other steps to take. From the Partner Center referrals user interface, when you create a new deal, there's a Help needed from Microsoft section, where these choices are presented to the user.
- Private deal: You choose not to share the deal with Microsoft, select "No help needed," and answer "no" to the question, "Would you like to share the deal with Microsoft sellers?"
- Partner led: You choose "No help needed" but answer "yes" to the question, "Would you like to share the deal with Microsoft sellers?"
- Co-sell: You choose to get help from Microsoft and also answer "yes" to the question, "Would you like to share the deal with Microsoft sellers?"
Prerequisites
- Credentials as described in Partner API authentication. This scenario supports authentication with App+User credentials.
REST Request
Request syntax
| Method | Request URI |
|---|---|
| POST | https://api.partner.microsoft.com/v1.0/engagements/referrals |
Request headers
- For more information, see Partner API REST headers.
Request body
This table describes the Referral properties in the request body for a brand new referral.
| Property | Type | Description |
|---|---|---|
| Name | string | The name of the Referral. |
| ExternalReferenceID | string | An external identifier for the referral. For example, your own Dynamics 365 lead or opportunity ID. |
| Status | ReferralStatus | An Enum with values that indicate the referral status. |
| Substatus | ReferralSubstatus | An Enum with values that indicate the referral substatus. |
| StatusReason | string | A descriptive message about the status. For example, explain why the referral was lost. |
| ReferralType | ReferralType | Represents the referral type. Required. |
| Qualification | ReferralQualification | Represents the quality of the referral. |
| CustomerProfile | CustomerProfile | Customer contact information. Required. |
| Consent | Consent | Consent flags around sharing information with other organizations and allowing them to contact users.Required. |
| Details | ReferralDetails | Customer details, notes, deal value, currency closing date. Required. |
| Team | Member | Represents users in the organizations that are involved in the partner engagement. |
| InviteContext | InviteContext | Represents more information a user can provide when inviting another organization into the partner engagement. |
| Target | ReferralTarget | Represents more information a user can provide when inviting another organization into the partner engagement. |
| Partner role | Required for Services co-sell referrals only | Can be one of the following values - Presales envisioning, Solution design, Proof of concept, Business strategy, Deployment services, Adoption and change management, Transaction, Managed services |
| Solution Area | Required for Services co-sell referrals only | The Solution area of the Customer need in the opportunity. See the following table for values. |
| Solution Play | Required for Services co-sell referrals only | The Solution play of the Customer need in the opportunity. See the following table for values. |
Solution Area and Solution Play values
The following table shows the values for Solution Area and Solution Play fields for FY 24.
| Solution Area | Solution Play |
|---|---|
| Business Applications | Accelerate Innovation with Low Code |
| Business Applications | Accelerate Revenue Generation |
| Business Applications | Modernize Service |
| Business Applications | Optimize Finance and Supply Chain |
| Business Applications | SMB Scale Business Operations |
| Data and AI | Power Business Decisions with Cloud Scale Analytics |
| Data and AI | Build and Modernize AI Apps |
| Digital and Application Innovation | Migrate Enterprise Apps |
| Digital and Application Innovation | Build and Modernize AI Apps |
| Digital and Application Innovation | Accelerate Developer Productivity |
| Digital and Application Innovation | Accelerate Innovation with Integration Services |
| Infrastructure | Migrate and Secure Windows Server and SQL Server |
| Infrastructure | Migrate SAP |
| Infrastructure | Innovate with HPC, AI Infrastructure |
| Infrastructure | Migrate Linux Estate |
| Infrastructure | Migrate Oracle |
| Modern Work | Frontline Workers |
| Modern Work | Employee Experience |
| Modern Work | Secure Productivity |
| Modern Work | Converged Communications |
| Modern Work | Cloud Endpoints |
| Modern Work | Modernize with Surface |
| Security | Threat protection with XDR and SIEM |
| Security | Multi Cloud Security |
| Security | Data Security |
| Security | Data Governance |
| Security | Modern Sec Ops |
| Security | Secure Identity and takeout Okta and Ping |
| Unified Support | Build a Strong Foundation with Unified |
| Unified Support | Drive Cloud Success with Enhanced Solutions |
Status and substatus transition states
| Status | Allowed status transition | Allowed substatus |
|---|---|---|
| New | New, Active, Closed | Pending, Received |
| Active | Active, Closed | Accepted |
| Closed | Closed | Won, Lost, Declined, Expired |
Request example
POST https://api.partner.microsoft.com/v1.0/engagements/referrals HTTP/1.1
Authorization: Bearer <token>
Host: api.partner.microsoft.com
Content-Type: application/json
{
"name": "Test Cosell Invite_20",
"status": "New",
"substatus": "Pending",
"statusReason": "Customer engagement was a success!",
"qualification": "SalesQualified",
"type": "Shared",
"target": [
{
"type": "SolutionProfile",
"id": "SOL-34104-EBB"
}
],
"customerProfile": {
"name": "Contoso Customer Inc",
"address": {
"addressLine1": "One Microsoft Way",
"addressLine2": "34",
"city": "Redmond",
"state": "WA",
"postalCode": "98052",
"country": "US"
},
"size": "10to50employees",
"team": [
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "Sue",
"lastName": "Smith",
"phoneNumber": "1234567890",
"email": "sue.smith@contoso.com"
},
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "Joe",
"lastName": "Hansen",
"phoneNumber": "4035698759",
"email": "joe.hansen@contoso.com"
}
],
"ids": []
},
"consent": {
"consentToToShareInfoWithOthers": true,
"consentToContact": true
},
"details": {
"notes": "Customer is looking to leverage Dynamics 365 to manage their supply chain. There's also a need to leverage a set of custom apps to enable their business processes.",
"dealValue": 50000,
"currency": "USD",
"closingDateTime": "2018-11-14T00:00:00Z",
"requirements": {
"industries": [
{
"id": "Manufacturing"
}
],
"products": [
{
"id": "Dynamics365Enterprise"
}
],
"services": [
{
"id": "DeploymentOrMigration"
}
],
"solutions": [
{
"name": "Dynamics 365 for Field Service",
"type": "Category",
"id": "Dynamics365forFieldService"
}
]
}
},
"team": [
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "1231231234",
"email": "john.doe@microsoft.com"
}
],
"inviteContext": {
"notes": "Hi ABC Partner, hoping you can help this customer. Thanks, John @ Microsoft",
"invitedBy": {
"organizationId": "msft"
}
}
}
REST Response
If successful, this method returns the populated Referral resource in the response body.
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and more debugging information. Use a network trace tool to read this code, error type, and other parameters. For the full list, see Error Codes.
Response example
{
"id": "4111fffc-f9ee-4d53-bba6-569135228642",
"engagementId": "37ef26aa-1d15-4533-9f93-a69bd33ab1e5",
"organizationId": "7d23e5ca-19dc-4eaa-aac8-5e6b559f0d1d",
"organizationName": "Contoso Company",
"name": "Test Cosell Invite_20",
"externalReferenceId": null,
"createdDateTime": "2019-02-23T02:05:23.2931817Z",
"updatedDateTime": "2019-02-23T02:05:23.2931817Z",
"expirationDateTime": null,
"status": "Active",
"substatus": "Accepted",
"statusReason": "Customer engagement was a success!",
"qualification": "SalesQualified",
"type": "Shared",
"eTag": "\"00006d10-0000-0000-0000-5c70aa630000\"",
"target": [
{
"type": "SolutionProfile",
"id": "SOL-34104-EBB"
}
],
"customerProfile": {
"name": "Contoso Customer Inc",
"address": {
"addressLine1": "One Microsoft Way",
"addressLine2": "34",
"city": "Redmond",
"state": "WA",
"postalCode": "98052",
"country": "US"
},
"size": "10to50employees",
"team": [
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "Sue",
"lastName": "Smith",
"phoneNumber": "1234567890",
"email": "sue.smith@contoso.com"
},
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "Joe",
"lastName": "Hansen",
"phoneNumber": "4035698759",
"email": "joe.hansen@contoso.com"
}
],
"ids": []
},
"consent": {
"consentToToShareInfoWithOthers": true,
"consentToContact": true
},
"details": {
"notes": "Customer is looking to leverage Dynamics 365 to manage their supply chain. There is also a need to leverage a set of custom apps to enable their business processes.",
"dealValue": 50000,
"currency": "USD",
"requirements": {
"industries": [
{
"id": "Manufacturing"
}
],
"products": [
{
"id": "Dynamics365Enterprise"
}
],
"services": [
{
"id": "DeploymentOrMigration"
}
],
"solutions": [
{
"name": "Dynamics 365 for Field Service",
"type": "Category",
"id": "Dynamics365forFieldService"
}
]
}
},
"team": [
{
"contactPreference": {
"locale": "en-us",
"disableNotifications": false
},
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "1231231234",
"email": "john.doe@microsoft.com"
}
],
"inviteContext": {
"notes": "Hi ABC Partner, hoping you can help this customer. Thanks, John @ Microsoft",
"invitedBy": {
"organizationId": "msft"
}
},
"links": {
"relatedReferrals": {
"uri": "https://api.partner.microsoft.com/v1.0/engagments/referrals?$filter=engagementId eq '37ef26aa-1d15-4533-9f93-a69bd33ab1e5'",
"method": "GET"
},
"self": {
"uri": "https://api.partner.microsoft.com/v1.0/engagments/referrals/4111fffc-f9ee-4d53-bba6-569135228642",
"method": "GET"
}
}
}
Upgrade from Private/Partner-led to Co-sell deal
To create a co-sell deal via the API, you have to first create a Private or Partner-led deal and then create the second referral and connect it with the first one. The steps are outlined in the following section.
Step 1: Create a Partner-led deal visible to Microsoft sellers
First, create a Partner-led deal visible to Microsoft sellers using the following request payload.
POST https://api.partner.microsoft.com/v1.0/engagements/referrals
{
"name": "TEST Contoso Cosell Deal",
"externalReferenceId": "",
"campaignId": "",
"customerProfile": {
"isMatchingComplete": true,
"name": "Contoso Test Test",
"address": {
"addressLine1": "One Microsoft Way",
"addressLine2": "",
"city": "Redmond",
"state": "",
"region": "",
"country": "US"
},
"size": "",
"team": [
{
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "123345667",
"email": "john@doe.com",
"title": "",
"phoneValidationStatus": "None",
"emailValidationStatus": "None",
"contactPreference": {
"disableNotifications": true
}
}
],
"ids": [
{
"profileType": "external",
"id": "9-XIPFFGUQI"
}
],
"type": ""
},
"consent": {
"ConsentToToShareInfoWithOthers": true,
"ConsentToContact": true,
"ConsentToMicrosoftToContactSpecificPartners": true,
"consentToShareReferralWithMicrosoftSellers": true
},
"details": {
"dealValue": 100000,
"currency": "USD",
"closingDateTime": "2024-11-23T18:30:00.000Z",
"notes": "",
"requirements": {
"solutions": [
{
"type": "Name",
"id": "SOL-8163-XCJ",
"name": "Contoso Solution",
"publisherName": "Contoso-ISV",
"price": null,
"currency": null,
"quantity": null,
"solutionType": "3P"
}
],
"additionalRequirements": {
"iot": {},
"attributes": [
{
"id": "HaveNotDecided",
"type": "CustomerMarketplaceIntent"
}
]
}
}
},
"team": [
{
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "12345667",
"email": "john@doe.com",
"title": "",
"phoneValidationStatus": "None",
"emailValidationStatus": "None"
}
],
"type": "Shared",
"qualification": "SalesQualified",
"attributes": {
"objectType": "Referral"
},
"target": [],
"mpnId": "<ENTER PARTNER_MPN_ID>",
"trackingInfo": {}
}
Step 2: Create a Microsoft referral using partner referral details
Then, create the Microsoft referral via another API call and link it to the Partner referral using the Engagement ID field returned from Step 1.
POST https://api.partner.microsoft.com/v1.0/engagements/referrals
{
"engagementId": "<ENTER_ENGAGEMENT_ID_OF_PARTNER_REFERRAL>",
"organizationId": "msft",
"organizationName": "Microsoft",
"name": "TEST Contoso Cosell Deal",
"customerProfile": {
"name": "Contoso Test Test",
"size": "",
"isMatchingComplete": true,
"isMaccEligible": null,
"address": {
"addressLine1": "One Microsoft Way",
"addressLine2": "",
"city": "Redmond",
"state": "",
"postalCode": null,
"country": "US",
"region": ""
},
"team": [
{
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "123345667",
"email": "john@doe.com",
"title": "",
"emailValidationStatus": "None",
"phoneValidationStatus": "None",
"linkedInProfileUrl": null,
"contactPreference": {
"disableNotifications": true
}
}
],
"ids": [
{
"profileType": "External",
"id": "9-XIPFFGUQI"
}
],
"activities": null
},
"consent": {
"consentToToShareInfoWithOthers": true,
"consentToContact": true,
"consentToShareReferralWithMicrosoftSellers": true
},
"details": {
"notes": "Test notes to Microsoft.",
"dealValue": 100000,
"currency": "USD",
"closingDateTime": "2024-11-23T18:30:00Z",
"requirements": {
"solutions": [],
"additionalRequirements": {
"iot": {},
"attributes": []
}
}
},
"team": [],
"inviteContext": {
"notes": "Proof of concept / Demo , Test notes to Microsoft.",
"invitedBy": {
"organizationId": "<PARTNER_ORGANIZATION_ID (ACCOUNT_ID GUID)>",
"organizationName": "<INVITING_PARTNERS_ORGANIZATION_NAME>"
},
"assistanceRequestCode": "ProofOfConceptOrDemo"
},
"type": "Shared",
"qualification": "SalesQualified",
"attributes": {
"objectType": "Referral"
},
"target": [],
"dealSensitivity": "None",
"trackingInfo": {}
}
Create a shared referral
There are two steps to create a referral of the Shared referral type:
The following flowchart illustrates these two steps in creating a shared referral.
Create your referral
- Create a referral with ReferralType set to shared.
- Copy the engagementID from the return response.
ReferralTarget sample for referral
"target": [
{
"type": "SolutionProfile",
"id": "SOL-ABC-DEF"
}
]
Create a connected referral
- Create another referral for Microsoft.
- Include the enagementID from your referral so they're tied together.
ReferralTarget sample for Microsoft referral
"target": [
{
"type": "BusinessProfileLocation",
"id": "msft"
}
]
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for