Before You Start
Before you take action on a proposal or RFP via the API, you need to get its unique numeric identifier. In this guide, you will learn how to retrieve the ID of a proposal or RFP as well as how to validate a proposal.
Get the Proposal ID
The proposal number available in the UI does not allow you to take action on the proposal via the API. To use the API methods for managing proposals, you first need to get a unique proposal ID.
Note: Proposal Id
is a unique value that is assigned automatically. The proposal Number
is either assigned automatically or set by the user; it is unique for a particular provider within a specific location.
To get the proposal ID by its number, send the following request:
GET odata/proposals?$select=Id&$filter=Number eq ‘{ProposalNumber}’
Parameter | Parameter type | Example value |
---|---|---|
$select | Query | Id |
$filter | Query | Number eq ‘prp50520123151873’ |
GET https://sb2api.servicechannel.com/v3/odata/proposals?$select=Id&$filter=Number%20eq%20%27prp50520123151873%27 HTTP/1.1
Authorization: Bearer {access_token}
Example response:
{
"@odata.context": "https://sb2api.servicechannel.com/v3/odata/$metadata#proposals(Id)",
"value": [
{
"Id": 10010836
}
]
}
Response code: HTTP/1.1 200 OK
The proposal Id
is in the response body.
Because users can create proposals with the same Number
value, multiple IDs may be returned in the response. In this case, pass the request below, find the proposal you need in the response body, and save its Id
.
GET odata/proposals?$filter=Number eq ‘{ProposalNumber}’
Parameter | Parameter type | Example value |
---|---|---|
$filter | Query | Number eq ‘prp51020193044397’ |
GET https://sb2api.servicechannel.com/v3/odata/proposals?$filter=Number%20eq%20%27prp51020193044397%27 HTTP/1.1
Authorization: Bearer {access_token}
Example response
{
"@odata.context": "https://sb2api.servicechannel.com/v3/odata/$metadata#proposals",
"value": [
{
"Id": 10024251,
"Number": "prp51020193044397",
"Description": "Replace office lighting",
"..."
},
{
"Id": 10024252,
"Number": "prp51020193044397",
"Description": "New roof for renovated location",
"..."
}
]
}
Validate a Proposal
Before taking action on a proposal, you may want to validate it. To check if a proposal exists for the current user, get the proposal ID as described earlier in this guide, and send the following request:
GET proposals/{proposalId}/validate
Parameter | Parameter type | Example value |
---|---|---|
proposalId | Path | 10010836 |
GET https://https://sb2api.servicechannel.com/v3/proposals/10010836/validate HTTP/1.1
Authorization: Bearer {access_token}
Response code: HTTP/1.1 200 OK No Content
The 200 response code indicates that the specified proposal exists for the current user.
Retrieve the RFP ID
Like the proposal number, the RFP number displayed in the UI is not unique in the ServiceChannel system; it is unique only within a specific location. To delete an RFP, assign it to another user, or retrieve proposals submitted through it via the API, you need to get a unique RFP ID. Please note that only subscriber users can manage RFPs.
Important: For each RFP sent to a specific provider, a separate record is automatically created in the system, and a unique ID is assigned to each request. If an RFP was dispatched to multiple providers, each of these RFPs has a unique Id
, while their Number
is the same.
To retrieve all requests sent to providers through an RFP, pass the following request:
GET odata/rfps?$filter=Number eq ‘{RFPNumber}’
Parameter | Parameter type | Example value |
---|---|---|
$filter | Query | Number eq ‘rfp410202020733’ |
GET https://sb2api.servicechannel.com/v3/odata/rfps?$filter=Number%20eq%20%27rfp410202020733%27 HTTP/1.1
Authorization: Bearer {access_token}
Example response
{
"@odata.context": "https://sb2api.servicechannel.com/v3/odata/$metadata#rfps",
"value": [
{
"Id": 886557,
"Number": "rfp410202020733",
"..."
"ProviderEmail": "jtmaintenanceworld@gmail.com",
"..."
},
{
"Id": 894666,
"Number": "rfp410202020733",
"..."
"ProviderEmail": "ifixxservices@gmail.com",
"..."
}
]
}
Response code: HTTP/1.1 200 OK
If the RFP was sent to multiple providers, the response body contains objects for each of these requests, including a unique RFP ID for each. One object is returned if the RFP was dispatched to a single provider. The field you are looking for is Id
.