openapi: 3.1.0
info:
  title: Howler API v3 Artists User API
  version: 3.6.1
  description: '*Last updated: 2026-01-20 21:15:49 +0200*

    '
servers:
- url: https://{defaultHost}/api/v3/consumer_portal
  variables:
    defaultHost:
      default: www.howler.co.za
  description: Server for consumer portal endpoints
security:
- bearer_header: []
  bearer_param: []
  api_key: []
  bearer_auth: []
tags:
- name: User
paths:
  /user:
    delete:
      summary: request user account deletion
      operationId: requestUserDeletion
      tags:
      - User
      description: Request deletion of a user account.
      responses:
        '204':
          description: successful
          content:
            application/json:
              schema:
                type: string
                nullable: true
                example: null
    get:
      summary: get user details
      operationId: getConsumerUser
      tags:
      - User
      description: 'Retrieve details of the current user.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/UserDetails'
    put:
      summary: update user details
      operationId: updateConsumerUser
      tags:
      - User
      description: 'Update details of the current user.

        '
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/UserDetails'
        '422':
          description: invalid locale
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      user:
                        type: object
                        properties:
                          language_locale:
                            type: array
                            items:
                              type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  $ref: '#/components/schemas/UserDetails'
              required:
              - user
        required: true
  /events/{event_id}/user/setup:
    parameters:
    - name: event_id
      in: path
      description: Event Id
      required: true
      schema:
        type: string
    get:
      summary: check if user is setup for event
      operationId: updateConsumerUserIsSetup
      tags:
      - User
      description: 'Checks if the current user is setup for a specific event. Will return true if all required details are filled in for the user profile.


        This can be compared to the event''s `user_validation_configuration`.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  event_id:
                    type: integer
                  is_setup?:
                    type: boolean
                required:
                - event_id
                - is_setup?
  /user/resend_confirmation:
    post:
      summary: resend user confirmation email
      operationId: resendUserConfirmation
      tags:
      - User
      description: 'Resend the confirmation email to the user''s primary email address.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  status:
                    type: string
                  message:
                    type: string
  /user/web:
    get:
      summary: input user details on a rendered form
      operationId: editConsumerUserWeb
      tags:
      - User
      description: 'Renders a webpage to allow the user to set their user details.


        Once the user information has successfully been entered, a redirect will be done to a specific URL.

        '
      responses:
        '200':
          description: successful
    put:
      summary: update user details from a rendered form
      operationId: updateConsumerUserWeb
      tags:
      - User
      description: '**Private API**

        This end-point should only ever be called using by the web page rendered using the GET version of this end-point.

        '
      parameters: []
      responses:
        '303':
          description: successful
        '200':
          description: failed
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
              required: []
        required: true
components:
  schemas:
    UserDetails:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: Primary Key
        first_name:
          type: string
          description: First Name
        last_name:
          type: string
          description: Last Name
        primary_email:
          type: string
          readOnly: true
          description: Email address of user or dummy user
        dummy?:
          type: boolean
          readOnly: true
          description: True if the user has not yet signed up for an account.
        auto_cashout:
          type: boolean
          readOnly: true
          description: Auto cashouts are enabled. This setting is updated when bank account details are captured.
        cellphone_number:
          type: string
          description: Cellphone Number
        country:
          type: string
          description: Country of Residence
        city:
          type: string
          description: City of Residence
        id_number:
          type: string
          description: South African ID Number
        gender:
          type:
          - string
          - 'null'
          enum:
          - male
          - female
          - other
          - null
          description: Gender
        date_of_birth:
          type: string
          format: ISO 8601
          description: Date of Birth
        nickname:
          type:
          - string
          - 'null'
          description: Nickname
        billing_address:
          type:
          - string
          - 'null'
          description: Billing Address
        is_rsa_citizen:
          type: boolean
          description: Indicates the user is a South African Citisen. If true they will need to fill in an ID number, otherwise they will need to fill in their passprt country and number.
        passport_number:
          type:
          - string
          - 'null'
          description: Passport Number
        passport_country:
          type:
          - string
          - 'null'
          description: Passport Country
        email_confirmed?:
          type: boolean
          description: Email has been confirmed
        avatar_url:
          type:
          - string
          - 'null'
          description: Avatar URL
        required_fields:
          type: array
          description: Required fields
        allow_email:
          type:
          - boolean
          - 'null'
          description: User allows email communication
        allow_sms:
          type:
          - boolean
          - 'null'
          description: User allows SMS communication
        postal_code:
          type:
          - string
          - 'null'
          description: Postal Code
        street_and_number:
          type:
          - string
          - 'null'
          description: Street and Number
        province:
          type:
          - string
          - 'null'
          description: Province
        country_of_birth:
          type:
          - string
          - 'null'
          description: Country of Birth
        province_of_birth:
          type:
          - string
          - 'null'
          description: Province of Birth
        city_of_birth:
          type:
          - string
          - 'null'
          description: City of Birth
        medical_aid_provider:
          type:
          - string
          - 'null'
          description: Medical Aid Provider
        medical_aid_number:
          type:
          - string
          - 'null'
          description: Medical Aid Number
        emergency_contact_name:
          type:
          - string
          - 'null'
          description: Emergency Contact Name
        emergency_contact_relationship:
          type:
          - string
          - 'null'
          description: Emergency Contact Relationship
        emergency_contact_number:
          type:
          - string
          - 'null'
          description: Emergency Contact Number
        allergies:
          type:
          - string
          - 'null'
          description: Allergies
        medical_conditions:
          type:
          - string
          - 'null'
          description: Medical Conditions
        language_locale:
          type: string
          description: User language preference
        is_language_locale_manually_set:
          type: boolean
          description: Whether the language locale was manually set by the user
      required:
      - id
      - first_name
      - last_name
      - primary_email
      - dummy?
      - allow_email
      - allow_sms
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 authentication for third-party applications
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            public: Public scope
            login: Login scope
            ott: One-time token scope
    bearer_header:
      type: http
      scheme: bearer
      bearerFormat: oauth2
      in: header
    bearer_param:
      type: apiKey
      scheme: bearer
      bearerFormat: oauth2
      name: bearer_token
      in: query
    jwt_header:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from basic authentication login
    jwt_param:
      type: apiKey
      name: bearer_token
      in: query
      description: JWT token as query parameter (alternative to Authorization header)
    basic_auth:
      type: http
      scheme: basic
      description: Basic authentication with email and password
    api_key:
      type: apiKey
      name: x-auth-token
      in: header
      description: API key authentication
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token authentication