Zapa Client Portals API (1.0.2)

Starts the OAuth 2.0 Authorization Code flow. Direct the user's browser here (on the web app domain, https://app.zapaportal.com) — they'll see a consent screen listing the scopes you requested and can approve or deny each one. After approval, the user is redirected to your redirect_uri with a short-lived code to exchange at the token endpoint.

Always pass a random state value and verify it on the redirect to protect against CSRF.

Exchanges an authorization code for an access token, or refreshes an expired access token. This endpoint lives on the API domain (https://api.zapaportal.com), unlike the authorize endpoint which is on the web app domain.

Access tokens expire after 1 hour (expires_in: 3600); store the refresh_token and use the refresh_token grant to get a new one without user interaction. The endpoint accepts both application/x-www-form-urlencoded and application/json bodies.

Returns the user and organization associated with the access token — user and org IDs and names, the OAuth client ID, and the scopes that were actually granted.

Call this first after obtaining a token: it verifies authentication works, tells you which scopes the user approved on the consent screen (they may have granted fewer than you requested), and gives you the org_id needed to build web links to portals and files. No specific scope is required — any valid token works.

Returns the organization's configured workflow states as {id, name} pairs. Call this before setting a portal's workflow state — the workflow endpoint requires both values, and they must match an existing state. Also handy for populating dropdowns in your integration's UI.

Returns all active (non-deleted) portals in your organization, including tags, workflow state, task counters, and recent-activity timestamps — useful for syncing portal lists into a CRM or dashboard.

Templates: pass templatesOnly=true to list your organization's portal templates instead of regular portals. Use a template's id as the templateId when creating a new portal to copy its folder structure and settings.

Linking: build a web link to any portal with https://app.zapaportal.com/org/{org_id}/vault/{id}/folder/main.

External-id lookup: pass both externalSystem and externalId to return only the portal(s) whose externalSystemIds[externalSystem] equals externalId — e.g. ?externalSystem=taxi&externalId=cust_12345. Returns an empty array when nothing matches.

Creates a new client portal — typically one per client or engagement.

Creating from a template (Business & Enterprise): first call GET /api/v1/portals?templatesOnly=true to find your template's id, then pass it as templateId. The new portal is created with the template's folder structure and default settings:

{ "name": "ABC Corp - 2026 Tax Return", "templateId": "TEMPLATE_UUID", "tags": ["tax-2026"] }

Set isTemplate: true instead to create a new template rather than a regular portal.

Next steps: invite the client with POST /api/v1/portals/{portalId}/guests, then upload files with POST /api/v1/portals/{portalId}/files. Subscribing a webhook to portal.created lets other systems react to portals created here or in the web app.

Returns a single portal's details, including tags, workflow state, and activity timestamps. Use this to refresh one portal's state instead of re-listing everything, or to resolve a portal ID received in a webhook payload.

Updates a portal's name, tags, workflow state, or archive status. Only include the fields you want to change.

Set archived: true to archive a portal when an engagement ends — nothing is deleted, and it can be restored later with archived: false. There is no delete endpoint; portals can only be permanently deleted from the web app.

External system ids: externalSystemIds is a merge-patch — keys you send are set, a null value deletes that key, and keys you omit are left unchanged. Each (system, id) pair must be unique within your organization; a duplicate returns 409 conflict. The response echoes the merged map.

Moves a portal to a different workflow state (e.g. "In Progress" → "Review"). Fetch valid workflowStateId/workflowStateName pairs from GET /api/v1/workflow-states first — both values are required and should come from that list.

State changes fire the portal.workflow_changed webhook event, making this a good integration point for driving external processes (e.g. notify your practice-management system when a portal reaches "Complete").

Returns metadata (name, size, extension, upload date/user) for every active file and folder in a portal. Folders appear as entries too — a file's parent_folder_file_id links it to its folder.

Linking to a file: to send someone to a specific file, build a web preview link: https://app.zapaportal.com/org/{org_id}/vault/{portalId}/folder/main?file={file_id} — opening it signs the user in (if needed) and opens that file's preview automatically.

Why no download endpoint? The API deliberately never returns file contents. Portal documents are often sensitive (tax records, contracts, signed agreements), and the OAuth consent screen promises users that connected apps cannot download their file contents. Downloads happen in the web app, where they're permission-checked per user and recorded in the portal's audit history. If your integration has a use case that requires content access, contact support@zapaportal.com to discuss it.

Uploads a file to a portal. Two modes are supported:

One-step (recommended for automation): include a public HTTPS file_url and the server fetches the file (up to 100 MB) and stores it immediately — the response is the completed file record. This is how the Zapier integration uploads files.

Two-step (for uploading local bytes): omit file_url and the response contains a presigned upload_url valid for 1 hour. Then:

1. PUT the raw file bytes to upload_url, sending the same Content-Type you specified here (the response echoes the exact method and headers to use)
2. Call POST /api/v1/portals/{portalId}/files/complete with the returned file_id to register the file — until you do, the file will not appear in the portal

Successful uploads fire the file.uploaded webhook event and notify portal users per their notification settings. Pass parent_folder_file_id (a folder's file ID from the list endpoint) to place the file inside a folder.

Registers a file after you've PUT its bytes to a presigned upload_url. This creates the file record so it appears in the portal, notifies users, and fires the file.uploaded webhook event.

Only needed for the two-step upload flow — one-step (file_url) uploads are registered automatically.

Returns all active tasks in a portal with their status, due date, assignees, and type. Useful for syncing outstanding client action items into an external task tracker, or checking whether a client has completed their requested items before advancing the portal's workflow state.

Creates a task in a portal — a request for the client (or your team) to do something, like "Upload your W-2" or "Review the engagement letter". Tasks are created with status Open.

action_type categorizes the request (Question?, File Request, Sign Document, Fill Form, or General). Creating a task fires the task.created webhook event.

Assignees: assigned_guest_ids must be user ids of guests already invited to the portal; assigned_member_ids must be user ids of members of your organization. Display names are resolved server-side. Unknown ids return 400.

Reminders: set send_reminder: true (requires due_date) to have Zapa email the portal's guests on its standard reminder cadence (14, 7, 3 and 0 days before due, and 7 days after).

Updates one or more fields on a task; omitted fields keep their current values. Task IDs come from the portal's task list endpoint.

You can change status here (e.g. reopen a task by setting a non-done status), but if you just want to finish a task, prefer POST /api/v1/tasks/{taskId}/complete — it also fires the task.completed webhook event.

Marks a task as completed and updates the portal's open/closed task counters. This is the preferred way to finish a task from an integration — for example, auto-completing a "File Request" task after your system uploads the requested document. Fires the task.completed webhook event.

Invites one or more guests (clients) to a portal by email. Each guest receives an invitation email; new users are prompted to create an account, existing users just accept the invitation. Accepts either singular (email, name) or plural (emails, names) forms.

This is the typical second step after creating a portal: create the portal, invite the client, upload their documents. Invitations fire the guest.invited webhook event.

Guest permissions can't be set through the API yet — new guests get your organization's default portal permissions, adjustable in the web app's Members panel. Contact support@zapaportal.com if your integration needs permission control.

Returns all webhook subscriptions for your organization, including each webhook's subscribed events, enabled status, signing secret, and delivery success/failure counters. Check the counters to spot endpoints that are failing deliveries.

Subscribes an HTTPS endpoint to real-time events. Deliveries are signed with HMAC-SHA256 in the X-Webhook-Signature header — verify it with the returned secret before trusting a payload (see the Developer Quickstart for example code). Failed deliveries are retried 3 times with exponential backoff.

After creating, use POST /api/v1/webhooks/{webhookId}/test to send a test event and confirm your endpoint receives and verifies it correctly.

Updates the URL, subscribed events, or enabled flag; at least one field is required. Setting enabled: false pauses deliveries without losing the configuration or signing secret — useful during maintenance windows on your receiving endpoint.

Permanently removes a webhook subscription — deliveries stop immediately and the signing secret is invalidated. If you only need a temporary stop, disable it with the update endpoint instead.

Sends a signed webhook.test event to the webhook's URL and reports the delivery result — use it to verify your endpoint is reachable and your signature verification works before relying on real events. The response's status_code is what your endpoint returned; a success: false with an error message usually means a network or TLS problem reaching your URL.