Docs contents

dms

Distribution (DMS)

Channel distribution (DMS) — distributors and their territories, delivery routes and drivers, deliveries to the trade, field-sales visits and trade promotions. Use these endpoints to sync a mobile field-force app, plan daily routes and push orders down the channel.

GET/v1/dms/distributorsScope: dms:read

List distributors

Returns a cursor-paginated list of distributors. Filter by sales territory.

Query parameters

territoryoptional	stringFilter by territory code.
limitoptional	integerPage size, 1–200 (default 50).

Request

curl "https://api.apusplatform.com/v1/dms/distributors" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "data": [
    {
      "id": "dst_4f21",
      "code": "DIST-HN-07",
      "name": "Hoan Kiem Trading Co.",
      "territory": "north",
      "credit_limit": {
        "amount": 500000000,
        "currency": "VND"
      },
      "credit_used": {
        "amount": 128000000,
        "currency": "VND"
      },
      "active": true,
      "updated_at": "2026-07-14T03:11:52Z"
    }
  ],
  "has_more": true,
  "next_cursor": "crsr_2b7f"
}

POST/v1/dms/distributorsScope: dms:write

Create a distributor

Onboards a distributor into a territory. credit_limit defaults to zero (cash only).

Body

namerequired	stringLegal or trading name.
territoryrequired	stringTerritory code the distributor belongs to.
credit_limitoptional	object{ amount (minor units), currency } — revolving credit ceiling.

Request

curl -X POST "https://api.apusplatform.com/v1/dms/distributors" \
  -H "Authorization: Bearer $APUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hoan Kiem Trading Co.",
    "territory": "north",
    "credit_limit": {
      "amount": 500000000,
      "currency": "VND"
    }
  }'

Response

{
  "id": "dst_4f21",
  "code": "DIST-HN-07",
  "created_at": "2026-07-20T02:20:00Z"
}

GET/v1/dms/distributors/{id}Scope: dms:read

Retrieve a distributor

Returns a single distributor by its id, or by code (prefix the value with code_).

Path parameters

idrequired

stringDistributor id.

Request

curl "https://api.apusplatform.com/v1/dms/distributors/dst_4f21" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "id": "dst_4f21",
  "code": "DIST-HN-07",
  "name": "Hoan Kiem Trading Co.",
  "territory": "north",
  "credit_limit": {
    "amount": 500000000,
    "currency": "VND"
  },
  "credit_used": {
    "amount": 128000000,
    "currency": "VND"
  },
  "contact": {
    "name": "Le Van Minh",
    "phone": "+84 24 3825 1090"
  },
  "active": true,
  "updated_at": "2026-07-14T03:11:52Z"
}

PATCH/v1/dms/distributors/{id}Scope: dms:write

Update a distributor

Updates mutable fields of a distributor. Only supplied fields change.

Path parameters

idrequired

stringDistributor id.

Body

nameoptional	stringLegal or trading name.
territoryoptional	stringTerritory code.
credit_limitoptional	object{ amount (minor units), currency }.
activeoptional	booleanActivate or suspend the distributor.

Request

curl -X PATCH "https://api.apusplatform.com/v1/dms/distributors/dst_4f21" \
  -H "Authorization: Bearer $APUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credit_limit": {
      "amount": 650000000,
      "currency": "VND"
    }
  }'

Response

{
  "id": "dst_4f21",
  "code": "DIST-HN-07",
  "updated_at": "2026-07-20T02:22:00Z"
}

GET/v1/dms/delivery-routesScope: dms:read

List delivery routes

Returns delivery routes, filterable by date and assigned driver.

Query parameters

dateoptional	stringRoute date (YYYY-MM-DD).
driver_idoptional	stringFilter by assigned driver id.

Request

curl "https://api.apusplatform.com/v1/dms/delivery-routes" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "data": [
    {
      "id": "rte_9c30",
      "date": "2026-07-21",
      "driver_id": "drv_71a2",
      "vehicle": "29H-114.02",
      "stops": 12,
      "status": "planned"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST/v1/dms/delivery-routesScope: dms:write

Create a delivery route

Plans a delivery route for a driver on a given date.

Body

daterequired	stringRoute date (YYYY-MM-DD).
driver_idrequired	stringDriver assigned to the route.
stopsoptional	integerPlanned number of stops (informational).

Request

curl -X POST "https://api.apusplatform.com/v1/dms/delivery-routes" \
  -H "Authorization: Bearer $APUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-07-22",
    "driver_id": "drv_71a2",
    "stops": 10
  }'

Response

{
  "id": "rte_9c31",
  "date": "2026-07-22",
  "created_at": "2026-07-20T02:24:00Z"
}

GET/v1/dms/delivery-routes/{id}Scope: dms:read

Retrieve a delivery route

Returns a single route with its ordered list of stops.

Path parameters

idrequired

stringRoute id.

Request

curl "https://api.apusplatform.com/v1/dms/delivery-routes/rte_9c30" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "id": "rte_9c30",
  "date": "2026-07-21",
  "driver_id": "drv_71a2",
  "vehicle": "29H-114.02",
  "status": "planned",
  "stops": [
    {
      "seq": 1,
      "distributor_id": "dst_4f21",
      "delivery_id": "dlv_a801"
    },
    {
      "seq": 2,
      "distributor_id": "dst_5b88",
      "delivery_id": "dlv_a802"
    }
  ]
}

