Additional Information & Notes

This page contains supplemental information on usage, data formats and expectations when using the API.

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

Submitting Default Values and Null Data

This section gives a brief overview of how we handle empty and invalid supplied data in It complements the API reference which provides details on the data types and defaults for each endpoint and data type.

Default Values

If a column is not provided in the payload of a request, the Keelvar API will use a default value. Defaults can be seen for all data types in the Schema specifications in OpenAPI Specification Some columns do not have defaults and these must be provided with valid values in the request, not doing so will cause a 400 Bad Request error to be raised.

For Example, if using the /api/jobs/create-sourcing-events endpoint to create a new Sourcing Event in Sourcing Optimizer, we submit a POST request with the following payload:

{
    "name": "Example Sourcing Event"
}

From Looking at the default values in the API reference, we can see that a sourcing event will be created with the following columns:

• Name: Example Sourcing Event This has come from the provided name field
• Event Type: rfq This has come from the default event_type field

Note: This is an abbreviated example. If issued as is, there would be errors elsewhere for other missing / invalid data. For more complete examples see the collection of sample requests.

Null Values

In some cases the API schema accepts null values as valid inputs. These are often data types where an empty string or zero would not make sense, for example if we expect an ISO timestamp string or a decimal string. In this case the null value has distinct meaning in that the column is intentionally not populated instead of using an empty string or a zero-value.

Using the above example of the /api/jobs/create-sourcing-events endpoint again, the following payload shows null values being used for the event schedule:

{
    "schedule": [
        {"starts": null, "ends": null}
    ]
}

This will result in a sourcing event being created with a single round, but no start or end time.

If we tried to use the following request to set the start and end times to empty strings, we get a 400 Bad Request error response as the API will reject invalid ISO timestamp strings.

{
    "schedule": [
        {"starts": "", "ends": ""}
    ]
}

Note: This is an abbreviated example. If issued as is, there would be errors elsewhere for other missing / invalid data. For more complete examples see the collection of sample requests.

Supplier External Id

An optional supplier external id may be sent as part of sourcing event and sourcing request creation. This external id will then be available for consumption on the export API for that supplier.

"suppliers": [
    {
        "name": "Supplier 1",
        "external_id": "SUPP_1",
        "contacts": [
            { "name": "Mary Jones", "email": "contact2.supplier.1@example.com" },
            { "name": "Joe Bloggs", "email": "contact1.supplier.1@example.com" }
        ]
    },
    {
        "name": "Supplier 2",
        "contacts": [
            { "name": "Max Mustermann", "email": "contact1.supplier.2@example.com" }
        ]
    }