Zapier Quickstart

Status: Active Version: v1.1.0 Last updated: 2026-02-25

Companion docs:

Agent Integration Kit — canonical 4-step flow with curl examples
Public API Contract — error codes, job lifecycle, quotas

Prerequisites

Zapier account (Team plan or higher — Custom Request actions require Team+)
RGL8R integration key (create via POST /api/integration-keys or Admin UI)
API base URL (e.g., https://api.rgl8r.com)

Limitations (read first)

Zapier does not support native polling loops. The 4-step flow (auth → enqueue → poll → fetch) requires workarounds:

No loop construct: You cannot poll GET /api/jobs/:id in a loop until completion. Use a Delay step + single status check instead.
Single-check pattern: This guide uses a fixed delay (60s) followed by one status check. For jobs that take longer, increase the delay or use a Zapier Schedule trigger to check periodically.
For complex flows: Use n8n or the CLI which support full polling loops natively.
P12-B will solve this: Async webhook callbacks (planned) will push job completion events to a Zapier Webhooks trigger, eliminating polling entirely.

4-Step Zap: SIMA Screening

Step 1: Trigger

Choose your trigger (Schedule, Google Sheets new row, email, etc.). The trigger provides the context for when to run a screening.

For manual testing, use Schedule by Zapier → Every Day.

Step 2: Token Exchange (Webhooks by Zapier)

Setting	Value
App	Webhooks by Zapier
Action	Custom Request
Method	`POST`
URL	`https://api.rgl8r.com/api/auth/token/integration`
Headers	`x-api-key`: (your integration key)

Output mapping: Map access_token from the response to use in subsequent steps.

Step 3: Enqueue Screening (Webhooks by Zapier)

Setting	Value
App	Webhooks by Zapier
Action	Custom Request
Method	`POST`
URL	`https://api.rgl8r.com/api/sima/batch`
Headers	`Authorization`: `Bearer {{step2.access_token}}`
Data	`{"skus": null, "runPolicy": "always", "screeningAuthority": "US"}`

Output mapping: Map jobId from the response.

Step 4: Delay + Check (Delay by Zapier + Webhooks by Zapier)

Sub-step 4a: Delay

Setting	Value
App	Delay by Zapier
Action	Delay For
Duration	60 seconds

Sub-step 4b: Check Job Status

Setting	Value
App	Webhooks by Zapier
Action	Custom Request
Method	`GET`
URL	`https://api.rgl8r.com/api/jobs/{{step3.jobId}}`
Headers	`Authorization`: `Bearer {{step2.access_token}}`

If status is COMPLETED, proceed to Step 5. If PENDING or PROCESSING, the job needs more time — increase the delay or set up a periodic re-check.

Step 5: Fetch Results (Webhooks by Zapier)

Setting	Value
App	Webhooks by Zapier
Action	Custom Request
Method	`GET`
URL	`https://api.rgl8r.com/api/sima/results?limit=50`
Headers	`Authorization`: `Bearer {{step2.access_token}}`

Use a Filter step after this to route based on screening outcomes (AT_RISK, NEEDS_REVIEW, CLEARED).

Common Follow-Up Actions

After Step 5, add actions to route results:

Outcome	Zapier Action	Example
`AT_RISK` SKUs found	Send Slack message	Alert compliance team with SKU list
`NEEDS_REVIEW` SKUs found	Create Google Sheet row	Log for manual review
All `CLEARED`	Send email summary	Confirmation to operations

SHIP Upload Variant

Replace Step 3 with a file upload. Note: Zapier’s Webhooks Custom Request has limited multipart support. For reliable file uploads, use the CLI or n8n.

If your source is a Google Sheet or similar, consider using the RGL8R API’s JSON endpoints instead of file upload.

Troubleshooting

Symptom	Likely Cause	Action
`401 INVALID_API_KEY` on Step 2	Bad or revoked integration key	Rotate key and update Zap
`401 INVALID_TOKEN` on Steps 3-5	Bearer token expired (default 1hr lifetime)	Reduce delay in Step 4 or re-authenticate
Step 4b shows `PENDING`	Job still processing	Increase delay duration or add a second delay+check cycle
`429 RATE_LIMITED`	Too many Zap runs hitting the API	Reduce Zap trigger frequency; check tenant quota
Multipart upload fails	Zapier Custom Request multipart limitations	Switch to CLI or n8n for file uploads

Next Steps

Webhook triggers (P12-B): When async callbacks ship, replace the Delay+Check pattern with a Webhooks by Zapier → Catch Hook trigger that fires on job completion
Native Zapier app: A dedicated RGL8R Zapier app is under evaluation (post-P12-A) — this would provide native triggers and actions without Custom Request steps
Complex workflows: For multi-step pipelines with branching and error handling, migrate to n8n

Plan ID: P12-A | Last updated: 2026-02-25