Award feed
When a Sourcing Event is complete, a winning scenario is nominated and the event is closed. Details of the final outcome of an event are available through the Award feed shortly after closure. Details will include the Sourcing Event, Lot, Supplier, share awarded, costing, bid values and modified time. See the OpenAPI specification for full details.
The Award feed will only show the closing state of winning bids. Unsuccessful bids and or bid data from earlier stages of the event are not included in this feed.
Events can be reopened and awards updated at any point in time. If an event is opened but the final award remains unchanged, there should be no change in the Award feed. If an event is opened and the final award is modified (e.g. new supplier selected or share size changed), the lots impacted will be updated but the remaining lots will be unchanged.
The records returned by the Award feed are called LotAward, each one represents the award information for a single
Lot in a Sourcing Event. The id field is unique and may be used for tracking data changes over time as described in
Data updates.
The Award 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 Award 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 Award feed, to be used with the /feeds/awards 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.
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#-0000-000000000000.
There are three Sourcing Events:
* Event 1 (00000000-1111-0000-0000-000000000000)
* Event 2 (00000000-2222-0000-0000-000000000000)
* Event 3 (00000000-3333-0000-0000-000000000000)
There are two suppliers in each Sourcing Event:
* Supplier 1 (00000000-????-1111-0000-000000000000)
* Supplier 2 (00000000-????-2222-0000-000000000000)
Lots have been awarded as follows:
* Event 1 - All lots awarded to Supplier 1
* Event 2 - All lots have been split between the two suppliers
* Event 3 - All lots awarded to Supplier 2
Each Sourcing Event contains a single tag named "Category"
* Events 1 and 2 have `Category=PACKAGING`
* Event 3 has `Category=LOGISTICS`
One Event has been created using a Sourcing Request:
* Event 3 - sourcing request ID 00000000-3333-0000-1111-111111111111
* There are two lots in each Sourcing Event: "Lot 1" and "Lot 2"
* Bid sheet values are intentionally stripped-down to simplify the examples. Events 2 & 3 have the minimum possible
number of bid sheet columns, while Event 1 has more to give a better idea of how they are represented.
* The events have all been processed in the past.
* The events have not been re-opened or modified since the initial event closure.
Basic Award feed
This example shows very simple use of the Awards feed. It is unfiltered so would return all LotAward records in the
order they have been added or modified, starting from the oldest.
Including Sourcing Event data
This example shows the include feature being used to request Sourcing Event data alongside the Award data.
This returns all known data so the response is quite large. As previously mentioned, only data for the Sourcing Events
related to the returned Award data is included. If the number of LotAward records in the requested results is large
enough to require pagination, only data for the Sourcing Events related to the current page's Award data would be
included.
Filtered Award feed example
The example below 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 examples outlined in this document include 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 added.
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.
Bid sheet data
As can be seen in the examples above, the Awards feed will include bid sheet values for all awarded lots.
If a lot is awarded to more than one supplier, buyer-defined values will be repeated for each supplier awarded.
Global bid inputs are values which apply at the bid sheet level instead of per-lot. To simplify processing of the Awards feed data, values of global bid inputs are copied to all lots in a Sourcing Event. In this way they can be treated the same as any other bid sheet values. In the snippet below, we can see that the first supplier bid sheet value is a global bid input, whose value is repeated across both lots.
"data": [
...
{
"id": "00000000-1111-0000-1111-000000000000",
"sourcing_event": "00000000-1111-0000-0000-000000000000",
"lot_name": "Lot 1",
...
"awards": [
{
"supplier": "00000000-1111-1111-0000-000000000000",
...
"bid_sheet_values": [
{ "column_name": "Lot Name", "value": "Lot 1" },
{ "column_name": "Quantity", "value": "Yes"}
{ "column_name": "Price", "value": "60.00", "currency": "EUR" },
{ "column_name": "Lead Time (days)", "value": "25" }
]
}
],
},
{
"id": "00000000-1111-0000-2222-000000000000",
"sourcing_event": "00000000-1111-0000-0000-000000000000",
"lot_name_": "Lot 2",
...
"awards": [
{
"supplier": "00000000-1111-1111-0000-000000000000",
...
"bid_sheet_values": [
{ "column_name": "Lot Name", "value": "Lot 2" },
{ "column_name": "Quantity", "value": "Yes"}
{ "column_name": "Price", "value": "50.00", "currency": "GBP" },
{ "column_name": "Lead Time (days)", "value": "30" }
]
}
],
},
...
]
Data updates
The data that is returned by the Awards feed represents awards in an organisations sourcing events. Each item in data
corresponds to an award in a sourcing event. The id field of each item is the UUID of a individual award. The data
returned is always the most recent data at the time of request.
Updates to data served by the Awards feed can occur if a Sourcing Event is re-opened, the award modified and the event re-closed. This may result in lots being (partially or fully) awarded to different suppliers, new lots being awarded or previously awarded lots being un-awarded.
If a given lot has been un-awarded, a record will be returned from the Awards feed containing an
empty array in the awards field. This would look the same as a lot that had never been awarded.
Records returned from the Awards 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.