Update a Proposal Status

2 minute read

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.

Updating a proposal status via the API

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.

Updated: