Updating Sourcing Event Examples
The following JSON examples may be used with the jobs endpoints as described in Usage.
The examples are specific to the update sourcing event API endpoint (/jobs/update-sourcing-events). Further details
on supported payload fields can be found in the OpenAPI Specification.
Info
Attributes excluded from the request payload will not be mutated on the Sourcing Event.
Updating an existing Sourcing Event
In this example, the sourcing_event ID corresponds with an event that exists in Keelvar. With this request,
we will update the name and settings.is_test and we will also set some tags and define a user role.
Basic Example
Existing Sourcing Event
For this example, we will be using an existing sourcing event (00000000-0000-0000-0000-000000000000) that has been created with the following specification:
Follow-up example
Building on our previous example, we will update the user's role type, modify a tag, and change the test status.
Follow-up Example
Existing Sourcing Event
For this example, we will be using our existing sourcing event (00000000-0000-0000-0000-000000000000) with the modification from our last request in the previous example:
{
"sourcing_event": "00000000-0000-0000-0000-000000000000",
"name": "My sourcing event (test)",
"event_type": "AUCTION",
"roles": [
{ "email": "editor@example.buyer.com", "role_type": "VIEWER" }
],
"tags": [
{ "name": "Category", "value": "Logistics" },
{ "name": "Project", "value": "PROJECT_ABC" }
],
"settings": {
"is_test": true
}
}
Updating Suppliers
Existing events can be updated with new Suppliers as follows:
"suppliers": [
{
"name": "Acme Inc",
"external_id": "ACME_123",
"contacts": [
{ "name": "John Doe", "email": "john.doe@acme.com" },
{ "name": "Jane Doe", "email": "jane.doe@acme.com" }
]
},
{
"name": "Bloggs Inc",
"external_id": "BLOGGS_123",
"contacts": [
{ "name": "Joe Bloggs", "email": "joe.bloggs@bloggs.com" }
]
},
]
Following on from the previous example existing suppliers for existing events can have additional contacts added as follows:
"suppliers": [
{
"name": "Bloggs Inc",
"external_id": "BLOGGS_123",
"contacts": [
{ "name": "Richard Roe", "email": "richard.roe@bloggs.com" }
]
}
]
Note it is not possible to amend existing contacts, any contacts supplied will be treated as additions. Providing an email address which already exists on the event will result in an error.
Updating tags
Tags consist of a list of regular tags (as strings) and organization tags (as a dictionary).
Use Cases:
Add a New Organization Tag
If a tag with the same name already exists, it will be updated. Otherwise, a new tag will be created.
Note: The organization tag must be created before creating the auction. This can be done using the "Tags" tab under the "Account Settings" page, where it must be set up before it can be used.
Example:
Add Two New Regular Tags
It is allowed to only update regular tags. To do so, provide a list of strings, which will be converted into tags.
Example:
Replace an Existing Regular Tag and Update an Organization Tag
To replace a regular tag and update an organization tag simultaneously, use the following format:
Example:
Remove an Organization Tag
Organization tags can be removed by sending a blank string as the value.
Example:
Extending the bidding deadline for the current round
The current round bidding close deadline can be updated as below.
{
"sourcing_event": "00000000-0000-0000-0000-000000000000",
"current_round": {
"ends": "2050-01-01T10:00:00+00:00"
}
}
Note that the bidding close updates for the current round, the sourcing event must be open when changing the bidding end time.
Renaming bid sheet columns
Use bid_sheet_column_renames to change the display names of existing bid sheet columns on a draft event. Specify the target column using either column_id or column_name (the current display name, matched case-insensitively). If both are provided, column_id takes priority.
{
"sourcing_event": "00000000-0000-0000-0000-000000000000",
"bid_sheet_column_renames": [
{
"column_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
"new_name": "Unit price (USD)"
},
{
"column_name": "Delivery weeks",
"new_name": "Lead time (weeks)"
}
]
}
Appending RFI questions
Use rfi_questions to append additional RFI questions to a draft event's RFI. New questions are added after any existing questions; this is append-only, so existing questions are never reordered or edited.
- Only flat, top-level questions are supported; sub-questions cannot be added via the API.
- Any
categoriesreferenced must already be defined on the event's RFI. Unknown category names are rejected. - A
currencyset on a question must be one of the event's currencies.
{
"sourcing_event": "00000000-0000-0000-0000-000000000000",
"rfi_questions": [
{
"text": "What is your typical lead time in weeks?",
"input_type": "NUMBER",
"question_type": "OPTIONAL"
},
{
"text": "Do you hold ISO 9001 certification?",
"input_type": "SINGLE_CHOICE",
"question_type": "MANDATORY",
"options": [
{ "value": "Yes" },
{ "value": "No" }
]
}
]
}
Adding bid sheet columns
Use bid_sheet_columns_to_add to append new columns to a draft event's bid sheet. Columns can be supplier-input (the default — each supplier fills in their own value when bidding) or buyer-input (the purchaser sets values upfront). New columns are added to the end of the bid sheet in payload order.
{
"sourcing_event": "00000000-0000-0000-0000-000000000000",
"bid_sheet_columns_to_add": [
{
"name": "Delivery weeks",
"input_type": "NUMBER",
"input_by": "SUPPLIER_INPUT",
"precision": 0
},
{
"name": "Country of origin",
"input_type": "TEXT"
},
{
"name": "Insurance cost",
"input_type": "CURRENCY",
"precision": 2
}
]
}
Adding line items
Use bid_sheet_lots_to_add to append new line items (lots) to a draft event's bid sheet. New line items are added after any existing ones; this is append-only. Each line item's values set buyer columns by column name — supplier-input and computed (formula/integration) columns cannot be set this way. Line items may be incomplete: values for mandatory columns can be filled in before the event is published.
Line item names must be unique (case-insensitive) within the event. When combined with bid_sheet_columns_to_add or bid_sheet_column_renames in the same request, line items are applied after the column changes, so they can reference columns added in the same call.
{
"sourcing_event": "00000000-0000-0000-0000-000000000000",
"bid_sheet_lots_to_add": [
{
"name": "Lot 3",
"values": [
{"column": "Volume", "value": "100"},
{"column": "Destination", "value": "Dublin"}
]
},
{
"name": "Lot 4"
}
]
}
Updating line items
Use bid_sheet_lots_to_update to amend existing line items (lots) on a draft event's bid sheet. Each update targets a lot by lot_id (preferred) or lot_name (matched case-insensitively). new_name renames the lot. values sets buyer-input cell values by column name. Supplier-input and computed (formula/integration) columns cannot be set this way.
Each lot can only appear once per batch. When combined with bid_sheet_columns_to_add, bid_sheet_column_renames, or bid_sheet_lots_to_add in the same request, updates are applied after those operations, so they can reference the resulting state.
{
"sourcing_event": "00000000-0000-0000-0000-000000000000",
"bid_sheet_lots_to_update": [
{
"lot_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
"new_name": "Lot 1A",
"values": [
{"column": "Volume", "value": "150"}
]
},
{
"lot_name": "Lot 2",
"values": [
{"column": "Volume", "value": "200"},
{"column": "Destination", "value": "Cork"}
]
}
]
}