Sam × Zapier Integration

Sam API Documentation

Send completed jobs from Zapier into Sam so your customers are automatically asked for a Google review. This documentation covers the production endpoint used by the Zapier integration, including API-key authentication, request fields, validation, response formats and duplicate handling.

Overview

How the integration works

When a job is marked complete in your job-management tool, a Zapier Zap sends a job.completed event to Sam's production endpoint. Sam matches (or creates) the customer, checks review-request eligibility, and either sends a review request immediately or schedules it according to your business settings.

The Zapier action authenticates with a Sam API key — not the account login. The same key is used for the auth test and the completed-job endpoint.

Authentication

Authenticating with your Sam API key

Every request must include your Sam API key, which starts withsam_live_.

Send the key in one of the following headers (in order of preference):

text

Authorization: Bearer sam_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# accepted fallbacks:
X-API-KEY:    sam_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Sam-Api-Key: sam_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key is scoped to a single business and only permits Zapier integration actions. It can be rotated or disabled at any time from the Sam dashboard without affecting your account login.

Setup

Generating or copying your API key

Sign in to your Sam account.
Complete first-run onboarding if you haven't already — this creates the business profile the key is attached to.
Open Integrations → Zapier.
Choose Set up. Your sam_live_… key is shown once — copy it immediately.
Paste it into your Zapier connection's API Key field.

Use Regenerate API key in the same panel to rotate the key, or Disable to revoke access. A regenerated key must be re-entered in Zapier.

Endpoint

Authentication test

Zapier calls this endpoint when a user connects their Sam account, to verify the API key. It returns safe business details only (a non-reversible public id and the business name).

http

GET https://samgetsreviews.com/functions/zapierAuthTest
Authorization: Bearer sam_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

200 — success

json

{
  "id": "pub_4f2a8c1d9b7e0a3f",
  "name": "Acme Plumbing Ltd"
}

401 — invalid or missing key

json

{ "success": false, "error": "Invalid API key" }

Endpoint

Send a completed job

The production endpoint Zapier calls to push a completed job into Sam. Send a JSON body with the completed customer and job details.

http

POST https://samgetsreviews.com/functions/zapierSendCompletedJob
Content-Type: application/json
Authorization: Bearer sam_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Reference

Request fields

Field	Type	Required	Notes
event	string	default	Defaults to `job.completed`. One of `job.completed`, `invoice.paid`, `customer.ready_for_review`.
event_id	string	optional	External event id. Powers idempotency — recommended.
customer.first_name	string	required	Customer's first name.
customer.last_name	string	optional	Customer's last name.
customer.email	string	one of	Valid email. Either email or phone is required.
customer.phone	string	one of	E.164 preferred (e.g. `+447700900000`).
customer.external_id	string	optional	Your system's customer id, stored for reference.
job.external_id	string	required	Unique job identifier from your system.
job.completed_at	ISO 8601	optional	Defaults to the time Sam receives the event.
job.service	string	optional	Service performed.
job.staff_member	string	optional	Staff member who completed the job.
job.value	number	optional	Job value.
job.currency	string	optional	ISO 4217 currency code, e.g. `GBP`.
source.app	string	optional	Name of the originating app.
source.zap_id	string	optional	The Zapier Zap id.

Note: send customer details nested under customer and job details under job. Flat top-level fields such as job_id are not supported.

Usage

Example request

http

POST https://samgetsreviews.com/functions/zapierSendCompletedJob
Content-Type: application/json
Authorization: Bearer sam_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "event": "job.completed",
  "event_id": "evt_1712345678901",
  "customer": {
    "first_name": "Alex",
    "last_name": "Morgan",
    "email": "alex.morgan@example.com",
    "phone": "+447700900123",
    "external_id": "cus_8842"
  },
  "job": {
    "external_id": "JOB-2024-1042",
    "completed_at": "2026-07-23T10:30:00Z",
    "service": "Boiler service",
    "staff_member": "Sam",
    "value": 180,
    "currency": "GBP"
  },
  "source": {
    "app": "Jobber",
    "zap_id": "123456.78"
  }
}

Reference

Successful response

200 — accepted

json

{
  "success": true,
  "status": "accepted",
  "event_id": "6a61e6f545818c6b026aeb4b",
  "customer_action": "created",
  "request_outcome": "sent",
  "scheduled_send_at": null,
  "message": "Alex Morgan was added and the review request was sent."
}

customer_action — created (new customer) or matched (existing customer updated).

request_outcome — one of:

sent — review request was sent immediately.
scheduled — request scheduled for later per business settings (scheduled_send_at set).
suppressed — customer matched but not contactable right now (e.g. opt-out or suppression).
not_eligible — a review was requested too recently.

Reference

Validation errors

A 400 response means the body failed validation. The error field describes the problem.

json

{ "success": false, "error": "customer.first_name is required" }

Common validation errors:

Request body must be valid JSON — body is not parseable JSON.
event is required — missing event and no default applied.
Unsupported event: <event> — event not in the supported list.
customer.first_name is required — missing nested customer first name.
customer.email or customer.phone is required — neither contact detail provided.
job.external_id is required — missing job identifier.

The most common mapping mistake is sending customer details flat or under a different key. Always nest them under customer, and the job under job.

Reference

Duplicate handling

Sam de-duplicates completed jobs so retries and replays never trigger a second review request. A request is treated as a duplicate if it matches a previously-received event by its idempotency key (derived from event_id, or provider + event + job id when no event_id is supplied) or by an exact payload hash safeguard.

200 — duplicate

json

{
  "success": true,
  "status": "duplicate",
  "message": "This completed job has already been received."
}

Reference

Rate limits

Sam applies a burst limit of 60 requests per minute per client IP on each endpoint, which comfortably covers normal Zapier use. Beyond that, requests are throttled.

429 — rate limit exceeded

json

{ "success": false, "error": "Rate limit exceeded" }

Maximum request body size is 256 KB. Larger payloads are rejected with 413 Payload too large.

Base URL: https://samgetsreviews.com · All endpoints accept application/json.