Skip to content

Sourcing Events Feed

Overview

High level details for a Sourcing Event are available through the Sourcing Event feed. The data that is returned by the feed represents sourcing events for an organisation.

Each item in data corresponds to a sourcing event. The id field of each item is the sourcing event UUID. Details will include the event name, type, status, currencies, tags, and bid sheet columns. For full details see the OpenAPI specification

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 created and in Draft state
  • 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
  • The event has been deleted

For more details of this see: Gotchas: Data updates

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 Sourcing Events feed, to be used with the /feeds/sourcing-events 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 Bid Data feed example.

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.

Sourcing Events
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
Suppliers
There are two suppliers in each Sourcing Event:
* Supplier 1 (00000000-????-1111-0000-000000000000)
* Supplier 2 (00000000-????-2222-0000-000000000000)
Tags
Each Sourcing Event contains a single tag named "Category"
* Events 1 and 2 have `Category=PACKAGING`
* Event 3 has `Category=LOGISTICS`
Sourcing Requests
One Event has been created using a Sourcing Request:
* Event 3 - sourcing request ID 00000000-3333-0000-1111-111111111111
Further details
* Bid sheet columns are intentionally stripped-down to simplify the examples.
  Event 1 has the most columns to give a more realistic idea of how an event would be represented.

Basic Sourcing Event feed

This example shows very simple use of the Sourcing Events feed. It is unfiltered so would return all SourcingEvent records in the order they have been added or modified, starting from the oldest.

Request

