Developer

Bid Express REST API Documentation

Bid Express® REST API Documentation

This API is intended for use by authorized developers and administrators who desire to interface with particular Bid Express functionalities. Use case possibilities range from simple scripting to complex integration within enterprise applications.

To use the API, client applications should make requests conforming to a RESTful HTTPS protocol. Response bodies are given in XML. A request URI determines the action and response. Specific details and request examples are given throughout this documentation, navigable on the left side of this page.

Because the Bid Express API is based on open standards, you can use any web development language to access the API.

Retrieving a Solicitation ID Number

This action allows API clients to find the Solicitation ID Number of the solicitation associated with a known Draft Solicitation ID Number. This number will be required for you to use certain actions in this API (for example, retrieving open bids). Please note that Solicitations ID Numbers are assigned once a draft solicitation is advertised. Therefore, Solicitation ID Numbers are not immediately available upon draft solicitation creation. Instead, we provide this endpoint for lookup of a Solicitation ID Number based upon a known Draft Solicitation ID Number.

URL

https://www.bidexpress.com/api/solicitations/find
Method GET
Request Parameters
Name Optional? Value
username required A valid Bid Express user id (email)
password required The password for the account specified in the username parameter.
draft_solicitation_id required Integer id of the draft solicitation whose associated solicitation you wish to retrieve
**Only accounts that have a Manager or Contract Administrator role can be used to access this API function.
Success Response

Code: 200 Content: The ID number of the associated solicitation and a success message.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: Could not find a solicitation associated with the provided Draft Solicitation ID.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X GET \
https://www.bidexpress.com/api/solicitations/find \
-F draft_solicitation_id=2 \
-F username=my_username@example.com \
-F password=my_password

Retrieving All Open Bids for a Solicitation

URL

https://www.bidexpress.com/api/solicitations/{solicitation_id}

Replace {solicitation_id} with the id of your solicitation

Example: https://www.bidexpress.com/api/solicitations/37
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express user id (email)
password required The password for the account specified in the username parameter.
include_all optional Boolean parameter that controls inclusion of Out-of-Date and Non-Responsive bids in the returned listing of open bids. Set this parameter to "true", "yes" or "1", to include all Out-of-Date and Non-Responsive bids in the response. Default: false.
**Only accounts that have a Manager or Contract Administrator role can be used to access this API function.
Success Response

Code: 200 Content: The specified solicitation and all its open bids in XML format.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified solicitation could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/solicitations/17 \
-F username=my_username@example.com \
-F password=my_password
Sample Output Open A Sample XML File For All Open Bids For a Solicitation

Retrieving a Single Bid

URL

https://www.bidexpress.com/api/bids/{bid_id}

Replace {bid_id} with the id of the bid you wish to retrieve

Example: https://www.bidexpress.com/api/bids/1048
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express user id (email)
password required The password for the account specified in the username parameter.
**Only accounts that have a Manager or Contract Administrator role can be used to access this API function.
Success Response

Code: 200 Content: The specified bid in XML format.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified bid could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/bids/13 \
-F username=my_username@example.com \
-F password=my_password
Sample Output Open A Sample XML File For A Single Bid

Retrieving All Bidders

This action allows API clients to retrieve a list of all Bidders for all closed Solicitations from a given Agency.

URL

https://www.bidexpress.com/api/bidders/
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express Agency user id (email)
password required The password for the account specified in the username parameter.
**An active Agency user account is needed to access this API function.
Success Response

Code: 200 Content: The specified bidders list in XML format.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified bidders could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/bidders \
-F username=my_username@example.com \
-F password=my_password
Sample Output Open A Sample XML File For All Bidders

Retrieving All Plan Holders

This action allows API clients to retrieve a list of all Plan Holders for all closed Solicitations from a given Agency.

URL

https://www.bidexpress.com/api/plan_holders
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express Agency user id (email)
password required The password for the account specified in the username parameter.
**An active Agency user account is needed to access this API function.
Success Response

Code: 200 Content: The specified plan holders list in XML format.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified plan holders could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/plan_holders \
-F username=my_username@example.com \
-F password=my_password
Sample Output Open A Sample XML File For All Plan Holders

