---
openapi: 3.0.3
info:
  title: "Braze REST API \u2013 Create data object"
  description: |
    ## Prerequisites

    To use this endpoint, you need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with `data_objects.create`.

    ## Rate limit

    This endpoint is in the Data Objects write bucket with a default limit of 1000 requests per minute.
  version: 1.0.0
  contact:
    name: Braze Support
    url: https://www.braze.com/docs/braze_support/
  license:
    name: Braze Documentation
    url: https://www.braze.com/docs/api/home/
servers:
- url: https://rest.iad-01.braze.com
  description: US-01
- url: https://rest.iad-02.braze.com
  description: US-02
- url: https://rest.iad-03.braze.com
  description: US-03
- url: https://rest.iad-04.braze.com
  description: US-04
- url: https://rest.iad-05.braze.com
  description: US-05
- url: https://rest.iad-06.braze.com
  description: US-06
- url: https://rest.iad-07.braze.com
  description: US-07
- url: https://rest.iad-08.braze.com
  description: US-08
- url: https://rest.us-10.braze.com
  description: US-10
- url: https://rest.fra-01.braze.eu
  description: EU-01
- url: https://rest.fra-02.braze.eu
  description: EU-02
- url: https://rest.au-01.braze.com
  description: AU-01
- url: https://rest.id-01.braze.com
  description: ID-01
- url: https://rest.jp-01.braze.com
  description: JP-01
- url: https://rest.kr-01.braze.com
  description: KR-01
