Share via

Get the list of leads and opportunities

  • Article

This article explains how to get the list of leads and Co-sell opportunities. These leads are received from Microsoft's Solution-Provider page, whereas Co-sell opportunities are received from Microsoft sellers or other partners. This process also fetches 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 Referrals 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: 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

For more information, see Partner REST headers.

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
Request-ID: 9f8bed52-e4df-4d0c-9ca6-929a187b0731
Content-Type: application/json

{
  "@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": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "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 retrieves 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 retrieves the most recent inbound leads and opportunities that aren't 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

Related content