Update a Proposal Status
Once created, a proposal is in the Open status. Subscribers can put a proposal on hold, approve, reject, or reopen it. If the project was canceled, or the scope of work changed, you can review submitted proposals again and update their status at any time if needed.
Note: You cannot approve a proposal in the following cases:
- The work order (WO) linked to the proposal is already invoiced.
- There is no work order attached to the proposal. Learn how to link a WO to a proposal.
- The proposal amount exceeds your approval limit. Find out more about setting limits for users in ServiceChannel University.
Before you change a proposal status, get the proposal ID. If you want to reject a proposal, retrieve valid values for the RejectReasonCodeId
parameter.
RejectReasonCodeId
Pass the request below to get a list of reasons for rejecting a proposal:
The response body contains reason codes and their detailed descriptions.
Now you can use the following API methods to update a proposal status:
PUT /proposals/{proposalId}/open to open a proposal
PUT /proposals/{proposalId}/onhold to put a proposal on hold
PUT /proposals/{proposalId}/approve to approve a proposal
PUT /proposals/{proposalId}/reject to reject a proposal
Header | Value |
---|---|
Content-Type | application/json |
Parameter | Parameter type | Required | Note |
---|---|---|---|
proposalId | Path | Required | Unique numeric identifier of the proposal, for example, 10010836. |
request | Body | Required | See the UpdateProposalStatusRequest object below for details. |
useProposalAlertEmails | Boolean | Optional | This parameter is only available in the PUT /proposals/{proposalId}/reject method. It defines if a proposal rejection notification is sent to all users listed in the Proposals/Proposal Alerts section of Dispatch Preferences: • true : Users from the Proposals/Proposal Alerts list get a proposal rejection notification if the ProviderEmail and UserEmail parameters are not passed.• false or not passed: This parameter is ignored. |
UpdateProposalStatusRequest
object
Element | Data type | Required | Note |
---|---|---|---|
Comments | String | Optional | Your comment describing why you are changing the proposal status. The comment is added to the work order note. |
ProviderEmail | String | Optional | Provider’s email address to which a notification about the proposal status change is sent. The default is the email address of the provider the proposal is assigned to. |
UserEmail | String | Optional | User’s email address to which a notification about the proposal status change is sent. The default is the email address of the current user. |
RejectReasonCodeId | Integer | Optional | Numeric identifier of the reason for rejecting the proposal. Pass value to this parameter when sending the PUT /proposals/{proposalId}/reject request. To retrieve a list of rejection reason codes and their descriptions, use the GET /proposals/RejectionReasons method. |
ActionSource | String | Optional | Parameter indicating whether the proposal status is updated based on the recommendations of the Decision Engine tool or not. Valid values: Standard, DecisionEngine. |
ReasonString | String | Optional | Reason for approving the proposal. Pass value to this parameter when sending the PUT /proposals/{proposalId}/approve request. The reason you enter is added to the work order note. |
Example request to reject a proposal:
PUT https://sb2api.servicechannel.com/v3/proposals/10010836/reject?useProposalAlertEmails=true HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
{
"Comments": "The project is canceled",
"ProviderEmail": "",
"UserEmail": "",
"RejectReasonCodeId": 7,
"ActionSource": "Standard",
"ReasonString": ""
}
Example request to approve a proposal:
PUT https://sb2api.servicechannel.com/v3/proposals/10010836/approve HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json
{
"Comments": "The project starts earlier than expected",
"ProviderEmail": "",
"UserEmail": "",
"RejectReasonCodeId": 0,
"ActionSource": "Standard",
"ReasonString": "Best fit for the job and scope"
}
Response code: HTTP/1.1 204 No Content
If the request succeeds, the proposal status is updated.