Feeds endpoints usage

Feed data

The Keelvar Export API provides access to your sourcing data in a way that is designed for end to end automation in conjunction with the Sourcing Intake APIs.

Sourcing data is extracted and transformed into formats that are tailored for machine-driven access patterns and processing mechanisms. The API structure is designed to handle small and large Sourcing Events consistently.

Querying for data

The data feeds provide easy to use options for filtering results, the details of these are fully documented in our OpenAPI specification, and we provide some common usage examples to get you started in the example sections for each data feed - e.g. Award feed

Rate Limits

The API imposes rate limits on the number of requests you can make within a specific time window.

A burst and sustained rate exist for the API endpoints:

Including additional data

Export feeds will typically refer to entities like events, suppliers and bid sheet column by ID/UUID rather than their user defined names. The mapping of ID/UUID to name along with other meta data can be retrieved using the includes function. See the OpenAPI specification for any feed-specific details.

The details of related entities may be requested using the include query parameter which is available on the Export APIs where it is required. For example, you can request that Sourcing Event summary data, Suppliers and Bid Sheet Columns be included alongside the main award data when using the Award feed. Related entities will be provided by their keys in the includes key of the response, as can be seen in the provided example: Including Sourcing Event data

The include parameter is optional, you may opt in to receiving some, all or none of the additional data. The default behaviour is to have no includes.

If the feed data is split across multiple pages, the includes feature will only include entities that are related to the feed data for the specific page returned in the feed response.

Modification dates

Export API feeds use a modified timestamp to track when a record was last updated. This field can be leveraged in date based filters to retrieve records that were updated in a given time window.

To use Awards feed as an example, when a Sourcing Event is awarded and closed, the modified timestamps returned from the Awards feed will reflect when the data was made available to the API.

If someone were to re-open the Sourcing Event, modify the award and re-close it, the Awards feed would reflect the award changes. The modified timestamp would only be updated for the records that had actually changed however.

See Dates, Times and Timezones

Data updates

The data returned by the Export API feeds can change over time. Changes may include the addition of new records or the modification or removal of existing ones.

Modified records are always appended to the dataset backing the feed, so may appear out of order. To illustrate this with an example, imagine a feed dataset with 5 records as shown below.

This is the order in which the data would be returned if requested from the feed at this point. If record 4 was updated to wxyz and record 2 was deleted, this is how the feed data would be returned:

The above example assumes that only current data is returned from a feed, which is the default behaviour for most feeds. If a feed does allow both current and historic data to be returned it will be highlighted in the documentation for that specific feed.

Currency handling

This section outlines how currencies will be represented in the feed responses. In many of the feed examples, you will see a currency code specified with an accompanying numeric value. This is seen on feeds which provide bid sheet values, such as the Awards and Bid Data feeds.

The snippet below is taken from the Basic Award feed example and highlights such a value.

"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": "1"},
                    { "column_name": "Price", "value": "60.00", "currency": "EUR" },
                    { "column_name": "Lead Time (days)", "value": "25" }
                ]
            }
        ],
    },
    ...
]

Linked Currency Columns

Even if the currency is defined at a bid sheet column level or using the linked currency columns feature within Sourcing Optimizer, the currency that is to be applied to the bid sheet value will be explicitly specified for each currency value.

Converting to Primary Currency

If a user wishes to convert a value with a currency defined to the primary currency of the Sourcing Event, they must fetch the exchange rates for that event using the "includes" mechanism described in the Including Sourcing Event data example. As indicated in the highlighted portion of the snippet below, this shows the exchange rates specified on the Sourcing Event to the event's primary currency.

"data": [
    ...
],
"includes": {
    "sourcing_events": [
        {
            "id": "00000000-1111-0000-0000-000000000000",
            "name": "Event 1",
            "primary_currency": "USD",
            "secondary_currencies": [
                { "code": "EUR", "exchange_rate": "1.2" },
                { "code": "GBP", "exchange_rate": "1.4" }
            ],
            ...
        },
        ...
    ],
    ...
}

Dates, Times and Timezones

All dates and times throughout the entire API for both input and output are ISO 8601 standard and use UTC as the timezone. The following examples highlighting 1 second before midnight:

Zero offset UTC timezone
2030-12-31T23:59:59Z
2030-12-31T23:59:59+00:00

Pagination

Any pagination details found in the standard HTTP Header Link are duplicated in any response body alongside the standard results under fields called next and/or prev.