Make & Zapier Connector API

Connect your workspace

Zyan provides native Make modules and Zapier triggers and actions. Private/custom installation is available through the connection flow; availability in a public marketplace is a separate provider approval.

Sign in to your Zyan workspace and open Settings → Integrations → Make or Zapier. Use the installation link offered there. If access is not available, contact team@zyan.ai.
In Make or Zapier, select Zyan and choose a trigger or action. Add a connection, enter your workspace subdomain, sign in, and review the workspace name and requested access.
A workspace owner or admin authorizes the connection. Select resources from the native pickers, then map only the fields your workflow needs.
Test with a synthetic record. Inspect the provider output and the result in Zyan or the destination app before enabling your scenario or Zap.
Use Zyan's integration panel to inspect connections, subscriptions, and recent delivery results. Reconnect from the provider if access expires, or disconnect from Zyan to revoke that connection.

When authoring a Zyan workflow, Save draft & connect saves your work before opening the exact provider panel. Return to automation restores the saved workflow and selected step. New starter recipes remain disabled until you deliberately enable them.

Workspace and permission boundaries

Each connection belongs to one agency workspace and its authorizing actor. API requests recheck that workspace and actor's access. The connector does not expose client-scoped workflows or add agency Gmail sending to them. Connection management, workflow authorship, and permission to approve or send are separate capabilities.

OAuth and scoped access

The native apps manage OAuth authorization-code exchange and refresh. End users do not paste API keys, client secrets, or refresh tokens. Zyan's registered provider-app credentials are separate from each workspace grant; contact support if you need a new developer client.

Authorization: https://app.zyan.ai/integrations/authorize
Token exchange / refresh: https://app.zyan.ai/api/connectors/oauth/token
Connector API base: https://app.zyan.ai/api/connectors/v1

Authorization uses response_type=code, a registered client_id, exact redirect_uri, state, and space-separated scope. Optional PKCE uses code_challenge_method=S256. Token requests use form-encoded grant_type=authorization_code or refresh_token. Token requests include the registered client credentials. An authorization-code exchange supplies code, the same redirect_uri, and code_verifier when PKCE is used. A refresh supplies refresh_token. Refresh tokens rotate; the native provider stores the replacement.

API calls use Authorization: Bearer <connector-access-token>. Connector tokens are not Google access tokens or Supabase session keys. Disconnecting, losing the authorizing role, or losing workspace access prevents further connector actions.

Scopes requested by the native integrations
Scope	Access
`events:read`	Read supported form, booking, lead, and pipeline events.
`subscriptions:write`	Create and remove instant-event subscriptions.
`resources:read`	Choose resources available to this workspace connection.
`leads:write`	Create or update leads and supported pipeline state.
`tasks:write`	Create team tasks.
`notifications:write`	Create in-app team notifications.
`automations:run`	Run published automations that explicitly accept external events.

Instant triggers

The native integration registers and removes event subscriptions during its trigger lifecycle. Choose a Zyan trigger inside the provider; no manual webhook URL is needed. Make's webhook belongs to its scenario configuration, and deleting that webhook detaches it. Turning a scenario off can retain the configured webhook, so also disconnect the Zyan connection when revoking access.

Seven supported events
Trigger / API event	When it fires
Form Submitted `form_submitted`	A successful hosted or embedded form submission. Repeat submissions by an existing lead are distinct events. Optional form.
Booking Created `booking_created`	A new scheduled meeting booking. Optional booking page.
Booking Status Changed `booking_status_changed`	A booking changes status, including cancellation. Optional booking page.
Booking Marked No-Show `booking_no_show`	A booking is manually marked as a no-show; this is not inferred from the clock. Optional booking page.
Lead Created `lead_created`	A new lead is created in the connected workspace. No additional filter.
Deal Stage Changed `deal_stage_changed`	An existing deal moves to another pipeline stage. Optional destination stage.
Data Sent by Automation `workflow_dispatch`	A published Zyan workflow uses Send to Make or Zapier to export explicitly mapped fields. Required destination key.

A form submission has its own event identity, separate from the CRM lead ID. Two successful submissions by the same person can trigger two workflows. Retrying delivery of one submission keeps the original event identity.

