Share via

Update a lead or opportunity

This article explains how to update the lead or opportunity details like the deal value, estimated close date or manage the sales stages among other details.

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
PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}

URI parameter

Name Type Required Description
ID string Yes The unique identifier for a lead or co-sell opportunity

Request headers

For more information, see Partner REST headers.

Request body

The request body follows the Json Patch format. A JSON Patch document has an array of operations. Each operation identifies a particular type of change. Examples of such changes include adding an array element or replacing a property value.

Important

The API currently only supports the replace and add operations.

Request example

PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID} HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation
Content-Type: application/json

[
    {
        "op": "replace",
        "path": "/details/dealValue",
        "value": "10000"
    },
    {
        "op": "add",
        "path": "/team/-",
        "value": {
            "email": "jane.doe@contoso.com",
            "firstName": "Jane",
            "lastName": "Doe",
            "phoneNumber": "0000000001"
        }
    }
]

Note

If the If-Match header is passed, it will be used for concurrency control.

REST Response

If successful, the response body contains the updated lead or opportunity.

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 other parameters.

Response example

HTTP/1.1 204 No Content
Content-Length: 0
Request-ID: 9f8bed52-e4df-4d0c-9ca6-929a187b0731

Tip

The response body depends on the Prefer header. If the header value is omitted in the request, the response body is empty with an HTTP Status code 204. Add Prefer: return=representation to the header to get the updated lead or opportunity.

Sample requests

  1. Updates the deal value for the opportunity to 10000 and updates the notes. There are no concurrency checks because of the absence of the If-Match header.

    PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}
Authorization: Bearer <token>
Content-Type: application/json

[
    {"op":"replace","path":"/details/dealValue","value":"10000"},
    {"op":"replace","path":"/details/notes","value":"Lorem ipsum dolor sit amet."}
]

  2. Updates the status of a lead or opportunity to Won.

    PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}
Authorization: Bearer <token>
Content-Type: application/json

[
    {"op":"replace", "path":"/status", "value":"Closed"},
    {"op":"replace", "path":"/substatus", "value":"Won"}
]

    Important

    The status and substatus fields should conform to the allowed set of transition values.

  3. Adds a new member from your organization to the lead or opportunity team. The response contains the updated lead or opportunity because of the presence of the Prefer: return=representation header.

    PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID} HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation
Content-Type: application/json

[
    {
        "op": "add",
        "path": "/team/-",
        "value": {
            "email": "jane.doe@contoso.com",
            "firstName": "Jane",
            "lastName": "Doe",
            "phoneNumber": "0000000001"
        }
    }
]

Create Deal Registrations

Use the Deal Registration API to create a deal registration in Partner Center when both the partner and the referral are eligible. For more information on deal registration concepts and workflows, see register deals in Partner Center.

Eligibility requirements

  • The partner must be approved for deal registration based on Microsoft's eligibility criteria.
  • The referral must support deal registration.

How eligibility works?

  • Partner eligibility is determined by Microsoft and isn't managed through the Partner Center Referrals workspace.
  • You can programmatically validate partner eligibility by calling the Partner Deal Registration Eligibility API before creating a deal registration.
  • The API response indicates whether the caller is allowed to proceed with deal registration creation.

The eligibility requirements ensure that only eligible partners can register deals and helps prevent failed or invalid submissions.

Partner Deal Registration Eligibility API

Request syntax

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

Request example

GET https://api.partner.microsoft.com/v1.0/engagements/partners/dealregistrationeligibility HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation

REST response

If successful, the response body contains the eligibility status.

Response success and error codes

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

Response example

HTTP/1.1 200 OK
Request-ID: 2d1bed51-2fd9-adfc-h4a7-019kk87c0627
Content-Type: application/json

{
  "isEligible": true,
  "policies": [
    {
      "isEligible": true
    }
  ]
}

Referral Deal Registration Eligibility

A referral is eligible for deal registration if all of the following conditions are met:

  • The deal type is Co-sell.
  • The customer is Microsoft Managed.
  • The total deal value is greater than USD 25,000.
  • At least one associated solution is Azure IP Co-sell eligible.
  • The Microsoft referral status is Accepted.

You can also validate referral eligibility programmatically by calling the Deal Registration Eligibility API. The API response confirms whether a given Co-sell referral qualifies for deal registration.

Deal Registration Eligibility API

Request syntax

Method Request URI
POST https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}/dealregistrations/eligibility

URI parameter

Name Type Required Description
ID string Yes The unique identifier for a co-sell opportunity

Request example

POST https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID}/dealregistrations/eligibility HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation

Note

Though it is a POST request, however there is not payload to be supplied for this http request.

REST response

If successful, the response body contains the eligibility status and set of failed and passed eligibility policies.

Response success and error codes

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

Response example

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

{
  "isEligible": true,
  "passedPolicies": [
    {
      "policyName": "isDealTypeCosellOrPartnerLed",
      "isEligible": true,
      "referralProperties": {
        "type": "Shared"
      }
    },
    {
      "policyName": "isMicrosoftReferralAcceptedOrWon",
      "isEligible": true,
      "referralProperties": {
        "status": "Active",
        "substatus": "Accepted"
      }
    },
    {
      "policyName": "isSolutionIncentiveEligible",
      "isEligible": true,
      "referralProperties": {
        "solutionId": "DEAL-123456-XYZ",
        "solutionName": "Contoso Experience Platform"
      },
      "additionalProperties": [
        "MSFT Internal Azure IP Co-Sell"
      ]
    },
    {
      "policyName": "isDealValueEligible",
      "isEligible": true,
      "referralProperties": {
        "currency": "USD",
        "dealValue": "30000"
      }
    },
    {
      "policyName": "isCustomerManaged",
      "isEligible": true,
      "referralProperties": {
        "isMatchingComplete": "true"
      },
      "additionalProperties": [
        "Managed"
      ]
    }
  ],
  "failedPolicies": []
}

Deal Registration API

Use the existing deal update operation (PATCH API) to create a deal registration.

Request example

PATCH https://api.partner.microsoft.com/v1.0/engagements/referrals/{ID} HTTP/1.1
Authorization: Bearer <token>
Prefer: return=representation
Content-Type: application/json

[
    {
        "op":"add",
        "path":"/registrations/-",
        "value":{
            "type":"AzureIPCoSell",
            "contract":{
                "currency":"USD",
                "endDateTime":"2026-02-28T09:14:19.454Z",
                "signDateTime":"2026-02-12T09:14:10.783Z",
                "startDateTime":"2026-02-12T09:14:16.319Z",
                "term":"Finite",
                "value":250000
            },
            "solutionDetails":[
                {
                    "id":"DEAL-123456-XYZ",
                    "isDeployedOnAzure":true,
                    "marketplaceTransactionDetails":{
                        "isMarketplaceTransacted":true,
                        "marketplaceTransactionDateTime":"2026-02-11T09:13:52.105Z"
                    },
                    "primaryDeploymentOn":"Partner",
                    "pricingModel":"Other",
                    "value":250000,
                    "currency":"USD"
                }
            ]
        }
    }
]

Response example

HTTP/1.1 204 No Content
Content-Length: 0
Request-ID: 9f8bed52-e4df-4d0c-9ca6-929a187b0731

Note

Once successful execution response is received, partner can fetch the source referral to see deal registration created.

Related content

  • Last updated on