Skip to main content

Viewcy API

Viewcy API (v2025_06) — API for third-party integrations.

Base URL​

All API requests should be made to:

https://api.viewcy.com/2025_06

Authentication​

Authenticate by passing your API token as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

You can generate API tokens from your Viewcy account settings in the Developer Zone section. Both User and School accounts have a Developer Zone, and a token always acts as its owner.

See Authentication & token model for the full contract — what a token represents, how it scopes access, and why operating on accounts you don't own will require OAuth.

Pagination​

List endpoints return paginated results. The response includes:

  • page — current page number
  • totalPages — total number of pages
  • perPage — items per page (default: 25)
  • totalCount — total number of items

Use the page and perPage query parameters to navigate through results.

Expanding and including fields​

Two query parameters reshape what a response contains:

  • expand — replace a referenced resource's id/url with the full nested object. For example, ?expand=location,occurrences on an event inlines those resources instead of linking to them.
  • include — add extra flat fields that are off by default because they're large or rarely needed. For example, ?include=guestEmailMessage,donorEmailMessage on an event.

Both accept a comma-separated list. Each endpoint's reference page lists the values it supports.

Rate Limits​

Read operations are rate limited to 60 per minute.

Write operations are rate limited to 20 per minute.

File uploads (POST /uploads) have their own limit of 30 per 10 minutes.

Read, write, and upload limits are tracked in independent buckets — write traffic never eats into your read budget, and vice versa. A request that exceeds its bucket returns 429.

Please contact Viewcy if your integration requires higher limits.

Error Responses​

The API uses standard HTTP status codes:

  • 401 — Authentication required or invalid token
  • 403 — Your OAuth token is missing a scope this endpoint requires (Insufficient scope). Returned only for scope gaps — never for cross-owner access (that's 404). Personal access tokens are never scope-limited.
  • 404 — Resource not found, or the resource exists but isn't owned by your token's account. The API does not distinguish these cases — it never returns 403 for cross-owner access.
  • 409 — Conflict. For writes, includes idempotency_in_progress — another request with the same Idempotency-Key is still being processed (see Idempotency).
  • 422 — Request was understood but failed validation. Examples: a destructive write that omits a required side-effect flag, or idempotency_key_mismatch when an Idempotency-Key was reused with a different request body.
  • 429 — Rate limited
  • 503 — Service unavailable. For writes, includes idempotency_unavailable — the idempotency cache could not be reached and the write was not executed.

Error responses follow this format:

{
  "object": "error",
  "status": 401,
  "message": "Authentication required"
}

Validation failures (422) add a per-field errors array:

{
  "object": "error",
  "status": 422,
  "message": "Validation failed",
  "errors": [
    { "field": "name", "message": "can't be blank" }
  ]
}

See Creating and updating resources for the full write contract.

Writes, async operations, and idempotency​

Write endpoints — especially destructive ones like refunds and cancellations — share a few extra rules that apply uniformly across the API:

  • Idempotency — set an Idempotency-Key header on every write so retries are safe. Replays return the original response within a 24-hour window.
  • Async, destructive, and idempotent operations — when responses are 202 Accepted vs. 200 OK, and why side-effect flags must be set explicitly on every request.

OpenAPI Specification​

The full OpenAPI spec is available at:

https://developer.viewcy.com/openapi/2025_06_viewcy_api.yaml

API Versioning and Development​

The API is in development. We will be adding new endpoints over time.

The API is versioned, any breaking changes in the API will be released as a new version.

Get help​

If you have any questions reach us at developer-support@viewcy.com