Zapier integration reference

What this integration exposes

Version 1.0.1 is the private Zapier Platform integration for First AI Employee. It exposes five REST hook triggers, three create actions, and two searches. Every request is tenant-scoped by the OAuth grant. Callers never supply a business or customer ID.

• Every event payload is flat and has a stable top-level id so Zapier can deduplicate it.
• Event timestamps use ISO 8601 UTC strings. Appointments preserve their local date and time together with the account IANA time zone.
• Contacts and Requests endpoints honor whether those Front Desk modules are available on the authorized account.

Authentication and scopes

Zapier uses the OAuth 2.0 authorization-code grant as a registered confidential client. The account owner reviews the requested scopes on the First AI Employee consent page. The Zapier client authenticates at the token endpoint with its registered client credentials. PKCE is accepted when supplied, but it is not mandatory for this confidential Zapier client.

GET https://api.firstaiemployee.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
  &response_type=code
  &scope=leads%3Aread%20calls%3Aread%20bookings%3Aread%20bookings%3Awrite%20contacts%3Aread%20contacts%3Awrite%20requests%3Aread%20requests%3Awrite
  &state=RANDOM_CSRF_VALUE

Eight requested scopes

Scopes are enforced both when a subscription is created and when each event is delivered. Reauthorization never silently widens an existing grant.

OAuth endpoints and token lifecycle

Access tokens last one hour. Refresh tokens rotate on every successful use and expire after 90 days of inactivity. Reusing an authorization code or an already-used refresh token revokes the grant because replay cannot be distinguished from credential theft.

POST https://api.firstaiemployee.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code=ONE_TIME_AUTHORIZATION_CODE
&redirect_uri=YOUR_REGISTERED_REDIRECT_URI

200 OK
{
  "access_token": "REDACTED",
  "refresh_token": "REDACTED",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "leads:read calls:read bookings:read bookings:write contacts:read contacts:write requests:read requests:write"
}

POST https://api.firstaiemployee.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&refresh_token=CURRENT_REFRESH_TOKEN

200 OK
{
  "access_token": "REDACTED",
  "refresh_token": "NEW_ROTATED_REFRESH_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "..."
}

Protocol endpoints

• redirect_uri must exactly match one of the client registered redirect URIs.
• Authorization codes are single-use. Do not resubmit a code exchange after an ambiguous result.
• Persist the new refresh_token from every successful response before refreshing again.
• A 401 can mean the access token expired. A successful refresh and retry leave the connection active. If /oauth/token returns invalid_grant because authorization was revoked, reconnect that saved account.
• Each saved connection has its own grant. Reconnecting one does not repair other revoked connections. Check the authorized business before publishing the Zap.
• A 403 can mean insufficient scopes or an unavailable module. Check error and error_description before reauthorizing.

Trigger and webhook lifecycle

All five triggers use the same subscription lifecycle. Zapier creates the subscription when a Zap is turned on, receives flat JSON events, and deletes the subscription when the Zap is turned off.

1. When a Zap is turned on, Zapier sends POST /api/zapier/hooks with targetUrl and one of the five supported events.
2. First AI Employee requires HTTPS on the exact hooks.zapier.com host, checks the event scope, and returns 201 with the subscription ID.
3. When the event occurs, First AI Employee posts one flat JSON payload to the Zapier URL. A write originating from that same grant is not echoed back to the same connection.
4. When the Zap is turned off, Zapier sends DELETE /api/zapier/hooks/{id} and receives 204.

POST https://api.firstaiemployee.com/api/zapier/hooks
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "targetUrl": "https://hooks.zapier.com/hooks/standard/REDACTED/",
  "event": "case.created"
}

201 Created
{ "id": "SUBSCRIPTION_UUID", "event": "case.created" }

POST https://hooks.zapier.com/hooks/standard/REDACTED/
Content-Type: application/json

{
  "id": "REQUEST_UUID",
  "eventId": "REQUEST_UUID",
  "event": "case.created",
  "source": "First AI Employee",
  "occurredAt": "2026-08-31T12:00:00.000Z",
  "businessName": "Example Service Company",
  "requestId": "REQUEST_UUID",
  "contactId": "CONTACT_UUID",
  "jobId": null,
  "summary": "Customer needs a repair estimate",
  "description": "Call before arriving.",
  "category": "quote",
  "priority": "normal",
  "status": "open",
  "requestSource": "zapier",
  "firstResponseTargetAt": null,
  "resolutionTargetAt": null
}

