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 amongst other details.
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 |
---|---|
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
See Partner REST headers for more information.
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}
Authorization: Bearer <token>
Content-Type: application/json
Prefer: return=representation
[
{
"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 additional debugging information. Use a network trace tool to read this code, the error type, and additional 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 a HTTP Status code 204. Add Prefer: return=representation
to the header to get the updated lead or opportunity.
Sample requests
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."} ]
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
andsubstatus
fields should conform to the allowed set of transition values.Adds a new member from your organization to the lead or opportunity team. The response will contain 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} Authorization: Bearer <token> Content-Type: application/json Prefer: return=representation [ { "op": "add", "path": "/team/-", "value": { "email": "jane.doe@contoso.com", "firstName": "Jane", "lastName": "Doe", "phoneNumber": "0000000001" } } ]
Next steps
Feedback
https://aka.ms/ContentUserFeedback.
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:Submit and view feedback for