> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shelfforce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Field Operations

> Manage stores, tasks, inventory, orders, accounts, alerts, and team members through the 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

```bash theme={null}
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"
    }
  }'
```

```json theme={null}
{
  "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

```bash theme={null}

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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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"]
  }'
```

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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

```bash theme={null}

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

```bash theme={null}
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

```bash theme={null}
curl -X DELETE https://shelfforce.ai/api/v1/inventory/inv_abc123 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."
```

### Delete a task

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
curl "https://shelfforce.ai/api/v1/members" \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."
```

### Invite a member

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:

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

```json theme={null}
{
  "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:

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Define inventory">
    Add your product catalog via `POST /api/v1/inventory` so Shelfforce can check for expected products.
  </Step>

  <Step title="Invite your team">
    Add field reps and managers to your organisation with `POST /api/v1/members/invite`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Field reps complete tasks">
    Reps visit stores, photograph shelves, and submit images. Shelfforce analyzes the photos and computes compliance.
  </Step>

  <Step title="Track orders">
    Create purchase orders via `POST /api/v1/orders` to track restock orders tied to your stores and accounts.
  </Step>

  <Step title="Monitor alerts">
    Poll `GET /api/v1/alerts` or register webhooks to stay on top of overdue tasks, price changes, and shelf share shifts.
  </Step>

  <Step title="Review results">
    Query task results and compliance scores via the API. Use store performance reports to identify underperforming locations.
  </Step>
</Steps>

<Tip>
  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.
</Tip>