Retrieving Attachments

In order to retrieve attachments for a solicitation, you will have to parse the XML that is returned when retrieving the solicitation and all its open bids (See Retrieving All Open Bids for a Solicitation). If the solicitation has attachments, one or more <attachment_url> elements will be present in the XML that is returned. The value of each of the <attachment_url> elements is the URI path you will use to retrieve each individual attachment. You will need to make a separate API call for each attachment you wish to retrieve.

URL

https://www.bidexpress.com/api/store/attachment/s3_attachment/{attachment_id}/{file_name}

{attachment _id} is the id of the attachment

{file_name} is the file name of the attachment

Example: https://www.bidexpress.com/api/store/attachment/attachment/106/PlanSheet.doc
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express user id (email)
password required The password for the account specified in the username parameter.
**Only accounts that have a Manager or Contract Administrator role can be used to access this API function.
Success Response

Code: 200 Content: The contents of the attachment

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified attachment could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/store/attachment/s3_attachment/1/test_image.jpg \
-F username=my_username@example.com \
-F password=my_password -o ~/test_image.jpg

Retrieving Required Documents

In order to retrieve required documents for a bid, you will have to parse the XML that is returned when retrieving that bid (See Retrieving All Open Bids for a Solicitation or Retrieving a Single Bid). If the bid has required documents, one or more <opened_document_url> elements will be present in the XML that is returned. The value of each of the <opened_document_url> elements is the URI path you will use to retrieve each individual required document. You will need to make a separate API call for each required document you wish to retrieve.

URL

https://www.bidexpress.com/api/store/bid_required_document/s3_opened_document/{required_document_id}/{file_name}

{required_document_id} is the id of the required document

{file_name} is the file name of the required document

Example: https://www.bidexpress.com/api/store/bid_required_document/s3_opened_document/96/Cert.doc
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express user id (email)
password required The password for the account specified in the username parameter.
**Only accounts that have a Manager or Contract Administrator role can be used to access this API function.
Success Response

Code: 200 Content: The contents of the attachment

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified required document could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/store/bid_required_document/s3_opened_document/1/test_image.jpg \
-F username=my_username@example.com \
-F password=my_password -o ~/test_image.jpg

Retrieving Plan Holders for a Solicitation

URL

https://www.bidexpress.com/api/solicitations/{solicitation_id}/plan_holders

{solicitation_id} is the id of the solicitation

Example: https://www.bidexpress.com/api/solicitations/96/plan_holders
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express user id (email)
password required The password for the account specified in the username parameter.
**Only accounts that have a Manager or Contract Administrator role can be used to access this API function.
Success Response

Code: 200 Content: The specified plan holders list in XML format.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified solicitation could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/solicitations/1/plan_holders \
-F username=my_username@example.com \
-F password=my_password

Retrieving Upcoming Solicitations

This action allows API clients to retrieve a list of solicitations with a deadline past a specified date. A select subset of header information for each matching solicitation (deadline, description, etc.) is also returned.

URL

https://www.bidexpress.com/api/solicitations/upcoming
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express user id (email)
password required The password for the account specified in the username parameter.
from_date optional A valid date in string format (can include a time). All upcoming solicitations returned by this API endpoint will have a deadline that is equal to or greater than this date. If timezone information is omitted, the timezone of the account making this request will be assumed. Default: current date & time.
include_restricted optional Boolean parameter that controls inclusion of restricted solicitations in the returned listing of upcoming solicitations. Solicitations marked “Publicly post restricted bid information as read only” are included by default. Set to "true", "yes" or "1" to also include restricted solicitations not already marked 'Public'. Default: false.
**An active Agency user account is needed to access this API function.
Success Response

Code: 200 Content: A list of upcoming solicitations (including select solicitation header information) in XML format.

Error Response

Code: 400 BAD REQUEST Reason: An invalid date was specified.

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/solicitations/upcoming \
-F 'username=my_username@example.com' \
-F 'password=my_password' \
-F 'from_date=2022-03-01 12:00:00 PM EST' \
-F include_restricted=true
Sample Output Open A Sample XML File For Upcoming Solicitations