security:
- BearerAuth: []
paths:
  /data_objects/objects/{type_name}:
    post:
      summary: Create data object
      operationId: post_data_objects_objects_type_name_post_create_data_object
      parameters:
        - name: type_name
          in: path
          required: true
          description: Data object type machine name.
          schema:
            type: string
          example: account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataObjectRequest'
            examples:
              create_account:
                summary: Create an account record
                description: This example creates an `account` record with the identifier `acct-new` and sets its `name` and `industry` attributes.
                value:
                  object_id: acct-new
                  attributes:
                    name: New Account
                    industry: software
      responses:
        "201":
          description: |
            Created. The request succeeded and the data object was created. No action needed.

            The status code `201` could return the following response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataObjectResponse'
              examples:
                success:
                  summary: Created data object
                  value:
                    data_object:
                      type_name: account
                      object_id: acct-new
                      attributes:
                        name: New Account
                        industry: software
        "400":
          description: |
            Bad request. Unknown attribute field or invalid attribute type. Confirm every field in `attributes` exists in the type schema and uses the correct data type.

            Braze also returns `400` with the `invalid_request` error code when a value or field name in the request body, path, or query isn't valid UTF-8 or contains the null character. The error names each affected field in `source` and doesn't include the value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unknown_attribute:
                  summary: Unknown attribute
                  value:
                    errors:
                      - id: unknown-attribute
                        message: Unknown attribute "region"
                invalid_characters:
                  summary: Value isn't valid UTF-8
                  value:
                    errors:
                      - id: 3f0c7a52-9b1e-4d6a-8c2f-5e7b1a9d4c60
                        status_code: 400
                        error_code: invalid_request
                        message: type_name must be valid UTF-8
                        source:
                          path: type_name
                date_only_value:
                  summary: Date field without a time and time zone
                  value:
                    error: "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
        "404":
          description: |
            Not found. Type not found (`data-object-type-not-found`). Confirm `type_name` exists in the workspace and matches the machine name exactly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                type_not_found:
                  summary: Type not found
                  value:
                    errors:
                      - id: data-object-type-not-found
                        message: Data object type not found.
                        parameters:
                          - type_name
                        parameter_values:
                          - account
        "409":
          description: |
            Conflict. Duplicate object (`duplicate-data-object`). Use a different `object_id`, or use `PUT` to replace the existing object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                duplicate_object:
                  summary: Duplicate object
                  value:
                    errors:
                      - id: duplicate-data-object
                        message: Duplicate data object.
        "422":
          description: |
            Unprocessable entity. Record limit reached (`data-object-record-limit-exceeded`). Reduce object count for the type, or contact Braze support about your workspace limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                record_limit_exceeded:
                  summary: Record limit reached
                  value:
                    errors:
                      - id: data-object-record-limit-exceeded
                        message: This company has reached its data object record limit
        "401":
          description: |
            Unauthorized. Missing or invalid REST API key. Verify the `Authorization` header uses `Bearer YOUR_REST_API_KEY` and that the key is active. Send the key to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_api_key:
                  summary: Missing or invalid API key
                  value:
                    error: Error authenticating credentials
        "403":
          description: |
            Access denied. API key lacks permission or request is blocked by allowlist. Confirm the key has `data_objects.create` and that your source IP is on the key allowlist, if configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                access_denied:
                  summary: Missing permission
                  value:
                    error: You do not have permission to access this resource
                ip_not_allowlisted:
                  summary: Source IP not on the key allowlist
                  value:
                    error: IP address 203.0.113.10 is not whitelisted
        "429":
          description: |
            Too many requests. Rate limit exceeded. Retry after `X-RateLimit-Reset` and reduce request frequency. See [API rate limits]({{site.baseurl}}/api/api_limits/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                over_rate_limit:
                  summary: Over rate limit
                  value:
                    errors:
                      - id: rate-limit-exceeded
                        message: You have exceeded your limit of 1000 requests per minute. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/.
        5XX:
          description: |
            Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: REST API key
      description: |
        REST API keys are created in the Braze dashboard at **Settings → APIs and
        Identifiers → API Keys**. The key must include the `data_objects.create` permission.
        Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
  schemas:
    CreateDataObjectRequest:
      title: Create data object request
      type: object
      required: [object_id, attributes]
      properties:
        object_id:
          type: string
          maxLength: 250
          pattern: '^[A-Za-z0-9_-]+$'
          description: Object identifier, unique within the type. Can only include letters, numbers, hyphens, and underscores, and must be 250 characters or fewer.
          example: acct-new
        attributes:
          type: object
          additionalProperties: true
          description: 'Field-name keyed values validated against the type schema. Date fields must be RFC 3339 date-time strings that include a time and time zone, such as `2026-11-03T00:00:00Z`. Braze rejects date-only values such as `2026-11-03` with a `400` error. For details, see [Date field format]({{site.baseurl}}/api/endpoints/data_objects#date-field-format).'
          example:
            name: New Account
            industry: software
        display_name:
          type: string
          description: Display label for the object. When the type has a display-name source field, the value of that field takes precedence. Defaults to `object_id`.
    DataObjectResponse:
      title: Create data object response
      type: object
      required: [data_object]
      properties:
        data_object:
          $ref: '#/components/schemas/DataObject'
    DataObject:
      title: Data object
      type: object
      description: Created data object record.
      required: [type_name, object_id, attributes]
      properties:
        type_name:
          type: string
          description: Data object type machine name.
          example: account
        object_id:
          type: string
          description: Data object identifier.
          example: acct-123
        attributes:
          type: object
          additionalProperties: true
          description: Stored object attributes keyed by field name.
          example:
            name: New Account
            industry: software
    ErrorDetail:
      title: Error detail
      type: object
      properties:
        id:
          type: string
          description: Machine-readable error identifier, such as `data-object-not-found`.
        message:
          type: string
          description: Human-readable error message.
        parameters:
          type: array
          description: Names of the request parameters the error refers to.
          items:
            type: string
        parameter_values:
          type: array
          description: Values of those parameters in the request.
          items:
            type: string
        status_code:
          type: integer
          description: HTTP status code. Included with `invalid_request` errors.
          example: 400
        error_code:
          type: string
          description: Error code, such as `invalid_request`. When it's present, `id` is a unique identifier for this error occurrence.
          example: invalid_request
        source:
          title: Error source
          type: object
          description: The request field the error applies to. Included with `invalid_request` errors.
          properties:
            path:
              type: string
              description: Dot-separated path to the field, such as `attributes.name`, when one field is affected.
            paths:
              type: array
              description: Dot-separated paths to each field, when more than one field is affected.
              items:
                type: string
    ErrorResponse:
      title: Error
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        error:
          type: string
          description: Human-readable error message returned for authentication, permission, and some validation errors.
        errors:
          type: array
          description: Optional list of detailed validation errors.
          items:
            $ref: '#/components/schemas/ErrorDetail'
