> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-pb-update-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# getOrCreateUser

> Retrieves the [User](#schema_user) object for given discriminating tags. If the user does not exist, it will be created. If the user already exists, its name, pictureUrl, attributes, and tags will be updated with the provided values.



## OpenAPI

````yaml /runtime-openapi.json post /v1/chat/users/get-or-create
openapi: 3.0.0
info:
  title: Botpress Runtime API
  description: API for Botpress Runtime
  version: 1.112.0
servers:
  - url: https://api.botpress.cloud
security:
  - BearerAuth: []
tags:
  - name: documented
  - name: experimental
paths:
  /v1/chat/users/get-or-create:
    post:
      tags:
        - Endpoints
      description: >-
        Retrieves the [User](#schema_user) object for given discriminating tags.
        If the user does not exist, it will be created. If the user already
        exists, its name, pictureUrl, attributes, and tags will be updated with
        the provided values.
      operationId: getOrCreateUser
      parameters:
        - name: x-bp-authenticated-principal
          in: header
          description: Authenticated principal. Injected by the authentication middleware.
          required: true
          schema:
            type: string
        - name: x-bot-id
          in: header
          description: Bot id
          required: true
          schema:
            type: string
        - name: x-integration-id
          in: header
          description: Integration id
          required: false
          schema:
            type: string
        - name: x-integration-alias
          in: header
          description: Integration alias
          required: false
          schema:
            type: string
        - name: x-real-ip
          in: header
          description: Caller's IP address. Injected by the edge proxy.
          required: false
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/getOrCreateUserBody'
      responses:
        '200':
          $ref: '#/components/responses/getOrCreateUserResponse'
        default:
          $ref: '#/components/responses/getOrCreateUserResponse'
components:
  requestBodies:
    getOrCreateUserBody:
      description: User data
      content:
        application/json:
          schema:
            type: object
            properties:
              tags:
                type: object
                additionalProperties:
                  type: string
                  maxLength: 500
                  nullable: true
                description: Tags for the user. Set to null or empty string to remove.
              integrationName:
                type: string
                maxLength: 200
                description: >-
                  [DEPRECATED] To create a [User](#schema_user) from within a
                  bot, call an action of the integration instead.
                deprecated: true
              name:
                type: string
                maxLength: 200
                description: Name of the user
              pictureUrl:
                type: string
                maxLength: 40000
                description: URI of the user picture
              properties:
                type: object
                additionalProperties:
                  type: string
                  maxLength: 200
                  nullable: true
                description: >-
                  **EXPERIMENTAL** - Optional shared properties. Set individual
                  properties to null or empty string to remove them.
              attributes:
                type: object
                additionalProperties:
                  type: string
                  maxLength: 200
                  nullable: true
                deprecated: true
                description: DEPRECATED - Use properties instead.
              discriminateByTags:
                type: array
                items:
                  type: string
                  maxLength: 500
                description: >-
                  Optional list of tag names to use for strict matching when
                  looking up existing users. If provided, all specified tags
                  must match exactly for a user to be considered a match. For
                  example, with an existing user whose tags are {"foo": "a",
                  "bar": "b", baz: "c"}: Without this parameter, ALL tags must
                  match exactly. With ["bar","baz"], all listed tags must match
                  their values, and other tags are not considered.
            required:
              - tags
            title: getOrCreateUserBody
            additionalProperties: false
  responses:
    getOrCreateUserResponse:
      description: >-
        Returns a [User](#schema_user) object if a valid identifier was
        provided. Returns an [Error](#errors) otherwise
      content:
        application/json:
          schema:
            type: object
            properties:
              user:
                $ref: '#/components/schemas/User'
              meta:
                type: object
                properties:
                  created:
                    type: boolean
                required:
                  - created
                additionalProperties: false
            required:
              - user
              - meta
            title: getOrCreateUserResponse
            additionalProperties: false
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          minLength: 28
          maxLength: 36
          description: Id of the [User](#schema_user)
        createdAt:
          type: string
          format: date-time
          description: Creation date of the [User](#schema_user) in ISO 8601 format
        updatedAt:
          type: string
          format: date-time
          description: Updating date of the [User](#schema_user) in ISO 8601 format
        tags:
          type: object
          additionalProperties:
            type: string
          description: >-
            Set of [Tags](/docs/developers/concepts/tags) that you can attach to
            a [User](#schema_user). The set of
            [Tags](/docs/developers/concepts/tags) available on a
            [User](#schema_user) is restricted by the list of
            [Tags](/docs/developers/concepts/tags) defined previously by the
            [Bot](#schema_bot). Individual keys can be unset by posting an empty
            value to them.
        name:
          type: string
          maxLength: 200
          description: Name of the [User](#schema_user)
        pictureUrl:
          type: string
          maxLength: 40000
          description: Picture URL of the [User](#schema_user)
        properties:
          type: object
          additionalProperties:
            type: string
            maxLength: 200
          description: Optional properties
        attributes:
          type: object
          additionalProperties:
            type: string
            maxLength: 200
          description: Optional attributes
      required:
        - id
        - createdAt
        - updatedAt
        - tags
      description: >-
        The user object represents someone interacting with the bot within a
        specific integration. The same person interacting with a bot in slack
        and messenger will be represented with two different users.
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````