Retrieving Solicitations for a Bidder

This action allows API clients to retrieve a list of all of an Agency's closed Solicitations which have opened Bids (including Out-of-Date and Non-Responsive Bids) from a given user.

URL

https://www.bidexpress.com/api/bidder/solicitations
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express Agency user id (email)
password required The password for the account specified in the username parameter.
email required The email address for the requested bidder.
**An active Agency user account is needed to access this API function.
Success Response

Code: 200 Content: The specified solicitations list in XML format.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified solicitations could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/bidder/solicitations \
-F username=my_username@example.com \
-F password=my_password \
-F email=bidder_email@example.com
Sample Output Open A Sample XML File For All Solicitations For a Bidder

Retrieving Solicitations for a Plan Holder

This action allows API clients to retrieve a list of all of an Agency's closed Solicitations for which a given user is a Plan Holder.

URL

https://www.bidexpress.com/api/plan_holder/solicitations
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express Agency user id (email)
password required The password for the account specified in the username parameter.
email required The email address for the requested plan holder.
**An active Agency user account is needed to access this API function.
Success Response

Code: 200 Content: The specified solicitations list in XML format.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified solicitations could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/plan_holder/solicitations \
-F username=my_username@example.com \
-F password=my_password \
-F email=plan_holder_email@example.com
Sample Output Open A Sample XML File For All Solicitations For a Plan Holder

Retrieving Solicitation Details

This action allows API clients to retrieve a solicitation and any or all of its components.

URL

https://www.bidexpress.com/api/solicitations/{solicitation_id}/details

Replace {solicitation_id} with the id of your solicitation

Example: https://www.bidexpress.com/api/solicitations/37/details
Method POST
Request Parameters
Name Optional? Value
username required A valid Bid Express user id (email)
password required The password for the account specified in the username parameter.
component_titles optional A comma-separated list of titles of those solicitation components that should be returned with this API request. If omitted or left blank, only solicitation header information is returned.
**An active Agency user account is needed to access this API function.
Success Response

Code: 200 Content: The specified solicitation, including the selected components, in XML format.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 404 NOT FOUND Reason: The specified solicitation could not be found.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -X POST \
https://www.bidexpress.com/api/solicitations/17/details \
-F 'username=my_username@example.com' \
-F 'password=my_password' \
-F 'component_titles=Item List 1, Required Document List, Custom Component 1'
Sample Output Open A Sample XML File For Solicitation Details

Creating a Draft Solicitation

URL

https://www.bidexpress.com/api/draft_solicitations
Method POST
Body Payload Parameters
Name Optional? Value
username required A valid Bid Express user id (email)
password required The password for the account specified in the username parameter.
draft_solicitation required Hash with parameters for creating draft solicitation.
  • template_name - Name of the template from which the draft solicitation will be created. {template_name}
  • number - Number for the draft solicitation that will be created. {number}
  • description - Description for the draft solicitation that will be created. {description}
  • restricted - Specifies if the draft solicitation is restricted. {"true" OR "false"}
  • deadline - specifies the deadline of draft solicitation. {yyyy-mm-dd hh:mm:ssAM/PM EST}
  • auto_advertise_at - Specifies when the draft solicitation should be auto advertised. {yyyy-mm-dd hh:mm:ssAM/PM EST}
  • restricted_vendors - Array of emails to whom the draft solicitation will be accessible once advertised. ["vendor1@example.com"]
template_name, number are required parameters.
**Only accounts that have a Manager or Contract Administrator role can be used to access this API function.
Success Response

Code: 200 Content: The id and url of the newly created draft solicitation in XML format.

Error Response

Code: 401 UNAUTHORIZED Reason: The supplied credentials are invalid.

Code: 500 INTERNAL SERVER ERROR Reason: An unspecified error has occurred.

Sample Request

A sample request using the cURL command-line tool:

curl -d '{"username":"my_username@example.com", "password":"my_password", "draft_solicitation": { "template_name": "my_template_name", "number": "solicitation_number" }}' -H "Content-Type: application/json"
-X POST
https://www.bidexpress.com/api/draft_solicitations