LimesWorth Zapier API

How the integration works

Zapier uses OAuth 2.0 Authorization Code flow. A reviewer or customer connects Zapier, signs in to LimesWorth, selects a permitted workspace, and grants the review_candidates scope. Zapier then sends review candidates to the workspace selected during authorization.

OAuth endpoints

• Authorize: GET /oauth/zapier/authorize — browser login and consent. Required query parameters: response_type=code, client_id, redirect_uri, scope=review_candidates, and state. The redirect URI must exactly be https://zapier.com/dashboard/auth/oauth/return/App247577CLIAPI/.
• Token: POST /oauth/zapier/token — form-encoded token exchange or refresh. Client credentials may be sent as HTTP Basic authentication or as client_id/client_secret form fields. Authorization-code exchange uses grant_type=authorization_code, code, and redirect_uri. Refresh uses grant_type=refresh_token and refresh_token.
• Current user: GET /oauth/zapier/me — send Authorization: Bearer <access_token> to return the connected user and selected workspace.

Access tokens expire after 1 hour. Refresh tokens expire after 30 days and are rotated when used.

The token response fields are access_token, token_type (always Bearer), expires_in (seconds), refresh_token, and scope. The /me response fields are id, email, name, and workspace; workspace contains type, id, name, and role.

Create Review Candidate

POST /api/zapier/v1/review-candidates

Authentication: Authorization: Bearer <access_token>. Send Content-Type: application/json.

Required field:

• sender — non-empty string.

Optional fields:

• event_id — string used as the stable external event identifier.
• subject — string.
• body — string; defaults to an empty string.
• thread_id — string identifying the source thread.
• to — string containing recipient information.
• url — string containing a source URL.

Example request:

POST https://limesworth.com/api/zapier/v1/review-candidates
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "sender": "client@example.com",
  "event_id": "event-123",
  "subject": "Please review",
  "body": "A new item needs review.",
  "thread_id": "thread-456",
  "to": "owner@example.com",
  "url": "https://example.com/item/1"
}

Responses and duplicate behavior

A newly created candidate returns HTTP 200:

{
  "ok": true,
  "duplicate": false,
  "candidate_id": 123,
  "event_id": "event-123",
  "status": "new"
}

Repeating the same event for the same connected workspace returns HTTP 200 with duplicate: true, the existing candidate_id, and status: "existing". When event_id is omitted, LimesWorth derives the idempotency identity from the supplied candidate fields.

The action creates a Passive Intake review candidate only. It does not automatically create a Project or Client Request.

Scopes and entitlements

• The only currently supported OAuth scope is review_candidates.
• Personal use requires a Pro Personal workspace.
• Agency use requires an active Agency entitlement and an Owner or Admin role in the selected workspace.
• Workspace selection is bound to the OAuth authorization and is enforced again when the token and action are used. Personal and Agency data are not interchangeable.

Basic errors

• 400 — invalid OAuth request or grant, malformed JSON, missing sender, or a field with the wrong type.
• 401 — invalid client credentials, missing/invalid/expired Bearer token, or revoked authorization.
• 403 — insufficient OAuth scope or a workspace that is not entitled or manageable.
• 409 — the authorized workspace has no active Zapier connection available for the action.
• 415 — the candidate request is not sent as JSON.

Errors are returned as JSON with a detail field. OAuth machine endpoints do not redirect unauthenticated API calls to the HTML login page.

Reviewer and customer notes

Reviewers should use the supplied LimesWorth test account, complete the normal login and consent flow, select the Personal workspace, and test the Create Review Candidate action with a unique event_id. Customers use the same OAuth authorization flow when connecting LimesWorth to Zapier. The selected workspace determines where the candidate appears for review.

Client credentials and access tokens are secrets. Keep them in Zapier's authentication configuration and do not place them in action fields, URLs, logs, or public examples.

Support

For integration questions or security concerns, contact hello@limesworth.com.