API docs by Redocly

FSRevs Integration API (1.0.0-beta.4)

Download OpenAPI specification:

Beta. Security, tenancy, idempotency, and delivery guarantees are production quality; the contract may evolve before Stable. Customers provide attribution and data, never implicit delivery instructions.

Validate a tenant API connection

Returns the authenticated workspace identity needed by integration adapters. A valid current tenant API credential is sufficient; no unrelated resource or webhook ability is required.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a Customer

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
required
string [ 1 .. 255 ] characters
Request Body schema: application/json
required
non-empty
Any of
non-empty
name
required
string or null [ 1 .. 255 ] characters
first_name
string or null [ 1 .. 255 ] characters
last_name
string or null [ 1 .. 255 ] characters
email
string or null <email> [ 1 .. 255 ] characters
phone
string or null non-empty

Responses

Request samples

Content type
application/json
{
  • "phone": "string",
  • "name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create or update a Customer

Atomically matches, creates, or updates one Customer. Supply source + external_id together for durable synchronization and optional source_updated_at protection, or omit all three and supply an exact email or phone for unlinked one-off intake. This operation never creates Review Requests, Custom Form requests, message intents, email, or SMS.

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
required
string <uuid>
Request Body schema: application/json
required
One of
Any of
name
required
string or null [ 1 .. 255 ] characters

Full name. When a corresponding explicit first_name or last_name is omitted, FSRevs derives that missing component from this value.

source
required
string or null [ 1 .. 80 ] characters

A durable source namespace supplied by the caller. FSRevs trims it, transliterates it with the application's standard ASCII helper, lowercases it, and collapses punctuation and whitespace to hyphens. The response returns the canonical value. Supply together with external_id, or omit both for one-off intake.

external_id
required
string or null [ 1 .. 191 ] characters

Trimmed but otherwise opaque, case-preserving, and case-sensitive. Supply together with source, or omit both for one-off intake.

first_name
string or null <= 255 characters

Explicit first name. Takes precedence over the first name derived from name.

last_name
string or null <= 255 characters

Explicit last name. Takes precedence over the last name derived from name.

email
string or null <email> <= 255 characters
phone
string or null
source_updated_at
string or null <date-time>

Available only with source + external_id. A strictly older timezone-qualified RFC 3339 value is ignored successfully; equal or absent values process normally.

Responses

Request samples

Content type
application/json
{
  • "source": "string",
  • "external_id": "string",
  • "source_updated_at": "2019-08-24T14:15:22Z",
  • "email": "user@example.com",
  • "name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "result": "created",
  • "source": "string",
  • "external_id": "string"
}

Look up a Customer by deterministic identity

Read-only body-based lookup. Identity values are never accepted in URL paths or query strings. Name is never a deterministic identity.

Authorizations:
bearerAuth
Request Body schema: application/json
required

Responses

Request samples

Content type
application/json
Example
{
  • "type": "contact_identity",
  • "email": "john@example.com",
  • "phone": "+18085551212"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

getCustomer

Authorizations:
bearerAuth
path Parameters
customer_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

updateCustomer

Authorizations:
bearerAuth
path Parameters
customer_id
required
string <uuid>
header Parameters
Idempotency-Key
required
string [ 1 .. 255 ] characters
Request Body schema: application/json
required
name
string or null <= 255 characters
first_name
string or null <= 255 characters
last_name
string or null <= 255 characters
email
string or null <email> <= 255 characters
phone
string or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "email": "user@example.com",
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

listCustomerExternalReferences

Authorizations:
bearerAuth
path Parameters
customer_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

createCustomerExternalReference

Authorizations:
bearerAuth
path Parameters
customer_id
required
string <uuid>
header Parameters
Idempotency-Key
required
string [ 1 .. 255 ] characters
Request Body schema: application/json
required
source
required
string [ 1 .. 80 ] characters

FSRevs canonicalizes this source using the same deterministic rule as customer synchronization. The response returns the canonical source.

external_id
required
string <= 191 characters

Trimmed but otherwise opaque, case-preserving, and case-sensitive.

Responses

Request samples

Content type
application/json
{
  • "source": "string",
  • "external_id": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Unlink one Customer external reference

Deletes only the explicitly identified external-reference link and preserves the Customer. Repeating the same deletion is safe. Disable the calling automation before unlinking and ensure a later synchronization can uniquely match email or phone before expecting relinking. Bulk clearing is intentionally unavailable.

Authorizations:
bearerAuth
path Parameters
customer_id
required
string <uuid>
external_reference_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "validation_failed",
  • "errors": {
    }
}

sendReviewRequest

Sends only to explicitly supplied destinations. Email and SMS channels are derived from the supplied email and phone; stored Customer contacts are never substituted.

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
required
string [ 1 .. 255 ] characters
Request Body schema: application/json
required
Any of
location_id
required
string <uuid>
review_flow_id
required
string <uuid>
customer_id
string or null <uuid>
name
string or null <= 255 characters
email
required
string or null <email> <= 255 characters
phone
string or null
channels
Array of strings (ExplicitSendChannels) [ 1 .. 2 ] items unique
Items Enum: "email" "sms"

Deprecated V1 compatibility input. The server derives channels from nonblank explicit email and phone destinations.

sender_id
string or null <uuid>
employee_id
string or null <uuid>

Responses

Request samples

Content type
application/json
{
  • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
  • "review_flow_id": "d4943273-8f94-4073-8400-2d38a1a7fb2b",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "name": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "channels": [
    ],
  • "sender_id": "3194e023-c19f-4a42-9172-9e18d68e3a3a",
  • "employee_id": "df4fd699-0854-488d-9cc2-15e751a80ee3"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "customer_resolution": {
    }
}

getReviewRequest

Authorizations:
bearerAuth
path Parameters
review_request_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

sendCustomFormRequest

Sends only to explicitly supplied destinations. Email and SMS channels are derived from the supplied email and phone; stored Customer contacts are never substituted.

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
required
string [ 1 .. 255 ] characters
Request Body schema: application/json
required
Any of
custom_form_id
required
string <uuid>
location_id
string or null <uuid>
customer_id
string or null <uuid>
name
string or null <= 255 characters
email
required
string or null <email> <= 255 characters
phone
string or null
channels
Array of strings (ExplicitSendChannels) [ 1 .. 2 ] items unique
Items Enum: "email" "sms"

Deprecated V1 compatibility input. The server derives channels from nonblank explicit email and phone destinations.

sender_id
string or null <uuid>
employee_id
string or null <uuid>

Responses

Request samples

Content type
application/json
{
  • "custom_form_id": "519db30f-7ece-484c-b3ff-f3605a8c37cf",
  • "location_id": "46910cc3-ab41-4b80-b4a7-94dab9f1b795",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "name": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "channels": [
    ],
  • "sender_id": "3194e023-c19f-4a42-9172-9e18d68e3a3a",
  • "employee_id": "df4fd699-0854-488d-9cc2-15e751a80ee3"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "customer_resolution": {
    }
}

getCustomFormRequest

Returns authorized dynamic answer data. Attachments are excluded.

Authorizations:
bearerAuth
path Parameters
custom_form_request_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

listLocations

Authorizations:
bearerAuth
query Parameters
search
string <= 100 characters

Case-insensitive resource name or Location label search.

limit
integer [ 1 .. 50 ]
Default: 50

Maximum options returned. Results are always bounded and never preloaded without a limit.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

listReviewFlows

Authorizations:
bearerAuth
path Parameters
location_id
required
string <uuid>
query Parameters
search
string <= 100 characters

Case-insensitive resource name or Location label search.

limit
integer [ 1 .. 50 ]
Default: 50

Maximum options returned. Results are always bounded and never preloaded without a limit.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

listCustomForms

Authorizations:
bearerAuth
query Parameters
location_id
string <uuid>
search
string <= 100 characters

Case-insensitive resource name or Location label search.

limit
integer [ 1 .. 50 ]
Default: 50

Maximum options returned. Results are always bounded and never preloaded without a limit.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

listReviewFlowEmployees

Authorizations:
bearerAuth
path Parameters
review_flow_id
required
string <uuid>
query Parameters
location_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

listCustomFormEmployees

Authorizations:
bearerAuth
path Parameters
custom_form_id
required
string <uuid>
query Parameters
location_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

listProxySenders

Authorizations:
bearerAuth
query Parameters
location_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

listWebhookSubscriptions

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

createWebhookSubscription

Requires an Idempotency-Key. A valid replay of the same logical operation returns the same subscription ID and original signing secret while the encrypted idempotency snapshot exists, after current authorization is rechecked. The secret is never available from GET or LIST.

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
required
string [ 1 .. 255 ] characters
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
endpoint_url
required
string <uri> <= 2048 characters ^https://[^/@:]+(?:\.[^/@:]+)+(?:/|$)

Public DNS hostname over HTTPS with port omitted or 443. IP literals, userinfo, fragments, redirects, internal hosts, and any hostname resolving partly or wholly to a non-public address are rejected.

event_types
required
Array of strings (PublicEventType) non-empty unique
Items Enum: "custom_form.completed" "customer.created" "customer.updated" "review_request.sent" "review_response.completed" "review_feedback.recorded" "review_destination.visited"
include_sensitive_details
boolean
Default: false

Opt in to immutable sensitive detail snapshots only for event types whose catalog contract supports them. Files and download URLs are never included. Native adapters use lean delivery plus authenticated hydration.

included_custom_form_ids
Array of strings or null <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Optional explicit Custom Form include-list for custom_form.completed. Null or omitted means all current and future Custom Forms. An empty list is invalid. The server canonicalizes, deduplicates, and sorts the list before idempotency fingerprinting.

included_review_flow_ids
Array of strings or null <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Optional explicit Review Flow include-list shared by review_request.sent, review_response.completed, review_feedback.recorded, and review_destination.visited. Null or omitted means all current and future Review Flows. An empty list is invalid. The server canonicalizes, deduplicates, and sorts the list before idempotency fingerprinting.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "endpoint_url": "http://example.com",
  • "event_types": [
    ],
  • "include_sensitive_details": false,
  • "included_custom_form_ids": [
    ],
  • "included_review_flow_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "signing_secret": "string"
}

getWebhookSubscription

Authorizations:
bearerAuth
path Parameters
subscription_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Idempotently disable a webhook subscription

Disables the authenticated User's subscription. A repeated request, an already-pruned subscription, or an identifier that is not owned by the authenticated User returns the same 204 response without exposing whether another User owns that identifier.

Authorizations:
bearerAuth
path Parameters
subscription_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "validation_failed",
  • "errors": {
    }
}

