Guides

Copy page

Common Patterns

Response Envelope

Every successful response is wrapped in a data envelope.

Single resource:

Code
 
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example Item"
  }
}

List of resources:

Code
 
{
  "data": [
    { "id": "...", "name": "Item 1" },
    { "id": "...", "name": "Item 2" }
  ],
  "next_cursor": "eyJpZCI6IjEyMzQ1..."
}

Request IDs

Every response includes a server-assigned x-request-id header containing a UUIDv4. Clients cannot choose this value.

Error envelopes include the same value in error.request_id. Log either value and include it when contacting support so the request can be traced across systems.

Code
 
x-request-id: 550e8400-e29b-41d4-a716-446655440000

Request Bodies

Request bodies are limited to 1 MiB. A larger body returns 413 PAYLOAD_TOO_LARGE; malformed or otherwise unparseable JSON returns 400 VALIDATION_ERROR. These responses describe a problem with the request, so do not retry them without changing the payload.

Pagination

All list endpoints use cursor-based pagination.

Parameter	Type	Default	Description
limit	integer	25	Items per page (1–200)
cursor	string	—	Opaque cursor from previous response

How to paginate:

1. Make your first request (optionally with limit)
2. Check the next_cursor field in the response
3. If next_cursor is not null, pass it as ?cursor=VALUE on the next request
4. Repeat until next_cursor is null (no more pages)

Code
 
# Page 1
curl "https://api.datavisual.ca/v1/items?limit=200" -H "Authorization: Bearer KEY"
# Response: { "data": [...], "next_cursor": "eyJpZCI6..." }

# Page 2
curl "https://api.datavisual.ca/v1/items?limit=200&cursor=eyJpZCI6..." -H "Authorization: Bearer KEY"
# Response: { "data": [...], "next_cursor": null }  <-- last page

Timestamps

All timestamps are returned as ISO 8601 strings (e.g., "2025-01-15T14:30:00.000Z").

Several list endpoints support an updated_since filter that accepts ISO 8601 timestamps and returns records modified on or after that time. See Syncing Data for the full list of supported endpoints.

Identifiers

All resources use UUIDs as public identifiers (the id field). Internal system identifiers are never exposed.

Related-resource fields like salesorder_id, shipment_id, item_id, and warehouse_id also reference public UUIDs. Item and warehouse references are null when the related resource is unavailable to the caller. Stock filters accept these public UUIDs in item_id and warehouse_id. You can use these directly in API calls — for example, pass a salesorder_id from an invoice to GET /v1/sales-orders/{id} without any translation.

Canonical line_item_id values are public UUIDs. Pending sales-order lines return line_item_id: null until the order is reconciled to canonical records.

Null Fields

Fields that have no value are returned as null, not omitted. This makes it safe to destructure responses without checking for key existence.