Taxi Integration
Send client uploads and signed documents from Zapa portals straight into the matching customer in Taxi. Once a portal is linked, every file a client uploads (and every PDF once all signatures are complete) is delivered to Taxi automatically, together with task and workflow updates.
The Taxi integration is available exclusively on the Enterprise plan, like API access and webhooks. Admins on other plans see an upgrade prompt on the Taxi tab, and pushes stop if an organization leaves the Enterprise plan.
Only organization administrators can connect or disconnect the integration. Linking individual portals requires the Manage Permissions portal permission.
How it works
Zapa pushes to Taxi; Taxi never receives access to read from Zapa.
- An administrator enters the API key and signing secret that Taxi issued for your firm under Settings → Taxi.
- On each portal, a team member enters the client's 6-digit Taxi customer id in the taxi External System ID field. Zapa verifies the id with Taxi and shows the customer's name.
- From then on, Zapa delivers files to that customer's inbox in Taxi, with a checksum that Taxi's storage verifies before accepting the file.
Every push is recorded in the portal's Activity as a download by "Taxi Integration", and guests who opted into download notifications receive one, exactly as if a team member had downloaded the file.
Connecting to Taxi
- In Taxi, generate an API key and signing secret pair for Zapa (Taxi issues them together).
- In Zapa, go to Settings → Taxi and click Connect to Taxi.
- Paste the key and secret and click Verify and save. Zapa checks the pair against Taxi before storing it. A rejected pair is not saved.
- Zapa adds taxi to your organization's External Systems automatically so the field appears on every portal's Settings.
The secret is stored encrypted and is never shown again; the connection card shows only the last four characters of the key and when it was last updated.
Rotating the credential
Taxi lets several key/secret pairs be active at once, so rotation has no downtime:
- Issue a new pair in Taxi.
- In Zapa, click Replace credential, paste the new pair, and save.
- Revoke the old pair in Taxi.
Disabling
Disable stops all pushes immediately and deletes the stored credential from Zapa. Portal links are kept, so reconnecting later resumes deliveries without re-linking each portal.
If Taxi starts rejecting the stored credential (for example after the key was revoked in Taxi), the Taxi tab shows a red banner with the reason and deliveries stop until a new pair is entered.
Linking a portal
- Open the portal and go to its Settings tab.
- Under External System IDs, enter the client's 6-digit Taxi customer id in the taxi field and press Enter (or click away).
- The status under the field updates:
| Status | Meaning |
|---|---|
| Linked: Name | Verified. Files now push to this customer. The name is the customer's display name in Taxi. |
| Verifying… | Zapa is checking with Taxi; refresh in a moment or click Re-verify. |
| Not found in Taxi | No active customer with this id in your Taxi tenant. Check the id, or the customer may be archived or merged. |
| Taxi credential rejected | Taxi refused the organization's API key. An administrator must update it under Settings → Taxi. |
| Error | Taxi could not be reached or returned an unexpected answer. Click Re-verify; if it persists, contact support. |
Each Taxi customer id can be assigned to only one portal in your organization.
The external system may be labelled taxi, Taxi or TAXI — the name is matched ignoring case, and an organization cannot have two labels that differ only by case.
Verification is automatic
Zapa checks the link with Taxi whenever the Taxi id is saved — from the portal settings page or through the API — and again automatically whenever a stale link would otherwise block a delivery:
- when the portal page is opened and the stored status is anything other than Linked to the current id, and
- when a file is uploaded (or a task completes) on a portal whose link is not Linked, before the delivery is queued.
So linking portals before connecting the organization's Taxi credential is fine: the first upload after the credential is saved verifies the portal and pushes the file. Re-verify remains available to force an immediate check.
Unlinking
Clear the taxi field and save. Pushes stop immediately and Taxi is notified that the portal was unlinked. Files already delivered stay in Taxi; Zapa never deletes or changes anything there.
What gets sent
| Zapa event | What Taxi receives |
|---|---|
| Client or team member uploads a file | The file bytes, name, size, folder path, uploader, and the task it fulfilled (if any) |
| All signatures on a PDF are complete | The signed PDF bytes, plus signer details |
| Task created / completed | Task title, type, status, assignees and (for completed tasks) the client's response |
| Workflow state changed | New and previous state |
| Portal unlinked | The former customer id |
Files over 200 MB are not sent and show as failed on the file.
Delivery status on files
On a linked portal, team members with Manage Permissions see a status chip next to each file:
- Sent to Taxi — delivered; hover to see when.
- Sending to Taxi — queued or retrying after a temporary problem. Zapa retries automatically with increasing delays for up to 24 hours.
- Taxi failed — not delivered. Hover to see the reason. Click Resend to try again (for example after fixing the credential or relinking the portal).
Files uploaded before the portal was linked are not sent retroactively; re-upload them or send them from Taxi's side if needed.
Troubleshooting
| Symptom | What to check |
|---|---|
| The taxi field does not appear on portals | Settings → Preferences → External Systems must include taxi. Zapa adds it when you connect; add it manually if it was removed. |
| Status stays on Verifying… | Click Re-verify. If it changes to Error, Taxi may be unavailable; try again later. |
| Files show Sending to Taxi for a long time | Taxi is returning temporary errors; Zapa keeps retrying for 24 hours, then marks the file failed with a Resend action. |
| Every file shows Taxi failed with a credential message | The API key was revoked or rotated in Taxi. Enter the new pair under Settings → Taxi, then click Resend on the files. |