# Batch create or update records (async)
- Operation ID: `createOrUpdateRecordBatchAsync`
- HTTP method: `POST`
- Path: `/brickworks/v1/async/schemas/{SchemaIdentifier}/records`
- [Human-readable API reference](https://hub.synerise.com/api-reference/brickworks#tag/Brickworks:-Records/operation/createOrUpdateRecordBatchAsync)
## Self-contained OpenAPI method
The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.
```yaml
openapi: 3.0.0
info:
title: Synerise Public API
version: 1.9.1
paths:
/brickworks/v1/async/schemas/{SchemaIdentifier}/records:
post:
tags:
- "Brickworks: Records"
summary: Batch create or update records (async)
description: |
This endpoint can only be used for simple schemas.
- If a record included in this request already exists, it's entirely overwritten by the content from the request (including the slug - if the slug isn't sent, it's removed).
- Provide the current identifier value (if your request changes the identifier, provide the one from before the change).
- The record must conform with the schema.
Asynchronous requests are processed according to the time they reach the service.
This means that requests to synchronous endpoints may overwrite asynchronous operations which were sent earlier and queued due to high traffic.
In some edge cases, changing a record may fail further in the backend, even when this endpoint returns no errors. In such cases, contact Support.
---
**API consumers:** Synerise User, Workspace (Business Profile)
**API key permission required:** `BRICKWORKS_RECORDS_CREATE`
**User role permission required:** `assets_brickworks: create`
operationId: createOrUpdateRecordBatchAsync
security:
- JWT: []
parameters:
- name: SchemaIdentifier
in: path
required: true
description: Schema identifier - can be a UUID (SchemaId) or a human-readable string (Schema AppId/API name, 3-25 characters)
schema:
oneOf:
- type: string
format: uuid
title: Schema UUID
- type: string
minLength: 3
maxLength: 25
pattern: ^(?!__)(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)[\w\-]+$
title: Schema AppId
examples:
uuid:
value: 550e8400-e29b-41d4-a716-446655440000
summary: Schema UUID
appId:
value: my_schema_app_id
summary: Schema AppId (API name)
requestBody:
description: Record data
content:
application/json:
schema:
type: array
items:
type: object
x-class-name: AsyncRecordRequest
x-interface-name-ts: AsyncRecordRequest
description: Async record request
required:
- identifier
- values
properties:
identifier:
type: object
description: Definition of a unique identifier of a record
properties:
name:
type: string
description: |
The name of the identifier. By default, `slug` and `id` are always available. You can also use a field that was configured as `unique`.
In this field, provide the current identifier. If you want to change the identifier with the request, send it in `values` (for unique fields) or `slug`.
value:
description: The value of the selected identifier (slug or a field that was configured as unique)
oneOf:
- type: string
- type: number
- type: boolean
values:
type: object
x-class-name: RecordValues
x-interface-name-ts: RecordValues
description: |
Values included in the record. Each key is the name of a field. The value must match the configuration of the field in the schema.
**Default values aren't explicitly saved in the record** or shown in GET requests which retrieve the record, but are returned when an object is generated from the record.
Supported value types:
- Float (number)
- Integer
- String
- Boolean
- Date (string, format: date)
- Date-time (string, format: date-time)
- Profile attribute (object with attributeName)
- Typed array
- UUID (string, format: uuid)
- Jinjava (string)
- Catalog (object with itemKey, id)
- Object (free-form)
- External source (empty object)
- One-to-one reference (string - record ID)
- One-to-many reference (array of record IDs)
- Analysis (string, format: uuid)
- Promotion (string - promotion ID)
- File/Image (string - file ID)
- Recommendation (object with id, params)
- Voucher (object with id)
- Untyped JSON (object)
- Untyped array
additionalProperties: true
example:
stringField: example string
numberField: 123.45
integerField: 42
booleanField: true
dateField: 2024-01-15
dateTimeField: 2024-01-15T10:30:00Z
uuidField: 550e8400-e29b-41d4-a716-446655440000
arrayField:
- item1
- item2
objectField:
key: value
profileAttribute:
attributeName: email
catalog:
itemKey: SKU123
id: catalog-id
recommendation:
id: recommendation-campaign-id
params:
itemId: item-123
slug:
type: string
minLength: 6
maxLength: 40
pattern: ^([a-zA-Z0-9\-]|_[a-zA-Z0-9\-])[\w\-]*
description: |
Unique (within a schema) identifier of a record. Can't be a UUID.
In singleton-type schemas, use the schema's `appId` or `id` in place of record identifiers for generating content.
name:
type: string
maxLength: 255
minLength: 1
nullable: true
description: The name of the record. If not defined and there are no fields with `useAsRecordName = true`, GET requests return `Unnamed`.
responses:
"201":
description: Operation added to queue
"207":
description: Some operations failed
content:
application/json:
schema:
type: array
x-class-name: ResponseBody207
x-interface-name-ts: ResponseBody207
items:
type: object
properties:
identifier:
type: object
properties:
name:
type: string
description: The name of the identifier you used
value:
type: string
description: The value of the identifier
errors:
type: array
description: Errors that occurred for this record
items:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
"400":
description: Incorrect request (malformed JSON, wrong parameters, etc.). See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
"401":
description: "Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc. See error message for details."
content:
application/json:
schema:
type: object
x-class-name: GatewayError
x-interface-name-ts: GatewayError
properties:
error:
type: string
description: Summary of the error
status:
type: integer
format: int32
description: Status code
timestamp:
type: string
description: Time when the message was sent
message:
type: string
description: Description of the problem
"403":
description: Forbidden; insufficient permissions. See error message for details.
content:
application/json:
schema:
type: object
x-class-name: GatewayError
x-interface-name-ts: GatewayError
properties:
error:
type: string
description: Summary of the error
status:
type: integer
format: int32
description: Status code
timestamp:
type: string
description: Time when the message was sent
message:
type: string
description: Description of the problem
"404":
description: Resource not found. See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
"409":
description: The request could not be completed due to a conflict with the current state of the resource. See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
"422":
description: The request was well-formed but could not be processed due to semantic or domain-related constraints. See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
"500":
description: See error message for details.
content:
application/json:
schema:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
x-snr-doc-urls:
- /api-reference/brickworks#tag/Brickworks:-Records/operation/createOrUpdateRecordBatchAsync
servers:
- description: Microsoft Azure EU
url: https://api.synerise.com
- description: Microsoft Azure USA
url: https://api.azu.synerise.com
- description: Google Cloud Platform
url: https://api.geb.synerise.com
tags:
- name: "Brickworks: Records"
components:
schemas:
brickworks-service-ObjectsError:
type: object
x-class-name: ObjectsError
x-interface-name-ts: ObjectsError
required:
- httpStatus
- errorCode
- timestamp
- message
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
errorCode:
type: string
description: |
Code of the error, needed for troubleshooting
See error reference: [https://developers.synerise.com/errors.html](https://developers.synerise.com/errors.html)
httpStatus:
type: integer
description: Error's HTTP status code
message:
type: string
description: Description of the problem
traceId:
type: string
description: Unique identifier of the request, useful for tracing logs
errors:
type: array
items:
$ref: "#/components/schemas/brickworks-service-ObjectsError"
source:
type: object
x-class-name: ObjectErrorSource
x-interface-name-ts: ObjectErrorSource
required:
- pointer
properties:
pointer:
type: string
description: JSON Pointer for invalid body path
value:
type: string
description: Value that caused the validation error
details:
type: object
x-class-name: ObjectsErrorDetails
x-interface-name-ts: ObjectsErrorDetails
additionalProperties:
type: object
description: Additional structured error information
field:
type: string
description: Name of the field that caused the error
securitySchemes:
JWT:
type: http
scheme: bearer
description: |-
JWT Bearer token. The header looks like this: `Bearer {JWT}`
Remember to include the space between 'Bearer' and the token.
Generate a token via the **Authorization** endpoints.
```