# Created records

Find and group records by who entered them and when.

Canonical HTML: https://developer.shelfcycle.com/guides/created-records

Find records by who entered them and when, carry that context into detail views, and group supported commercial reports by Created By.

## Read creation context

Supported responses use the same two fields:

```json
{
  "createdBy": {
    "type": "user",
    "id": "00000000-0000-4000-8000-000000000101",
    "displayName": "Jordan Buyer"
  },
  "createdAt": "2026-09-18T14:35:00.000Z"
}
```

`createdBy` identifies the person who entered the record. It is separate from the salesperson, buyer, account owner, or assigned teammate. Records entered by ShelfCycle rather than a person use `type: "system"` and display `System User`. `createdAt` is the ISO timestamp when the record entered ShelfCycle.

Creation context is available on the supported finder rows below and on selected order, purchase-order, opportunity, lot, certification, contact, note, and purchase-receipt detail responses documented in OpenAPI.

## Find records by creator or time

| Finder | Scope |
| --- | --- |
| `GET /orders` | `orders:read` |
| `GET /purchase-orders` | `purchase-orders:read` |
| `GET /opportunities` | `opportunities:read` |
| `GET /customers` | `customers:read` |
| `GET /suppliers` | `suppliers:read` |
| `GET /product-directory` | `products:read` |
| `GET /lots` | `lots:read` |
| `GET /cost-book-entries` | `cost-book-entries:read` |
| `GET /price-book-entries` | `price-book-entries:read` |
| `GET /certification-records` | `certifications:read` |

Use `createdById` for one creator. Use `createdFrom` and `createdTo` for an ISO timestamp window, with the start included and the end excluded. You can combine creator and time filters with the other documented filters for the selected finder.

```bash
curl "$SHELFCYCLE_API_BASE_URL/orders?createdById=00000000-0000-4000-8000-000000000101&createdFrom=2026-09-01T00%3A00%3A00-04%3A00&createdTo=2026-09-08T00%3A00%3A00-04%3A00&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Order entry review"
```

New created-time finder windows can cover up to 366 days. Keep both endpoints of the window together. Opportunity search retains its existing created-time behavior.

Use a `createdBy.id` from a returned record, `data.actor.id` from `GET /me` for the current user, or a report row's `groupId`. This keeps creator identity exact even when people share a display name.

## Group reports by Created By

The following reports accept `groupBy=createdBy` with their existing `reports:read` access:

- `sales-summary`
- `purchase-summary`
- `open-sales-orders`
- `pipeline-summary`

```bash
curl "$SHELFCYCLE_API_BASE_URL/reports/purchase-summary?groupBy=createdBy&startDate=2026-01-01&endDate=2026-09-24&limit=50" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

Each creator row includes `groupId`. Use that exact ID as `createdById` on a matching finder to move from the summary to the individual records.

For sales activity, `dateField=enteredDate` groups the window by when each sales order entered ShelfCycle. When `includeStatuses` is omitted with Entered date, the report includes draft, confirmed, shipped, and delivered orders.

```bash
curl "$SHELFCYCLE_API_BASE_URL/reports/sales-summary?groupBy=createdBy&startDate=2026-09-01&endDate=2026-09-24&dateField=enteredDate&limit=50" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

## Continue supplier results

Supplier discovery now supports creator and created-time filters with signed continuation. Start with the filters and `limit`; when `meta.nextCursor` is present, send only that exact cursor on the next request.

```bash
curl "$SHELFCYCLE_API_BASE_URL/suppliers?createdFrom=2026-01-01T00%3A00%3A00-05%3A00&createdTo=2026-09-25T00%3A00%3A00-04%3A00&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

curl "$SHELFCYCLE_API_BASE_URL/suppliers?cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

## Check current availability

Call `GET /me` before building a creator-based workflow. `createdRecordDiscovery` appears with the matching effective capability for Product Directory, opportunities, customers, suppliers, Cost Book, Price Book, sales orders, purchase orders, lots, and certifications. Reports continue to use `effectiveCapabilities.reports.available`.

These capabilities use the same existing read scopes as their finder or report. See [Scopes](/guides/scopes) for the full access model, [Finders](/guides/finders) for continuation rules, and [Reports](/guides/reports) for report shapes and totals.

> **Guardrail**: Keep the returned creator ID with the display name. Filter and drill through by ID so a later name change or two people with the same name does not change which records the workflow selects.