The Zest API lets you programmatically fetch data from any saved report. Use it to pull report data into your own systems for automated reconciliation, data warehousing, or custom dashboards.

Getting Started

Request an API Key

API access is provisioned by Zest. Contact support to request an API key for your organization.

Important: Treat your API key like a password. Do not share it publicly or commit it to source control. We will also notify you when we recommend rotating your key.

Authentication

All API requests must include your API key in the x-api-key header:

x-api-key: your-api-key-here

Base URL

All endpoints are available at: https://gifts.zest.co/api/partners

Verify Your API Key

Before building an integration, confirm your API key is working:

Request

GET /api/partners/health-check

Headers

Header	Value
x-api-key	your-api-key-here

Response

{
  "status": "healthy",
  "organizationName": "Your Organization Name"
}

If you receive a 401 UNAUTHORIZED response, your API key may be invalid or expired. Contact Zest support.

Fetch Report Data

The report-data endpoint returns paginated data from any saved report.

Step 1 — Save a Report in the Dashboard

Before you can fetch data via API, you need a saved report:

Go to Reports in the Zest dashboard.

Create or open a report (Child Orders, Transactions, Taxes, Marketing, or Outstanding Inventory).

Configure your columns, filters, and sort.

Click Save as report and give it a name.

Tip: Reports with relative date filters (e.g., "Is in previous 30 days") stay current each time the API fetches data — you don't need to update filters manually.

Step 2 — Get the Report ID

Open your saved report in the dashboard. The report ID is the last segment of the URL: https://gifts.zest.co/partners/reports/{reportId}

Copy this ID for use in API requests.

Step 3 — Fetch the First Page

Request

POST /api/partners/report-data
Content-Type: application/json

Headers

Header	Value
x-api-key	your-api-key-here
Content-Type	application/json

Body

{
  "reportId": "your-report-id",
  "pageSize": 500
}

Parameter	Type	Required	Description
reportId	string	Yes	The ID of the saved report.
pageSize	number	No	Number of rows per page (1–1000). Defaults to 500.
cursor	string	No	Pagination cursor from a previous response. Omit for the first page.

Response

{
  "data": [
    {
      "orderSubmittedDate": "2025-03-01T12:00:00.000Z",
      "total": 49.99,
      "reconciliationKey": "1234"
    }
  ],
  "nextCursor": "abc123"
}

Field	Type	Description
data	array	Array of row objects. Keys match the column IDs configured in your saved report.
nextCursor	string or null	Pass this value as cursor in the next request to fetch the next page. null means there are no more pages.

Step 4 — Paginate Through All Results

To fetch all rows, keep passing the nextCursor from each response as the cursor in the next request until nextCursor is null.

{
  "reportId": "your-report-id",
  "pageSize": 500,
  "cursor": "abc123"
}

Error Handling

Status Code	Meaning
200	Success.
401	Unauthorized — invalid or missing API key.
404	Report not found — check the report ID and ensure the report belongs to your organization.
500	Internal server error — retry the request or contact support.

Frequently Asked Questions

Which report types can I access via API?

All report types are supported: Child Orders, Transactions, Taxes, Marketing, and Outstanding Inventory. Save any report in the dashboard and use its ID with the API.

Can I create or modify reports via API?

No. Reports must be created and configured in the Zest dashboard. The API is read-only — it fetches data from existing saved reports.

Do relative date filters work with the API?

Yes. If your saved report uses a relative date filter like "Is in previous 30 days," the API evaluates that filter at the time of each request. You don't need to update the report's filters.