Zapier connector API reference for integrators
Use the current Britixo lead API, OAuth and REST Hook contracts through an approved integration, with the correct methods, scopes and boundaries.
Before you begin
This guide is for an authorised integrator. Confirm the registered callback and approved app configuration with support. Keep all credentials in the approved secret/connection store and use HTTPS.
CRM workspace → Tools → Britixo Automations (or Utilities in a classic layout)
Follow these steps
- Resolve the active workspace through the approved connection flow and retain the canonical workspace URL returned by validation.
- Use the OAuth authorisation-code flow. Token and revoke requests are form-encoded POSTs; public-client code exchange requires S256 PKCE.
- Send API access in the Authorization: Bearer header with the scopes required by the operation. Do not supply an alternative tenant ID.
- Read the endpoint table and allowlisted create fields below. Handle non-2xx responses, validation, limits and pagination deliberately.
- Test the full approved app contract: identity response, token refresh replacement, subscription/unsubscription, sample extraction, event mapping and action result mapping.
- Use bounded retries with state verification for writes. Design deduplication and recovery rather than assuming a request reference provides idempotency.
Check the result
The app consumes the documented response envelopes and correctly handles expiry, scopes, workspace context, empty results, errors and event references.
Rules, fields and operating limits
- Resource URLs below are relative to the verified workspace base URL.
- API success responses use success plus data; OAuth token responses use the standard token fields directly.
- Lead event bodies use id, event, occurred_at and data. The event ID is distinct from data.id, which is the CRM lead ID.
- Webhook destinations are restricted to approved HTTPS Zapier hosts. This is not a general-purpose webhook relay.
Endpoint reference
Use your verified workspace base address before these paths. Parent workspace validation and broker operations are described in the questions below; they are not tenant-level resources.
| Method | Workspace-relative endpoint | Access | Behaviour |
|---|---|---|---|
GET | /britixo_zapier/api/v1/health | Public | Basic availability; does not test a connection or Zap. |
GET | /britixo_zapier/api/v1/me | identity.read | Connected workspace, staff identity and scopes. |
GET | /britixo_zapier/api/v1/leads | leads.read | List with limit and after_id; success/data envelope. |
GET | /britixo_zapier/api/v1/leads/{id} | leads.read | One workspace-local lead, or 404. |
GET | /britixo_zapier/api/v1/leads/search | leads.read | email, phonenumber and query; OR matching; up to 20 rows. |
GET | /britixo_zapier/api/v1/leads/sources | leads.read | Available lead source IDs and names. |
GET | /britixo_zapier/api/v1/leads/statuses | leads.read | Available lead status IDs and names. |
POST | /britixo_zapier/api/v1/leads | leads.write | Create one lead from the documented field allowlist. |
POST | /britixo_zapier/api/v1/webhooks | webhooks.manage | Subscribe using event and target_url; stores subscription ID. |
DELETE | /britixo_zapier/api/v1/webhooks/{id} | webhooks.manage | Remove a subscription owned by the current connection. |
GET | /britixo_zapier/oauth/authorize | Staff sign-in + consent | response_type=code, client_id, approved redirect_uri, state and scope; S256 PKCE when used. |
POST | /britixo_zapier/oauth/token | Approved OAuth client | Form-encoded authorization_code or refresh_token grant. |
POST | /britixo_zapier/oauth/revoke | Approved OAuth client | Form-encoded token revocation. |
If something does not look right
If the app expects a flat record but receives an envelope, fix the app mapping rather than modifying customer data. Request an exact callback registration or unsupported action through the implementation process.
Questions and answers
Which methods create and remove a subscription?
POST /britixo_zapier/api/v1/webhooks with event and target_url creates a subscription; DELETE /britixo_zapier/api/v1/webhooks/{id} removes one owned by the current connection.
Which events can the backend accept?
lead.created and lead.updated. Treat lead.updated as limited to the currently hooked save paths; it is not a complete change-data-capture feed.
How does list pagination work?
GET leads accepts limit and after_id. With a positive after_id it returns IDs above that value in ascending order; without it the default is newest first. Track returned IDs explicitly and do not invent an opaque cursor or total-count field.
How are multiple search fields combined?
email, phonenumber and query are alternatives combined with OR. Text query matches name, company or email. Inspect and verify candidate matches.
Where is workspace validation available?
The parent broker exposes GET /britixo_zapier/api/v1/workspaces/validate?url=... for active registered workspace validation. It is not a general resolver on a tenant workspace.
Which token endpoint should the app use?
Use the approved configuration. The module provides a workspace /britixo_zapier/oauth/token endpoint and a parent /britixo_zapier/oauth/broker/token endpoint that validates and forwards to a workspace. Do not swap them without checking the app contract.
Can I use the event’s delivery signature in a custom receiver?
The current transport includes X-Britixo-Signature and X-Britixo-Delivery headers, but approved destinations are restricted. A custom receiver and signing-secret distribution require a separately approved integration; this public guide supplies no signing material.
Can the API return data from another company?
Use a distinct connection for the other workspace. The module operates against the database namespace selected for the current workspace, not a caller-supplied tenant switch.
Useful next steps
Contact Britixo support. Include the workspace, action, run reference and time; keep credentials private.