ZI2 Square

Documentation · API

REST API reference

The ZI² Square API is a versioned REST surface over HTTPS. Every workspace endpoint requires an authenticated session token; platform-admin endpoints additionally require the owner role on the platform organization.

← Back to docs

Base URL & versioning

All endpoints sit under https://zisquare.app/api/v1. We commit to backwards-compatibility within a major version; breaking changes will be released under /api/v2 with a minimum 90-day overlap.

Authentication

Send the access token from POST /auth/login in the Authorization: Bearer <token> header. Access tokens expire after 15 minutes (900 seconds); refresh tokens are valid for 30 days and are rotated on every use. When a workspace has a TOTP-verified user, the login response returns mfaRequired: true and the client must resubmit with mfaCode.

Response envelope

Every response is a JSON object with a top-level success boolean and either a data payload or an error object containing code and message. List endpoints add a pagination object with page, limit, total, and totalPages.

Errors

HTTP status codes follow the standard semantics. 400 for validation, 401 for missing or invalid authentication, 403 for insufficient permissions, 404 for missing resources, 409 for conflicts, 429 for rate limits, and 5xx for server-side faults. Validation errors include a data map of field then list of issues.

Rate limits

Default limit: 100 requests per minute per client IP across the workspace API. Authentication endpoints (login, register, password reset) are limited to 10 attempts per 15 minutes per IP to deter credential-stuffing. Sync and bulk-import endpoints have their own narrower limits. Rate-limit headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are returned on every response.

Endpoint catalog

A short list of the most-used routes. The full reference, generated from the live API, is at /api/v1/docs/.

Authentication

  • POST/api/v1/auth/loginAuthenticate with email + password (returns access + refresh tokens).
  • POST/api/v1/auth/refreshExchange a refresh token for a new access token.
  • POST/api/v1/auth/logoutRevoke the current refresh token.
  • POST/api/v1/auth/forgot-passwordSend a password-reset email.
  • POST/api/v1/auth/reset-passwordSet a new password using a reset token.

Calendar & Events

  • GET/api/v1/calendarsList calendars in the workspace.
  • POST/api/v1/calendarsCreate a calendar.
  • GET/api/v1/eventsList events with date-range filters.
  • POST/api/v1/eventsCreate an event.
  • PATCH/api/v1/events/:idUpdate an event.

CRM

  • GET/api/v1/contactsList contacts with search, pagination, and tag filters.
  • POST/api/v1/contactsCreate a contact (with optional encrypted PII).
  • GET/api/v1/companiesList companies.
  • GET/api/v1/dealsList deals by pipeline / stage.
  • POST/api/v1/dealsCreate a deal.

Bookings

  • GET/api/v1/booking/pagesList booking pages.
  • POST/api/v1/booking/pagesCreate a public booking page.
  • GET/api/v1/booking/appointmentsList appointments.

Finance

  • GET/api/v1/invoicesList invoices.
  • POST/api/v1/invoicesCreate an invoice with line items.
  • POST/api/v1/invoices/:id/sendEmail an invoice to the billing recipient.
  • GET/api/v1/paymentsList payments.

Mail

  • GET/api/v1/mail-validator/listsList email-validation lists.
  • POST/api/v1/mail-validator/validateRun validation against a list.
  • GET/api/v1/mail-guard/mailboxesList connected mailboxes.
  • POST/api/v1/mail-guard/mailboxesConnect an IMAP mailbox for inbound triage.

Document Vault

  • GET/api/v1/documentsSearch and list documents.
  • POST/api/v1/documents/upload-initInitiate an encrypted multi-part upload.
  • GET/api/v1/doc-foldersList folders.

SMS

  • GET/api/v1/sms/templatesList SMS templates.
  • POST/api/v1/sms/campaignsCreate an SMS campaign.

Platform admin

  • GET/api/v1/platform/tenantsList all tenants (platform-admin scope only).
  • POST/api/v1/platform/tenantsCreate a tenant in one call (owner + addons + optional demo seed).
  • PATCH/api/v1/platform/tenants/:idUpdate plan, seats, or enabled addons.