Move your First AI Employee data with a contract you can reason about.

Client API overview

The Client API is a live, tenant-scoped, read-only interface for approved partners. V1 exposes calls, contacts, bookings, reviews, client accounts, jobs, tasks, pipeline opportunities, activities, saved views, reports, automation executions, dashboard summaries, and a complete field-allowlisted CSV catalog. Unregistered OAuth clients remain denied.

Access and registration

Access starts with a reviewed integration and manual OAuth client registration. The public website never issues OAuth client credentials, API keys, or bearer tokens.

What must happen before a first request

1. 1First AI Employee reviews the integration and agrees on the minimum scopes.
2. 2An administrator registers the client and its exact HTTPS redirect URIs. There is no self-service registration.
3. 3The client creates a PKCE verifier and S256 challenge, then keeps the verifier until the callback.
4. 4A signed-in customer approves the scopes on the First AI Employee consent screen.
5. 5The partner exchanges the one-time code and stores the returned tokens securely.

Quickstart

Use this sequence after First AI Employee registers your integration. The example values are placeholders and will not work as credentials.

GET https://api.firstaiemployee.com/oauth/authorize
  ?response_type=code
  &client_id=client_example
  &redirect_uri=https%3A%2F%2Fpartner.example%2Foauth%2Fcallback
  &scope=calls%3Aread%20bookings%3Aread
  &state=opaque_csrf_value
  &code_challenge=base64url_sha256_verifier
  &code_challenge_method=S256

curl "https://api.firstaiemployee.com/api/client/v1/calls?limit=50" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

The Client API is read-only. Zapier has separate partner-specific write behavior that is not part of this contract.

OAuth 2.0

First AI Employee acts as an OAuth 2.0 authorization server. The implemented flow supports Authorization Code, exact registered redirect URIs, mandatory PKCE S256 for Client API clients, customer consent, hashed token storage, and refresh-token rotation.

curl https://api.firstaiemployee.com/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=client_example" \
  --data-urlencode "client_secret=stored_server_side" \
  --data-urlencode "code=one_time_authorization_code" \
  --data-urlencode "redirect_uri=https://partner.example/oauth/callback" \
  --data-urlencode "code_verifier=original_pkce_verifier"

{
  "access_token": "returned_once_redacted",
  "refresh_token": "returned_once_redacted",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "calls:read bookings:read"
}

Authorization flow

• Authorization endpoint: GET /oauth/authorize.
• Token endpoint: POST /oauth/token with application/x-www-form-urlencoded.
• Resource endpoints accept OAuth Bearer access tokens only. Customer session cookies never authorize Client API requests.
• Access token lifetime: 3,600 seconds.
• Refresh token lifetime: 90 days. Every successful refresh returns a replacement refresh token.
• The customer can disconnect the grant, which invalidates the integration.

Client obligations

• Keep confidential client secrets and refresh tokens in a server-side secrets store.
• Validate state on the callback and send the original PKCE verifier during the code exchange.
• Request only the scopes needed for the current feature.
• On 401, refresh once and retry once. Do not loop. A 403 needs a new grant with the required scope.

Pagination and time

Every v1 list uses the same opaque cursor envelope. The cursor advances an offset into the current result order. It is not a database snapshot, so inserts during a long sync can shift later pages. Overlap and deduplicate during backfills.

{
  "data": [
    {
      "id": "b50ff6fb-1f3a-4f4e-8462-07cbd6546f5f",
      "occurred_at": "2026-08-24T14:32:08.000Z",
      "caller": {
        "name": "Jordan Lee",
        "phone": "+15550100100"
      }
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "opaque_cursor_returned_by_server",
    "has_more": true
  }
}

• Use limit between 1 and 100. The default is 50.
• Send the returned next_cursor unchanged. Never parse or construct a cursor.
• Deduplicate every resource by its stable id because records can move between offset pages while new data arrives.
• For long-running syncs, persist the last successful cursor only after the destination transaction commits. Periodically restart from the first page and stop after reaching IDs already seen in a completed pass.

Dates, times, and phone numbers

Most timestamps are UTC ISO 8601 strings. Booking starts_at and ends_at are local wall-clock strings without an offset; interpret them with the current time_zone returned by /me. Phone numbers are returned in E.164 where source data permits. Preserve the original field when your destination has stricter formatting.

Errors and retries

OAuth endpoints use error and error_description. Implemented v1 resource errors add a stable request_id for support. Client API limiters use the smaller { error } body, so retry logic must key off the HTTP status and Retry-After. Normal authenticated budgets are isolated by the verified client and business pair. Do not branch on human-readable descriptions.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This token lacks the contacts:read scope.",
    "request_id": "req_01J..."
  }
}