GET /api/feeds/sourcing-events
Response 
{
    "data": [
        {
            "id": "00000000-1111-0000-0000-000000000000",
            "name": "Event 1",
            "reference_id":  "E1GN-1",
            "type": "RFQ",
            "roles":  [
                {
                    "role_type":  "ADMIN",
                    "user": [{ "id": "00000000-1111-0000-0000-000000000001", "email": "admin_user@example.com" }]
                }
            ],
            "closed": "2020-01-01T18:00:00.000000Z",
            "created": "2020-01-01T09:00:00.000000Z",
            "created_by": {
                "id": "00000000-1111-0000-0000-000000000001",
                "email": "creator@example.com"
            },
            "published": "2020-01-01T10:00:00.000000Z",
            "rounds": [
                { 
                  "starts": "2020-01-01T10:00:00.000000Z",
                  "ends": "2020-01-01T16:00:00.000000Z",
                  "status": "COMPLETE",
                  "awarded_cost": "100.00",
                  "awarded_lot_count": 100 
                },
                { 
                  "starts": "2020-01-02T10:00:00.000000Z",
                  "ends": "2020-01-02T16:00:00.000000Z",
                  "status": "ACTIVE"
                }
            ],
            "event_contact": { "name": "Full name", "email": "user@example.com" },
            "status": "OPEN",
            "columns": [
                { "name": "Lot Name" },
                { "name": "Quantity" },
                { "name": "Price" },
                { "name": "Lead Time (days)" }
            ],
            "lot_count": 15,
            "scenario_count": 5,
            "evaluated_scenario_count": 3,
            "is_test": false,
            "primary_currency": "USD",
            "secondary_currencies": [
                { "code": "EUR", "exchange_rate": "1.2" },
                { "code": "GBP", "exchange_rate": "1.4" }
            ],
            "suppliers": [
                { 
                    "id": "00000000-1111-1111-0000-000000000000",
                    "name": "Supplier 1",
                    "invite_count": 1,
                    "accepted": true,
                    "participated": true,
                    "external_id": "SUPP_1",
                    "last_successful_bid" : "2020-01-01T18:00:00.000000Z",
                    "last_failed_bid" : "2020-01-01T00:00:00.000000Z",
                    "last_accessed": "2020-01-01T18:00:00.000000Z"
                },
                { 
                    "id": "00000000-1111-2222-0000-000000000000",
                    "name": "Supplier 2",
                    "invite_count": 1,
                    "accepted": true,
                    "participated": false,
                    "external_id": "SUPP_2" 
                }
            ],
            "tags": [
                { "name": "Category", "value": "PACKAGING" }
            ],
            "category": "Construction",
            "modified": "2020-01-01T18:00:00.000000Z"
        },
        {
            "id": "00000000-2222-0000-0000-000000000000",
            "name": "Event 2",
            "reference_id":  "E1GN-2",
            "type": "DUTCH",
            "roles":  [
                {
                    "role_type":  "ADMIN",
                    "user": [{ "id": "00000000-2222-0000-0000-000000000001", "email": "admin_user@example.com" }]
                }
            ],
            "closed": "2020-01-02T18:00:00.000000Z",
            "created": "2020-01-01T09:00:00.000000Z",
            "created_by": {
                "id": "00000000-2222-0000-0000-000000000001",
                "email": "creator@example.com"
            },
            "published": "2020-01-01T10:00:00.000000Z",
            "rounds": [
                { 
                  "starts": "2020-01-01T10:00:00.000000Z",
                  "ends": "2020-01-02T16:00:00.000000Z",
                  "status": "COMPLETE",
                  "awarded_cost": "100.00",
                  "awarded_lot_count": 100 
                }
            ],
            "event_contact": { "name": "Full name" },
            "status": "CLOSED",
            "is_test": false,
            "primary_currency": "EUR",
            "columns": [
                { "name": "Lot Name" },
                { "name": "Initial Price" },
                { "name": "Reserve" },
                { "name": "Bid decrement" },
                { "name": "Volume" }
            ],
            "suppliers": [
                { 
                    "id": "00000000-2222-1111-0000-000000000000",
                    "name": "Supplier 1",
                    "invite_count": 1,
                    "accepted": true,
                    "participated": true,
                    "last_successful_bid" : "2020-01-01T18:00:00.000000Z",
                    "last_failed_bid" : "2020-01-01T00:00:00.000000Z",
                    "last_accessed": "2020-01-02T18:00:00.000000Z"
                },
                { 
                    "id": "00000000-2222-2222-0000-000000000000",
                    "name": "Supplier 2",
                    "invite_count": 1,
                    "accepted": true,
                    "participated": true,
                    "last_successful_bid" : "2020-01-02T18:00:00.000000Z",
                    "last_failed_bid" : "2020-01-02T00:00:00.000000Z",
                    "last_accessed": "2020-01-02T18:00:00.000000Z"
                }
            ],
            "tags": [
                { "name": "Category", "value": "PACKAGING" }
            ],
            "category": "Construction",
            "modified": "2020-01-02T18:00:00.000000Z"
        },
        {
            "id": "00000000-3333-0000-0000-000000000000",
            "name": "Event 3",
            "reference_id":  "E1GN-3",
            "type": "RFQ",
            "roles":  [
                {
                    "role_type":  "ADMIN",
                    "user": [{ "id": "00000000-3333-0000-0000-000000000001", "email": "admin_user@example.com" }]
                },
                {
                    "role_type":  "EDITOR",
                    "user": [{ "id": "00000000-3333-0000-0000-000000000002", "email": "editor_user@example.com" }]
                },
                {
                    "role_type":  "VIEWER",
                    "user": [{ "id": "00000000-3333-0000-0000-000000000003", "email": "viwer_user@example.com" }]
                }
            ],
            "closed": "2020-01-03T17:00:00.000000Z",
            "created": "2020-01-02T09:00:00.000000Z",
            "created_by": {
                "id": "00000000-3333-0000-0000-000000000001",
                "email": "creator@example.com"
            },
            "published": "2020-01-02T10:00:00.000000Z",
            "rounds": [
                { 
                  "starts": "2020-01-02T10:00:00.000000Z",
                  "ends": "2020-01-03T16:00:00.000000Z",
                  "status": "COMPLETE",
                  "awarded_cost": "100.00",
                  "awarded_lot_count": 100 
                }
            ],
            "event_contact": { "email": "contact@example.com" },
            "status": "CLOSED",
            "lot_count": 10,
            "scenario_count": 1,
            "evaluated_scenario_count": 1,
            "is_test": false,
            "columns": [
                { "name": "Lot Name" },
                { "name": "Price" },
                { "name": "Lead Time (days)" }
            ],
            "suppliers": [
                { 
                    "id": "00000000-3333-1111-0000-000000000000",
                    "name": "Supplier 1",
                    "invite_count": 1,
                    "accepted": true,
                    "participated": true,
                    "last_successful_bid" : "2020-01-02T18:00:00.000000Z",
                    "last_failed_bid" : "2020-01-02T00:00:00.000000Z",
                    "last_accessed": "2020-01-02T18:00:00.000000Z"
                },
                { 
                    "id": "00000000-3333-2222-0000-000000000000",
                    "name": "Supplier 2",
                    "invite_count": 1,
                    "accepted": true,
                    "participated": true,
                    "last_successful_bid" : "2020-01-02T18:00:00.000000Z",
                    "last_failed_bid" : "2020-01-02T00:00:00.000000Z",
                    "last_accessed": "2020-01-02T18:00:00.000000Z"
                }
            ],
            "primary_currency": "EUR",
            "tags": [
                { "name": "Category", "value": "LOGISTICS" }
            ],
            "category": "Alternative",
            "bot": "dac13760-4d2d-4b7c-aa93-274ec71755ee",
            "sourcing_requests": [ "00000000-3333-0000-1111-111111111111" ],
            "modified": "2020-01-03T15:00:00.000000Z"
        }
    ]
}

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.