Send selected workflow data

Choose Data Sent by Automation in the provider and set a destination key. In Zyan, add Send to Make or Zapier, choose that connection and active destination, and map field names to literals or event variables. Only those selected fields are exported. This step does not accept arbitrary destination URLs.

Advanced: reduce data shared by a trigger

Under Event Data, All supported fields is the default. Choose IDs, status and time only to reduce data shared with the provider. Fetched event samples and live deliveries follow the selected mode. API callers set filters.payload_mode=identifiers_only when subscribing, or payload_mode=identifiers_only when requesting event samples.

With no event history, the native app's built-in example uses IDs, status, and time only, including in full mode. Generate a synthetic event and reload samples before mapping contact details or freeform fields.

The envelope keeps valid event IDs, event type, occurrence time, and connection lineage: id, event_id, event_type, event, occurred_at, origin.connection_ids, and source_connection_id.

When present and valid, data and its flat compatibility fields contain only UUIDs (lead_id, form_id, submission_id, booking_id, booking_page_id, deal_id), ISO timestamps (submitted_at, starts_at, ends_at), and supported state values (status, previous_status, attendance_status, previous_attendance_status, stage, previous_stage). Names, emails, phone numbers, answers, and freeform fields are omitted. workflow_dispatch has empty data in this mode, including all explicitly mapped fields.

A subscription can switch from full to reduced data, or reconnect with the same mode. To send full details after restricting a subscription, create a new native trigger or webhook. Reusing the restricted subscription returns HTTP 409 payload_mode_locked.

Native actions

Every action requires a stable Source Event ID. Use the source tool's event ID and add an action suffix when one event causes multiple different operations.

The field names below are the API JSON keys; native apps provide labeled forms for them. Every action also accepts optional origin_event_id for verified event provenance.

Create or Update Lead

POST /actions/upsert_lead

Inputs: email (required); optional name, phone, company, website, source, tags (array), and attribution (object).

Uses the existing lead deduplication and non-destructive merge. Updating a matching lead preserves its existing name and email identity.

Update Lead

POST /actions/update_lead

Inputs: lead_id (required); supported changes: status, engagement_level, add_tags, remove_tags, assignee_user_id, and stage.

Choose a lead from the resource picker or map the ID returned by an earlier Zyan action. It cannot update arbitrary fields or create a deal by changing its stage.

Create Task

POST /actions/create_task

Inputs: title (required); optional description, assigned_to, due_at, and priority.

Creates a team task through the existing task domain. The due date uses YYYY-MM-DD.

Notify Team

POST /actions/notify_team

Inputs: title and message (required).

Creates an in-app notification for eligible operators, respecting their notification preferences. This action does not send email or SMS.

Run Published Automation

POST /actions/trigger_automation

Inputs: automation_id (required); optional lead_id, event_key, and payload (object).

Queues the selected enabled, published agency automation only if its trigger is External event. Existing approval and sending rules still apply.

Resource pickers

Native pickers expose resources available to the connection: forms, booking pages, leads, pipeline stages, eligible team members, and enabled published automations with an External event trigger. You can also map the lead ID returned by an earlier Zyan action. Client-scoped and unsupported automations are excluded.

An external-event workflow runs only when selected by the action. Its optional event key must match the request. Additional Event Data becomes {{event.data.field_name}} in workflow mappings; the event key is {{event.event_key}}. Publishing or running it does not bypass email review or other sending controls.

Connector API v1

All paths below are relative to https://app.zyan.ai/api/connectors/v1. Native Make and Zapier integrations supply authentication and translate their fields to this shared API.

GET /me: Returns the connection ID, workspace identity, provider, and granted scopes.
GET /resources/:kind: Supported kinds: forms, booking_pages, leads, stages, automations, team_members. Returns items with IDs and display names, plus next_page. Pages start at 0; page_size is 1–100. Follow next_page until null.
GET /events?event=:event: Returns recent event samples in items. Apply the same optional form, booking-page, stage, or destination-key filter as the trigger.
POST /subscriptions: Accepts {event, target_url, filters} and returns the subscription id. The callback must be an approved Make or Zapier HTTPS callback. The native app supplies it.
DELETE /subscriptions/:id: Disconnects that subscription within the authenticated connection.
POST /actions/:action: Accepts the action's validated JSON input and an Idempotency-Key header. Returns an id plus the domain result, such as lead_id, task_id, notification_event_id, or run_id.

