# Bulk create or update records

Creates or updates multiple records in one request. Returns HTTP 201 when every item succeeds (no per-record errors). Returns HTTP 200 when one or more items fail validation; successful items are still persisted and listed in data.records, with failures in errors.

Endpoint: PUT /api/v2/records/{objectName}/bulk
Version: 2.0
Security: bearerAuth

## Path parameters:

  - `objectName` (string, required)

## Query parameters:

  - `ignoreErrors` (boolean)
    If 'true', allows each save to proceed while ignoring certain non-critical validation errors, when supported.

## Request fields (application/json):

  - `records` (array)
    Records to create or update.

  - `records.uuid` (string)
    UUID of an existing record to update. Omit to create a new record.

  - `records.clientRef` (string)
    Client-side reference for matching the item back after create (e.g. row-3).

  - `records.properties` (object)
    Property values to set on the record.
    Example: {"email":"a@b.com"}

  - `records.relations` (array)
    Relations to create or merge after the record is saved. Same shape as createOrUpdate.

  - `records.relations.relationName` (string, required)
    Name of the relation type
    Example: "works_at"

  - `records.relations.uuid` (string)
    UUID of an existing record to link to

  - `records.relations.properties` (object)
    Properties to update on the existing record referenced by uuid before linking

  - `records.relations.edgeProperties` (object)
    Values for properties declared on the relation schema, stored on the relation edge itself (not on either record). Omit to leave existing edge values untouched; a null value clears a key.
    Example: {"partstat":"ACCEPTED"}

  - `records.relations.record` (object)
    Nested record to create or update (by uuid or unique properties) before linking

  - `records.relations.record.uuid` (string, required)
    Unique identifier for the entity

  - `records.relations.record.name` (string, required)
    The name of the entity

  - `records.relations.record.label` (string)
    Display label for the entity, can be different from name

  - `records.relations.record.createdAt` (integer)
    Unix timestamp when the entity was created

  - `records.relations.record.createdBy` (object)
    Identifier of the user who created the entity

  - `records.relations.record.createdBy.name` (string, required)

  - `records.relations.record.createdBy.label` (string)

  - `records.relations.record.createdBy.createdAt` (integer)

  - `records.relations.record.createdBy.updatedAt` (integer)

  - `records.relations.record.createdBy.deletedAt` (integer)

  - `records.relations.record.createdBy.createdByUuid` (string)

  - `records.relations.record.createdBy.updatedByUuid` (string)

  - `records.relations.record.createdBy.deletedByUuid` (string)

  - `records.relations.record.createdBy.index` (integer)

  - `records.relations.record.createdBy.deleted` (boolean)

  - `records.relations.record.createdBy.complete` (boolean)

  - `records.relations.record.createdBy.uuid` (string, required)

  - `records.relations.record.createdBy.properties` (array)

  - `records.relations.record.createdBy.properties.icon` (string)

  - `records.relations.record.createdBy.properties.name` (string)

  - `records.relations.record.createdBy.properties.value` (any)

  - `records.relations.record.createdBy.properties.type` (string)

  - `records.relations.record.createdBy.properties.label` (string)

  - `records.relations.record.createdBy.objects` (object)

  - `records.relations.record.createdBy.user` (object)

  - `records.relations.record.createdBy.user.uuid` (string)

  - `records.relations.record.createdBy.user.email` (string)

  - `records.relations.record.createdBy.user.firstname` (string)

  - `records.relations.record.createdBy.user.lastname` (string)

  - `records.relations.record.createdBy.user.initials` (string)

  - `records.relations.record.createdBy.user.scopes` (array)

  - `records.relations.record.createdBy.user.filters` (object)

  - `records.relations.record.createdBy.user.role` (string)

  - `records.relations.record.createdBy.user.record` (object)

  - `records.relations.record.updatedAt` (integer)
    Unix timestamp when the entity was last updated

  - `records.relations.record.updatedBy` (object)
    Identifier of the user who last updated the entity

  - `records.relations.record.updatedBy.name` (string, required)

  - `records.relations.record.updatedBy.label` (string)

  - `records.relations.record.updatedBy.createdAt` (integer)

  - `records.relations.record.updatedBy.updatedAt` (integer)

  - `records.relations.record.updatedBy.deletedAt` (integer)

  - `records.relations.record.updatedBy.createdByUuid` (string)

  - `records.relations.record.updatedBy.updatedByUuid` (string)

  - `records.relations.record.updatedBy.deletedByUuid` (string)

  - `records.relations.record.updatedBy.index` (integer)

  - `records.relations.record.updatedBy.deleted` (boolean)

  - `records.relations.record.updatedBy.complete` (boolean)

  - `records.relations.record.updatedBy.uuid` (string, required)

  - `records.relations.record.updatedBy.properties` (array)

  - `records.relations.record.updatedBy.properties.icon` (string)

  - `records.relations.record.updatedBy.properties.name` (string)

  - `records.relations.record.updatedBy.properties.value` (any)

  - `records.relations.record.updatedBy.properties.type` (string)

  - `records.relations.record.updatedBy.properties.label` (string)

  - `records.relations.record.updatedBy.objects` (object)

  - `records.relations.record.updatedBy.user` (object)

  - `records.relations.record.updatedBy.user.uuid` (string)

  - `records.relations.record.updatedBy.user.email` (string)

  - `records.relations.record.updatedBy.user.firstname` (string)

  - `records.relations.record.updatedBy.user.lastname` (string)

  - `records.relations.record.updatedBy.user.initials` (string)

  - `records.relations.record.updatedBy.user.scopes` (array)

  - `records.relations.record.updatedBy.user.filters` (object)

  - `records.relations.record.updatedBy.user.role` (string)

  - `records.relations.record.updatedBy.user.record` (object)

  - `records.relations.record.deletedAt` (integer)
    Unix timestamp when the entity was deleted (null if not deleted)

  - `records.relations.record.deletedBy` (object)
    Identifier of the user who deleted the entity

  - `records.relations.record.deletedBy.name` (string, required)

  - `records.relations.record.deletedBy.label` (string)

  - `records.relations.record.deletedBy.createdAt` (integer)

  - `records.relations.record.deletedBy.updatedAt` (integer)

  - `records.relations.record.deletedBy.deletedAt` (integer)

  - `records.relations.record.deletedBy.createdByUuid` (string)

  - `records.relations.record.deletedBy.updatedByUuid` (string)

  - `records.relations.record.deletedBy.deletedByUuid` (string)

  - `records.relations.record.deletedBy.index` (integer)

  - `records.relations.record.deletedBy.deleted` (boolean)

  - `records.relations.record.deletedBy.complete` (boolean)

  - `records.relations.record.deletedBy.uuid` (string, required)

  - `records.relations.record.deletedBy.properties` (array)

  - `records.relations.record.deletedBy.properties.icon` (string)

  - `records.relations.record.deletedBy.properties.name` (string)

  - `records.relations.record.deletedBy.properties.value` (any)

  - `records.relations.record.deletedBy.properties.type` (string)

  - `records.relations.record.deletedBy.properties.label` (string)

  - `records.relations.record.deletedBy.objects` (object)

  - `records.relations.record.deletedBy.user` (object)

  - `records.relations.record.deletedBy.user.uuid` (string)

  - `records.relations.record.deletedBy.user.email` (string)

  - `records.relations.record.deletedBy.user.firstname` (string)

  - `records.relations.record.deletedBy.user.lastname` (string)

  - `records.relations.record.deletedBy.user.initials` (string)

  - `records.relations.record.deletedBy.user.scopes` (array)

  - `records.relations.record.deletedBy.user.filters` (object)

  - `records.relations.record.deletedBy.user.role` (string)

  - `records.relations.record.deletedBy.user.record` (object)

  - `records.relations.record.index` (integer)
    Index number for ordering entities

  - `records.relations.record.properties` (object)
    Property values as a name→value map, or a LEGACY array of {name,type,value} objects (same shape as LEGACY GET responses).
    Example: {"key1":"value1","key2":123}

  - `records.relations.record.user` (object)
    The user of the record if the user trait is enabled.

  - `records.relations.record.user.uuid` (string)

  - `records.relations.record.user.email` (string)

  - `records.relations.record.user.firstname` (string)

  - `records.relations.record.user.lastname` (string)

  - `records.relations.record.user.initials` (string)

  - `records.relations.record.user.scopes` (array)

  - `records.relations.record.user.filters` (object)

  - `records.relations.record.user.role` (string)

  - `records.relations.record.user.record` (object)

  - `records.relations.record.user.record.name` (string, required)

  - `records.relations.record.user.record.label` (string)

  - `records.relations.record.user.record.createdAt` (integer)

  - `records.relations.record.user.record.updatedAt` (integer)

  - `records.relations.record.user.record.deletedAt` (integer)

  - `records.relations.record.user.record.createdByUuid` (string)

  - `records.relations.record.user.record.updatedByUuid` (string)

  - `records.relations.record.user.record.deletedByUuid` (string)

  - `records.relations.record.user.record.index` (integer)

  - `records.relations.record.user.record.deleted` (boolean)

  - `records.relations.record.user.record.complete` (boolean)

  - `records.relations.record.user.record.uuid` (string, required)

  - `records.relations.record.user.record.properties` (array)

  - `records.relations.record.user.record.properties.icon` (string)

  - `records.relations.record.user.record.properties.name` (string)

  - `records.relations.record.user.record.properties.value` (any)

  - `records.relations.record.user.record.properties.type` (string)

  - `records.relations.record.user.record.properties.label` (string)

  - `records.relations.record.user.record.objects` (object)

  - `records.relations.record.user.record.user` (object)

  - `records.relations.record.relations` (array)
    Relations to create or merge after the record is saved. Each item links to an existing record (uuid) or creates a nested record first.

  - `records.relations.objectName` (string)
    Object name for nested record create when relation allows multiple target types

  - `records.relations.primary` (boolean)
    When true, marks this relation edge as primary

  - `records.relations.merge` (boolean)
    When true, MERGE relation edge instead of CREATE
    Example: true

