Jobs endpoint usage
Warning
The examples provided here are just for reference and should not be used in production code.
Python requirements
- Python Version: A minimum python version of 3.6 is required for the examples to work as provided
- Required Libraries: You may need to install the requests library if it is not present in your environment
Using the Jobs API
The Keelvar intake APIs operate asynchronously to process data when creating new or updating existing Sourcing Events and Sourcing Requests. When you submit a request to the API, it is first checked against the documented schema and if it is valid, then we will return a Job ID.
The API offers endpoints for checking the status of a specific Job ID as shown in Checking the status of a job, as well as endpoints for retrieving multiple jobs, as seen in the OpenAPI Specification
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:
| Endpoint | Burst | Sustained |
|---|---|---|
api/jobs/create-sourcing-events api/jobs/create-sourcing-events-from-template api/jobs/create-sourcing-requests api/jobs/update-sourcing-event api/jobs/attach-files-to-sourcing-request api/jobs/attach-files-to-sourcing-event |
120/hour | 500/day |
api/jobs/ |
30/min | 600/hour |
Usage examples
This section provides simple code examples demonstrating how to make requests using Python or Curl and illustrate the expected responses.
In the examples below we use the following syntax to show printed output next to the commands/code that would produce it:
#>
Submitting requests
The below example creates a very basic Sourcing Event to demonstrate the usage of the Jobs API. It has a few bid-sheet columns and lots, but does not add supplier(s), formula(e) nor a custom schedule. This example and all of the others below will create a test event.
The usage examples in the following sections provide only the request payload for brevity. The data in those examples
may used to replace the payload value in the Python example, or as the data payload (after the -d option) in the curl example.
You can also customise the data as you like to add columns, lots, change settings, as long as you adhere to the schema.
Take note of the id field in the API response, as it is needed to monitor the job for completion. You can check the status
of the job by following the instructions below. In this example which creates a Sourcing Event,
Once the job status transitions to COMPLETED, the event will be visible in Sourcing Optimizer.
import requests
import json
api_key = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {api_key}"}
url = "https://my.keelvar.app/api/jobs/create-sourcing-events"
payload = {
"name": "Basic Event",
"description": "Demonstration of the Keelvar Jobs API",
"bid_sheet": {
"column_roles": {
"lot_identifier": "Lot Name"
},
"columns": [
{
"name": "Lot Name",
"column_type": "INPUT",
"input_by": "BUYER_INPUT",
"input_type": "TEXT"
},
{
"name": "Quantity",
"column_type": "INPUT",
"input_by": "BUYER_INPUT",
"input_type": "NUMBER",
"precision": 0
},
{
"name": "Unit Price",
"column_type": "INPUT",
"input_by": "SUPPLIER_INPUT",
"input_type": "CURRENCY",
"precision": 2
}
],
"lots": [
{
"name": "Lot 1",
"values": [
{"column": "Lot Name", "value": "Lot 1"},
{"column": "Quantity", "value": "100"}
]
}
]
},
"primary_cost_calculation": "Unit Price * Quantity",
"settings": {"is_test": True}
}
response = requests.post(url, headers=headers, json=payload)
# Show the Job creation result:
print(json.dumps(response.json(), indent=4))
#> {
#> "id": "4f373848-4ae5-4b73-930e-25553e7cb5a3",
#> "type": "CREATE_SOURCING_EVENT",
#> "status": "PENDING",
#> "created": "2020-01-01T09:00:00.000000Z"
#> }
curl -X POST https://my.keelvar.app/api/jobs/create-sourcing-events \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"name": "Basic Event",
"description": "Demonstration of the Keelvar Jobs API",
"bid_sheet": {
"column_roles": {
"lot_identifier": "Lot Name"
},
"columns": [
{
"name": "Lot Name",
"column_type": "INPUT",
"input_by": "BUYER_INPUT",
"input_type": "TEXT"
},
{
"name": "Quantity",
"column_type": "INPUT",
"input_by": "BUYER_INPUT",
"input_type": "NUMBER",
"precision": 0
},
{
"name": "Unit Price",
"column_type": "INPUT",
"input_by": "SUPPLIER_INPUT",
"input_type": "CURRENCY",
"precision": 2
}
],
"lots": [
{
"name": "Lot 1",
"values": [
{"column": "Lot Name", "value": "Lot 1"},
{"column": "Quantity", "value": "100"}
]
}
]
},
"primary_cost_calculation": "Unit Price * Quantity",
"settings": {"is_test": true}
}'
#> {"id":"40570e96-eed1-401a-a160-0d9cd306e17b","type":"CREATE_SOURCING_EVENT","status":"PENDING","created":"2020-01-01T09:00:00.000000Z"}%
Checking the status of a job
In the above example it was mentioned to note the id returned when making requests to the API. This ID can be used in the
below example as JOB_ID to get the status of the job. The normal flow is that a job will remain at the PENDING state for some
time while it is processed, then go to COMPLETED if successful or FAILED if there was a problem.
If the job status is COMPLETED, the created entity UUID (i.e. a Sourcing Event) will be seen in the created_entity field
of the response.
If an error happens during job processing and the status returns FAILED, the reason will be shown in the errors field of the response.
import requests
import json
api_key = "YOUR_API_KEY"
job_ID = "JOB_ID"
headers = {"Authorization": f"Bearer {api_key}"}
url = "https://my.keelvar.app/api/jobs/create-sourcing-events/{job_id}"
response = requests.get(f"{url}/{job_id}", headers=headers)
# Print the final job details
print(json.dumps(response.json(), indent=4))
#> {
#> "id": "4f373848-4ae5-4b73-930e-25553e7cb5a3",
#> "type": "CREATE_SOURCING_EVENT",
#> "status": "COMPLETED",
#> "created": "2020-01-01T09:00:00.000000Z"
#> "created_entity": "e88b78da-62a0-11ee-882c-b82ef852b962"
#> }
# Note the created_entity is the created Sourcing Event UUID if creation was successful
job_id="JOB_ID"
curl -X GET https://my.keelvar.app/api/jobs/$job_id -H 'Authorization: Bearer YOUR_API_KEY'
#> {"id":"40570e96-eed1-401a-a160-0d9cd306e17b","type":"CREATE_SOURCING_EVENT","status":"COMPLETED","created":"2020-01-01T09:00:00.000000Z","created_entity": "e88b78da-62a0-11ee-882c-b82ef852b962"}%