Latest Bids feed
Details of the submitted bids and associated bid sheet data for a Sourcing Event are available through the Latest Bids feed shortly after certain points in the lifecycle of that event. Details will include the Sourcing Event, Lot, Supplier, bids, bid sheet values and modified time. See the OpenAPI specification for full details.
It is important to note the feed is only updated after certain key occasions in the lifecycle of an event, these include:
- The event is initially published, or re-published
- The event is resumed after it has been paused
- Bidding round is closed
- The event is closed after all bidding rounds have been completed
Any event which is in Draft state will not appear in the feed - this includes all new events which are yet to be published.
Events and rounds within an event can be reopened and bids updated before the event or round is re-closed. If the event or round is reopened but there are no changes made to the bid data, there should be no change in the feed. If an event is reopened and bid sheet values are changed, new records will be available in the feed for all updated values. No new records will be added for bid data that was not modified.
The records returned by the feed are named SupplierLotBid, each one represents the bids and bid sheet data
for each supplier and lot in a Sourcing Event. Records will only be returned for complete bids.
The feed will reference Sourcing Events and Suppliers by ID (UUID) rather than string name. The string name may be
found via the includes option, details of which are provided in the
Including additional data section of the usage page.
Examples
The following examples show how the feed may be used to get sourcing data, explaining terminology and
techniques for filtering results to match your requirements. In each example, we show the URL used with a GET request
and the corresponding response JSON. Click on the Response section to see the full response content for each example.
These examples are specific to the Latest Bids feed, to be used with the /feeds/latest-bids endpoint which is
more fully described in the OpenAPI specification.
Sample data
A single sample dataset will be used across each of the examples. This dataset is for illustrative purposes and used solely to demonstrate how filtering and other options affect the response you will get from the API. The dataset is similar in structure to the Awards sample, however has slightly different bids to demonstrate the bid data feed behaviour more clearly.
Details of the sample dataset are outlined below. To make it easier to identify the Sourcing Events and Suppliers,
IDs are in the format 00000000-Event#-Supplier#-Lot#-000000000000.
There are three Sourcing Events:
* Event 1 (00000000-1111-0000-0000-000000000000) - RFQ event
* Event 2 (00000000-2222-0000-0000-000000000000) - Dutch Auction event
* Event 3 (00000000-3333-0000-0000-000000000000) - RFQ event
There are two suppliers in each Sourcing Event:
* Supplier 1 (00000000-????-1111-0000-000000000000)
* Supplier 2 (00000000-????-2222-0000-000000000000)
Bids have been placed on lots as follows:
* Event 1 - Supplier 1 has a complete bid on both lots, Supplier 2 has bid on lot 1 only
* Event 2 - Supplier 1 has bid twice on both lots at different price points. Supplier 2 has not bid.
* Event 3 - Supplier 1 has a complete bid on both lots, Supplier 2 has a partial bid on Lot 1, and a withdrawn bid on Lot 2
Each Sourcing Event contains a single tag named "Category"
* Events 1 and 2 have `Category=PACKAGING`
* Event 3 has `Category=LOGISTICS`
Basic Bid Data feed
This example shows very simple use of the Latest Bids feed. It is unfiltered so would return all SupplierLotBid
records in the order they have been added or modified, starting from the oldest.
The Bids section describes the bids entry here and explores the more advanced behaviour seen in
Event 3 in more detail.
Including Sourcing Event data
This example shows the include feature being used to request Sourcing Event and supplier data alongside the bid data.
As previously mentioned, only data for the Sourcing Events related to the returned feed records are included. If the
number of SupplierLotBid records in the requested results is large enough to require pagination, only data for the
Sourcing Events related to the current page's bid data would be included.
Filtered example
The below example uses some of the available filtering and include techniques to show how these operations can be combined to work together. For the complete list of supported filters, see the Filters section.
The modified_after clause excludes Event 1, and the tags filter excludes Event 3, so only data for Event 2 will be
returned.
Filters
The above examples have shown a limited set of the available filter query parameters. The following list describes the complete list of filters and their behaviour. These are also detailed on the OpenAPI specification.
The filters are applied additively, and it is worth noting that certain combinations may result in no records being returned.
This filters the feed to records associated with the specified Sourcing Event id.
This filters the feed to records associated with the specified Sourcing Request id.
This filters the feed to records associated with the Sourcing Events that have the specified tags.
This filters the feed to records which have been modified within the specified date range. One or both ends of the
range may be provided. The filter may be specified as a full timestamp or just a date. If a date is supplied, the
time will default to 00:00 UTC.
Data updates
The data that is returned by the Latest Bid feed represents bids in an organisations sourcing events. Each item in data
corresponds to a bid from a supplier. The id field of each item is the UUID of a individual bid. The data returned is
always the most recent data at the time of request. Updates to data served by the Bid Data feed can occur if a Sourcing
Event is re-opened, the bids modified and the event re-closed. As mentioned previously, a similar scenario occurs if a
round is re-opened, bids modified and the round re-closed. Bid data may also be updated by the buyer after the close of
a round.
Depending on the Sourcing Event settings, bids may be partially or completely removed. This behaviour will result in updated feed records as described in the Bids section.
Records returned from the Bid Data feed can be uniquely identified using the id (UUID) field. This ID can be used to
track changes as described in Data Updates section of the usage document.
Bids
Each entry in the feed contains a bids key which is used to provide information on bidding behaviour in addition to
the raw bid sheet values provided by the bid_sheet_values data.
For all event types bids will be an array of objects.
For RFQs and English Auctions the array will contain a single object with a value field. The value here is the
result of the primary cost calculation for that supplier's inputs on that lot, in the primary currency for the
Sourcing Event. This is highlighted in the following snippet.
"data": [
...
{
"id": "00000000-2222-1111-1111-000000000000",
"sourcing_event": "00000000-2222-0000-0000-000000000000",
"supplier": "00000000-2222-2222-0000-000000000000",
"lot_name": "Lot 1",
"bids": [
{ "value": "35.71" }
],
"bid_sheet_values": [
{ "column_name": "Lot Name", "value": "Lot 1" },
{ "column_name": "Price", "value": "55", "currency": "GBP" },
{ "column_name": "Lead Time (days)", "value": "35" }
],
"modified": "2020-01-02T09:00:00.000Z"
}
...
]
For Dutch Auctions, the bids array will contain an array of objects with value and volume keys representing
the ask price(s) and corresponding volume(s) the supplier has bid on for the lot. A supplier may make multiple bids on
the same lot for different volumes at different ask prices as the auction evolves.
"data": [
...
{
"id": "00000000-2222-1111-2222-000000000000",
"sourcing_event": "00000000-2222-0000-0000-000000000000",
"supplier": "00000000-2222-1111-0000-000000000000",
"lot_name": "Lot 2",
"bids": [
{ "value": "50.00", "volume": "150" }
],
"bid_sheet_values": [
{ "column_name": "Lot Name", "value": "Lot 1" },
{ "column_name": "Initial Price", "value": "75.00", "currency": "EUR" },
{ "column_name": "Reserve", "value": "25.00", "currency": "EUR" },
{ "column_name": "Bid decrement", "value": "5" },
{ "column_name": "Volume", "value": "0" }
],
"modified": "2020-01-02T09:00:00.000Z"
},
...
]
Withdrawn bids
Withdrawn bids are also shown on Event 3 in the examples. In this case, the event was closed at some point with a bid
for supplier 2 on lot 2, but was re-opened and the bid removed. This is represented by the empty bids and
bid_sheet_values arrays highlighted below.
These records are provided to distinguish from the situation where there has never been a bid for the supplier and lot. They are intended to signal to users of the feed that if they have received previous values they may now be invalid.
"data": [
...
{
"id": "00000000-3333-2222-2222-000000000000",
"sourcing_event": "00000000-3333-0000-0000-000000000000",
"sourcing_request": "00000000-3333-0000-0000-111111111111",
"supplier": "00000000-3333-2222-0000-000000000000",
"lot_name": "Lot 2",
"bids": [ ],
"bid_sheet_values": [ ],
"modified": "2020-01-02T09:00:00.000Z"
},
...
]