Skip to Content
APIPull

Pull API

The Pull API is the source of truth for partner data. All timestamps are UTC in ISO 8601. Authenticate with a static API key in the Authorization header.

Base URL and authentication

  • Base URL: https://api.zing.com/partner/v1
  • Authentication: Send your API key on every request:
Authorization: Api-Key <your_api_key>

You can obtain the API key from the Admin UI. Keep it secret and do not expose it in client-side code.

Conventions

Pagination

List endpoints support cursor-based pagination:

  • limit (optional) — Max items per page (1–1000, default 100).
  • cursor (optional) — Use the next_cursor value from the previous response to fetch the next page. Omit for the first page.

Responses include a meta object with limit and next_cursor. When next_cursor is null, there are no more pages.

Time filters

Where supported, use from and to as UTC ISO 8601 date-time query parameters. Items are filtered by occurred_at or created_at: included if >= from and < to.

Errors

  • 401 — Missing or invalid API key. Check Authorization: Api-Key <key>.
  • 404 — Resource not found (e.g. user or workout ID does not exist or is not in your partner scope).
  • 429 — Rate limit exceeded. Use the Retry-After response header (seconds) before retrying.

Error responses are JSON with a detail string describing the issue.

Quick check

Verify connectivity and authentication:

curl -s -H "Authorization: Api-Key YOUR_API_KEY" https://api.zing.com/partner/v1/status

Example response:

{
  "status": "ok",
  "partner_name": "Your Partner",
  "timestamp": "2025-03-12T10:00:00.000Z"
}

Endpoints by use case

Health and self-service

MethodPathDescription
GET/statusHealth check; returns status, partner name, and timestamp.

Webhook delivery audit

Use these to debug missed webhooks or reconcile with your system.

MethodPathDescription
GET/webhooks/deliveriesList webhook delivery records. Optional query: partner_user_id, status (pending, delivered, failed, failed_final), from, to, limit, cursor.

Users

MethodPathDescription
GET/usersEnumerate partner user IDs (paginated).
GET/users/{partner_user_id}Get user summary (latest workout, tests, body composition, streak, etc.).
DELETE/users/{partner_user_id}Delete user (GDPR/contract end). Emits user.deleted webhook; user can re-register with a clean profile.

Workouts

MethodPathDescription
GET/users/{partner_user_id}/workoutsList workouts for a user. Optional: from, to, limit, cursor.
GET/workouts/{workout_id}Get full workout detail by ID (includes exercises with duration, weight, reps).

Tests

MethodPathDescription
GET/users/{partner_user_id}/testsList tests for a user. Optional: type (fitness | flexibility), from, to, limit, cursor.
GET/tests/{test_id}Get full test result by ID (includes metrics).

Body composition

MethodPathDescription
GET/users/{partner_user_id}/body_compositionList body composition measurements. Optional: from, to, limit, cursor.
GET/users/{partner_user_id}/body_composition/latestGet latest measurement for the user. Returns 204 if none.

Reporting (usage)

MethodPathDescription
GET/usage/dailyDaily usage for a date. Required query: date (YYYY-MM-DD). Returns active users, workouts, tests by type, body composition count.
GET/usage/monthlyMonthly usage. Required query: date (YYYY-MM). Same metric shape as daily.

Example: list workouts for a user

curl -s -H "Authorization: Api-Key YOUR_API_KEY" \
  "https://api.zing.com/partner/v1/users/partner-usr-123/workouts?limit=10"

Example response shape:

{
  "data": [
    {
      "workout_id": "wkt_abc",
      "partner_user_id": "partner-usr-123",
      "occurred_at": "2025-03-12T09:00:00.000Z",
      "updated_at": "2025-03-12T09:15:00.000Z",
      "duration_seconds": 1800,
      "completion_percentage": 100,
      "intensity": "moderate",
      "summary": "Full body strength"
    }
  ],
  "meta": {
    "limit": 10,
    "next_cursor": "eyJpZCI6InhrdF94eXoifQ=="
  }
}

Use next_cursor in the next request: ?limit=10&cursor=eyJpZCI6InhrdF94eXoifQ==.

Example: get full workout after a webhook

When you receive a workout.completed webhook, fetch the full detail with the workout ID from the payload:

curl -s -H "Authorization: Api-Key YOUR_API_KEY" \
  "https://api.zing.com/partner/v1/workouts/wkt_abc"

The response includes the same list fields plus exercises (exercise type, name, duration, weight, reps) and optional metadata.

Considerations

  • Rate limits — If you receive 429, back off using Retry-After and use exponential backoff for repeated failures.
  • Idempotency — GET and list endpoints are safe to retry. DELETE is idempotent: a second delete returns 404.
  • Partner isolation — You only see data for users belonging to your partner account; user IDs are the same values you send to Zing when creating users.

For receiving change notifications and implementing a webhook consumer, see Webhooks. For exhaustive endpoint details, parameters, and response schemas, see the Reference (opens in new window).

Last updated on
OverviewWebhooks