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..."
}

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 and shipment_id also reference public IDs. 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.

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.