Skip to main content

Using the Master Data API

Workist requires master data from the ERP system. Master data can be submitted:

  • As a file
  • As a link to a publicly accessible file
  • As a list of objects in JSON format (in chunks)

Up to seven groups of master data objects are supported:

GroupRequired
Customers (buyers / debtors)
Delivery addresses (goods recipients)optional
Invoice addresses (invoice recipients)optional
Contact persons (of the goods recipient)optional
Articles
Customer-specific articlesoptional
Framework agreementsoptional

Each group is identified by a lookup_definition_id.

API Documentation (Swagger): https://api.workist.com/v1/swagger/

Notes on Bulk Imports​

Workist always receives complete master data imports (no delta updates). Large amounts of data can be paginated (chunks of 1000 elements each).

Procedure:

  1. Create a batch import with "batched": true in POST /master-data/imports → returns import_id
  2. Add data batches via POST /master-data/imports/:import_id/data
  3. Trigger processing manually via POST /master-data/imports/:import_id/start
import requests
import json

def chunk(it, size):
    from itertools import islice
    it = iter(it)
    return iter(lambda: tuple(islice(it, size)), ())

base_url = "https://api.workist.com/api/v1/master-data"
lookup_definition_id = "<Article Lookup Definition ID>"
token = "<Your Auth Token>"
headers = {"Authorization": f"Bearer {token}"}

articles = [
    {"article_id1": "123", "description": "abc", "order_units": ["PCS", "KG"]},
    {"article_id1": "456", "description": "def", "order_units": ["KG"]},
    {"article_id1": "789", "description": "def", "order_units": ["M"]}
]
articles_chunked = list(chunk(articles, 1))

url = f"{base_url}/articles/imports"
response = requests.request("POST", url, headers=headers, data={
    "lookup_definition_id": lookup_definition_id,
    "batched": True,
})
import_id = response.json().get("import_id")

for articles_batch in articles_chunked:
    url = f"{base_url}/imports/{import_id}/data"
    response = requests.request("POST", url, headers=headers, data={"data": json.dumps(articles_batch)})

url = f"{base_url}/articles/start"
response = requests.request("POST", url, headers=headers)

Customers​

clients = [
    {"client_id1": "C-001", "company_name": "Test SE", "address1": "Test street 1", ...},
    {"client_id1": "C-002", "company_name": "Muster GmbH&Co. KG", ...}
]
url = f"{base_url}/clients/imports?replace=True"
payload = {"lookup_definition_id": "<your lookup definition>", "data": json.dumps(clients)}
response = requests.request("POST", url, headers=headers, data=payload)

Delivery Addresses​

Linked to customers via partition_id. The delivery address field should contain company names only.

delivery_addresses = [
    {"partition_id": "C-001", "address_id1": "L-001", "name": "Tester 2 GmbH", "address1": "Test street 2", ...}
]
url = f"{base_url}/addresses/imports?replace=True"
payload = {"lookup_definition_id": "<your lookup definition>", "data": json.dumps(delivery_addresses)}
response = requests.request("POST", url, headers=headers, data=payload)

Articles​

order_unit must be submitted as an array (e.g. ["KG", "STK"]).

articles = [
    {"article_id1": "ART-001", "description": "Sensor Module", "order_units": ["PCE", "KG"]},
]
url = f"{base_url}/articles/imports?replace=True"
payload = {"lookup_definition_id": "<your lookup definition>", "data": json.dumps(articles)}
response = requests.request("POST", url, headers=headers, data=payload)

Customer-Specific Articles​

Each entry requires partition_id (customer reference) and article_id1 (internal article). article_id2 contains the customer article number.

client_articles = [
    {"partition_id": "C-001", "article_id1": "ART-001", "article_id2": "CUST-ART-555"},
]
url = f"{base_url}/articles/imports?replace=True"
payload = {"lookup_definition_id": "<your client-specific lookup definition>", "data": json.dumps(client_articles)}
response = requests.request("POST", url, headers=headers, data=payload)

Import Status​

url = f"https://api.workist.com/api/v1/master-data/imports/{import_id}"
response = requests.request("GET", url, headers=headers)
# Returns: {"id": "...", "status": "SUCCESS", "lookup_type": "ARTICLE_LOOKUP", ...}

Postman Collection​

A Postman collection for the master data API is available on request. Contact your Workist representative or email support@workist.com.

Lookup Definition IDs​

Lookup IDs can be configured per channel in Workist:

  1. Select a channel
  2. Open the menu in the top right → "Manage channel"
  3. Select "Master data"
  4. Copy the IDs

For more details: Retrieve Lookup IDs