Event envelopes contain id, event, occurred_at, source_connection_id, and data. Use the event ID for deduplication. Do not submit tenant IDs, actor IDs, or client-portal IDs as authority; the connection supplies that scope.

Advanced Make API calls

Make also offers Make an API Call for advanced configuration. Select a request from its supported list: workspace identity, event samples, resource reads, or the five action endpoints above. Supply query fields as needed; mutations require a stable Source Event ID and a JSON body using that action's supported fields.

The module uses the existing OAuth connection and the fixed Connector API base. It does not accept arbitrary URLs, API keys, custom authorization headers, or access to other Zyan APIs. The same workspace, scope, validation, and retry rules apply.

Example: start a selected automation

This example assumes an enabled, published workflow with External event and event key team_handoff. Native users configure these same fields in the provider; the token and headers are managed for them.

POST /actions/trigger_automation
Authorization: Bearer <connector-access-token>
Content-Type: application/json
Idempotency-Key: external-form-123:follow-up

{
  "automation_id": "<published-automation-id>",
  "event_key": "team_handoff",
  "payload": {
    "source": "External form",
    "label": "Synthetic validation"
  }
}

The returned run ID means the run was queued. Check Automation History and the destination's result for completion. A successful API response alone does not prove a later workflow step delivered.

Retries, loops, and troubleshooting

Reuse IDs on retries. After an action completes, repeating the same action and payload with the same Source Event ID returns its stored receipt. A changed payload with the same key is rejected with HTTP 409; give a genuinely new operation its own ID. In-progress or attention-required operations must be resolved before treating a retry as a new action.
Keep actions distinct. For one incoming record, use IDs such as form-123:lead and form-123:task. Do not generate a fresh timestamp every time the provider retries.
Carry event provenance. When a scenario or Zap begins with a Zyan trigger, map its event ID into the action's advanced Original Zyan Event ID field. Zyan verifies that lineage so returning events do not automatically loop back to the same connection.
Respect ambiguous delivery. Explicit provider throttling can be retried with backoff. A timeout, server error, or expired in-flight attempt may mean the provider already accepted the event; these deliveries need review instead of automatic resending. Inspect the provider's history before taking further action.
Reconnect or detach when needed. HTTP 401 requires reconnection or a fresh grant; 403 indicates missing scope or workspace permission. A provider callback returning 404 or 410 disconnects the subscription. Recreate the native trigger or reconnect it through the provider.

In Settings → Integrations, expand Triggers and recent delivery for subscription state, delivery status, attempts, and safe error details. Recent counts cover a bounded set of recent records. “Delivered” means the provider accepted that event; inspect the scenario or Zap to confirm its downstream work.

Zyan's Run Test previews do not send to Make/Zapier or append to Google Sheets. A real canary uses a dedicated synthetic event and a deliberately enabled validation workflow. Keep customer workflows and recipients out of validation.

Starter workflows

Zyan form → reporting or handoff: use Form Submitted in Make/Zapier, choose a form, then add the destination app's reporting or team action. Repeat form submissions retain separate event IDs.
External form → Zyan lead → follow-up: use Create or Update Lead, preserve the Source Event ID, and keep the default make or zapier source when using the corresponding Zyan lead-follow-up recipe. Personalized follow-up recipes create review drafts.
Booking change → operational handoff: use Booking Created, Booking Status Changed, or Booking Marked No-Show and select the relevant booking page. Built-in booking confirmations remain responsible for receipts.
External event → selected Zyan automation: publish an agency workflow with External event, then choose it in Run Published Automation. For a reporting canary, map its event key and payload fields to an authorized Google Sheets worksheet with column headers.

Test once, inspect the result, repeat with the same ID to verify deduplication, then enable only the scenario or Zap you intend to run. Keep unused test scenarios inactive.