Search Custom Forms eligible for webhook resource scope

Returns a bounded tenant-local list using the same coarse configuration eligibility as webhook subscription creation. Labels include safe Location context to disambiguate duplicate names. This operation does not authorize any event occurrence.

Authorizations:
bearerAuth
query Parameters
search
string <= 100 characters

Case-insensitive resource name or Location label search.

limit
integer [ 1 .. 50 ]
Default: 50

Maximum options returned. Results are always bounded and never preloaded without a limit.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Search Review Flows eligible for webhook resource scope

Returns a bounded tenant-local list across eligible Locations using the same coarse configuration eligibility as webhook subscription creation. Labels include safe Location context to disambiguate duplicate names. This operation does not authorize any event occurrence.

Authorizations:
bearerAuth
query Parameters
search
string <= 100 characters

Case-insensitive resource name or Location label search.

limit
integer [ 1 .. 50 ]
Default: 50

Maximum options returned. Results are always bounded and never preloaded without a limit.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Retrieve recent authorized examples in the exact live webhook envelope

Returns at most ten retained real business occurrences for adapter setup. It is not a polling feed. webhook.test is synthetic-only and is rejected here.

Authorizations:
bearerAuth
Request Body schema: application/json
required
event_type
required
string (PublicEventType)
Enum: "custom_form.completed" "customer.created" "customer.updated" "review_request.sent" "review_response.completed" "review_feedback.recorded" "review_destination.visited"
included_custom_form_ids
Array of strings or null <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Optional explicit Custom Form include-list. Null or omitted means all current and future Custom Forms. The server canonicalizes, deduplicates, and sorts the list.

included_review_flow_ids
Array of strings or null <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Optional explicit Review Flow include-list. Null or omitted means all current and future Review Flows. The server canonicalizes, deduplicates, and sorts the list.

limit
integer [ 1 .. 10 ]
Default: 3

Responses

Request samples

Content type
application/json
{
  • "event_type": "custom_form.completed",
  • "included_custom_form_ids": [
    ],
  • "limit": 3
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

Verify a retained webhook delivery and hydrate its current resource

Platform-neutral adapter endpoint for webhook runtimes that cannot expose the exact original request bytes. The normal bearer credential must be the subscription's current creating credential. FSRevs locates the retained occurrence, delivery, and attempt; reconstructs the exact delivery payload; verifies the existing timestamp-and-payload HMAC; rechecks current event, scope, user, credential, and resource authorization; and returns the canonical event with the current authorized resource. Parsed webhook data is never trusted as proof.

Authorizations:
bearerAuth
Request Body schema: application/json
required
subscription_id
required
string <uuid>
event_id
required
string <uuid>
timestamp
required
integer [ 1 .. 4102444800 ]
signature
required
string^v1=[a-f0-9]{64}$

Responses

Request samples

Content type
application/json
{
  • "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627",
  • "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
  • "timestamp": 1,
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}