Request

GET /api/feeds/sourcing-events?modified_after=2020-01-02&filter[tags.Category]=PACKAGING
Response 
{
    "data": [
        {
            "id": "00000000-2222-0000-0000-000000000000",
            "name": "Event 2",
            "reference_id":  "E1GN-2",
            "type": "DUTCH",
            "roles":  [
                {
                    "role_type":  "ADMIN",
                    "user": [{ "id": "00000000-2222-0000-0000-000000000001", "email": "admin_user@example.com" }]
                }
            ],
            "closed": "2020-01-02T18:00:00.000000Z",
            "created": "2020-01-01T09:00:00.000000Z",
            "created_by": {
                "id": "00000000-2222-0000-0000-000000000001",
                "email": "creator@example.com"
            },
            "published": "2020-01-01T10:00:00.000000Z",
            "rounds": [
                { 
                  "starts": "2020-01-01T10:00:00.000000Z",
                  "ends": "2020-01-02T16:00:00.000000Z",
                  "status": "COMPLETE",
                  "awarded_cost": "100.00",
                  "awarded_lot_count": 100 
                }
            ],
            "event_contact": { "name": "Full name" },
            "status": "CLOSED",
            "is_test": false,
            "primary_currency": "EUR",
            "columns": [
                { "name": "Lot Name" },
                { "name": "Initial Price" },
                { "name": "Reserve" },
                { "name": "Bid decrement" },
                { "name": "Volume" }
            ],
            "suppliers": [
                {
                    "id": "00000000-2222-1111-0000-000000000000",
                    "name": "Supplier 1",
                    "invite_count": 1,
                    "accepted": true,
                    "participated": true,
                    "last_successful_bid" : "2020-01-01T18:00:00.000000Z",
                    "last_failed_bid" : "2020-01-01T00:00:00.000000Z",
                    "last_accessed": "2020-01-02T18:00:00.000000Z"
                },
                {
                    "id": "00000000-2222-2222-0000-000000000000",
                    "name": "Supplier 2",
                    "invite_count": 1,
                    "accepted": true,
                    "participated": true,
                    "last_successful_bid" : "2020-01-02T18:00:00.000000Z",
                    "last_failed_bid" : "2020-01-02T00:00:00.000000Z",
                    "last_accessed": "2020-01-02T18:00:00.000000Z"
                }
            ],
            "tags": [
                { "name": "Category", "value": "PACKAGING" }
            ],
            "category": "Construction",
            "modified": "2020-01-02T18:00:00.000000Z"
        }
    ]
}

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 the specified Sourcing Event id.

GET /api/feeds/sourcing-events?id=00000000-2222-0000-1111-000000000000

This filters the feed to records associated with the specified Sourcing Request id. You can specify multiple sourcing requests using a comma separated list.

GET /api/feeds/sourcing-events?sourcing_requests=00000000-3333-0000-0000-000000000000

This filters the feed to Sourcing Events that have the specified tags.

GET /api/feeds/sourcing-events?filter[tags.Category]=LOGISTICS

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.

GET /api/feeds/sourcing-events?modified_after=2020-01-01&modified_before=2020-01-03

This filters the feed to Sourcing Events with a specified status.

GET /api/feeds/sourcing-events?status=OPEN

Gotchas

Data Updates

The data returned is the most recent data in the feed at the time of requests. However the feed is only updated at certain key occasions during the lifecycle of an event described in the Overview

It is therefore possible that the event status in Sourcing Optimiser may not be the same as that in the feed.

Events and their bidding rounds can be reopened and bids updated before the event or round is then re-closed. Any changes made will be reflected in the latest data retrieved from the Sourcing Event feed.

Records returned from the Sourcing Event 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.

Published / Closed Fields

As it is possible to unpublish, republish, close and then subsequently reopen events - The published and closed fields represent the most recent occasion the actions were performed.

Rounds Field

Within the rounds field there is a status which is one of:

  • PENDING
  • ACTIVE
  • CLOSED
  • COMPLETE

Note that CLOSED and COMPLETE have two distinct meanings in Sourcing Optimiser. CLOSED is an interim state, where the round has ended but not yet been awarded. COMPLETE is the end state, where the round has both ended and been awarded. Entries in the rounds field which are in the COMPLETE state will have the awarded_cost and awarded_lot_count fields for that round present and populated.

Missing Fields

As new fields are added to the Sourcing Event feed over time. It is possible events may not contain the data for the newly introduced fields. Typically if these new fields are empty / blank for any given event, they are omitted from the feed.