> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedreach.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Schema Update
> Returns the status of a schema update submitted with `async=true`. Poll until status is `succeeded` (the response carries the saved schema) or `failed` (the response carries the status code and body the synchronous update would have returned).
## OpenAPI
````yaml GET /partner/schema-definitions/{schemaIdOrName}/updates/{updateId}
openapi: 3.1.0
info:
title: Reach API
version: 1.0.0
description: API documentation for Reach platform
servers:
- url: https://api.embedreach.com
description: Production server
security: []
tags:
- name: Default Partner Resources
x-reach-introduction: >-
---
title: 'Default Partner Resources'
description: 'Convenience endpoints for default resource schemas'
---
Reach provides three default resource schemas that are available to
partners upon request: **customers**, **locations**, and **transactions**.
These schemas come pre-configured with common fields and can be used
immediately once enabled for your partner account.
These default schemas can be customized to match your specific data structure. See [Schema Definitions](/api-reference/endpoint/get-partner-schema-definitions) for information on customizing or creating your own schemas.
## Available Default Schemas
- **customers**: For storing customer/user data
- **locations**: For storing business location data
- **transactions**: For storing transaction/order data
## Using Default Resource Endpoints
The endpoints in this section provide convenient shortcuts for all CRUD
operations on the default resource schemas. These endpoints are equivalent
to using the generic [Partner
Resources](/api-reference/endpoint/get-api-resources-schemadefinitionnameorid)
endpoints with the schema name (`customers`, `locations`, or
`transactions`).
Operations supported:
- **Create**: Single and batch upload
- **Read**: List all resources or get by external ID
- **Update**: Patch single resource or batch patch
- **Delete**: Delete single resource or batch delete
- name: Schema Definitions
x-reach-introduction: >-
---
title: 'Overview'
description: 'Define the shape of your data before you send it'
---
A **schema definition** describes your data as it exists in your system —
a JSON Schema for your customers, transactions, locations, or any custom
record type. These endpoints let you create, read, update, and list those
definitions. Defining a schema is self-service; you don't need to wait on
Reach to do it for you.
**New to this? Read the concepts first — they'll save you a redesign.**
Schema definitions are one half of a two-part model, and the shape you
choose here determines what your tenants can segment and message on later.
- [How Reach models your data](/data-sharing/data-model) — the three
canonical concepts (contact, transaction, location), and the
definition-vs-mapping distinction.
- [Custom Schemas](/data-sharing/custom-schemas) — the JSON Schema format,
`$ref` references between schemas, categories, and PII annotations.
- [Data Sync Setup](/onboarding/data-sync-setup) — how defining schemas
fits into onboarding.
A definition on its own is just a shape Reach stores. To turn it into a
contact, transaction, or location, pair it with a [Schema
Mapping](/api-reference/endpoint/get-partner-schema-mappings).
Validation is strict, and it protects existing data: you can always
**add** fields, but **removing, renaming, or retyping** a field that
resources already use is restricted, and fields that live tenant segments
or merge fields depend on are protected. Iterate freely before go-live; be
deliberate after.
- name: Schema Mappings
x-reach-introduction: >-
---
title: 'Overview'
description: 'Tell Reach how to read your data as its core concepts'
---
A **schema mapping** tells Reach how to interpret your [schema
definitions](/api-reference/endpoint/get-partner-schema-definitions) in
terms of its three canonical concepts — **contact**, **transaction**, and
**location**. It's the step that says "the `email` field on this schema is
the contact's email," "this schema is a `transactions_schema` and
`transactionTotal` is the amount," and so on.
**Definition vs. mapping is the distinction partners most often trip on —
read this before you map.**
- A **definition** is *the shape of your data* (your field names, your
structure).
- A **mapping** is *how Reach reads that shape as its concepts*.
Two steps, two parts of the UI. Start here:
- [How Reach models your data](/data-sharing/data-model) — the concepts
and the definition-vs-mapping split.
- [Custom Schemas → Partner Schema
Mappings](/data-sharing/custom-schemas#partner-schema-mappings) — the full
mapping field reference for contacts, transactions, and locations.
Define your schemas first, then map them. A mapping references a schema
definition by ID, so the definition must exist before you can map it.
- name: Tenants
x-reach-introduction: >-
---
title: 'Overview'
description: 'Create and manage the businesses you serve'
---
A **tenant** is one of your customers — a business you manage on behalf of
your platform. Creating one is the first call you make against the Reach
API: it returns the tenant `id` that every other tenant-scoped call, JWT,
and embedded UI session refers back to.
## Identifying a tenant
A tenant has two identifiers: the Reach `id` returned by **Create
Tenant**, and the `externalId` you supply — your own key for the same
business. **Get**, **Update**, **Delete**, and **Reactivate** each accept
either one in the path, so you never have to store the Reach `id` if you
would rather look tenants up by your own.
## Lifecycle
`POST /partner/tenants` with a name and your `externalId`. Reach provisions the tenant's default resources asynchronously, so some of them appear shortly after the response returns rather than in it.
`PATCH /partner/tenants/{id}` — every field is optional, so send only what changed.
`DELETE /partner/tenants/{id}` deactivates rather than destroys. The tenant drops out of **List Tenants** unless you pass `includeDeleted=true`, and **Get Tenant** keeps returning it with `deletedAt` set.
`POST /partner/tenants/{id}/reactivate` restores a deactivated tenant with its data intact.
## What lives on a tenant
| Field | What it is for |
| --- | --- |
| `name`, `website` | How the business is identified across Reach, and the
site the tracking snippet reports from |
| `locations` | The business's physical addresses |
| `branding` | Logo, colors, brand name, and brand voice — what the
embedded UI and generated content adopt |
| `timezone`, `businessHours` | When the business is open — see below |
| `smsOptInImageUrls` | Evidence of how the business captures SMS consent,
used for carrier registration |
If your partner account is configured with a location schema, the
`locations` you send are stored as location resources rather than on the
tenant record. Reads return them either way, so the field behaves the same
from your side.
### Merged fields and replaced fields
On update, `branding` is **merged** key by key into what is already
stored, so you can send just the keys you want to change. `locations`,
`smsOptInImageUrls`, and `businessHours` are **replaced wholesale** — send
the complete value every time, or you will drop what you left out.
## Listing tenants
**List Tenants** is cursor-paginated through `cursor` and `limit` (default
100). Narrow it with `search`, which matches on name, external id, or
website; order it with `orderBy` and `orderDirection`; include deactivated
tenants with `includeDeleted=true`. For portfolio-wide sweeps, pass
`fields` — a comma-separated projection such as `id,name` — to trim the
payload to what you actually read.
## Timezone and business hours
`timezone` and `businessHours` record when a tenant is open. Both are
accepted on **Create Tenant** and **Update Tenant**, and returned by **Get
Tenant**. They sit on the business itself rather than on any one product,
so one schedule serves every Reach feature that needs it — AI Voice uses
`timezone` today to give the agent the tenant's local time.
You are the source of truth for both. Reach never infers a timezone from a
tenant's address, and an unset value means *not configured* — it does not
mean always open, and it does not mean always closed.
`timezone` is any IANA timezone id — `America/New_York`, `Europe/London`,
`Pacific/Honolulu`. Send `null` to clear it.
`businessHours` is an object carrying all seven weekday keys, `monday`
through `sunday`. Each key is either `null` or an empty list (closed that
day), or a list holding exactly one interval of 24-hour `HH:MM` times:
```json
{
"monday": [{ "open": "09:00", "close": "17:00" }],
"tuesday": [{ "open": "09:00", "close": "17:00" }],
"wednesday": [{ "open": "09:00", "close": "17:00" }],
"thursday": [{ "open": "09:00", "close": "17:00" }],
"friday": [{ "open": "09:00", "close": "20:00" }],
"saturday": [{ "open": "10:00", "close": "14:00" }],
"sunday": null
}
```
Those are local wall-clock times in the tenant's `timezone`, never UTC.
Reach reads them against the tenant's local clock at the instant it
evaluates them, so daylight saving shifts resolve on their own. **The
opening time is inclusive and the closing time is exclusive** — against
`09:00`–`17:00`, a moment at exactly `09:00` counts as in hours, and a
moment at exactly `17:00` does not.
The schedule format is deliberately narrow for now:
- **One interval per weekday.** Split shifts — a midday closure — are not
supported yet.
- **`open` must be earlier than `close`.** An interval cannot cross
midnight, so overnight hours such as `20:00` to `02:00` cannot be
expressed yet.
- **All seven weekdays are required, and an update replaces the whole
schedule.** There is no per-day merge: send every day on each update, and
send `null` for the whole field to clear the schedule.
Tenants can also edit their own timezone and hours from the Voice settings
in the embedded Reach UI. Those edits write to the same business record,
so **Get Tenant** can return values you did not send. Re-read the tenant
if your system needs to stay in sync.
- name: Automation Templates
x-reach-introduction: >
---
title: 'Overview'
description: 'Author automation templates and roll them out to your
tenants'
---
An **automation template** is an automation you define once and sync to
your tenants. Each tenant gets its own automation built from the template.
## Editing steps
A template's steps live in `contents.actionData`. Every step has a
`templateActionId`, which is how a sync matches a template step to the
step it created in each tenant's automation.
| To | Do this |
| --- | --- |
| Edit a step | Send it with its existing `templateActionId`. Tenants'
automations keep the same step, and a message step keeps its communication
group. |
| Add a step | Send it without a `templateActionId`. Reach assigns one. |
| Remove a step | Leave it out of `actionData`. See [Removing
steps](#removing-steps). |
| Reorder steps | Change their `index` values. Steps run in ascending
`index` order. |
Always send back the `templateActionId` you read. A step sent without one
is treated as new, so tenants' automations get a new step in place of the
old one. Each step needs its own `templateActionId`: when you copy a step
to add another, leave the ID out of the copy.
## Removing steps
Removing a step affects customers already in the automation, and adding
the step back doesn't undo it:
- **Customers on the removed step stop.** A customer waiting at a wait
step when a sync removes it stops there with an error. A customer whose
message from a removed step is about to send still receives it, then
stops. Neither continues to the steps that follow. Customers on other
steps are unaffected and continue past the removed step.
- **Adding a message step back doesn't restore tenants' edits.** Once a
sync has removed a message step, adding it back, even with its original
`templateActionId`, gives tenants a new message built from the template.
## Updating a template
`PATCH /partner/automation-templates/{id}` replaces only the fields you
send. Inside `contents`, each field you send replaces the stored one
whole: sending `actionData` replaces the full step list.
A template's `contents.feature` can't change once it's created. A step's
`type` can't change, except between the two wait-until behaviors
(`wait_until_next_occurrence` and `wait_until_next_fixed_time`). To turn a
step into a different kind of step, remove it and add a new one without a
`templateActionId`.
To avoid overwriting someone else's edit, send the `ETag` from **Get
Automation Template** as `If-Match`. If the template was saved after you
read it, the update returns 412 and writes nothing; read it again and
reapply your change.
## Rolling changes out
Saving a template does not update tenants' existing automations. Start a
sync with `POST /partner/automation-templates/{id}/syncs`, then poll `GET
/partner/automation-templates/{id}/syncs/{jobId}` until `status` is
`completed` or `failed`. A finished sync reports `failed` if any tenant
failed; check each tenant's entry in `tenants`.
Some changes reach tenants without a sync:
- **Categories** set with the Automation Template Categories endpoints
apply to tenants' automations right away.
- **Tenants set up later**, such as new tenants on a template in `all`
mode, get the latest saved template.
- **A sync already running** can apply a template saved after it started
to the tenants it hasn't reached yet.
## Choosing tenants
`tenants` sets which tenants receive the template:
| `mode` | Who receives it |
| --- | --- |
| `all` | Every tenant, including tenants created later, except those in
`excludedTenantIds` |
| `selected` | Only the tenants in `tenantIds`. An empty list means none,
which keeps the template a draft. |
A sync deactivates the automation of a tenant that no longer receives the
template, when the automation's current status allows it.
## What a sync changes
- **Trigger settings** are reset to the template's on every tenant
automation that differs, including active ones. Changing a date-based
template's date moves every tenant's scheduled date.
- **Messages a tenant edited** keep the tenant's version. Template changes
to that email or SMS body do not reach them.
- **One-time automations** that are scheduled or already sent are left
unchanged. The sync still reports those tenants as `completed`.
- **Segments** the template uses are created on each tenant, and
reactivated if the tenant deactivated them. A tenant that cannot receive
one of them fails to sync; check its entry in the sync's `tenants`.
paths:
/partner/schema-definitions/{schemaIdOrName}/updates/{updateId}:
get:
tags:
- Schema Definitions
summary: Get Schema Update
description: >-
Returns the status of a schema update submitted with `async=true`. Poll
until status is `succeeded` (the response carries the saved schema) or
`failed` (the response carries the status code and body the synchronous
update would have returned).
parameters:
- schema:
type: string
description: The ID or name of the schema definition
required: true
description: The ID or name of the schema definition
name: schemaIdOrName
in: path
- schema:
type: string
format: uuid
description: The update ID returned when the update was submitted
required: true
description: The update ID returned when the update was submitted
name: updateId
in: path
responses:
'200':
description: Status 200 response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
updateId:
type: string
format: uuid
description: ID of the background update
schemaDefinitionId:
type: string
format: uuid
description: ID of the schema definition being updated
baseVersionNumber:
type: number
description: >-
Schema version the update was based on. The update
fails with a 409 if another change is saved first.
status:
type: string
enum:
- pending
- running
- succeeded
- failed
description: Current state of the update
statusPath:
type: string
description: Path to poll for the result of the update
submittedAt:
type: string
description: When the update was submitted
startedAt:
type:
- string
- 'null'
description: When the update started running
completedAt:
type:
- string
- 'null'
description: When the update finished
schemaDefinition:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier for the schema definition
platform_id:
type: string
format: uuid
description: Platform ID this schema belongs to
name:
type: string
description: Name of the schema
plural_name:
type: string
description: >-
[Deprecated] Please use pluralName instead. Plural
name of the schema
pluralName:
type: string
description: Plural name of the schema
description:
type:
- string
- 'null'
description: Description of the schema
category:
type: string
enum:
- contacts_schema
- transactions_schema
- custom_schema
- combined_schema
- locations_schema
- customer_fields
description: Schema category
version_number:
type: number
description: >-
[Deprecated] Please use versionNumber instead.
Schema version number
versionNumber:
type: number
description: Schema version number
dataConnectionId:
type:
- string
- 'null'
format: uuid
description: Data connection ID for the schema
source_query:
type:
- string
- 'null'
description: >-
[Deprecated] Please use sourceQuery instead.
Source query for the schema
sourceQuery:
type:
- string
- 'null'
description: Source query for the schema
reference_schemas:
type:
- array
- 'null'
items:
type: string
description: >-
[Deprecated] Please use referenceSchemas instead.
References to other schemas
referenceSchemas:
type:
- array
- 'null'
items:
type: string
description: References to other schemas
schema:
type: object
additionalProperties: {}
description: The actual JSON schema definition
external_id_field:
type: string
description: >-
[Deprecated] Please use externalIdField instead.
Field used for external ID references
externalIdField:
type: string
description: Field used for external ID references
deactivated_at:
type:
- string
- 'null'
description: >-
[Deprecated] Please use deactivatedAt instead.
When this schema was deactivated
deactivatedAt:
type:
- string
- 'null'
description: When this schema was deactivated
created_at:
type: string
description: >-
[Deprecated] Please use createdAt instead.
Creation timestamp
createdAt:
type: string
description: Creation timestamp
updated_at:
type: string
description: >-
[Deprecated] Please use updatedAt instead. Last
update timestamp
updatedAt:
type: string
description: Last update timestamp
fieldsToExpose:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the field
description:
type: string
description: The description of the field
jsonPath:
type: string
description: >-
The JSON path to the field in the custom
resource (e.g. .user.rewards.points for the
json { "user": { "rewards": { "points": 100
} } })
exposure:
type: array
items:
type: string
enum:
- segments
- merge-fields
- agent-tools
description: >-
How to expose this field, is it available in
segments, email builder, etc.
required:
- name
- jsonPath
- exposure
description: Fields to expose
exposeNameJsonPath:
type:
- string
- 'null'
description: >-
The JSON path to the field in the schema that will
be used to expose the resource to the user. If not
provided, the resource will not be exposed to the
user.
displayMetadata:
type:
- object
- 'null'
properties:
label:
type: string
minLength: 1
maxLength: 60
description: >-
Human-readable schema name shown in place of
the schema name, e.g. "Job"
icon:
type: object
properties:
type:
type: string
enum:
- lucide
value:
type: string
enum:
- User
- Users
- Contact
- Briefcase
- Building2
- Home
- Store
- MapPin
- ShoppingCart
- Receipt
- CreditCard
- DollarSign
- Package
- Box
- Truck
- Car
- Calendar
- Clock
- Ticket
- Wrench
- ClipboardList
- FileText
- Mail
- MessageSquare
- Phone
- Bell
- Tag
- Tags
- Hash
- Flag
- Star
- Heart
- Award
- Gift
- CircleCheck
- Zap
- Sparkles
- Layers
- Database
- Dog
required:
- type
- value
color:
type: string
pattern: ^#[0-9a-fA-F]{6}$
reporting:
type: object
properties:
status:
type: object
properties:
path:
type: string
minLength: 1
maxLength: 200
required:
- path
additionalProperties: false
effectiveDate:
type: object
properties:
path:
type: string
minLength: 1
maxLength: 200
required:
- path
additionalProperties: false
resourceLink:
oneOf:
- type: object
properties:
source:
type: string
enum:
- field
path:
type: string
minLength: 1
maxLength: 200
required:
- source
- path
additionalProperties: false
- type: object
properties:
source:
type: string
enum:
- pattern
pattern:
type: string
minLength: 1
maxLength: 2048
required:
- source
- pattern
additionalProperties: false
additionalProperties: false
additionalProperties: false
description: >-
Presentation and reporting metadata associated
with the schema.
required:
- id
- platform_id
- name
- plural_name
- pluralName
- description
- category
- version_number
- versionNumber
- reference_schemas
- referenceSchemas
- schema
- external_id_field
- externalIdField
- created_at
- createdAt
- updated_at
- updatedAt
- fieldsToExpose
description: >-
The saved schema definition. Present when status is
succeeded.
failure:
type: object
properties:
statusCode:
type: integer
description: >-
HTTP status the synchronous update would have
returned
body:
type: object
properties:
success:
type: boolean
enum:
- false
message:
type: string
required:
- success
- message
additionalProperties: {}
description: >-
Response body the synchronous update would have
returned
required:
- statusCode
- body
description: >-
Present when status is failed. statusCode and body are
what the synchronous update would have returned, for
example the 409 conflict payload.
required:
- updateId
- schemaDefinitionId
- baseVersionNumber
- status
- statusPath
- submittedAt
- startedAt
- completedAt
required:
- success
'400':
description: Bad Request - Validation or request error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
default: false
message:
type: string
description: Error message describing what went wrong
errors:
type: array
items:
type: string
description: Optional array of specific validation errors
required:
- message
'404':
description: Status 404 response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: 'null'
required:
- success
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.