Contents

hivi-x API reference (v1)

hivi-x API reference (v1)

API v1 serves registered connected apps, currently the hivi-x app for Zapier. There are no personal API keys. To receive events in your own system, use webhooks.

  • Base URL: https://hivi-x.ca
  • JSON in and out. Dates are ISO 8601 with a time zone. Every item has a unique id.
  • Files, government ID numbers and bank or card numbers are never returned.

Authentication (OAuth 2.0)

StepRequest
AuthorizeBrowser to GET https://hivi-x.ca/oauth/authorize?client_id=…&redirect_uri=…&response_type=code&state=…&scope=… (optional code_challenge + code_challenge_method=S256)
ExchangePOST /api/oauth/token with grant_type=authorization_code, code, redirect_uri, and client credentials (body or HTTP Basic). Add code_verifier with PKCE
RefreshPOST /api/oauth/token with grant_type=refresh_token, refresh_token, client credentials
RevokePOST /api/oauth/revoke with token (a refresh token) and client credentials; ends the connection

The token response is { access_token, token_type: "Bearer", expires_in: 3600, refresh_token, scope }. Refresh tokens rotate: each refresh returns a new one. A refresh token presented again within 60 seconds still works; later, the connection is ended as a precaution.

Send the access token as Authorization: Bearer <token>. A 401 means: refresh the token, or the connection was removed.

Scopes

ScopeAllows
account:readGET /api/v1/me
clients:readList and find clients; New Client trigger
clients:writeCreate and update clients
checklists:readChecklist triggers (submitted, reviewed, completed, document expiring)
checklists:sendTemplates list; send a checklist
esign:readSignature Request Completed trigger
extractions:readRead Fields Confirmed trigger (income documents only). Off unless the person ticks it

Endpoints

Method and pathScopeNotes
GET /api/v1/meaccount:readPerson, workspace name, team role, granted scopes
GET /api/v1/clients?limit=clients:readNewest first, up to 100
GET /api/v1/clients/search?email= or ?name=clients:readAlways an array (up to 10)
POST /api/v1/clientsclients:writefirstName, lastName or fullName, email, phone, address, tags[], notes. An existing email returns that client with created: false (200); a new one created: true (201)
PATCH /api/v1/clients/:idclients:writefullName, email, phone, status (active/inactive)
GET /api/v1/checklist-templateschecklists:sendid, name, itemCount
POST /api/v1/clients/:id/checklistschecklists:sendtemplateId, delivery (guest_link or portal), dueDate, instructions, notifyClient (default true; false needs portal, since the secure link only travels by email)
GET /api/v1/samples/:trigger?limit=trigger's scopeRecent items with the hook payload's fields, for the Zap editor
POST /api/v1/hookstrigger's scope{ trigger, targetUrl, filter? } → { id }. targetUrl must be on hooks.zapier.com
DELETE /api/v1/hooks/:id—Idempotent

Triggers: client.created, checklist.item_submitted, checklist.item_reviewed (filter { reviewStatus: "approved" \| "rejected" }), checklist.completed, esign.envelope_completed, document.expiring, extraction.confirmed.

Hook delivery

  • One JSON POST per event to the subscribed URL, the same fields as /api/v1/samples/:trigger.
  • 2xx is success. Otherwise retried after 1 minute, 5 minutes, 30 minutes and 2 hours (5 attempts).
  • 410 Gone deletes the subscription.
  • A team member's hooks only carry events they are allowed to see. Nothing is sent while the account's billing is blocked.

Errors

Errors are { success: false, code, message } with an HTTP status. message is written for the person who set up the Zap.

StatusExample code
400INVALID_EMAIL, MISSING_NAME, CLIENT_EMAIL_REQUIRED, HOOK_URL_NOT_ALLOWED
401invalid_token (refresh, or reconnect)
403SCOPE_REQUIRED, CLIENT_LIMIT_REACHED, BILLING_BLOCKED, TEAM_CAPABILITY_REQUIRED
404CLIENT_NOT_FOUND
409CLIENT_EXISTS: the email belongs to a client you can't see (staff limited to assigned clients)
429rate_limited: more than 120 requests a minute on one connection

Related

Answers are general operational information only — not legal, tax, regulatory, clinical, privacy, immigration, or professional advice. Requirements vary by matter, client, and regulator.

Frequently asked questions

Can I get an API key for my own code?
Not yet. API v1 serves registered apps (Zapier) through OAuth. For your own code, use webhooks to receive events.
Where can hooks be delivered?
Only to Zapier (hooks.zapier.com). For other receivers, use webhooks.

Organize client document intake with checklists

hivi-x helps Ontario professionals collect client documents with reusable checklists, secure Canadian hosting, and exportable PDF packages.

hivi-x API v1 Reference: OAuth, Clients, Checklists, Hooks | hivi-x Docs