## Response 200 fields (application/json):

  - `message` (string)
    Result message.

  - `data` (object)
    Successfully saved records.

  - `data.records` (array)
    Successfully saved records.

  - `data.records.uuid` (string)
    UUID of the saved record.

  - `data.records.clientRef` (string)
    Client reference echoed from the request, if provided.

  - `data.records.created` (boolean)
    True when the record was created; false when updated.

  - `errors` (array)
    Per-record errors when one or more items failed validation.

  - `errors.uuid` (string)
    UUID of the record that failed, if known.

  - `errors.clientRef` (string)
    Client reference echoed from the request, if provided.

  - `errors.message` (string)
    Summary message for this record's failure.

  - `errors.errors` (array)
    Field-level validation errors.

  - `errors.errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

## Response 201 fields (application/json):

  - `message` (string)
    Result message.

  - `data` (object)
    Successfully saved records.

  - `data.records` (array)
    Successfully saved records.

  - `data.records.uuid` (string)
    UUID of the saved record.

  - `data.records.clientRef` (string)
    Client reference echoed from the request, if provided.

  - `data.records.created` (boolean)
    True when the record was created; false when updated.

  - `errors` (array)
    Per-record errors when one or more items failed validation.

  - `errors.uuid` (string)
    UUID of the record that failed, if known.

  - `errors.clientRef` (string)
    Client reference echoed from the request, if provided.

  - `errors.message` (string)
    Summary message for this record's failure.

  - `errors.errors` (array)
    Field-level validation errors.

  - `errors.errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

