Zapier app setup and troubleshooting

Use this runbook when you need a predictable production setup path.

Default setup path (templates first)

For first launch, do not start from a blank/free-form Zap. Start with one canonical template:

• Template A: Source invoice event -> Create Deadline Project from Invoice
• Template B: Upcoming Deadline -> Slack/Teams message
• Template C: Deadline Reminder -> Email/SMS message
• Template D: Upcoming Deadline -> Google Sheets/Airtable row append

Internal mapping/idempotency spec: docs/zapier-workflow-templates.md.

Step 1: Open the setup flow

1. Open Dashboard → Integrations.
2. Click Open setup under Zapier Integration.
3. Use Read setup guide if you want the public article open beside the dashboard flow.
4. In the setup page, click Open Zapier App, then start with Connect Account.

Step 2: Complete OAuth connection

1. Zapier redirects to LienDeadline OAuth authorize endpoint.
2. If prompted, sign in to LienDeadline.
3. Approve and return to Zapier.
4. Run Test authentication.

Expected result: auth test succeeds and account is connected.

Step 3: Test LienDeadline triggers

Select a canonical template first, then test the required trigger:

• Upcoming Deadline
• or Deadline Reminder

Both return stable records using id as the dedupe field.

Step 4: Activate and verify

1. Turn the Zap on.
2. Wait for the first poll cycle.
3. Confirm task creation in destination app (Slack, Asana, email, CRM).

Troubleshooting map

• invalid_client: Verify OAuth client id/secret in Zapier app auth config match server env.

• invalid_grant: Authorization code or refresh token is stale/reused; reconnect account.

• No records found: Check there are projects with deadlines inside your days_ahead window.

• Duplicate tasks: Set dedupe to id; do not use only project_id.

• Expected instant polling: Zapier polling frequency depends on your Zapier plan and can delay first run.

Endpoints used by the Zapier app

• OAuth authorize: GET /api/zapier/oauth/authorize

• OAuth token: POST /api/zapier/oauth/token

• Upcoming trigger: GET /api/zapier/v2/triggers/upcoming

• Reminder trigger: GET /api/zapier/v2/triggers/reminders

• Create action: POST /api/zapier/webhook/invoice

QA verification checklist

1. Setup starts from one canonical template (A-D), not a blank Zap.
2. OAuth auth test passes in Zapier.
3. Trigger test returns sample records.
4. Live Zap run creates downstream action.
5. No duplicate task creation when polling repeatedly.
6. Telemetry counters increment for OAuth + poll + webhook events.