Assign or Escalate a Proposal

4 minute read

In some organizations, many employees have access to proposals. Subscriber users may sometimes need to assign a proposal to their colleagues. This is especially important to ensure that the information provided by contractors reaches the company’s decision-makers.

If the multi-level proposal approval, or MLP approval, is enabled for a subscriber, an employee can escalate a proposal to another user in their organization’s MLP approval hierarchy. Note that MLP levels are determined by your ServiceChannel administrator.

Assign a Proposal to a User

You can assign a proposal to a user in your organization if it hasn’t been assigned yet. If the proposal already has an assignee, you can reassign it to another user. The parameters required to send this API request are proposalId and userId.

Note: You cannot assign a proposal in the Approved or Rejected status via the API.

Step 1. Get the Proposal ID

Retrieve the ID of the proposal that you want to assign to a user.

Step 2. Retrieve a List of Users

Some employees in your organization may not have the necessary permissions to manage proposals. Or, they may not have access to the location or trade the proposal is created for. Before going to the next step, send the request below to retrieve a list of users that can be assigned the proposal.

GET /proposals/{proposalId}/users

Parameter Parameter type Example value
proposalId Path 10010836

Example request:

GET https://sb2api.servicechannel.com/proposals/10010836/users HTTP/1.1
Authorization: Bearer {access_token}

Example response

[
   "..."
   {
      "Id": 1417703,
      "UserName": "pmagneri-api",
      "FullName": "Pasquale Magneri",
      "Email": "pmagneri+api@servicechannel.com",
      "LevelInfo": null
   },
   {
      "Id": 1431539,
      "UserName": "SC_API_test",
      "FullName": "SC_API_test",
      "Email": "",
      "LevelInfo": null
   }
]

Response code: HTTP/1.1 200 OK

Find the user you want to assign the proposal to, and save their Id. You will need it in the next step.

Step 3. Assign the Proposal

Pass the following API request to assign the proposal to the selected user:

PUT /proposals/{proposalId}/assignUser

Header Value
Content-Type application/json
Parameter Parameter type Example value
proposalId Path 10010836
request Body See below

AssignUserToProposalRequest object

Element Data type Required Note
UserId Integer Required The unique numeric identifier of the user to assign the proposal to.
Comments String Optional Your comment describing why you are assigning or reassigning the proposal to the specified user.
UserEmail String Optional The email address to send a notification about the assigned proposal to. The default is the email address of the user who is assigned the proposal.
ReasonString String Optional Don’t pass.
Note String Optional Note added upon assigning or reassigning the proposal.

Example request:

PUT https://sb2api.servicechannel.com/proposals/10010836/assignUser HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
   "UserId": 1417703,
   "Comments": "Proposal reassigned at the request of the Store Manager",
   "UserEmail": "",
   "ReasonString": "",
   "Note": ""
}

Response code: HTTP/1.1 204 No Content

Escalate a Proposal (for MLP Users)

MLP users can escalate a proposal to another user in their company’s MLP hierarchy. When you submit this request via the API, you can also attach a work order to the proposal or create a new one.

Important: MLP users can escalate proposals only if they have the required permissions to do so:

  • The user’s approval level corresponds to the proposal level.
  • The Override option is enabled for the user in case their approval level is higher than the proposal level.

First, get the ID of the proposal you want to escalate. After that, pass the below API request:

PUT /proposals/{proposalId}/escalate

Header Value
Content-Type application/json
Parameter Parameter type Example value
proposalId Path 10010836
request Body See below

MlpWoRecommendationRequest object

Element Data type Required Note
Action String Required Proposal escalation action. Valid values: Approve, Reject, OnHold, Return.
WoType Integer Optional Work order type. Valid values: 0 — Origin, 1 — New, 2 — Existing.
TrackingNumber Integer Optional The unique numeric identifier of the work order. Required if the WoType is 2 — Existing.
PoNumber String Optional Purchase order number.
ExistingPoNumber String Optional The existing purchase order number. If the PoNumber parameter is passed, its value is used instead of ExistingPoNumber.
Category String Optional The overall classification of a WO, such as Maintenance, Repair, or CAPEX. Required if the WoType is 1 — New.
The value you enter must be a valid category. Pass the GET /categories request to find the required Category and CategoryId.
CategoryId Integer Optional Numeric identifier of the category.
ApprovalCode String Optional Approval code, or GL code, used when approving an invoice.
Priority String Optional Period during which a service provider should check in to perform the requested service. Required if the WoType is 1 — New.
The value you enter must be a valid priority. Send the GET /workorders/priorities request to retrieve a list of priorities for the current subscriber.
Comment String Optional Your comment describing why you are escalating the proposal.
RejectReasonCodeId Integer Optional Don’t pass.
ReasonString String Optional Don’t pass.
EmailsToNotify String Optional The email address of the user to notify about the proposal escalation. When entering multiple addresses, separate them with a comma or semicolon.
EmailMyself Boolean Optional Defines if the proposal escalation notification is sent to the current user.
MyEmail String Optional The email address of the current user to which a proposal escalation notification is sent.
ProposalId Integer Optional The unique numeric identifier of the proposal to escalate.

Example request:

PUT https://sb2api.servicechannel.com/proposals/10010836/escalate HTTP/1.1
Authorization: Bearer {access_token}
Content-Type: application/json

{
   "Action": "Approve",
   "WoType": 2,
   "TrackingNumber": 140324907,
   "PoNumber": "",
   "ExistingPoNumber": "",
   "Category": "",
   "CategoryId": ,
   "ApprovalCode": "",
   "Priority": "",
   "Comment": "Escalating proposal to the General Manager",
   "RejectReasonCodeId": 0,
   "ReasonString": "",
   "EmailsToNotify": "john.smith@domain.com",
   "EmailMyself": false,
   "MyEmail": "",
   "ProposalId": 10010836
}

Response code: HTTP/1.1 204 No Content

Updated: