Public API v1

Connect CRM, booking, or point-of-sale systems with Ratezing to sync business directories, pull customer reviews, automate review requests, and receive signed outbound webhooks.

Authentication & Setup

All API requests must be sent over HTTPS with a Bearer token in the Authorization header:

Authorization: Bearer rvk_live_...

Security requirement: Never pass keys or secrets in URL query parameters or request bodies. Requests placing keys in URLs receive an immediate 400 key_in_url error.

API keys are created from the dashboard under Settings → Developers by Workspace Owners or Admins. Each key can be restricted to specific CIDR IP ranges, given an optional expiration date, and scoped with granular permissions:

businesses:read — List entitled businesses
locations:read — List locations under reachable businesses
reviews:read — Stream and filter customer reviews (Requires Pro tier)
review_requests:write — Create single or batch review requests (Requires Growth tier)
webhooks:read & webhooks:write — Manage outbound webhook subscriptions and test deliveries (Requires Growth tier)

Rate Limits & Response Headers

Every response returns rate limit and observability headers:

RateLimit-Limit: Total calls allowed in the active window
RateLimit-Remaining: Remaining calls before receiving a 429 rate_limited error
RateLimit-Reset: Seconds until the rate limit window resets
Request-Id: Unique request identifier (e.g. req_...) for tracing and audit logging

1. Directory Resources

Discover businesses and locations within your key's granted scope.

List Businesses

GET /v1/businesses?limit=20
Authorization: Bearer <key>

Requires businesses:read. Returns a paginated list of businesses on an active plan.

List Locations

GET /v1/locations?limit=20&business_id=biz_01K7AP1H6YT9Z2QX7JKRNM8CDV
Authorization: Bearer <key>

Requires locations:read. Optional business_id filters results to a single business.

Pagination uses cursor-based navigation with cursor, has_more, and next_cursor.

2. Reviews Resource Pro Tier

Pull public reviews aggregated from verified review platforms.

GET /v1/reviews?location_id=loc_01K7AP1H6YT9Z2QX7JKRNM8CDV&limit=50
Authorization: Bearer <key>

Requires reviews:read and requires the location's business to be on the Pro plan or above.

Incremental Sync

Pass updated_since as an RFC 3339 timestamp (e.g. 2026-10-12T00:00:00Z) to switch to chronological sync ordered by update timestamp. Integrators can store the latest cursor to sync updates incrementally.

3. Review Requests Growth Tier

Invite customers to review your business by email and SMS.

No sentiment gating: Ratezing never gates reviews based on satisfaction or pre-survey scores. Every customer invited sees the same public review platforms. One tree is planted for every review received.

Ask One Person

POST /v1/review-requests
Authorization: Bearer <key>
Content-Type: application/json
Idempotency-Key: invoice-94812-request

{
  "location_id": "loc_01K7AP1H6YT9Z2QX7JKRNM8CDV",
  "recipient": {
    "name": "Alex Smith",
    "email": "[email protected]",
    "phone": "+13203185594"
  },
  "send_now": false,
  "validate_only": false,
  "sms_consent": true,
  "sms_consent_statement": "sms_consent_v1"
}

Idempotency-Key header: Required for 24-hour replay protection. Repeating the same request replays the exact response with header Idempotent-Replayed: true.
validate_only: true: Tests validation, location eligibility, and pack allowance without queueing sends or burning quota.
send_now: true: Sends step 1 immediately rather than waiting for the location's scheduled send delay.
sms_consent: Must be set along with sms_consent_statement: "sms_consent_v1" to send SMS invitations.

Bulk Send / Batch Requests

Send review requests to multiple customers in a single transactional call:

POST /v1/review-requests/batch
Authorization: Bearer <key>
Content-Type: application/json
Idempotency-Key: pos-closeout-20261012

{
  "location_id": "loc_01K7AP1H6YT9Z2QX7JKRNM8CDV",
  "recipients": [
    { "name": "Maria Silva", "email": "[email protected]" },
    { "name": "John Doe", "phone": "+13203185594" }
  ],
  "sms_consent": true,
  "sms_consent_statement": "sms_consent_v1"
}

Batch size limit: Maximum 100 recipients per call (body up to 256 KiB).
Pacing: Batches are automatically paced across the location's daily quota to ensure high deliverability and avoid spikes.
Result indexing: The response returns an indexed array of recipients matching input order, reporting status as scheduled or indicating safeguard skips (skipped_recent, skipped_unsubscribed, skipped_suppressed, etc.).

4. Outbound Webhooks Growth Tier

Subscribe to real-time events delivered to your HTTPS endpoints with cryptographically signed payloads.

Endpoint Management

GET /v1/webhook-endpoints — List configured endpoints
POST /v1/webhook-endpoints — Create an endpoint (URL, description, subscribed event_types). Returns the signing secret (whsec_...) once.
GET /v1/webhook-endpoints/{id} — View endpoint details and status
PATCH /v1/webhook-endpoints/{id} — Update URL, description, or status (enabled / disabled)
DELETE /v1/webhook-endpoints/{id} — Delete an endpoint
POST /v1/webhook-endpoints/{id}/roll — Roll the signing secret with a 24-hour dual-signing grace period
POST /v1/webhook-endpoints/{id}/test — Queue an immediate test ping event
GET /v1/webhook-endpoints/{id}/deliveries — View delivery attempt history for the last 30 days

Verifying Signatures

Outbound deliveries follow the Standard Webhooks specification with headers:

webhook-id: Unique delivery identifier
webhook-timestamp: Unix epoch seconds
webhook-signature: Space-separated signatures formatted as v1,<base64(hmac-sha256)>

To verify: construct the signed payload <webhook-id>.<webhook-timestamp>.<body>, compute HMAC-SHA256 with the secret (stripping whsec_ and base64-decoding the remaining bytes), and verify against the signature.

5. Error Catalog

Every error response returns standard JSON with error, message, request_id, and a direct doc_url anchor.

400 key_in_url: Send API credentials in the Authorization header, never in URL query parameters or bodies.
400 invalid_body: Request body must be valid UTF-8 JSON within size limits.
400 invalid_json: Malformed JSON or invalid object structure.
400 idempotency_key_required: Provide an Idempotency-Key header for state-changing write operations.
400 invalid_idempotency_key: Idempotency keys must be 1 to 255 printable ASCII characters.
400 invalid_cursor: Cursor is invalid, expired, or was generated with different filters.
401 unauthenticated: Missing, expired, revoked, or invalid API key.
403 insufficient_scope: Your API key lacks the required permission scope for this action.
403 plan_required: This feature requires a higher subscription tier (e.g. Pro for Reviews, Growth for Review Requests and Webhooks).
403 contact_rights_required: API key must be created with explicit contact-rights attestation.
403 ip_not_allowed: Caller IP address is not permitted by this API key's CIDR allowlist.
404 not_found: The requested resource, location, or endpoint does not exist.
405 method_not_allowed: HTTP method is not supported on this endpoint.
409 idempotency_in_progress: A concurrent request with the same Idempotency-Key is currently running. Retry after the indicated period.
409 location_inactive: The target location is currently archived or inactive.
409 no_review_site: The location does not have any active public review destinations configured.
422 idempotency_key_reused: This Idempotency-Key was previously used with a different request payload.
422 invalid_parameter: Parameter value is invalid or out of allowed bounds.
422 unknown_parameter: Unrecognized fields present in JSON payload.
422 invalid_id: Malformed prefixed identifier.
422 invalid_limit: Limit parameter must be an integer between 1 and 100.
422 invalid_language: Language must be one of: en, pt, fr, lt.
422 invalid_sms_consent: SMS consent confirmation requires sms_consent_statement set to "sms_consent_v1".
422 invalid_recipient: Each recipient must provide a valid email address or phone number.
422 too_many_recipients: Batch size exceeds the maximum limit of 100 recipients per call.
429 rate_limited: Rate limit exceeded. Check Retry-After response header.
429 pack_exhausted: Location's monthly review request allowance is exhausted. Check resets_at header.
500 internal_error: Internal server error. Note the request_id for support.
503 unavailable: Service temporarily unavailable.