Before You Start

2 minute read

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.

The proposal number displayed on the Proposals List in Service Automation

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’

Example request:

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’

Example request:

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

Example request:

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.

The RFP number displayed on the RFPs List in Service Automation

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’

Example request:

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.

Updated: