Supplier Management API 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.9 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 Supplier Management endpoints

The Keelvar Supplier APIs operate asynchronously to process data when creating new or updating existing Suppliers in Keelvar. 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 reference ID.

The API offers endpoints for the following:

Retrieving individual Suppliers shown in Retrieve a Specific Supplier.
Retrieving all Supplier records shown in Retrieve All Suppliers.
Creating one or more new Suppliers shown in Creating Suppliers.
Updating one or more existing Suppliers shown in Updating Suppliers.
Retrieving the details of any Supplier Changes submitted show in Manage Supplier Changes.

A more detailed breakdown of the requests and the response data is described 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/manage/suppliers`	30/min	600/hour
`api/manage/supplier_changes` (`GET`)	30/min	600/hour
`api/manage/supplier_changes` (`POST`)	60/hour	500/day

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:

#>

The below examples demonstrate how to retrieve and modify Supplier information by using the Supplier Management APIs.

First, we will retrieve a list of all the Suppliers in Keelvar. Then get detailed information for a singular supplier. Finally, we will create and modify some suppliers.

Retrieve All Suppliers

PythonCurl

import requests
import json

api_key = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {api_key}"}
url = "https://my.keelvar.app/api/manage/suppliers"

response = requests.get(url, headers=headers)

# Show the Supplier result:
print(json.dumps(response.json(), indent=2))

{
  "result": [
    {
      "external_id": "KV_0001",
      "name": "Keelvar's Supplier",
      "fields": {
        "ESG Score": "59"
      },
      "archived": false
    },
    {
      "external_id": "KV_0002",
      "name": "Keelvar's Other Supplier",
      "fields": {
        "ESG Score": "81"
      },
      "archived": false
    }
  ],
  "count": 2,
  "page_size": 20,
  "page_number": 1,
  "num_pages": 1,
  "next": null,
  "previous": null,
  "used_endpoints": [
    "manage/suppliers"
  ],
  "gsn": 42,
  "includes": {},
  "extras": {}
}

curl -X GET https://my.keelvar.app/api/manage/suppliers \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \

#> {"result":[{"name":"Keelvar's Supplier","external_id":"KV_0001","fields":{"ESG Score":"59"},"archived":false},{"name":"Keelvar's Other Supplier","external_id":"KV_0002","fields":{"ESG Score":"59"},"archived":false}],"count":2,"page_size":20,"page_number":1,"num_pages":1,"next":null,"previous":null,"used_endpoints":["manage/suppliers"],"gsn":42,"includes":{},"extras":{}}%

Retrieve a Specific Supplier

In the above example we can see the external_id was returned when listing all the suppliers. This ID can be used in the below example as to get detailed for a single supplier. It will also be used to update Supplier information in later examples.

PythonCurl

import requests
import json

api_key = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {api_key}"}
url = "https://my.keelvar.app/api/manage/suppliers/KV_0001"

response = requests.get(url, headers=headers)

# Show the Supplier result:
print(json.dumps(response.json(), indent=2))

{
  "result": {
    "external_id": "KV_0001",
    "name": "Keelvar's Supplier",
    "fields": {
      "ESG Score": "59"
    },
    "archived": false
  },
  "used_endpoints": [
    "manage/suppliers"
  ],
  "gsn": 42,
  "includes": {},
  "extras": {}
}

$external_id="KV_0001"
curl -X GET https://my.keelvar.app/api/manage/suppliers/$external_id -H 'Authorization: Bearer YOUR_API_KEY'

#> {"result":{"name":"Keelvar's Supplier","external_id":"KV_0001","fields":{"ESG Score":"59"},"archived":false},"used_endpoints":["manage/suppliers"],"gsn":42,"includes":{},"extras":{}}%

Creating Suppliers

This operation is supported by the manage/supplier_changes endpoint. You will see in the below example the change_data field contains all of the suppliers to be created. Each supplier to be created is uniquely identified via the external_id. It is possible to create multiple suppliers in a single request, by providing the details of each supplier in the suppliers field.

Once submitted the request is fulfilled asynchronously. You can leverage the url or uuid returned on submission to retrieve the request status from the Manage Supplier Changes endpoint.

Note: Supplier profile attributes declared in the fields must be created online, new attribute creation is not supported via the APIs.

PythonCurl

import requests
import json

api_key = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {api_key}"}
url = "https://my.keelvar.app/api/manage/supplier_changes"
data = {
    "change_data": {
        "suppliers": [
            {
                "name": "My Supplier",
                "external_id": "kv_0003",
                "fields": {
                    "Contact Name": "John Doe",
                    "Contact Email": "john.doe@email.com"
                }
            }
        ]
    },
}

response = requests.post(url, headers=headers, data=data)

# Show the Job creation result:
print(json.dumps(response.json(), indent=2))

{
  "result": {
    "url": "http://my.keelvar.app/api/manage/supplier_changes/c32d7d1a-1b83-11f0-96af-93fccb08484e",
    "uuid": "c32d7d1a-1b83-11f0-96af-93fccb08484e"
  },
  "used_endpoints": [
    "manage/supplier_changes"
  ],
  "gsn": 42,
  "includes": {},
  "extras": {}
}

curl -X POST https://my.keelvar.app/api/manage/supplier_changes
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer YOUR_API_KEY'
-d '{
        "change_data": {
            "suppliers": [
                {
                    "name": "My Supplier",
                    "external_id": "kv_0003",
                    "fields": {
                        "Contact Name": "John Doe",
                        "Contact Email": "john.doe@email.com"
                    }
                }
            ]
        },
    }'

#> {'result': {'url': 'http://my.keelvar.app/api/manage/supplier_changes/c32d7d1a-1b83-11f0-96af-93fccb08484e', 'uuid': 'c32d7d1a-1b83-11f0-96af-93fccb08484e'}, 'used_endpoints': ['manage/supplier_changes'], 'gsn': 42, 'includes': {}, 'extras': {}}%

Updating Suppliers

This operation is supported by the manage/supplier_changes endpoint. You will see in the below example the change_data field contains all of the suppliers to be updated. Each supplier to be updated is uniquely identified via the external_id. It is possible to update multiple suppliers in a single request, by providing the details of each supplier to be updated in the suppliers field.

Once submitted the request is fulfilled asynchronously. You can leverage the url or uuid returned on submission to retrieve the request status from the Manage Supplier Changes endpoint.

Note: Supplier profile attributes declared in the fields must be created online, updating attributes which do not yet exist, is not supported via the APIs.

PythonCurl

import requests
import json

api_key = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {api_key}"}
url = "https://my.keelvar.app/api/manage/supplier_changes"
data = {
    "change_data": {
        "suppliers": [
            {
                "name": "My Renamed Supplier",
                "external_id": "kv_0003",
                "fields": {
                    "Contact Name": "Jane Doe",
                    "Contact Email": "jane.doe@email.com"
                }
            }
        ]
    },
}

response = requests.post(url, headers=headers, data=data)

# Show the Job creation result:
print(json.dumps(response.json(), indent=2))

{
  "result": {
    "url": "http://my.keelvar.app/api/manage/supplier_changes/c32d7d1a-1b83-11f0-96af-93fccb08484e",
    "uuid": "c32d7d1a-1b83-11f0-96af-93fccb08484e"
  },
  "used_endpoints": [
    "manage/supplier_changes"
  ],
  "gsn": 42,
  "includes": {},
  "extras": {}
}

curl -X POST https://my.keelvar.app/api/manage/supplier_changes
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer YOUR_API_KEY'
-d '{
        "change_data": {
            "suppliers": [
                {
                    "name": "My Renamed Supplier",
                    "external_id": "kv_0003",
                    "fields": {
                        "Contact Name": "Jane Doe",
                        "Contact Email": "jane.doe@email.com"
                    }
                }
            ]
        },
    }'

#> {'result': {'url': 'http://my.keelvar.app/api/manage/supplier_changes/c32d7d1a-1b83-11f0-96af-93fccb08484e', 'uuid': 'c32d7d1a-1b83-11f0-96af-93fccb08484e'}, 'used_endpoints': ['manage/supplier_changes'], 'gsn': 42, 'includes': {}, 'extras': {}}%

Manage Supplier Changes

This endpoint provides details of any supplier changes which have been submitted. As the supplier changes are processed asynchronously, the data returned from this API provides the progress and results of any supplier change submissions. It is possible to list all the supplier change submissions:

PythonCurl

import requests
import json

api_key = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {api_key}"}
url = "https://my.keelvar.app/api/manage/supplier_changes/"

response = requests.get(url, headers=headers)

# Show the Job creation result:

{
  "result": [
    {
      "uuid": "e24d792d-1b82-11f0-8526-42390dd5eafe",
      "current_state": "UNPROCESSED",
      "state_errors": {},
      "change_summary": null,
      "change_warnings": null,
      "created_by": "ef315a29-52bb-43de-b2d5-8939ed1f666b",
      "last_changed": "2025-04-17T23:59:59.999Z",
      "user_name": "John Doe",
      "url": "http://my.keelvar.app/api/supplier_changes/e24d792d-1b82-11f0-8526-42390dd5eafe"
    },
    {
      "uuid": "e24df25f-1b82-11f0-81f6-d2a40fc813f6",
      "current_state": "UNPROCESSED",
      "state_errors": {},
      "change_summary": null,
      "change_warnings": null,
      "created_by": "96f463fa-85c8-48cc-b412-e2d1354e7093",
      "last_changed": "2025-04-17T23:59:59.999Z",
      "user_name": "Jane Doe",
      "url": "http://my.keelvar.app/api/supplier_changes/e24df25f-1b82-11f0-81f6-d2a40fc813f6"
    },
    {
      "uuid": "e24e093c-1b82-11f0-a694-96edbc220a4f",
      "current_state": "PROCESSED",
      "state_errors": {},
      "change_summary": [{"header": "Updated Suppliers", "messages": ["The following supplier has been updated: 'My Renamed Supplier'."]}],
      "change_warnings": [],
      "created_by": "2abdc640-3384-4ab8-afbc-e045d150f014",
      "last_changed": "2025-04-17T23:59:59.999Z",
      "user_name": "John Doe",
      "url": "http://my.keelvar.app/api/supplier_changes/e24e093c-1b82-11f0-a694-96edbc220a4f"
    }
  ],
  "count": 3,
  "page_size": 20,
  "page_number": 1,
  "num_pages": 1,
  "next": null,
  "previous": null,
  "used_endpoints": [
    "manage/supplier_changes"
  ],
  "gsn": 42,
  "includes": {},
  "extras": {}
}

curl -X GET https://my.keelvar.app/api/manage/supplier_changes/ -H 'Authorization: Bearer YOUR_API_KEY'

#> {'result': [{'uuid': 'a4e10cf8-1b82-11f0-b753-3a34fe6c3fc0', 'organisation': '00000000-0000-0000-0000-000000000000', 'state': {'current': 'UNPROCESSED', 'errors': {}, 'is_transitioning': False, 'attempts': 0, 'parameters': {}}, 'current_state': 'UNPROCESSED', 'state_errors': {}, 'change_summary': None, 'change_warnings': None, 'change_type': '', 'created_by': 'ce85b641-2c3c-462a-ae19-a2440af289d6', 'last_changed': '2025-04-17T23:59:59.999Z', 'file_name': '', 'url': 'http://my.keelvar.app/api/supplier_changes/a4e10cf8-1b82-11f0-b753-3a34fe6c3fc0'}, {'uuid': 'a4e18bb5-1b82-11f0-98a4-4d9fb57e0691', 'organisation': '00000000-0000-0000-0000-000000000000', 'state': {'current': 'UNPROCESSED', 'errors': {}, 'is_transitioning': False, 'attempts': 0, 'parameters': {}}, 'current_state': 'UNPROCESSED', 'state_errors': {}, 'change_summary': None, 'change_warnings': None, 'change_type': '', 'created_by': 'a6344f76-2166-40e5-bace-e3626ac82552', 'last_changed': '2025-04-17T23:59:59.999Z', 'file_name': '', 'url': 'http://my.keelvar.app/api/supplier_changes/a4e18bb5-1b82-11f0-98a4-4d9fb57e0691'}, {'uuid': 'a4e1a4a4-1b82-11f0-9be0-341b3847b8e0', 'organisation': '00000000-0000-0000-0000-000000000000', 'state': {'current': 'UNPROCESSED', 'errors': {}, 'is_transitioning': False, 'attempts': 0, 'parameters': {}}, 'current_state': 'UNPROCESSED', 'state_errors': {}, 'change_summary': None, 'change_warnings': None, 'change_type': '', 'created_by': '8cb2ea49-a178-430f-8270-e1cd74a213a3', 'last_changed': '2025-04-17T23:59:59.999Z', 'file_name': '', 'url': 'http://my.keelvar.app/api/supplier_changes/a4e1a4a4-1b82-11f0-9be0-341b3847b8e0'}], 'count': 3, 'page_size': 20, 'page_number': 1, 'num_pages': 1, 'next': None, 'previous': None, 'used_endpoints': ['manage/supplier_changes'], 'gsn': 42, 'includes': {}, 'extras': {}}%

It is also possible to retrieve the details of a specific supplier change submission:

PythonCurl

import requests
import json

api_key = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {api_key}"}
uuid = "d9b0ae9c-1b80-11f0-a259-71a905176953"
url = f"https://my.keelvar.app/api/manage/supplier_changes/{uuid}"

response = requests.get(url, headers=headers)

# Show the Job creation result:
print(json.dumps(response.json(), indent=2))

{
  "result": {
    "uuid": "d8962d7c-1b81-11f0-be0e-272654970920",
    "current_state": "UNPROCESSED",
    "state_errors": {},
    "change_summary": null,
    "change_warnings": null,
    "created_by": "2a35a520-909b-444b-af4e-edaeace1fd45",
    "last_changed": "2025-04-1723:59:59.999Z",
    "user_name": "John Doe",
    "url": "http://my.keelvar.app/api/supplier_changes/d8962d7c-1b81-11f0-be0e-272654970920"
  },
  "used_endpoints": [
    "manage/supplier_changes"
  ],
  "gsn": 42,
  "includes": {},
  "extras": {}
}

$uuid="d9b0ae9c-1b80-11f0-a259-71a905176953"
curl -X GET https://my.keelvar.app/api/manage/supplier_changes/$uuid -H 'Authorization: Bearer YOUR_API_KEY'

#> {'result': {'uuid': '53795971-1b82-11f0-819c-802a369aac2a', 'organisation': '00000000-0000-0000-0000-000000000000', 'state': {'current': 'UNPROCESSED', 'errors': {}, 'is_transitioning': False, 'attempts': 0, 'parameters': {}}, 'current_state': 'UNPROCESSED', 'state_errors': {}, 'change_summary': None, 'change_warnings': None, 'change_type': '', 'created_by': '15623518-df7e-4b87-8fea-697c6c47ae50', 'last_changed': '2025-04-17T23:59:59.999Z', 'file_name': '', 'url': 'http://my.keelvar.app/api/supplier_changes/53795971-1b82-11f0-819c-802a369aac2a'}, 'used_endpoints': ['manage/supplier_changes'], 'gsn': 42, 'includes': {}, 'extras': {}}%