Field Operations - Shelfforce API

Shelfforce provides a complete task management system for field teams. Create stores (places), assign shelf audit tasks to field reps, track compliance results, manage purchase orders, and organize your team — all through the API.

Concepts

Concept	Description
Place	A physical retail location (store, supermarket, pharmacy, etc.) with an address and optional geographic coordinates.
Task	A field assignment linked to a place, with a due date, assigned user, and compliance criteria.
Inventory	Your product catalog — brands, SKUs, and expected shelf items that tasks can reference.
Order	A purchase order or sales order linked to a supplier/account, with line items and delivery tracking.
Account	A business entity (brand, supplier, distributor, retailer, or partner) that you work with.
Alert	A system-generated notification about important events (overdue tasks, price changes, etc.).
Member	A user in your organisation with a specific role and reporting structure.

Managing places (stores)

Create a place

curl -X POST https://shelfforce.ai/api/v1/places \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Grocery",
    "address": "123 Main St, New York, NY 10001",
    "countryCode": "US",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "metadata": {
      "chain": "FreshMart",
      "region": "Northeast"
    }
  }'

{
  "id": "place_5e6f7g8h",
  "name": "Downtown Grocery",
  "address": "123 Main St, New York, NY 10001",
  "countryCode": "US",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "metadata": {
    "chain": "FreshMart",
    "region": "Northeast"
  },
  "createdAt": "2026-02-23T09:00:00Z"
}

List places

curl "https://shelfforce.ai/api/v1/places" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."


curl "https://shelfforce.ai/api/v1/places?metadata.chain=FreshMart" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Update a place

curl -X PATCH https://shelfforce.ai/api/v1/places/place_5e6f7g8h \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Grocery — Renovated",
    "metadata": {
      "chain": "FreshMart",
      "region": "Northeast",
      "renovated": "2026-01"
    }
  }'

Delete a place

curl -X DELETE https://shelfforce.ai/api/v1/places/place_5e6f7g8h \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Creating tasks

Tasks represent field assignments. Each task is linked to a place and can include instructions, due dates, and inventory references.

Create a task

curl -X POST https://shelfforce.ai/api/v1/tasks \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly shelf audit — Beverages",
    "placeId": "place_5e6f7g8h",
    "dueDate": "2026-03-01T00:00:00Z",
    "instructions": "Photograph all beverage shelves in aisles 3-5. Include price tags.",
    "assigneeEmail": "rep@company.com",
    "expectationIds": ["inv_abc123", "inv_def456"]
  }'

{
  "id": "task_1a2b3c4d",
  "title": "Weekly shelf audit — Beverages",
  "status": "pending",
  "placeId": "place_5e6f7g8h",
  "dueDate": "2026-03-01T00:00:00Z",
  "instructions": "Photograph all beverage shelves in aisles 3-5. Include price tags.",
  "assigneeEmail": "rep@company.com",
  "expectationIds": ["inv_abc123", "inv_def456"],
  "createdAt": "2026-02-23T09:30:00Z"
}

Task parameters

Parameter	Type	Required	Description
`title`	`string`	Yes	Short description of the task.
`placeId`	`string`	Yes	ID of the place (store) where the task should be completed.
`dueDate`	`string`	No	ISO 8601 due date.
`instructions`	`string`	No	Detailed instructions for the field rep.
`assigneeEmail`	`string`	No	Email of the user to assign the task to.
`expectationIds`	`string[]`	No	IDs of expectation items to check for during analysis.

Task lifecycle

Tasks follow a simple state machine:

pending → in_progress → completed

Status	Description
`pending`	Task has been created but not yet started.
`in_progress`	A field rep has started working on the task (e.g., arrived at the store).
`completed`	The task is finished. Analysis results and compliance data are available.

Update task status

curl -X PATCH https://shelfforce.ai/api/v1/tasks/task_1a2b3c4d \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress"
  }'

Get task details

curl https://shelfforce.ai/api/v1/tasks/task_1a2b3c4d \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

When a task is completed, the response includes associated analysis results and compliance data:

{
  "id": "task_1a2b3c4d",
  "title": "Weekly shelf audit — Beverages",
  "status": "completed",
  "placeId": "place_5e6f7g8h",
  "completedAt": "2026-02-24T14:30:00Z",
  "analyses": [
    {
      "id": "an_8x7k2m3n4p5q",
      "status": "completed",
      "productsCount": 24,
      "totalFacings": 96
    }
  ],
  "compliance": {
    "score": 0.85,
    "totalChecks": 20,
    "passed": 17,
    "failed": 3,
    "details": [
      {
        "check": "Coca-Cola minimum 4 facings",
        "status": "passed",
        "actual": 6
      },
      {
        "check": "Pepsi price below $1.50",
        "status": "failed",
        "actual": 1.69
      }
    ]
  }
}

Managing inventory

Inventory items represent the products you expect to find on shelves. Link them to tasks to enable compliance checking.

Create inventory items

curl -X POST https://shelfforce.ai/api/v1/inventory \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Coca-Cola",
    "name": "Coca-Cola Original Taste",
    "category": "Carbonated Soft Drinks",
    "sku": "5449000000996",
    "size": "330ml"
  }'

{
  "id": "inv_abc123",
  "brand": "Coca-Cola",
  "name": "Coca-Cola Original Taste",
  "category": "Carbonated Soft Drinks",
  "sku": "5449000000996",
  "size": "330ml",
  "createdAt": "2026-02-23T08:00:00Z"
}

List inventory

curl "https://shelfforce.ai/api/v1/inventory" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."


curl "https://shelfforce.ai/api/v1/inventory?brand=Coca-Cola" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Update inventory

curl -X PATCH https://shelfforce.ai/api/v1/inventory/inv_abc123 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "size": "330ml can"
  }'

Delete an inventory item

curl -X DELETE https://shelfforce.ai/api/v1/inventory/inv_abc123 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Delete a task

curl -X DELETE https://shelfforce.ai/api/v1/tasks/task_1a2b3c4d \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Managing orders

Orders track purchase orders, sales orders, and invoices. Each order can have line items linked to inventory.

Create an order

curl -X POST https://shelfforce.ai/api/v1/orders \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "supplierName": "UNFI Distribution",
    "orderDate": "2026-02-20T00:00:00Z",
    "status": "pending",
    "currency": "USD",
    "notes": "Weekly restock order",
    "items": [
      { "sku": "CC-330ML-CAN", "name": "Coca-Cola Original 330ml Can", "quantity": 48, "unitPrice": 0.89 },
      { "sku": "SP-500ML-BTL", "name": "Sprite 500ml Bottle", "quantity": 24, "unitPrice": 1.15 }
    ]
  }'

List orders

# All orders
curl "https://shelfforce.ai/api/v1/orders" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

# Filter by status
curl "https://shelfforce.ai/api/v1/orders?status=pending" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Update order status

curl -X PATCH https://shelfforce.ai/api/v1/orders/ord_a1b2c3 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "confirmed",
    "expectedDeliveryDate": "2026-02-27T00:00:00Z"
  }'

Delete an order

curl -X DELETE https://shelfforce.ai/api/v1/orders/ord_a1b2c3 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Managing accounts

Accounts represent the businesses you work with — brands, suppliers, distributors, retailers, and partners.

Create an account

curl -X POST https://shelfforce.ai/api/v1/accounts \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coca-Cola Company",
    "type": "brand",
    "contactName": "John Smith",
    "contactEmail": "john@coca-cola.com",
    "website": "https://www.coca-cola.com"
  }'

List accounts

# All accounts
curl "https://shelfforce.ai/api/v1/accounts" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

# Filter by type
curl "https://shelfforce.ai/api/v1/accounts?type=supplier" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Update an account

curl -X PATCH https://shelfforce.ai/api/v1/accounts/acc_d4e5f6 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "contactPhone": "+1-555-0199",
    "notes": "Renewed partnership agreement for 2026."
  }'

Monitoring alerts

Alerts are system-generated notifications for important events like overdue tasks, price changes, and shelf share shifts. You can read and update alert status, but alerts cannot be created via the API.

List alerts

# Unread alerts
curl "https://shelfforce.ai/api/v1/alerts" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