GET/v1/dms/deliveriesScope: dms:read

List deliveries

Returns deliveries to distributors, filterable by distributor and status.

Query parameters

distributor_idoptional	stringFilter by distributor id.
statusoptional	stringOne of pending, confirmed, delivered, cancelled.

Request

curl "https://api.apusplatform.com/v1/dms/deliveries" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "data": [
    {
      "id": "dlv_a801",
      "distributor_id": "dst_4f21",
      "route_id": "rte_9c30",
      "status": "pending",
      "total": {
        "amount": 24600000,
        "currency": "VND"
      },
      "created_at": "2026-07-20T01:40:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "crsr_7d21"
}

POST/v1/dms/deliveriesScope: dms:write

Create a delivery

Creates a delivery order for a distributor. Attach it to a route now or later.

Body

distributor_idrequired	stringDistributor receiving the goods.
route_idoptional	stringRoute this delivery is assigned to.
linesrequired	arrayOrder lines — array of { sku, quantity }.

Request

curl -X POST "https://api.apusplatform.com/v1/dms/deliveries" \
  -H "Authorization: Bearer $APUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "distributor_id": "dst_4f21",
    "route_id": "rte_9c30",
    "lines": [
      {
        "sku": "BEV-COLA-330",
        "quantity": 240
      },
      {
        "sku": "BEV-WATER-500",
        "quantity": 120
      }
    ]
  }'

Response

{
  "id": "dlv_a801",
  "status": "pending",
  "created_at": "2026-07-20T02:26:00Z"
}

POST/v1/dms/deliveries/{id}/confirmScope: dms:write

Confirm a delivery

Confirms a pending delivery, reserving stock and locking the order lines.

Path parameters

idrequired

stringDelivery id.

Request

curl -X POST "https://api.apusplatform.com/v1/dms/deliveries/dlv_a801/confirm" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "id": "dlv_a801",
  "status": "confirmed",
  "confirmed_at": "2026-07-20T02:30:00Z"
}

GET/v1/dms/visitsScope: dms:read

List field-sales visits

Returns field-sales visits, filterable by sales rep and date.

Query parameters

rep_idoptional	stringFilter by sales rep id.
dateoptional	stringVisit date (YYYY-MM-DD).

Request

curl "https://api.apusplatform.com/v1/dms/visits" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "data": [
    {
      "id": "vst_e004",
      "distributor_id": "dst_4f21",
      "rep_id": "rep_2210",
      "checked_in_at": "2026-07-21T02:05:00Z",
      "notes": "Restocked cooler, collected aging invoice."
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST/v1/dms/visitsScope: dms:write

Log a field-sales visit

Records a rep's visit to a distributor. Typically posted from a mobile field-force app.

Body

distributor_idrequired	stringDistributor visited.
rep_idrequired	stringSales rep who made the visit.
notesoptional	stringFree-text visit notes.

Request

curl -X POST "https://api.apusplatform.com/v1/dms/visits" \
  -H "Authorization: Bearer $APUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "distributor_id": "dst_4f21",
    "rep_id": "rep_2210",
    "notes": "Restocked cooler, collected aging invoice."
  }'

Response

{
  "id": "vst_e004",
  "created_at": "2026-07-21T02:05:00Z"
}

GET/v1/dms/promotionsScope: dms:read

List trade promotions

Returns trade promotions. Pass active=true to return only currently running ones.

Query parameters

activeoptional

booleanReturn only promotions active today.

Request

curl "https://api.apusplatform.com/v1/dms/promotions" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "data": [
    {
      "id": "promo_31aa",
      "code": "Q3-BUY10-GET1",
      "name": "Buy 10 get 1 — beverages",
      "starts_on": "2026-07-01",
      "ends_on": "2026-09-30",
      "active": true
    }
  ]
}

Ready to build?

Create an API client in the Account Console to get your credentials, or talk to an integration engineer about your use case.

Get API credentials Talk to an integration engineer

← PrevSales & CRM · crm Next →HRM