Get the list of leads and opportunities

  • Article

This article explains how to get the list of leads received from Microsoft solution provider page and co-sell opportunities received from Microsoft sellers or other partners. This process will also fetch the list of co-sell opportunities or pipeline deals created by your organization.

Note

Leads received from the Microsoft commercial marketplace (Azure Marketplace and AppSource) aren't supported.

Prerequisites

  • Credentials as described in Partner API authentication. This scenario supports authentication with App+User credentials.
  • This API currently supports only user access where partners must be in one of the following roles: Global Admin, Referral Admin or Referral User.

REST request

Request syntax

Method Request URI
GET https://api.partner.microsoft.com/v1.0/engagements/referrals

Supported OData operations

Name Description Required Example
$select Selects fields No /referrals?$select=id,status,customerProfile
$filter Filters results Recommended /referrals?$filter=engagementId eq '65edc0b5-3485-41b7-a17e-dfa9ef4706e2'
/referrals?$filter=status eq 'New' and qualification eq 'SalesQualified'
/referrals?$filter=customerProfile/address/country eq 'US' and direction eq 'Incoming'
$orderby Orders results Recommended /referrals?$orderby=createdDateTime desc

Supported orderby parameters

Use the following $orderby parameters to sort the list of leads and opportunities

Name Type Description
createdDateTime DateTime Creation date and time of the lead or opportunity
updatedDateTime DateTime Update date and time of the lead or opportunity

Request headers

See Partner REST headers for more information.

Request body

None.

Request example

GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

REST response

If successful, the response body contains a collection of leads and/or opportunities.

Response success and error codes

Each response comes with an HTTP status code that indicates success or failure and other debugging information. Use a network trace tool to read this code, the error type, and more parameters.

Response example

HTTP/1.1 200 OK
Content-Type: application/json
Request-ID: 9f8bed52-e4df-4d0c-9ca6-929a187b0731

{
  "@odata.context": "http://api.partner.microsoft.com/v1.0/$metadata#Referrals",
  "@odata.count": 1,
  "value": [
    {
      "id": "c5fbb3b6-be74-4795-9fb5-4324c73fed37",
      "engagementId": "65edc0b5-3485-41b7-a17e-dfa9ef4706e2",
      "organizationId": "7d23e5ca-19dc-4eaa-aac8-5e6b559f0d1d",
      "organizationName": "Contoso Company",
      "createdDateTime": "2020-10-30T21:03:00.0000000Z",
      "updatedDateTime": "2020-10-30T21:03:00.0000000Z",
      "status": "New",
      "substatus": "Pending",
      "qualification": "Direct",
      "type": "Independent",
      "direction": "Incoming",
      "customerProfile": {
        "name": "Fabrikam Customer Inc",
        "address": {
          "addressLine1": "One Microsoft Way",
          "addressLine2": "",
          "city": "Redmond",
          "state": "WA",
          "postalCode": "98052",
          "country": "US"
        }
      },
      "details": {
        "notes": "We are interested in deploying Microsoft 365 and are looking for support in training our employees. Can you help?",
        "dealValue": 10000,
        "currency": "USD",
        "closingDateTime": "2020-12-01T00:00:00Z",
        "requirements": {
            "industries": [ { "id": "Education" } ],
            "products": [ { "id": "Microsoft365" } ],
            "services": [ { "id": "LearningAndCertification" } ],
            "solutions": [ { "id": "SOL-Microsoft365", "name": "Microsoft365" }
          ]
        }
      },
      "links": {
        "relatedReferrals": {
          "uri": "https://api.partner.microsoft.com/v1.0/engagements/referrals?$filter=engagementId eq '65edc0b5-3485-41b7-a17e-dfa9ef4706e2'",
          "method": "GET"
        },
        "self": {
          "uri": "https://api.partner.microsoft.com/v1.0/engagements/referrals/c5fbb3b6-be74-4795-9fb5-4324c73fed37",
          "method": "GET"
        }
      }
    }
  ],
  "@odata.nextLink": "http://api.partner.microsoft.com/v1.0/referrals?$skiptoken=k181pEdP0ykypkieJfcxX"
}

Use the @odata.nextLink to get the next page of results.

Note

The fields in this example aren't exhaustive. The actual API response contains more fields like the customer and partner teams. For the full list of supported fields, see referral resources.

Sample requests

The following example gets the top 10 most recent inbound co-sell opportunities. The request fetches opportunities initiated by a Microsoft sales representative or another partner, inviting your organization to participate in a co-selling activity.

GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$top=10&$filter=(type eq 'Shared' and direction eq 'Incoming')&$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

The following example gets the most recent inbound leads and opportunities that have not been responded to.

GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$top=10&$filter=(direction eq 'Incoming' and substatus eq 'Pending')&$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Important

If you don't respond to a lead or opportunity within the allotted time (currently 14 days), we'll archive it as Expired and notify either Microsoft or the partner who sent you this opportunity.

The following example gets the most recent active co-sell opportunities initiated by your organization and being worked on by a specific seller.

GET https://api.partner.microsoft.com/v1.0/engagements/referrals?$filter=status eq 'Active' and direction eq 'Outgoing' and type eq 'Shared' and team/any(t:t/email eq 'r2d2@contoso.com')&$orderby=createdDateTime desc HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

Next steps