# Filter by severity
curl "https://shelfforce.ai/api/v1/alerts?severity=critical" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

# Include dismissed/snoozed alerts
curl "https://shelfforce.ai/api/v1/alerts?status=dismissed" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Acknowledge or dismiss an alert

curl -X PATCH https://shelfforce.ai/api/v1/alerts/alt_m1n2o3 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "acknowledged"
  }'

Snooze an alert

curl -X PATCH https://shelfforce.ai/api/v1/alerts/alt_m1n2o3 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "snoozed",
    "snoozeDurationMs": 86400000
  }'

Managing team members

Manage your organisation’s team. Member endpoints require an API key with admin role.

List members

curl "https://shelfforce.ai/api/v1/members" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Invite a member

curl -X POST https://shelfforce.ai/api/v1/members/invite \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "rep@company.com",
    "role": "tasker"
  }'

Update a member

curl -X PATCH https://shelfforce.ai/api/v1/members/usr_qrs789 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "role": "member"
  }'

Remove a member

curl -X DELETE https://shelfforce.ai/api/v1/members/usr_qrs789 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Store performance reports

Query aggregated performance data across stores:

curl "https://shelfforce.ai/api/v1/reports/store-performance?from=2026-02-01&to=2026-02-23" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

{
  "period": {
    "from": "2026-02-01T00:00:00Z",
    "to": "2026-02-23T23:59:59Z"
  },
  "stores": [
    {
      "placeId": "place_5e6f7g8h",
      "name": "Downtown Grocery",
      "tasksCompleted": 4,
      "analysesRun": 12,
      "averageComplianceScore": 0.87,
      "shareOfShelf": {
        "Coca-Cola": 0.34,
        "Pepsi": 0.22
      }
    }
  ]
}

Workflow example

Here is a typical field operations workflow:

Set up accounts and stores

Create accounts for your suppliers and brands via POST /api/v1/accounts, then create places for each retail location using POST /api/v1/places.

Define inventory

Add your product catalog via POST /api/v1/inventory so Shelfforce can check for expected products.

Invite your team

Add field reps and managers to your organisation with POST /api/v1/members/invite.

Create tasks

Assign weekly shelf audit tasks to field reps with POST /api/v1/tasks, linking each task to a store and relevant inventory items.

Field reps complete tasks

Reps visit stores, photograph shelves, and submit images. Shelfforce analyzes the photos and computes compliance.

Track orders

Create purchase orders via POST /api/v1/orders to track restock orders tied to your stores and accounts.

Monitor alerts

Poll GET /api/v1/alerts or register webhooks to stay on top of overdue tasks, price changes, and shelf share shifts.

Review results

Query task results and compliance scores via the API. Use store performance reports to identify underperforming locations.

Register webhooks for task.completed to trigger downstream workflows — such as sending compliance reports to brand managers — as soon as field reps finish their tasks.

​Concepts

​Managing places (stores)

​Create a place

​List places

​Update a place

​Delete a place

​Creating tasks

​Create a task

​Task parameters

​Task lifecycle

​Update task status

​Get task details

​Managing inventory

​Create inventory items

​List inventory

​Update inventory

​Delete an inventory item

​Delete a task

​Managing orders

​Create an order

​List orders

​Update order status

​Delete an order

​Managing accounts

​Create an account

​List accounts

​Update an account

​Monitoring alerts

​List alerts

​Acknowledge or dismiss an alert

​Snooze an alert

​Managing team members

​List members

​Invite a member

​Update a member

​Remove a member

​Store performance reports

​Workflow example

Concepts

Managing places (stores)

Create a place

List places

Update a place

Delete a place

Creating tasks

Create a task

Task parameters

Task lifecycle

Update task status

Get task details

Managing inventory

Create inventory items

List inventory

Update inventory

Delete an inventory item

Delete a task

Managing orders

Create an order

List orders

Update order status

Delete an order

Managing accounts

Create an account

List accounts

Update an account

Monitoring alerts

List alerts

Acknowledge or dismiss an alert

Snooze an alert

Managing team members

List members

Invite a member

Update a member

Remove a member

Store performance reports

Workflow example