Assign or Escalate a Proposal
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 |
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. |
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. |
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