> ## 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.

# Batch Upload Resources

> Uploads multiple resources via the event processor for asynchronous processing. This is more efficient for large batches of data. When upsert is enabled, new data is merged with existing data (PATCH-like behavior), preserving existing fields. Null values will explicitly delete the field (required fields cannot be deleted and will return a validation error). The batch ID can be used to retrieve the status of the batch using the /api/batches/:batchId endpoint. The maximum number of resources that can be uploaded in a single batch is 1000. If dependencyWaitTimeout is set to a value > 0, resources with missing dependencies (from schema definitions using $ref fields) will be stored in a pending state. The pending resources will be automatically processed once their dependencies become available. The pending resources will be deleted after the specified duration (dependencyWaitTimeout) if their dependencies are not available. The default value for dependencyWaitTimeout is 0, which means that resources with missing dependencies will be rejected immediately.



## OpenAPI

````yaml POST /api/resources/{schemaDefinitionNameOrId}/batch
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.


      <Note>
        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.
      </Note>


      ## 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.


      <Note>

      **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.

      </Note>


      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).


      <Warning>

      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.

      </Warning>
  - 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.


      <Note>

      **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.

      </Note>


      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


      <Steps>
        <Step title="Create">
          `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.
        </Step>
        <Step title="Update">
          `PATCH /partner/tenants/{id}` — every field is optional, so send only what changed.
        </Step>
        <Step title="Deactivate">
          `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.
        </Step>
        <Step title="Reactivate">
          `POST /partner/tenants/{id}/reactivate` restores a deactivated tenant with its data intact.
        </Step>
      </Steps>


      ## 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 |


      <Note>

      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.

      </Note>


      ### 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.


      <Warning>

      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.

      </Warning>


      <Note>

      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.

      </Note>
  - 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:
  /api/resources/{schemaDefinitionNameOrId}/batch:
    post:
      tags:
        - Partner Resources
      summary: Batch Upload Resources
      description: >-
        Uploads multiple resources via the event processor for asynchronous
        processing. This is more efficient for large batches of data. When
        upsert is enabled, new data is merged with existing data (PATCH-like
        behavior), preserving existing fields. Null values will explicitly
        delete the field (required fields cannot be deleted and will return a
        validation error). The batch ID can be used to retrieve the status of
        the batch using the /api/batches/:batchId endpoint. The maximum number
        of resources that can be uploaded in a single batch is 1000. If
        dependencyWaitTimeout is set to a value > 0, resources with missing
        dependencies (from schema definitions using $ref fields) will be stored
        in a pending state. The pending resources will be automatically
        processed once their dependencies become available. The pending
        resources will be deleted after the specified duration
        (dependencyWaitTimeout) if their dependencies are not available. The
        default value for dependencyWaitTimeout is 0, which means that resources
        with missing dependencies will be rejected immediately.
      parameters:
        - name: reach-tenant-id
          in: header
          required: false
          schema:
            type: string
            description: >-
              If using a platform scoped JWT, you can pass in a header to
              impersonate a specific tenant to impersonate the request as.
        - schema:
            type: string
            description: The name or id of the schema definition to upload the resources to
          required: true
          description: The name or id of the schema definition to upload the resources to
          name: schemaDefinitionNameOrId
          in: path
        - schema:
            type: string
            enum:
              - upsert
              - reject
            default: upsert
            description: >-
              What to do if the resource already exists. upsert will merge new
              data with existing data (PATCH-like behavior), preserving existing
              fields not included in the request. Null values will delete
              fields. reject will throw an error if the resource already exists
          required: false
          description: >-
            What to do if the resource already exists. upsert will merge new
            data with existing data (PATCH-like behavior), preserving existing
            fields not included in the request. Null values will delete fields.
            reject will throw an error if the resource already exists
          name: onconflict
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
            description: >-
              Whether to allow extra fields that are not defined in the schema.
              If true, extra fields will be accepted but not saved. If false,
              requests with extra fields will be rejected.
          required: false
          description: >-
            Whether to allow extra fields that are not defined in the schema. If
            true, extra fields will be accepted but not saved. If false,
            requests with extra fields will be rejected.
          name: ignoreUnknownFields
          in: query
        - schema:
            type:
              - integer
              - 'null'
            minimum: 0
            maximum: 86400
            default: 0
            description: >-
              Timeout in seconds for storing resources with missing dependencies
              as pending. Dependencies refer to resources referenced via $ref
              fields in the schema definition. If 0 or not provided, resources
              with missing dependencies will be rejected. If > 0, resources with
              missing dependencies will be stored in pending state for the
              specified duration. Maximum value is 86400 seconds (24 hours).
          required: false
          description: >-
            Timeout in seconds for storing resources with missing dependencies
            as pending. Dependencies refer to resources referenced via $ref
            fields in the schema definition. If 0 or not provided, resources
            with missing dependencies will be rejected. If > 0, resources with
            missing dependencies will be stored in pending state for the
            specified duration. Maximum value is 86400 seconds (24 hours).
          name: dependencyWaitTimeout
          in: query
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                resources:
                  type: array
                  items:
                    type: object
                    additionalProperties: {}
                    description: Resource data matching its schema definition
                  description: An array of resources to upload
              required:
                - resources
      responses:
        '202':
          description: Status 202 response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      batchId:
                        type: string
                        description: The batch ID for tracking the processing status
                      message:
                        type: string
                        description: Status message about the processing request
                      recordCount:
                        type: number
                        description: The number of records sent for processing
                      schemaDefinitionId:
                        type: string
                        description: The schema definition ID used for processing
                    required:
                      - batchId
                      - message
                      - recordCount
                      - schemaDefinitionId
                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: object
                    properties:
                      error:
                        type: string
                    required:
                      - error
                required:
                  - success

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.