Skip to main content
GET
/
customers
List customers
curl --request GET \
  --url https://api.simcel.io/master/v1/customers \
  --header 'Authorization: Bearer <token>'
{
  "total": 312,
  "limit": 50,
  "skip": 0,
  "data": [
    {
      "ref": "CUST-FR-001",
      "name": "Carrefour France",
      "type": "Customer",
      "channel": "Modern Trade",
      "subChannel": "Hypermarket",
      "region": "Western Europe",
      "country": "FR",
      "city": "Paris",
      "keyAccount": true,
      "status": "Active"
    }
  ]
}

​
The facility network

In SIMCEL, all physical nodes in your supply chain — customers, distributors, and distribution centers — are stored in a single Facility Master. The type field distinguishes them:
TypeDescription
CustomerEnd customer (modern trade, e-commerce, traditional trade)
SecondaryCustomerSub-customer or ship-to party downstream of a distributor
DistributorThird-party distributor in the network
DCCompany-owned or 3PL distribution center
The /customers endpoint is a convenience shortcut that returns only Customer and SecondaryCustomer records. Use /facilities when you need the full network including DCs and distributors.

​
List customers

resp = requests.get(
    "https://api.simcel.io/master/v1/customers",
    headers={"Authorization": f"Bearer {token}"},
    params={
        "workspaceId": "ws_abc123",
        "channel": "Modern Trade",
        "country": "FR",
        "limit": 100,
    }
)

for customer in resp.json()["data"]:
    ka = "⭐ Key Account" if customer.get("keyAccount") else ""
    print(f"{customer['ref']} — {customer['name']} ({customer['city']}) {ka}")

​
Get full network (all facility types)

# Get all DCs in the network
resp = requests.get(
    "https://api.simcel.io/master/v1/facilities",
    headers={"Authorization": f"Bearer {token}"},
    params={
        "workspaceId": "ws_abc123",
        "type": "DC",
    }
)

dcs = resp.json()["data"]
print(f"{len(dcs)} distribution centers found:")
for dc in dcs:
    print(f"  {dc['ref']} — {dc['name']} ({dc['country']})")

​
Override a facility

Use PATCH to correct or update facility attributes. Common use cases:
  • Reassigning a customer to a new region
  • Deactivating a closed DC
  • Updating channel classification after a trade renegotiation
resp = requests.patch(
    "https://api.simcel.io/master/v1/facilities/DC-PARIS",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    params={"workspaceId": "ws_abc123"},
    json={
        "status": "Inactive",
    }
)
print(resp.json())
# { "success": true, "overrideId": "ovr_fac_abc", "appliedAt": "..." }

​
Common use cases for AI agents

Map customers to regions for geo analysis: 
customers = []
skip = 0
while True:
    batch = requests.get(
        "https://api.simcel.io/master/v1/customers",
        headers={"Authorization": f"Bearer {token}"},
        params={"workspaceId": "ws_abc123", "limit": 500, "skip": skip}
    ).json()
    customers.extend(batch["data"])
    skip += 500
    if skip >= batch["total"]:
        break

# Group by region
from collections import defaultdict
by_region = defaultdict(list)
for c in customers:
    by_region[c.get("region", "Unknown")].append(c["ref"])

for region, refs in sorted(by_region.items()):
    print(f"{region}: {len(refs)} customers")
Cross-reference supply performance with DC metadata: 
supply = requests.get(
    "https://api.simcel.io/insights/v1/supply-performance",
    headers={"Authorization": f"Bearer {token}"},
    params={
        "planId": "plan_9xKz2",
        "scenarioIds": "scen_committed",
        "groupBy": "dc",
        "interval": "M",
    }
).json()

facilities = requests.get(
    "https://api.simcel.io/master/v1/facilities",
    headers={"Authorization": f"Bearer {token}"},
    params={"workspaceId": "ws_abc123", "type": "DC"}
).json()

dc_map = {f["ref"]: f for f in facilities["data"]}

for row in supply["scenarios"][0]["series"]:
    dc = dc_map.get(row["groupKey"], {})
    country = dc.get("country", "?")
    print(f"{row['groupKey']} ({country}) | SL: {row['serviceLevel']:.1%} | Stock: {row['closingStock']:,}")

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
workspaceId
string
required

The workspace ID to query master data from

​
channel
string

Filter by sales channel

​
region
string

Filter by region

​
country
string

Filter by country code (ISO 3166-1 alpha-2)

​
keyAccount
boolean

Filter by key account flag

​
search
string

Search by customer name or ref (partial match)

​
limit
integer
default:50

Maximum number of records to return (max 500)

Required range: x <= 500
​
skip
integer
default:0

Number of records to skip (for pagination)

Response

Paginated list of customers

​
total
integer
​
limit
integer
​
skip
integer
​
data
object[]