Calls

Calls are tenant-owned call-history projections. The calls:read scope exposes an allowlisted record with caller details, timing, outcome, intent, sentiment, services mentioned, follow-up state, spam status, summary, and transcript.

{
  "id": "b50ff6fb-1f3a-4f4e-8462-07cbd6546f5f",
  "occurred_at": "2026-08-24T14:32:08.000Z",
  "caller": {
    "name": "Jordan Lee",
    "phone": "+15550100100"
  },
  "duration_seconds": 164,
  "outcome": "follow_up",
  "intent": "estimate",
  "sentiment": "neutral",
  "services_mentioned": "water heater",
  "follow_up_needed": true,
  "spam_status": "not_spam",
  "summary": "Caller asked for a water heater estimate.",
  "transcript": "..."
}

Related read-only resources

Bookings

The bookings:read scope returns booking projections with starts_at, ends_at, status, completed_at, and created_at. The official Client API has no booking write route in v1.

curl "https://api.firstaiemployee.com/api/client/v1/bookings?limit=25" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Treat status as source data and preserve the original value before mapping it to a destination enum. A booking record does not by itself prove that a specific third-party calendar still contains an event.

Webhooks

Event delivery should complement polling, not replace reconciliation. Consumers must be able to process an event more than once and should periodically compare against the source API.

{
  "id": "evt_01J...",
  "type": "lead.created",
  "created_at": "2026-08-24T14:32:09.000Z",
  "data": {
    "id": "lead_01J..."
  }
}

• Acknowledge with a 2xx response only after the event is durably queued.
• Use the event id as the idempotency key. Duplicate deliveries must be harmless.
• Verify a signature over the raw request body before parsing JSON.
• Reject stale timestamps and keep signing-secret rotation overlap short.

Complete exports

The exports:read scope provides complete CSV portability across every field-allowlisted dataset already available to the account owner. The catalog spans calls, conversations, CRM, jobs, files, sales, tasks, reports, settings, custom fields, and their applicable history.

curl "https://api.firstaiemployee.com/api/client/v1/exports" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

curl "https://api.firstaiemployee.com/api/client/v1/exports/jobs.csv" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: text/csv" \
  --output first-ai-employee-jobs.csv

Safe import sequence

1. 1Fetch the catalog and explicitly select reviewed dataset ids.
2. 2Download each CSV to temporary storage and require a complete connection close.
3. 3Validate headers, counts, JSON cells, time offsets, and required relationships.
4. 4Import into a staging table before promoting destination changes atomically.
5. 5Retry partial downloads from the beginning and delete staging files under the approved retention policy.

Porting playbook

A reliable port is a checkpointed synchronization, not one large request. Start with the smallest useful resource set and record provenance in the destination.

Recommended destination mapping

Versioning

The major version lives in the resource path. OAuth protocol endpoints remain unversioned. Successful resource responses also carry X-FAE-API-Version: v1. A new major version is required when a safe migration cannot preserve existing client behavior.

• New optional response fields are compatible. Clients must ignore fields they do not understand.
• New enum values are compatible. Store unknown values instead of rejecting the whole record.
• Removing or renaming a field, changing its meaning, or making an optional field required is breaking.
• Security fixes can change rejection behavior without a major version when preserving it would be unsafe.

Endpoint status

Status is part of the contract. Live means the official v1 route is available to registered clients with the required grant. Draft is a design example only. Reserved means no Client API resource implementation exists.

Do not build production dependencies against a Reserved row. Request developer access to register an integration for the live v1 routes.