---
openapi: 3.0.3
info:
  title: "Braze REST API \u2013 Replace user relationship"
  description: |
    ## Prerequisites

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

    ## 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}/{object_id}/users:
    put:
      summary: Replace user relationship
      operationId: put_data_objects_objects_type_name_object_id_users_put_replace_user_relationship
      parameters:
        - name: type_name
          in: path
          required: true
          description: Object type
          schema:
            type: string
          example: account
        - name: object_id
          in: path
          required: true
          description: Object identifier
          schema:
            type: string
          example: acct-123
      requestBody:
        required: true
        description: This section includes a sample JSON payload and a sample cURL request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceUserRelationshipRequest'
            examples:
              external_id:
                summary: Sample request payload
                description: This example replaces the attributes on the `account_user` relationship between the user and `acct-123`, overwriting any attributes previously stored on it.
                value:
                  user:
                    external_id: user-123
                  rel_kind: account_user
                  attributes:
                    role: admin
              user_alias:
                summary: Alternate example using user alias
                value:
                  user:
                    alias:
                      alias_name: jane@example.com
                      alias_label: crm_email
                  rel_kind: account_user
                  attributes:
                    role: admin
      responses:
        "200":
          description: |
            OK. The user relationship was created or replaced. No action needed.

            This section includes a sample successful response and the response fields.

            The status code `200` could return the following response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplaceUserRelationshipResponse'
              examples:
                success:
                  summary: Example success response
                  value:
                    user_relationship:
                      type_name: account
                      object_id: acct-123
                      rel_kind: account_user
                      user:
                        external_id: user-123
                        braze_id: 507f1f77bcf86cd799439011
                      attributes:
                        role: admin
        "400":
          description: |
            Bad request. To resolve it:

            - **Missing or empty `user`, no identifier, more than one identifier, blank identifier, malformed `braze_id`, `email`, or `alias`, phone that can't convert to E.164, or the old top-level `braze_id` body:** Send a `user` object with exactly one valid identifier.
            - **Unknown `rel_kind` for the type or schema validation error:** Confirm `rel_kind` is valid for the object type and `attributes` match the relationship schema.
            - **Value or field name that isn't valid UTF-8 or contains the null character:** Remove the invalid characters. The `invalid_request` error names each affected field in `source`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                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: object_id must be valid UTF-8
                        source:
                          path: object_id
                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 '#/start_date' must be a valid RFC3339 date/time string"
        "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.

            The REST API key is missing, malformed, or sent to the wrong REST endpoint. Send the key to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints).
          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: |
            Forbidden. API key lacks permission or request is blocked by allowlist. Confirm the key has `data_objects.user_relationships.update` and that your source IP is on the key allowlist, if configured.

            This status means the REST API key doesn't have the required permission, or the request came from an IP address that isn't on the key's allowlist.
          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_allowed:
                  summary: Source IP not on the allowlist
                  value:
                    error: IP address 203.0.113.10 is not whitelisted
        "404":
          description: Not found. Relationship, object, or user not found (`user-not-found` or `data-object-relationship-not-found`). Confirm the object, user, and relationship key values all exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                object_not_found:
                  summary: Object not found
                  value:
                    errors:
                      - id: data-object-not-found
                        message: Data object not found.
                        parameters:
                          - type_name
                          - object_id
                        parameter_values:
                          - account
                          - acct-123
                relationship_not_found:
                  summary: Relationship not found
                  value:
                    errors:
                      - id: data-object-relationship-not-found
                        message: Data object relationship not found.
                user_not_found:
                  summary: User not found
                  value:
                    errors:
                      - id: user-not-found
                        message: User not found.
                        parameters:
                          - user
        "422":
          description: Unprocessable entity. Objects-per-user limit reached (`data-objects-per-user-limit-exceeded`) or users-per-object limit reached (`users-per-data-object-limit-exceeded`). Reduce the relationship count for the user or the object, or contact Braze support about your workspace limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                objects_per_user_limit:
                  summary: Objects-per-user limit reached
                  value:
                    errors:
                      - id: data-objects-per-user-limit-exceeded
                        message: User has reached the limit for linked data objects.
                users_per_object_limit:
                  summary: Users-per-object limit reached
                  value:
                    errors:
                      - id: users-per-data-object-limit-exceeded
                        message: Account has reached the limit for linked users.
        "429":
          description: |
            Too many requests. Rate limit exceeded. Retry after `X-RateLimit-Reset` and reduce request frequency.

            You exceeded the rate limit for this endpoint. 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.user_relationships.update` permission.
        Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
  schemas:
    UserAlias:
      title: User alias
      type: object
      description: User alias object with `alias_name` and `alias_label` (both required when used).
      required: [alias_name, alias_label]
      properties:
        alias_name:
          type: string
          example: jane@example.com
        alias_label:
          type: string
          example: crm_email
    UserIdentifier:
      title: User
      description: |
        The user to relate to the object. Must contain exactly one of `external_id`, `braze_id`, `alias`, `email`, or `phone`.

        - Pass exactly one identifier in `user`. Zero or more than one non-null identifier returns `400`. Null identifier fields alongside one valid identifier are accepted.
        - If an email or phone number matches more than one user profile, Braze picks the identified user (one with an `external_id`). If there's still a tie, Braze picks the most recently updated profile.
        - Use `external_id` where available.
      oneOf:
        - title: By external ID
          type: object
          required: [external_id]
          properties:
            external_id:
              type: string
              description: The user's external ID.
              example: user-123
        - title: By Braze ID
          type: object
          required: [braze_id]
          properties:
            braze_id:
              type: string
              description: The Braze user ID.
              example: 507f1f77bcf86cd799439011
        - title: By user alias
          type: object
          required: [alias]
          properties:
            alias:
              $ref: '#/components/schemas/UserAlias'
        - title: By email address
          type: object
          required: [email]
          properties:
            email:
              type: string
              description: The user's email address.
              example: jane@example.com
        - title: By phone number
          type: object
          required: [phone]
          properties:
            phone:
              type: string
              description: The user's phone number. Must be convertible to E.164.
              example: "+15555550100"
    ReplaceUserRelationshipRequest:
      title: Replace user relationship request
      type: object
      required: [user, rel_kind]
      properties:
        user:
          $ref: '#/components/schemas/UserIdentifier'
        rel_kind:
          type: string
          description: Relationship kind
          example: account_user
        attributes:
          type: object
          additionalProperties: true
          description: 'Relationship attributes. 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:
            role: admin
    LinkedUser:
      title: Linked user
      type: object
      description: Linked user object containing the identifier as sent plus `braze_id`
      required: [braze_id]
      properties:
        external_id:
          type: string
          description: The user's external ID, when the request identified the user by `external_id`.
          example: user-123
        braze_id:
          type: string
          description: Braze user identifier
          example: 507f1f77bcf86cd799439011
        alias:
          $ref: '#/components/schemas/UserAlias'
        email:
          type: string
          description: The user's email address, when the request identified the user by `email`.
        phone:
          type: string
          description: The user's phone number, when the request identified the user by `phone`.
    UserRelationship:
      title: User relationship
      type: object
      description: Created or replaced user relationship record
      required: [type_name, object_id, rel_kind, user, 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
        rel_kind:
          type: string
          description: Relationship kind value
          example: account_user
        user:
          $ref: '#/components/schemas/LinkedUser'
        attributes:
          type: object
          additionalProperties: true
          description: Relationship attributes (always present, empty object if none)
          example:
            role: admin
    ReplaceUserRelationshipResponse:
      title: Replace user relationship response
      type: object
      required: [user_relationship]
      properties:
        user_relationship:
          $ref: '#/components/schemas/UserRelationship'
    ErrorResponse:
      title: Error
      type: object
      properties:
        error:
          type: string
          description: Error message returned for authentication and permission errors, and for some validation errors.
        message:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          description: Optional list of detailed validation errors. Each entry has an `id` and a human-readable `message`, and may name the request `parameters` it applies to.
          items:
            type: object
            properties:
              id:
                type: string
                description: Error identifier, such as `user-not-found`.
              message:
                type: string
                description: Human-readable error message.
              parameters:
                type: array
                description: The request parameters the error applies to.
                items:
                  type: string
              parameter_values:
                type: array
                description: The values sent for those parameters.
                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
