Hellou AI Profile API

openapi: 3.2.0
info:
  title: HellouOne Profile API
  version: 1.0.0
  description: 'The HellouOne REST API: everything the dashboard does, available to your

    own systems — CRMs, bots, BI tools and back-office automation.'
  termsOfService: https://hellou.ai/en/legal/terms/
  contact:
    name: HellouOne support
    email: support@hellou.ai
servers:
- url: https://one.hellou.ai
  description: HellouOne cloud
security:
- userApiKey: []
tags:
- name: Profile
paths:
  /auth/sign_in:
    post:
      tags:
      - Profile
      operationId: signIn
      summary: Sign in
      description: 'Signs a user in with `email` and `password`, or with `email` and a single-use `sso_auth_token`

        (the Google sign-in and SSO link flows). Without MFA the answer is `200` and the session credentials

        are in the response headers. A user with MFA on gets `206` and an `mfa_token` instead, and no

        credentials: finish with `POST /auth/mfa/verify`. A password reset or an email confirmation of

        such a user answers `206` the same way. Impersonation sessions skip the second step.


        Wrong credentials, an unconfirmed account and an unknown email all answer the same `401`.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: The user's email.
                password:
                  type: string
                  description: The user's password. Send this or `sso_auth_token`.
                sso_auth_token:
                  type: string
                  description: Single-use token from a Google sign-in or SSO link. Send this or `password`.
      responses:
        '200':
          description: Signed in. Send `access-token`, `client` and `uid` on later requests.
          headers:
            access-token:
              description: Session token.
              schema:
                type: string
            client:
              description: Session client id.
              schema:
                type: string
            uid:
              description: The user's uid.
              schema:
                type: string
            expiry:
              description: When the session ends, in Unix seconds.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/user'
        '206':
          description: The user has MFA on. Complete the sign-in with `POST /auth/mfa/verify`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mfa_required'
        '401':
          description: Invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_error'
        '429':
          description: Too many sign-in attempts. Retry after the `Retry-After` header.
  /auth/mfa/verify:
    post:
      tags:
      - Profile
      operationId: verifyMfaSignIn
      summary: Finish a sign-in with a second-step code
      description: 'Second sign-in step for a user with MFA on. Send the `mfa_token` from the `206` answer plus

        `otp_code` (the 6-digit code of the authenticator app) or `backup_code`. On success the answer is

        the same as a plain sign-in: `200`, the session credentials in the response headers.


        The `mfa_token` is single use: it stops working after a successful verify, after 5 wrong codes,

        after 5 minutes and when the password changes. A wrong code answers `422` and the token can be

        tried again until then. A missing, expired or used token answers `401`.


        Limited to 5 requests per `mfa_token` and 10 per IP address every 5 minutes, and a user who gets

        10 codes wrong in 15 minutes is refused with `429`.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - mfa_token
              properties:
                mfa_token:
                  type: string
                  description: The token from the `206` answer of the first step.
                otp_code:
                  type: string
                  description: The current 6-digit code of the authenticator app. Send this or `backup_code`.
                backup_code:
                  type: string
                  description: One of the user's unused backup codes. Send this or `otp_code`.
      responses:
        '200':
          description: Signed in. Send `access-token`, `client` and `uid` on later requests.
          headers:
            access-token:
              description: Session token.
              schema:
                type: string
            client:
              description: Session client id.
              schema:
                type: string
            uid:
              description: The user's uid.
              schema:
                type: string
            expiry:
              description: When the session ends, in Unix seconds.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/user'
        '401':
          description: The `mfa_token` is missing, expired, used or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_error'
        '422':
          description: The code is wrong. The token stays valid until its failures run out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_error'
        '429':
          description: Too many requests, or too many wrong codes for this user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/auth_error'
  /api/v1/profile:
    get:
      tags:
      - Profile
      operationId: fetchProfile
      summary: Fetch user profile
      description: Get the user profile details
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
        '401':
          description: Unauthorized
  /api/v1/profile/reset_access_token:
    post:
      tags:
      - Profile
      operationId: resetProfileAccessToken
      summary: Reset the API access token
      description: 'Revokes your current `api_access_token` and issues a new one, returned

        in the profile. Every integration using the old token gets `401` from

        then on.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
        '401':
          description: Unauthorized
  /api/v1/profile/mfa:
    get:
      tags:
      - Profile
      operationId: fetchMfaStatus
      summary: Fetch the MFA status
      description: 'Tells whether you have two-step verification (MFA) on, whether a setup is waiting for its first

        code, and how many backup codes are left. It never returns the secret or the backup codes.


        MFA can be managed with a signed-in session only. A request with an `api_access_token` gets `403`.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mfa_status'
        '401':
          description: Unauthorized
        '403':
          description: The request used an API access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    post:
      tags:
      - Profile
      operationId: startMfaEnrolment
      summary: Start the MFA setup
      description: 'Creates a new authenticator secret and returns it with the provisioning URI and a QR code. Nothing

        changes for sign-in until you confirm the first code with `POST /api/v1/profile/mfa/verify`. Calling

        this again before confirming replaces the pending secret. The secret is returned only here.


        Send `current_password` to prove it is you, so a stolen session cannot enrol an authenticator of its own.

        A user who signs in with Google may leave it out for 10 minutes after that same session signed in

        with Google. Without a valid proof the answer is `422` with `error: reauth_required` and `reauth` set

        to `password` (send the password) or `google` (sign in with Google again). Wrong passwords count

        towards 10 per 15 minutes for the user, after which the answer is `429`. Also limited to 10 requests

        per IP address every 5 minutes.


        Answers `422` when MFA is already on: turn it off first.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                current_password:
                  type: string
                  description: Your current password. Optional only within 10 minutes of a Google sign-in of this session.
      responses:
        '200':
          description: The setup was started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mfa_enrolment'
        '401':
          description: Unauthorized
        '403':
          description: The request used an API access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: MFA is already on, or a fresh proof of identity is needed (`error` is `reauth_required`).
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/mfa_reauth_required'
                - $ref: '#/components/schemas/error_message'
        '429':
          description: Too many requests, or too many wrong tries for this user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    delete:
      tags:
      - Profile
      operationId: disableMfa
      summary: Turn MFA off
      description: 'Turns MFA off and deletes the secret and the backup codes. When MFA is on, send `current_password`

        or a current authenticator code in `otp_code`, so a stolen session cannot switch it off. A backup

        code is not accepted here. An unconfirmed setup is cancelled without either. The user gets an email.


        Wrong passwords and codes answer `422`, limited to 10 per 15 minutes for the user, after which

        the answer is `429`. Also limited to 10 requests per IP address every 5 minutes.


        While any account you belong to requires MFA, an active MFA cannot be turned off: the answer is `422`

        with `error: mfa_enforced`. An administrator of that account turns the requirement off first.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                current_password:
                  type: string
                  description: Your current password. Send this or `otp_code`.
                otp_code:
                  type: string
                  description: The current 6-digit code of the authenticator app. Send this or `current_password`.
      responses:
        '200':
          description: MFA is off.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mfa_status'
        '401':
          description: Unauthorized
        '403':
          description: The request used an API access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: The password or code is wrong, or an account you belong to requires MFA (`error` is `mfa_enforced`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '429':
          description: Too many requests, or too many wrong tries for this user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
  /api/v1/profile/mfa/verify:
    post:
      tags:
      - Profile
      operationId: confirmMfaEnrolment
      summary: Confirm the MFA setup
      description: 'Finishes the setup started with `POST /api/v1/profile/mfa`: send the current 6-digit code of the

        authenticator app in `otp_code`. On success MFA is on and the answer carries the first set of backup

        codes. They are shown only in this response. The user gets an email.


        The setup must be confirmed from the session that started it, within 15 minutes. Another session, or a

        setup older than that, gets `422`: start the setup again.


        Answers `422` when the code is wrong or no setup is pending. Wrong codes count toward 10 per 15 minutes

        for the user, after which the answer is `429`. Also limited to 10 requests per IP address every 5 minutes.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - otp_code
              properties:
                otp_code:
                  type: string
                  description: The current 6-digit code of the authenticator app.
      responses:
        '200':
          description: MFA is on.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mfa_backup_codes'
        '401':
          description: Unauthorized
        '403':
          description: The request used an API access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: The code is wrong, or there is no setup to confirm from this session (none started, started elsewhere, or older than 15 minutes).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '429':
          description: Too many requests, or too many wrong tries for this user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
  /api/v1/profile/mfa/backup_codes:
    post:
      tags:
      - Profile
      operationId: regenerateMfaBackupCodes
      summary: Regenerate the MFA backup codes
      description: 'Replaces all backup codes with a new set; the old ones stop working. Send `current_password` or a

        current authenticator code in `otp_code`. A backup code is not accepted here. The codes are shown

        only in this response.


        Answers `422` when MFA is off or the password or code is wrong. Wrong tries count toward 10 per

        15 minutes for the user, after which the answer is `429`. Also limited to 10 requests per IP address

        every 5 minutes.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                current_password:
                  type: string
                  description: Your current password. Send this or `otp_code`.
                otp_code:
                  type: string
                  description: The current 6-digit code of the authenticator app. Send this or `current_password`.
      responses:
        '200':
          description: The new backup codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mfa_backup_codes'
        '401':
          description: Unauthorized
        '403':
          description: The request used an API access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: MFA is off, or the password or code is wrong.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '429':
          description: Too many requests, or too many wrong tries for this user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  schemas:
    mfa_required:
      type: object
      description: The first sign-in step succeeded but the user has MFA on. No session credentials were issued; send `mfa_token` plus a code to `POST /auth/mfa/verify`.
      properties:
        mfa_required:
          type: boolean
          description: Always `true`.
        mfa_token:
          type: string
          description: Single-use token for the second step. Valid for 5 minutes, and for 5 wrong codes.
      required:
      - mfa_required
      - mfa_token
    mfa_reauth_required:
      type: object
      description: Starting the MFA setup needs a fresh proof of identity and the request did not carry one.
      properties:
        error:
          type: string
          enum:
          - reauth_required
          description: Always `reauth_required`.
        reauth:
          type: string
          enum:
          - password
          - google
          description: Which proof to send. `password` asks for `current_password`; `google` asks the user to sign in with Google again.
      required:
      - error
      - reauth
    account:
      type: object
      properties:
        id:
          type: number
          description: Account ID
        name:
          type: string
          description: Name of the account
        role:
          type: string
          enum:
          - administrator
          - agent
          description: The user role in the account
    auth_error:
      type: object
      description: A sign-in step that did not succeed.
      properties:
        success:
          type: boolean
          description: Always `false`.
        errors:
          type: array
          description: Human-readable reasons, in the language of the request.
          items:
            type: string
      required:
      - errors
    error_message:
      type: object
      description: An error with a human-readable message.
      properties:
        error:
          type: string
          description: What went wrong.
        reason:
          type: string
          description: Machine-readable cause, when there is one (for example `feature_disabled`).
      required:
      - error
    mfa_enrolment:
      type: object
      description: A started MFA setup. It is shown once and only in this response; it does nothing until the first code is confirmed.
      properties:
        secret:
          type: string
          description: The authenticator secret, for apps that take it typed in.
        provisioning_uri:
          type: string
          description: The `otpauth://` URI that authenticator apps read.
        qr_code_svg:
          type: string
          description: The provisioning URI as an SVG image of a QR code, ready to show.
      required:
      - secret
      - provisioning_uri
      - qr_code_svg
    mfa_backup_codes:
      type: object
      description: A fresh set of backup codes. It is shown once and only in this response.
      properties:
        backup_codes:
          type: array
          description: Single-use codes, each one usable instead of an authenticator code when signing in.
          items:
            type: string
      required:
      - backup_codes
    user:
      type: object
      properties:
        id:
          type: number
        uid:
          type: string
        name:
          type: string
        available_name:
          type: string
        display_name:
          type: string
        email:
          type: string
        account_id:
          type: number
        role:
          type: string
          enum:
          - agent
          - administrator
        confirmed:
          type: boolean
        custom_attributes:
          type: object
          description: Available for users who are created through platform APIs and has custom attributes associated.
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/account'
    mfa_status:
      type: object
      description: Whether the signed-in user has two-step verification (MFA) on. Never carries the secret or the backup codes.
      properties:
        enabled:
          type: boolean
          description: True once the first code was confirmed. Signing in asks for a code from then on.
        setup_pending:
          type: boolean
          description: True when a setup was started and not confirmed yet.
        backup_codes_remaining:
          type: integer
          description: How many backup codes are still unused.
      required:
      - enabled
      - setup_pending
      - backup_codes_remaining
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A user''s access token, from **Profile settings → Access token** in the dashboard.

        Requests act with that user''s role: administrators reach everything in their

        account, agents only what their role and visibility settings allow.

        '
    agentBotApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'An agent bot''s access token, shown to administrators on the bot''s settings page.

        Bot tokens reach a limited set of conversation and message endpoints.

        '
    platformAppApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A platform app token, issued by the installation operator. Used to provision

        accounts, users, account memberships and agent bots.

        '
    connectorInvokeToken:
      type: http
      scheme: bearer
      description: 'A connector''s invoke token (`hci_…`), sent as `Authorization: Bearer <token>`.

        Each connector install has its own; it is rotated whenever the connector is

        reconnected or disconnected, so a stale copy stops working.

        '
x-tagGroups:
- name: Guides
  tags:
  - Introduction
  - Authentication
  - Errors
  - Pagination
  - Rate limits
  - Webhook events
- name: Webhook payloads
  tags:
  - Event payloads
- name: Platform
  tags:
  - Accounts
  - Account Users
  - AgentBots
  - Users
- name: Application
  tags:
  - Account AgentBots
  - Agents
  - Automation Rule
  - Campaigns
  - Canned Responses
  - Contacts
  - Contact Labels
  - Conversation Assignment
  - Conversation Labels
  - Conversations
  - Custom Attributes
  - Custom Filters
  - Help Center
  - Inboxes
  - Integrations
  - Macros
  - Messages
  - Profile
  - Reports
  - Security Settings
  - Teams
  - Webhooks
- name: Business tools
  tags:
  - AI Classifications
  - Assignment Settings
  - Calls
  - AI Phone Lines
  - Connectors
  - ElevenLabs Integration
  - Facebook Marketing
  - HellouAI Integration
  - Knowledge Base
  - Marketing Consent
  - Plan Upgrades
  - Voice Campaigns
  - WhatsApp Campaigns
  - WhatsApp Flows
  - WhatsApp Templates
- name: Client
  tags:
  - Inbox API
  - Contacts API
  - Conversations API
  - Messages API
- name: Others
  tags:
  - CSAT Survey Page