Sourcing Request Creation Examples
The following examples provide JSON data which may be used with the jobs endpoints as described in Usage.
These examples are specific to the sourcing request creation API, to be used with the /jobs/sourcing-requests endpoint which is fully described
in the OpenAPI Specification.
Create a Basic Sourcing Request
The below example creates a very basic, single item Sourcing Request. It has some purchaser inputs, a request description and custom bidding deadline. No suppliers are added as part of this Sourcing Request. Note that suppliers can be added on intake or at a later stage in the sourcing workflow.
The bot field represents the unique identifier (UUID) of the Sourcing Request bot which will process this request. This identifier may be found
in the example request shown in the bot configuration page within the Autonomous Sourcing application.
You will need to provide the correct identifier for your Sourcing Request bot, otherwise the request will not be created and the job will return an error.
The description field is optional and if populated, will be visible to suppliers via their invitation email and event overview in Sourcing Optimizer.
{
"bot": "00000000-0000-0000-0000-000000000000",
"description": "Ocean FCL 40' High Cube 9'6 from IEORK to USNYC",
"bidding_deadline": "2024-01-01T09:00:00.000Z",
"item_fields": [
[
{
"name": "Reason for Ocean Freight", "value": "Previous contract expired"
},
{
"name": "Transportation Mode", "value": "Port to Port"
},
{
"name": "Origin Port Code", "value": "IEORK"
},
{
"name": "Destination Port Code", "value": "USNYC"
},
{
"name": "Container Type", "value": "40' High Cube 9'6"
},
{
"name": "Number of Containers", "value": "14"
}
]
]
}
Note on Sourcing Request item_fields structure
Before we dive into a more advanced example, we should examine how the basic Sourcing Request item_fields structure is
defined in a little more detail.
Each element in the item_fields list represents an item to be added to the Sourcing Request, and within each item is a list
of key-value objects. The key-value objects each refer to a Sourcing Request intake field, with the field name in the name key,
and the value assigned using the value key.
The following key-value object taken from the above example will assign a value of "14" to the request intake field called "Number of Containers".
Create a more advanced Sourcing Request
The example below creates a Sourcing Request with a little more detail than previously demonstrated, using more of the features available in Autonomous Sourcing. It will create a Sourcing Request with multiple request items and some suppliers. A requester email is also included, which specifies the user associated with the created request. It's also possible to add tags.
Request description and bidding deadline are not included in this example. Note that the bidding deadline and request description
can be added at a later stage in the sourcing workflow. By default, bidding_deadline is set to 7 days if not provided/updated
by the requester.
The suppliers field consists of a list of supplier and contact specifications as seen in the example.
{
"bot": "00000000-0000-0000-0000-000000000000",
"requester": "requester@organisation.com",
"item_fields": [
[
{
"name": "Reason for Ocean Freight", "value": "Previous contract expired"
},
{
"name": "Transportation Mode", "value": "Port to Port"
},
{
"name": "Origin Port Code", "value": "IEORK"
},
{
"name": "Destination Port Code", "value": "USNYC"
},
{
"name": "Container Type", "value": "40' High Cube 9'6"
},
{
"name": "Number of Containers", "value": "14"
}
],
[
{
"name": "Reason for Ocean Freight", "value": "Previous contract expired"
},
{
"name": "Transportation Mode", "value": "Port to Port"
},
{
"name": "Origin Port Code", "value": "IEORK"
},
{
"name": "Destination Port Code", "value": "DEBRV"
},
{
"name": "Container Type", "value": "40' Dry Container"
},
{
"name": "Number of Containers", "value": "5"
}
]
],
"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",
"external_id": "SUPP_2",
"contacts": [
{ "name": "Max Mustermann", "email": "contact1.supplier.2@example.com" }
]
}
],
"tags": [
{"name": "Category", "value": "Logistics"}
]
}
Note on the Intake step within the sourcing workflow
The presence of an intake step within the sourcing workflow is optional.
If an intake step is present, Sourcing Requests submitted via the sourcing request creation API will automatically be created in a Draft state. This allows requesters to review, update or add additional information, such as request description and custom bidding deadline to the request prior to submitting.
If the sourcing workflow does not contain an intake step, the request submitted via the sourcing request creation API will automatically progress to the next step in the workflow.
Note on the Supplier Selection step within the sourcing workflow
The presence of a supplier selection step within the sourcing workflow is optional.
Suppliers submitted via the sourcing request creation API are automatically added to the Sourcing Event, provided a supplier selection step is not present on the sourcing workflow.
If the sourcing workflow contains a supplier selection step, the output of that step will be used instead of suppliers added via the API.
Note on Sourcing Request intake downstream validation
Due to the complex nature of input data for Sourcing Requests, and the delayed verification of some data at the point of Sourcing Event creation, it is not always possible to validate all data in the intake API.
The following notes are provided to ensure successful creation of Sourcing Events downstream of any Sourcing Requests submitted via the API:
- Supplier contact emails, if specified, must be valid in order for Sourcing Optimizer to dispatch event invite emails.
- If the Sourcing Request bot which will process the request has mandatory fields specified, these fields must be populated prior to the creation of the Sourcing Event. If the workflow configuration is set so that requests are submitted as a DRAFT, awaiting submission by a requester user, mandatory fields can be updated/populated manually on the UI. However, if the workflow configuration is set so that requests are progressed automatically past DRAFT stage (perhaps to Supplier Selection, Approval or Event Creation), then all mandatory fields must be completed as part of the sourcing request creation API
Notifications in event schedule
Multiple timed notifications can be setup for each round as part of the event schedule. Each BiddingRoundNotification is defined by a reminder_type and a relative_config. The notification types are PENDING_INVITE, BID_NOT_SUBMITTED, or BID_ACTIVITY_REPORT and each bidding round can have multiple notifications of the same type.
The relative_config is used to set the timing for each notification. Accepted value for relative_to is AFTER_START. Combined with delta_seconds, a notification can be configured to send a reminder at a fixed time after the round starts.
Auto-provision new users
The example below creates a Sourcing Request and also creates and associates the requester user which do not yet exist. It does this by auto-provisioning the user account with the specified details.
{
"bot": "00000000-0000-0000-0000-000000000000",
"description": "Ocean FCL 40' High Cube 9'6 from IEORK to USNYC",
"requester": {
"full_name": "John Doe",
"email": "john.doe@example.com"
},
"bidding_deadline": "2025-01-01T09:00:00.000Z",
"item_fields": [
[
{
"name": "Lot Name", "value": "Lot Value"
}
]
]
}
Note: That for a successful user auto-provision, it is necessary to supply both an email and a full_name at a minimum. If your
organisation makes use of SSO for authentication, an sso_id for each user may also be required:
{
"bot": "00000000-0000-0000-0000-000000000000",
"description": "Ocean FCL 40' High Cube 9'6 from IEORK to USNYC",
"requester": {
"full_name": "John Doe",
"email": "john.doe@example.com",
"sso_id": "john_does_sso"
},
"bidding_deadline": "2025-01-01T09:00:00.000Z",
"item_fields": [
[
{
"name": "Lot Name", "value": "Lot Value"
}
]
]
}