---
openapi: 3.0.3
info:
  title: Braze REST API – Search existing dashboard user account by email
  description: |
    ## Prerequisites

    To use this endpoint, you'll need a SCIM token. You'll use your service origin as the `X-Request-Origin` header. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning).

    ## Rate limit

    This endpoint has a rate limit of 20,000 requests per day, per company. This rate limit is shared with the `/scim/v2/Users/` PUT, GET, DELETE, and POST endpoints as documented in [API rate limits]({{site.baseurl}}/api/api_limits).
  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:
  /scim/v2/Users:
    get:
      summary: Search existing dashboard user account by email
      operationId: get_scim_v2_users_filter_username_20eq_20_user_40test_com_get_search_existing_dashboard_user
      parameters:
        - name: filter
          in: query
          required: true
          description: |
            SCIM filter expression to search by email. Braze supports `userName eq "user@example.com"` only. The email value must be wrapped in double quotes.

            Braze only supports exact-match filters on `userName` using the `eq` operator. Other SCIM filter fields or operators return a `400` response.
          schema:
            type: string
          example: userName eq "user@example.com"
        - name: X-Request-Origin
          in: header
          required: true
          description: 'Your service origin, sent as `X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE`. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning).'
          schema:
            type: string
          example: YOUR-REQUEST-ORIGIN-HERE
      responses:
        "200":
          description: The request succeeded and the response body lists the matching dashboard users. No action needed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchUsersResponse'
              examples:
                success:
                  summary: Matching dashboard users
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:ListResponse
                    totalResults: 1
                    Resources:
                    - userName: user@example.com
                      id: dfa245b7-24195aec-887bb3ad-602b3340
                      name:
                        givenName: Test
                        familyName: User
                      department: finance
                      createdAt: 2024 Nov 11, 4:20 PM
                      lastSignInAt: NA
                      permissions:
                        companyPermissions:
                        - manage_company_settings
                        appGroup:
                        - appGroupId: a1b2c3d4-e5f6-4a1b-8c2d-3e4f5a6b7c8d
                          appGroupName: Test Workspace
                          appGroupPermissions:
                          - view_campaigns
                          - view_canvases
                          team:
                          - teamId: a1b2c3d4-e5f6-4a1b-8c2d-3e4f5a6b7c8d
                            teamName: Test Team
                            teamPermissions:
                            - edit_campaigns
                            - launch_campaigns
                            - edit_canvases
                            - launch_canvases
        "400":
          description: |
            Bad request. The `filter` is missing or malformed. Provide a valid SCIM `filter`, such as `userName eq "user@example.com"`.

            If the `filter` parameter is missing or malformed, the endpoint returns:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_filter:
                  summary: The filter is missing or malformed
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 400
                    detail: Request is unparsable, syntactically incorrect, or violates schema.
        "401":
          description: |
            Unauthorized. The SCIM bearer token is missing or invalid, the request origin isn't recognized, your IP isn't allowlisted, or SCIM isn't enabled. Send a valid SCIM bearer token from an allowlisted IP, and confirm SCIM provisioning is enabled. To enable SCIM, contact your Braze account manager.

            If you receive a `401` response, confirm you're using a SCIM token (not a REST API key), that `X-Request-Origin` matches your service origin, and that your IP address is on the SCIM allowlist. For details, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_request_origin:
                  summary: The X-Request-Origin header is missing
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: X-Request-Origin header is missing.'
                invalid_token:
                  summary: The SCIM token isn't valid
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: token not valid.'
                ip_not_allowlisted:
                  summary: The request IP isn't allowlisted
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: Request IP is not in the configured IP allowlist.'
                scim_not_enabled:
                  summary: SCIM API access isn't enabled
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: SCIM API access is not enabled.'
        "429":
          description: |
            Rate limited. You exceeded the SCIM daily rate limit of 20,000 requests per day. Slow your request rate and retry later. 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:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 429
                    detail: You have exceeded your limit of 20000 requests per day. 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: SCIM token
      description: |
        SCIM endpoints authenticate with a SCIM token, not a REST API key. Generate the token in the
        Braze dashboard at **Settings → Company Settings → Admin Settings → SCIM Provisioning**.
        Pass the token as `Authorization: Bearer YOUR-SCIM-TOKEN-HERE`, and send your service
        origin in the `X-Request-Origin` header.
  schemas:
    SearchUsersResponse:
      title: Search dashboard users response
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          description: SCIM list response schema.
        totalResults:
          type: integer
          description: Number of matching dashboard users (0 if no match).
        Resources:
          type: array
          description: 'Array of user objects. Each object uses the same fields as [GET: Look up an existing dashboard user account]({{site.baseurl}}/get_see_user_account_information).'
          items:
            $ref: '#/components/schemas/DashboardUser'
    DashboardUser:
      title: User object
      type: object
      properties:
        id:
          type: string
          description: "The user's resource ID."
        userName:
          type: string
          description: "The user's email address."
        name:
          allOf:
            - $ref: '#/components/schemas/UserName'
          description: "Contains `givenName` and `familyName`."
        department:
          type: string
          description: "The user's department, if set."
        createdAt:
          type: string
          description: "When the user account was created. Returns `NA` when unset; otherwise formatted as `YYYY Mon DD, H:MM AM/PM`."
        lastSignInAt:
          type: string
          description: "When the user last signed in. Returns `NA` if the user has not signed in; otherwise formatted as `YYYY Mon DD, H:MM AM/PM`."
        permissions:
          allOf:
            - $ref: '#/components/schemas/Permissions'
          description: "Company, workspace, team, and role permissions. See the [permissions object]({{site.baseurl}}/api/objects_filters/scim_api_appendix)."
    TeamPermissions:
      title: Team permissions
      type: object
      properties:
        teamId:
          type: string
        teamName:
          type: string
        teamPermissions:
          type: array
          items:
            type: string
    PermissionSet:
      title: Permission set
      type: object
      properties:
        appGroupPermissionSetName:
          type: string
        appGroupPermissionSetId:
          type: string
        permissions:
          type: array
          items:
            type: string
    WorkspacePermissions:
      title: Workspace permissions
      type: object
      properties:
        appGroupId:
          type: string
        appGroupName:
          type: string
        appGroupPermissions:
          type: array
          items:
            type: string
        team:
          type: array
          items:
            $ref: '#/components/schemas/TeamPermissions'
        appGroupPermissionSets:
          type: array
          items:
            $ref: '#/components/schemas/PermissionSet'
    Role:
      title: Role
      type: object
      properties:
        roleName:
          type: string
        roleId:
          type: string
        appGroup:
          type: array
          items:
            $ref: '#/components/schemas/WorkspacePermissions'
    Permissions:
      title: Permissions
      type: object
      properties:
        companyPermissions:
          type: array
          items:
            type: string
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        appGroup:
          type: array
          items:
            $ref: '#/components/schemas/WorkspacePermissions'
    UserName:
      title: Name
      type: object
      properties:
        givenName:
          type: string
          example: Test
        familyName:
          type: string
          example: User
    ErrorResponse:
      title: Error
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          description: SCIM error message schema.
          example:
            - urn:ietf:params:scim:api:messages:2.0:Error
        status:
          type: integer
          description: The HTTP status code of the error.
          example: 404
        detail:
          type: string
          description: The error message describing why the request failed.