Operation coverage for v1.0.1

These are the ten visible Zapier operations and the exact API contracts behind them. Trigger test endpoints return up to three recent records or one clearly marked synthetic sample when the account has no matching records.

Authenticated endpoint inventory

Request and response examples

The examples use placeholders and example data. They do not contain production credentials or customer records. All API calls use JSON except the OAuth token endpoint, which uses form encoding.

Verify a live Zap

1. Test the connection and confirm the correct business. Review every action and its destination before turning the Zap on.
2. An editor test retrieves a sample for field mapping. To verify delivery, publish and enable the Zap, then generate a controlled event in that same account.
3. In Zap History, confirm the trigger and actions succeeded. Keep the Zap enabled and its successful run history available during review.
4. To test New Contact or New Request, create the record from the dashboard or through another connection authorized to the same account. Writes are not echoed to their own grant.
5. Find Booking searches the 200 most recent booking events using structured name, date, and time. A synthetic trigger test does not save an appointment that the search can find.

POST https://api.firstaiemployee.com/api/zapier/contacts
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "phone": "+12025550123",
  "name": "Jordan Lee",
  "email": "[email protected]"
}

201 Created
{
  "id": "CONTACT_UUID",
  "contactId": "CONTACT_UUID",
  "contactName": "Jordan Lee",
  "contactPhone": "+12025550123",
  "contactEmail": "[email protected]",
  "created": true,
  "reused": false,
  "filledBlankFields": []
}

POST https://api.firstaiemployee.com/api/zapier/bookings
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "Jordan Lee",
  "date": "2026-09-02",
  "time": "15:00",
  "reason": "Estimate visit"
}

201 Created
{
  "status": "booked",
  "detail": null,
  "name": "Jordan Lee",
  "date": "2026-09-02",
  "time": "15:00",
  "reason": "Estimate visit"
}

POST https://api.firstaiemployee.com/api/zapier/requests
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "sourceRecordId": "ticket-90210",
  "contactId": "CONTACT_UUID",
  "jobId": null,
  "summary": "Customer needs a repair estimate",
  "description": "Call before arriving.",
  "category": "quote",
  "priority": "normal"
}

201 Created
{
  "id": "REQUEST_UUID",
  "requestId": "REQUEST_UUID",
  "created": true,
  "replayed": false
}

GET https://api.firstaiemployee.com/api/zapier/contacts/find?phone=%2B12025550123
Authorization: Bearer ACCESS_TOKEN

200 OK
[{ "id": "CONTACT_UUID", "contactId": "CONTACT_UUID", "contactPhone": "+12025550123" }]

GET https://api.firstaiemployee.com/api/zapier/bookings/find?name=Jordan%20Lee&date=2026-09-02&time=15%3A00
Authorization: Bearer ACCESS_TOKEN

200 OK
[{ "id": "BOOKING_ID", "contactName": "Jordan Lee", "appointmentDate": "2026-09-02", "appointmentTime": "15:00" }]

• Request categories are general, appointment, service, quote, billing, complaint, and other.
• Request priorities are low, normal, and high. Omitted values default to general and normal.
• Searches return a one-item array for an exact match and an empty array when no record matches.

Errors, retries, and idempotency

Errors use a stable error code and a human-readable error_description. Field validation errors may also include field. Retry safety differs by action, so do not treat every write as generically retryable.

409 Conflict
Content-Type: application/json

{
  "error": "idempotency_key_reused",
  "error_description": "That Source Record ID was already used with different request details."
}

Statuses and recovery

Action-specific retry safety

• Create or Update Contact is safe to repeat with the same normalized phone. It reuses the contact and only fills blank fields.
• Create Request is safe to repeat within the same OAuth grant with the same Deduplication Key, sent as sourceRecordId, and identical details. It returns 200 with replayed: true and Idempotency-Replayed: true. Different details with the same key return 409. After reconnecting, check whether the Request already exists before retrying: a new grant can create a duplicate.
• Create Booking has no general idempotency key. After an ambiguous timeout, use Find Booking with the exact name, date, and time before creating again.
• GET requests may be retried with bounded backoff after transient failures. Do not retry 400, 403, 404, or 409 without changing the state or input.

Version, revocation, and support

This reference covers Zapier integration version 1.0.1. Customers can revoke a connection from Connected Apps in the First AI Employee dashboard. Revocation stops authenticated requests and webhook fan-out for that grant.

Integration support: [email protected]