## Response 400 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 401 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 403 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 404 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

## Response 500 fields (application/json):

  - `message` (string)
    The error message providing details about the failure.
    Example: "Resource not found."

  - `errors` (array)
    A list of error types providing further details about the error.

  - `errors.message` (string, required)
    The error message providing details about the failure.
    Example: "Invalid file type."

  - `errors.type` (string, required)
    The type of error.
    Enum: "VALIDATION", "NOT_FOUND", "TEST", "RELATION_NOT_ALLOWED", "INVALID_VALUE", "GENERAL", "INVALID_FILE_TYPE", "INTERNAL_SERVER_ERROR", "CARAER_ERROR", "INVALID_EMAIL", "INVALID_DATE"

  - `errors.correctionSuggestion` (string, required)
    A suggestion on how to correct the error.
    Example: "Try uploading a different file type."

  - `status` (integer)
    The HTTP status code associated with the error.
    Example: 400

  - `stackTrace` (string)

  - `roles` (array)
    Roles the caller is missing when the failure is an authorization error.
    Enum: "USER", "ADMIN", "RESELLER", "DEVELOPER", "SUPER_ADMIN"

  - `scopes` (array)
    Scopes the caller is missing when the failure is an authorization error.

  - `requestId` (string)
    Request correlation ID for support and log tracing.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"