Skip to main content

API 1.0.0

Released July 7, 2026

Initial public release of the Zapa Client Portals REST API.

Enterprise Feature

API access requires an Enterprise plan with API access enabled for your organization.

Authentication​

  • OAuth 2.0 Authorization Code flow. Users approve access on the consent screen at https://app.zapaportal.com/oauth/authorize; tokens are issued from https://api.zapaportal.com/oauth/token.
  • Access tokens are JWTs valid for 1 hour; refresh tokens are valid for 30 days.
  • Organization admins create OAuth clients under Settings → API Settings and choose the scopes each client may request. Users can further narrow the granted scopes on the consent screen.
  • Scopes: portal:read, portal:write, file:list, file:upload, task:read, task:write, guest:invite, webhook:manage.

Endpoints​

AreaEndpoints
UserGET /api/v1/me
Workflow statesGET /api/v1/workflow-states
PortalsGET /api/v1/portals, POST /api/v1/portals, GET /api/v1/portals/{portalId}, PATCH /api/v1/portals/{portalId}, POST /api/v1/portals/{portalId}/workflow
FilesGET /api/v1/portals/{portalId}/files, POST /api/v1/portals/{portalId}/files, POST /api/v1/portals/{portalId}/files/complete
TasksGET /api/v1/portals/{portalId}/tasks, POST /api/v1/portals/{portalId}/tasks, PATCH /api/v1/tasks/{taskId}, POST /api/v1/tasks/{taskId}/complete
GuestsPOST /api/v1/portals/{portalId}/guests
WebhooksGET /api/v1/webhooks, POST /api/v1/webhooks, PATCH /api/v1/webhooks/{webhookId}, DELETE /api/v1/webhooks/{webhookId}, POST /api/v1/webhooks/{webhookId}/test

File uploads support a one-step mode (Zapa fetches the file from a public file_url, up to 100 MB) and a two-step mode (request a presigned upload_url, PUT the bytes, then call /files/complete).

Webhooks​

Seven events can be subscribed to per webhook: portal.created, portal.workflow_changed, file.uploaded, file.signed, task.created, task.completed, and guest.invited.

  • Deliveries are POST requests with a flat JSON body (event, org_id, portal_id, timestamp, plus event-specific fields).
  • Each delivery is signed with HMAC-SHA256 of the raw body in the X-Webhook-Signature header and carries a unique X-Webhook-Delivery-Id.
  • Failed deliveries are retried 3 times with exponential backoff. Delivery logs, pause/resume, and a test-send button are available under Settings → Webhooks.

Zapier integration 1.0.0​

The Zapa Client Portals app on Zapier ships alongside the API:

  • Triggers (7): New Portal, Portal Workflow Changed, File Uploaded, File Signed, New Task, Task Completed, Guest Invited.
  • Actions (8): Create Portal, Update Portal, Set Workflow State, Upload File, Create Task, Update Task, Complete Task, Invite Guest.
  • Searches (2): Find Portal, Find Files.

Design notes​

  • No file downloads. The API returns file metadata only. Downloads stay in the web app where access is permission-checked and audited, and every consent screen states that connected apps cannot download file contents. Link users to a file with https://app.zapaportal.com/org/{org_id}/vault/{portal_id}/folder/main?file={file_id}.
  • Rate limit: 10,000 requests per day per client.

Resources​