openapi.yaml

openapi: 3.0.0
info:
  title: Hyperplane API Gateway
  description: ''
  version: '1.0'
  contact: {}
  x-konfig-ignore:
    potential-incorrect-type: true
servers:
  - url: https://api.sandbox-65ebc.chico.ai
  - url: http://api.sandbox-65ebc.chico.ai
tags:
  - name: AutoML Service
  - name: Personas
  - name: Enriched Transactions
  - name: Users
  - name: Auth
  - name: Client
  - name: Health
  - name: Statistics
  - name: Transactions
paths:
  /v1/auth/token:
    post:
      tags:
        - Auth
      summary: Get Token
      operationId: Auth_clientAuthenticate
      description: Authenticate a client and get an access token
      requestBody:
        description: Request body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.AuthRequest'
        required: true
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.AuthResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '401':
          description: Invalid client credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '404':
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
  /v1/automl/lookalike:
    post:
      tags:
        - AutoML Service
      summary: Create an AutoML lookalike request
      operationId: AutoMlService_createLookalikeRequest
      security:
        - PASETO: []
      parameters:
        - description: Model Version
          name: model_version
          in: query
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
      requestBody:
        description: Lookalike Request Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.AutoMLLookalikeCreateRequest'
        required: true
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.AutoMLLookalikeCreateResponse'
  /v1/automl/runs:
    get:
      tags:
        - AutoML Service
      summary: Get all AutoML runs in a specified module
      operationId: AutoMlService_getAllAutomlRuns
      security:
        - PASETO: []
      parameters:
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.AutoMLRunsGetResponse'
  /v1/automl/runs/{run_id}:
    get:
      tags:
        - AutoML Service
      summary: Get run summary for a specified AutoML run
      operationId: AutoMlService_getRunSummary
      security:
        - PASETO: []
      parameters:
        - description: Run ID
          name: run_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.AutoMLRunGetIdResponse'
  /v1/automl/runs/{run_id}/generate_batch_scores:
    post:
      tags:
        - AutoML Service
      summary: >-
        Rerun the inference and store the updated scores in the output
        connection of the module
      operationId: AutoMlService_rerunInferenceAndUpdateScores
      security:
        - PASETO: []
      parameters:
        - description: Run ID
          name: run_id
          in: path
          required: true
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.AutoMLBatchScoresCreateResponse'
  /v1/automl/runs/{run_id}/rescore:
    post:
      tags:
        - AutoML Service
      summary: Rerun inference on latest user snapshots to update scores
      operationId: AutoMlService_rerunInference
      security:
        - PASETO: []
      parameters:
        - description: Run ID
          name: run_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.AutoMLLookalikeCreateResponse'
  /v1/automl/runs/{run_id}/status:
    get:
      tags:
        - AutoML Service
      summary: Get status of a specified AutoML run
      operationId: AutoMlService_getRunStatus
      security:
        - PASETO: []
      parameters:
        - description: Run ID
          name: run_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoMlServiceGetRunStatusResponse'
  /v1/automl/runs/{run_id}/status_batch_scores:
    get:
      tags:
        - AutoML Service
      summary: Get status of the batch scores request for an AutoML run
      operationId: AutoMlService_getStatusBatchScores
      security:
        - PASETO: []
      parameters:
        - description: Run ID
          name: run_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoMlServiceGetStatusBatchScoresResponse'
  /v1/automl/runs/{run_id}/users:
    post:
      tags:
        - AutoML Service
      summary: Get top users from a specified AutoML run excluding training users
      operationId: AutoMlService_excludeTrainingUsers
      security:
        - PASETO: []
      parameters:
        - description: Run ID
          name: run_id
          in: path
          required: true
          schema:
            type: string
        - description: Page number, starting at 1
          name: page_number
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - description: >-
            Number of users scored in run per page. Between 1 and 10000.
            Defaults to 500
          name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 500
      requestBody:
        description: Request Options
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.AutoMLRunUsersGetRequest'
        required: true
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.AutoMLRunUsersGetResponse'
  /v1/automl/users:
    get:
      tags:
        - AutoML Service
      summary: Get available users for training an AutoML run in a specified module
      operationId: AutoMlService_getAvailableUsers
      security:
        - PASETO: []
      parameters:
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
        - description: Page number, starting at 1
          name: page_number
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - description: >-
            Number of users scored in run per page. Between 1 and 10000.
            Defaults to 500
          name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 500
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.AutoMLUsersGetResponse'
  /v1/batch/user/personas:
    post:
      tags:
        - Personas
        - Users
      summary: Get all the facet attributes for a list of users.
      operationId: Personas_getFacetAttributes
      security:
        - PASETO: []
      description: Returns all personas associated with a user.
      parameters:
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
        - description: Reference month for persona scores in `YYYY-MM` format.
          name: month
          in: query
          schema:
            type: string
        - description: Minimum user persona score threshold to be included in the response.
          name: persona_score_threshold
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 1
      requestBody:
        description: List of user IDs
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.BatchUserPersonasRequest'
        required: true
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonasGetFacetAttributesResponse'
        '400':
          description: >-
            Will return a 400 (Bad Request) error if the provided module ID or
            month is invalid, or number of requested users exceed the maximum
            allowed (1000).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '404':
          description: >-
            Will return a 404 (Not Found) error if any of the users with
            provided `user_id` does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
  /v1/client/{access_key_id}:
    get:
      tags:
        - Client
      summary: Get Client
      operationId: Client_getByAccessKeyId
      security:
        - PASETO: []
      description: Fetch a client by its access key ID
      parameters:
        - description: Access Key ID
          name: access_key_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ClientResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '404':
          description: Client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
  /v1/health:
    get:
      tags:
        - Health
      summary: Health check
      operationId: Health_checkStatus
      description: Check if the server is alive
      responses:
        '200':
          description: I'm alive!
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckStatusResponse'
  /v1/module/transaction-enrichment/statistics:
    get:
      tags:
        - Enriched Transactions
      summary: Get statistics for transaction enrichment module.
      operationId: EnrichedTransactions_getStatistics
      security:
        - PASETO: []
      description: >-
        Retrieves statistics about a transaction enrichment module.

        The payload includes the number of distinct users and number of
        transactions.
      parameters:
        - description: Module ID
          name: module-id
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/models.TransactionEnrichmentStatisticsResponse
  /v1/module/transaction-enrichment/users:
    get:
      tags:
        - Enriched Transactions
      summary: List the users in a transaction enrichment module.
      operationId: EnrichedTransactions_listUserTransactions
      security:
        - PASETO: []
      description: >-
        List the users in a transaction enrichment module.

        Optionally, you can pass a `user_id_prefix` as a query parameter to
        filter users by a user ID prefix.

        Every user will contain their user ID, as well as their first and last
        transaction dates.
      parameters:
        - description: Module ID
          name: module-id
          in: header
          required: true
          schema:
            type: string
        - description: >-
            Prefix used to filter user_id results (e.g.: prefix = '2'-> users =
            ['23456', '24562']).
          name: user_id_prefix
          in: query
          schema:
            type: string
        - description: Page number, starting at 1
          name: page_number
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - description: Number of elements per page. Defaults to 100
          name: page_size
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.TransactionEnrichmentUsersResponse'
  /v1/persona:
    get:
      tags:
        - Personas
      summary: List existing personas.
      operationId: Personas_listExisting
      security:
        - PASETO: []
      description: >-
        Lists all existing personas.


        Personas are sorted by creation date, with the most recently created
        personas appearing first.

        By default, all personas are returned. However, you can specify the type
        of personas you want

        by passing specific facet types as a query parameter. (e.g. `GET
        /persona?facet_types=interest,demographic`)

        Optionally, you can paginate the results by specifying the `page_number`
        and `page_size` query parameters.

        If either `page_number` and `page_size` are not specified, all personas
        will be returned.
      parameters:
        - description: >-
            Comma-separated facet types to select. By default, all personas are
            returned. Valid facet types are: interest, demographic,
            pre_defined_persona, custom.
          name: facet_types
          in: query
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
        - description: Page number, starting at 1
          name: page_number
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - description: >-
            Number of personas per page, between 1 and 10000. Will return all
            personas if not specified.
          name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
      responses:
        '200':
          description: A list of personas available in the database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ListPersonasResponse'
        '400':
          description: >-
            Will return a 400 (Bad Request) error if the module-id is not
            provided when required or the month is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '404':
          description: >-
            Will return a 404 (Not Found) error if the provided facet type is
            invalid or if a specific persona wasn't found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
    post:
      tags:
        - Personas
      summary: Create a persona definition.
      operationId: Personas_createDefinition
      security:
        - PASETO: []
      description: >-
        Creates a persona definition from a list of facet weights.


        Personas enable you to define a weighted combination of interests,
        demographics, and financial behaviors

        to create highly targeted audiences for specialized use cases.

        They are defined using a list of facet weights, each containing a facet
        name and a weight.

        To create a persona, you must provide at least one facet weight. Each
        facet weight must contain a valid facet name

        and must be registered in the field with corresponding facet type. For
        example, if you want to create a persona with

        a facet weight for the "Travel" interest facet, you must provide a facet
        weight with the name "Travel" with the facet

        type "interest", the facet weight must be defined in the
        `interest_facets` field.
      parameters:
        - description: Model Version
          name: model_version
          in: query
          schema:
            type: string
            default: '"latest"'
      requestBody:
        description: Persona Request Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.PersonaCreateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.PersonaCreateResponse'
        '400':
          description: >-
            Will return a 400 (Bad Request) error if no facets are provided, one
            or more of the facet names does not exist, or is a custom facet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '409':
          description: >-
            Will return a 409 (Conflict) error if a persona with the same name
            already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
  /v1/persona/{persona_id}:
    get:
      tags:
        - Personas
      summary: Fetch information and score statistics about a persona definition.
      operationId: Personas_getPersonaStatistics
      security:
        - PASETO: []
      description: >-
        Returns statistics and information about a persona definition.


        The response includes the original persona definition, its creation
        date, as well as

        statistics about the persona's score distribution (e.g. number of users,
        average score,

        score percentiles, etc.). You can also specify the minimum persona score
        threshold

        that a user must meet to be included in the response.


        You must provide a valid persona ID. Otherwise, a 404 (Not Found) error
        will be returned.
      parameters:
        - description: Persona ID
          name: persona_id
          in: path
          required: true
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
        - description: >-
            Reference month for persona scores in `YYYY-MM` format. Defaults to
            current month.
          name: month
          in: query
          schema:
            type: string
        - description: >-
            Minimum user persona score threshold to count a user as belonging to
            a persona in the response.
          name: persona_score_threshold
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 1
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.PersonaDetailsResponse'
        '400':
          description: >-
            Will return a 400 (Bad Request) error if the provided module ID or
            month is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '404':
          description: >-
            Will return a 404 (Not Found) error if the persona with provided
            `persona_id` does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
    delete:
      tags:
        - Personas
      summary: Delete a persona definition.
      operationId: Personas_deleteCustomPersona
      security:
        - PASETO: []
      description: >-
        Deletes a custom persona for a provided `persona_id`.


        Personas with facet type other than `custom` cannot be deleted.
        Attempting to delete

        a persona with facet type other than `custom` will result in a 403
        Forbidden error.
      parameters:
        - description: Persona ID
          name: persona_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonasDeleteCustomPersonaResponse'
        '403':
          description: >-
            Will return a 403 (Forbidden) error if the persona ID is a
            pre-defined persona.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '404':
          description: >-
            Will return a 404 (Not Found) error if the persona ID does not
            exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
  /v1/persona/{persona_id}/percentile_score:
    get:
      tags:
        - Personas
      summary: Fetch score on a given percentile for a persona id.
      operationId: Personas_getPercentileScore
      security:
        - PASETO: []
      description: Returns the score associated with a given percentile for a persona id.
      parameters:
        - description: Persona ID
          name: persona_id
          in: path
          required: true
          schema:
            type: string
        - description: 'Target percentile. Defaults to 50th percentile (i.e.: the median)'
          name: percentile
          in: query
          required: true
          schema:
            type: number
            minimum: 0
            maximum: 100
            default: 50
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
        - description: >-
            Reference month for persona scores in `YYYY-MM` format. Defaults to
            current month.
          name: month
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.PercentileScore'
        '400':
          description: >-
            Will return a 400 (Bad Request) error if the provided module ID or
            month is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '404':
          description: >-
            Will return a 404 (Not Found) error if the persona with provided
            `persona_id` does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
  /v1/persona/{persona_id}/users:
    post:
      tags:
        - Personas
      summary: Get ranked list of users who match a persona definition.
      operationId: Personas_getRankedUsers
      security:
        - PASETO: []
      description: >-
        Returns a ranked list of users who match a persona definition.


        Users are sorted by their persona score, with the highest scoring users
        appearing first. Results are paginated

        by default, with 500 users per page. You can specify the page number and
        page size by passing the `page_number`

        and `page_size` query parameters. (e.g. `GET
        /persona/{persona_id}/users?page_number=2&page_size=100`)


        You can also specify the minimum persona score threshold that a user
        must meet to be included in the response.

        If not specified, will default to the hyperplane suggested threshold for
        the given persona_id.


        You can also use a blocklist to exclude specific users from the
        response.
      parameters:
        - description: Persona ID
          name: persona_id
          in: path
          required: true
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
        - description: Page number, starting at 1
          name: page_number
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - description: >-
            Number of users scored in run per page, between 1 and 10000.
            Defaults to 500.
          name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 500
        - description: >-
            Reference month for persona scores in `YYYY-MM` format. Defaults to
            current month.
          name: month
          in: query
          schema:
            type: string
        - description: >-
            Minimum user persona score threshold for user to be included in the
            response.
          name: persona_score_threshold
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 1
      requestBody:
        description: Optional user filters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.PostPersonaUsersRequest'
        required: true
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.PersonaUsersResponse'
        '400':
          description: >-
            Will return a 400 (Bad Request) error if the provided module ID or
            month is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '404':
          description: >-
            Will return a 404 (Not Found) error if the persona with provided
            `persona_id` does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
  /v1/statistics/latest_month:
    get:
      tags:
        - Statistics
      summary: Get the latest month with valid data.
      operationId: Statistics_getLatestMonthData
      security:
        - PASETO: []
      description: Returns the latest month with valid data.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatisticsGetLatestMonthDataResponse'
  /v1/user/{user_id}/cashflow/categories:
    get:
      tags:
        - Enriched Transactions
      summary: Get a user's cashflow aggregated per category.
      operationId: EnrichedTransactions_getUserCashflowCategories
      security:
        - PASETO: []
      description: >-
        Detailed percentages of inflow and outflow for each category.

        Lists all the top level categories and the discrimination under each top
        level category
      parameters:
        - description: User ID
          name: user_id
          in: path
          required: true
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          required: true
          schema:
            type: string
        - description: >-
            Minimum transaction date to be included (e.g. '2020-09-18
            10:00:00').
          name: start_date
          in: query
          schema:
            type: string
        - description: >-
            Maximum transaction date to be included (e.g. '2020-09-18
            10:00:00').
          name: end_date
          in: query
          schema:
            type: string
        - description: >-
            Specifies if we must include only an specific account type. Can be
            'CREDIT_CARD', 'DEBIT_CARD', 'SAVINGS', 'CHECKING', 'INVESTMENT',
            'PENSION', or 'LOAN'.
          name: account_type
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.UserCashflowPerCategoryResponse'
  /v1/user/{user_id}/cashflow/history:
    get:
      tags:
        - Enriched Transactions
      summary: Get the cashflow history for a given user.
      operationId: EnrichedTransactions_getUserCashflowHistory
      security:
        - PASETO: []
      description: >-
        Creates a cashflow timeline for a given user, aggregating all
        transactions in a given window.

        The period windows can be of 1 hour, day, week, month or year.
      parameters:
        - description: User ID
          name: user_id
          in: path
          required: true
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          required: true
          schema:
            type: string
        - description: >-
            Minimum transaction date to be included (e.g. '2020-09-18
            10:00:00').
          name: start_date
          in: query
          schema:
            type: string
        - description: >-
            Maximum transaction date to be included (e.g. '2020-09-18
            10:00:00').
          name: end_date
          in: query
          schema:
            type: string
        - description: >-
            How to aggregate the cashflows in periods. Can be 'HOUR', 'DAY',
            'WEEK', 'MONTH', or 'YEAR'.
          name: aggregation
          in: query
          schema:
            type: string
        - description: >-
            Specifies if we must include only an specific account type. Can be
            'CREDIT_CARD', 'DEBIT_CARD', 'SAVINGS', 'CHECKING', 'INVESTMENT',
            'PENSION', or 'LOAN'.
          name: account_type
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.UserCashflowHistoryResponse'
  /v1/user/{user_id}/cashflow/statistics:
    get:
      tags:
        - Enriched Transactions
      summary: Get the cashflow statistics for a given user.
      operationId: EnrichedTransactions_getUserCashflowStatistics
      security:
        - PASETO: []
      description: >-
        Get the cashflow statistics for a given user per account type. That
        includes inflow, outflow, and net cashflow for each account type.
      parameters:
        - description: User ID
          name: user_id
          in: path
          required: true
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          required: true
          schema:
            type: string
        - description: >-
            Minimum transaction date to be included (e.g. '2020-09-18
            10:00:00').
          name: start_date
          in: query
          schema:
            type: string
        - description: >-
            Maximum transaction date to be included (e.g. '2020-09-18
            10:00:00').
          name: end_date
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/EnrichedTransactionsGetUserCashflowStatisticsResponse
  /v1/user/{user_id}/transactions:
    get:
      tags:
        - Enriched Transactions
      summary: Get the transaction history for a given user.
      operationId: EnrichedTransactions_getUserHistory
      security:
        - PASETO: []
      description: Returns the enriched transaction history of a user
      parameters:
        - description: User ID
          name: user_id
          in: path
          required: true
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          required: true
          schema:
            type: string
        - description: Page number, starting at 1
          name: page_number
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - description: Number of elements per page
          name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            default: 100
        - description: >-
            Minimum transaction date to be included (e.g. '2020-09-18
            10:00:00').
          name: start_date
          in: query
          schema:
            type: string
        - description: >-
            Maximum transaction date to be included (e.g. '2020-09-18
            10:00:00').
          name: end_date
          in: query
          schema:
            type: string
        - description: >-
            The flow type from transactions to be returned, must be either
            'inflow', or 'outflow'. Defaults to returning both.
          name: flow_type
          in: query
          schema:
            type: string
        - description: The minimum amount from transactions to be returned.
          name: min_amount
          in: query
          schema:
            type: number
        - description: The maximum amount from transactions to be returned.
          name: max_amount
          in: query
          schema:
            type: number
        - description: Specifies if we must include only an specific account type.
          name: account_type
          in: query
          schema:
            type: string
        - description: >-
            List of categories to filter. Accept only category codes present on
            our taxonomy.
          name: categories
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - description: Search for a specific string in the transaction description.
          name: search_name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.UserTransactionsResponse'
  /v1/user/{user_id}/transactions/statistics:
    get:
      tags:
        - Enriched Transactions
      summary: Get the transaction statistics for a given user.
      operationId: EnrichedTransactions_getUserStatistics
      security:
        - PASETO: []
      description: Get the number of transactions, average transaction value and median.
      parameters:
        - description: User ID
          name: user_id
          in: path
          required: true
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          required: true
          schema:
            type: string
        - description: "Minimum\ttransaction\tdate\tto\tbe\tincluded\t(e.g. '2020-09-18 10:00:00')."
          name: start_date
          in: query
          schema:
            type: string
        - description: >-
            Maximum transaction date to be included (e.g. '2020-09-18
            10:00:00').
          name: end_date
          in: query
          schema:
            type: string
        - description: >-
            The flow type from transactions to be returned, must be either
            'inflow', or 'outflow'. Defaults to returning both.
          name: flow_type
          in: query
          schema:
            type: string
        - description: The minimum amount from transactions to be returned.
          name: min_amount
          in: query
          schema:
            type: number
        - description: The maximum amount from transactions to be returned.
          name: max_amount
          in: query
          schema:
            type: number
        - description: Specifies if we must include only an specific account type.
          name: account_type
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.UserTransactionsStatisticsResponse'
  /v1/users/{user_id}/personas:
    get:
      tags:
        - Personas
        - Users
      summary: List personas associated with a user.
      operationId: Personas_listUserPersonas
      security:
        - PASETO: []
      description: >-
        Returns a list of personas and their scores for a given user.

        Personas are sorted by their persona score, in descending order.


        You can also specify the minimum persona score threshold that a user
        must meet to be included in the response.

        Defaults to hyperplane's suggested threshold to determine if the user
        belongs to the persona.
      parameters:
        - description: User ID
          name: user_id
          in: path
          required: true
          schema:
            type: string
        - description: Module ID
          name: module-id
          in: header
          schema:
            type: string
        - description: Reference month for persona scores in `YYYY-MM` format.
          name: month
          in: query
          schema:
            type: string
        - description: Minimum user persona score threshold to be included in the response.
          name: persona_score_threshold
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 1
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.UserPersonasResponse'
        '400':
          description: >-
            Will return a 400 (Bad Request) error if the provided module ID or
            month is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
        '404':
          description: >-
            Will return a 404 (Not Found) error if the user with provided
            `user_id` does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.ErrResponse'
  /v1alpha1/transaction/categorize:
    post:
      tags:
        - Transactions
      summary: Categorize a list of transactions
      operationId: Transactions_categorizeList
      security:
        - PASETO: []
      description: Categorizes a list of transactions.
      requestBody:
        description: Object containing transactions to be categorized
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.CategorizeTransactionsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.CategorizeTransactionsResponse'
components:
  securitySchemes:
    PASETO:
      description: >-
        Authorization token using the PASETO scheme. Enter the token with the
        "Bearer" prefix, e.g. "Bearer v2.local.V0bmLbcYzFAs4w0VL...".
      type: apiKey
      name: Authorization
      in: header
  schemas:
    api.ErrResponse:
      type: object
      properties:
        error:
          type: string
    models.AccountCashflowOverview:
      description: Cashflow details for a given account of a given user
      type: object
      required:
        - account_type
        - inflow_amount
        - net_cashflow_amount
        - outflow_amount
      properties:
        account_type:
          description: Account type
          type: string
        inflow_amount:
          description: Inflow amount on the given window
          type: number
        net_cashflow_amount:
          description: Net cashflow amount on the given window
          type: number
        outflow_amount:
          description: Outflow amount on the given window
          type: number
    models.AuthRequest:
      type: object
      required:
        - client_id
        - client_secret
      properties:
        client_id:
          type: string
          example: 4681f83e-a4e9-11ee-a506-0242ac120002
        client_secret:
          type: string
          example: W5qNTpWIT81r5qE3wHrtwXBujKdmGAvx
    models.AuthResponse:
      type: object
      properties:
        api_key:
          type: string
          example: >-
            v2.local.V0bmLbcYzFAs4w0VLqdV-XBssuwRPIflBf94lhrUHu3Lcg18Qiwb4fPgqIc9pLqvhDYPQhTDho5sBCWV_ZwwJ4sKYEc0g5GKEn9BUA8d-KnIbHnLyYKuqMDZflzQSCUdhwnFAcDqAlIqqpENdDVf01IL4wyhyC2F3CLqLVnwWCCFLonLjwpi7eNztZJ4REYPellWBDq3jL-2td4fQmcUvhGXz0T7GBlg9jGtOrs47sbUWS_QHgd1esEjgYm823OdTAk5yjuWD7CKF8P7bqg66A.bnVsbA
    models.AutoMLBatchScoresCreateResponse:
      type: object
      required:
        - path
      properties:
        path:
          description: Path where parquet file with the batch scores will be written
          type: string
    models.AutoMLLookalikeCreateRequest:
      type: object
      required:
        - engagement_type
        - positive_label_users
      properties:
        engagement_type:
          description: >-
            Intended use case of this product, between MULTI_ENGAGE and
            SINGLE_ENGAGE
          type: string
        negative_label_users:
          description: >-
            List of negative users in lookalike model. Model will be trained to
            identify users dissimilar to these users. If None, negative users
            will be generated from data. List length must be either 0 or greater
            than 10.
          type: array
          items:
            $ref: '#/components/schemas/models.LookalikeLabel'
        positive_label_users:
          description: >-
            List of positive users in lookalike model. Model will be trained to
            identify users similar to these users. This list must contain at
            least ten elements.
          type: array
          items:
            $ref: '#/components/schemas/models.LookalikeLabel'
        run_description:
          description: Custom run description to attach to run
          type: string
    models.AutoMLLookalikeCreateResponse:
      type: object
      required:
        - input_label_summary
        - run_id
      properties:
        input_label_summary:
          $ref: '#/components/schemas/models.InputLabelSummary'
        run_description:
          description: Description of the run
          type: string
        run_id:
          description: RunID is the unique identifier for the AutoML run
          type: string
      x-konfig-properties:
        input_label_summary:
          description: >-
            Analysis of input labels detailing amounts of labels given, amounts
            of labels detected, monthly breakdowns of positive rates and counts,
            and a breakdown of weights by label value.
    models.AutoMLRunGetIdResponse:
      type: object
      required:
        - run_description
        - run_id
        - status
        - timestamp
      properties:
        engagement_type:
          description: Engagement type of this product run
          type: string
        input_label_summary:
          $ref: '#/components/schemas/models.InputLabelSummary'
        number_of_inference_users:
          description: NumberOfInferenceUsers is the number of users in model inference
          type: integer
        number_of_train_users:
          description: NumberOfTrainUsers is the number of users in model training
          type: integer
        run_description:
          description: RunDescription is the description of the AutoML training run
          type: string
        run_id:
          description: RunID is the unique identifier for the AutoML run
          type: string
        run_metrics:
          $ref: '#/components/schemas/models.AutoMLRunMetrics'
        status:
          description: RunStatus is the status of the AutoML training run
          type: string
        timestamp:
          description: Timestamp is the time when the training run began
          type: string
      x-konfig-properties:
        input_label_summary:
          description: >-
            Analysis of input labels detailing amounts of labels given, amounts
            of labels detected, monthly breakdowns of positive rates and counts,
            and a breakdown of weights by label value.
        run_metrics:
          description: RunMetrics is the metrics of the AutoML training run
    models.AutoMLRunMetrics:
      type: object
      properties:
        cumulative_positive_rate:
          description: >-
            Cumulative positive rates at various thresholds, including ascending
            (lower to higher thresholds) and descending (higher to lower
            thresholds). It indicates how the proportion of positive instances
            within the total instances changes as the classification threshold
            is adjusted.
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: number
        label_positive_rate:
          description: The percentage of users with positive label in the test set.
          type: number
        positive_rate_by_decile:
          description: >-
            The percentage of positive examples (examples with a positive label)
            in each of the ten equally-sized groups (deciles) of the test data
            when this data is sorted based on the model's predicted scores.
          type: object
          additionalProperties:
            type: number
        test_auc:
          description: AUC of the test set
          type: number
        test_ks:
          description: KS of the test set
          type: number
        train_auc:
          description: AUC of the training set
          type: number
        train_ks:
          description: KS of the training set
          type: number
    models.AutoMLRunSummary:
      type: object
      required:
        - run_description
        - run_id
        - status
        - timestamp
      properties:
        engagement_type:
          description: Engagement type of this product run
          type: string
        input_label_summary:
          $ref: '#/components/schemas/models.InputLabelSummary'
        number_of_inference_users:
          description: NumberOfInferenceUsers is the number of users in model inference
          type: integer
        number_of_train_users:
          description: NumberOfTrainUsers is the number of users in model training
          type: integer
        run_description:
          description: RunDescription is the description of the AutoML training run
          type: string
        run_id:
          description: RunID is the unique identifier for the AutoML run
          type: string
        run_metrics:
          $ref: '#/components/schemas/models.AutoMLRunMetrics'
        status:
          description: RunStatus is the status of the AutoML training run
          type: string
        timestamp:
          description: Timestamp is the time when the training run began
          type: string
      x-konfig-properties:
        input_label_summary:
          description: >-
            Analysis of input labels detailing amounts of labels given, amounts
            of labels detected, monthly breakdowns of positive rates and counts,
            and a breakdown of weights by label value.
        run_metrics:
          description: RunMetrics is the metrics of the AutoML training run
    models.AutoMLRunUsersGetRequest:
      type: object
      properties:
        allow_users:
          description: List of users to return user scores for
          type: array
          items:
            $ref: '#/components/schemas/models.UserMetadata'
        block_users:
          description: List of users to omit from returned user scores
          type: array
          items:
            $ref: '#/components/schemas/models.UserMetadata'
        tag_filters:
          description: Categorical Filters on pf_type metadata
          type: array
          items:
            $ref: '#/components/schemas/models.TagCategoricalAttributeFilter'
    models.AutoMLRunUsersGetResponse:
      type: object
      required:
        - user_scores
      properties:
        last_scored_date:
          description: Date string of last inference in `YYYY-MM-DD hh:mm:ss` format
          type: string
        user_scores:
          description: List of user scores
          type: array
          items:
            $ref: '#/components/schemas/models.UserScore'
    models.AutoMLRunsGetResponse:
      type: object
      required:
        - runs
      properties:
        runs:
          description: List of AutoML run summaries
          type: array
          items:
            $ref: '#/components/schemas/models.AutoMLRunSummary'
    models.AutoMLUsersGetResponse:
      type: object
      required:
        - user_list
      properties:
        user_list:
          description: List of users' metadata
          type: array
          items:
            $ref: '#/components/schemas/models.UserMetadata'
    models.BatchUserPersonasRequest:
      type: object
      required:
        - user_ids
      properties:
        user_ids:
          description: All user ids we want to fetch personas for
          type: array
          items:
            type: string
    models.CashflowWindowStatistics:
      description: Inflow and outflow for a given user in a given time window
      type: object
      properties:
        inflow_amount:
          description: Inflow amount on the given window
          type: number
        outflow_amount:
          description: Outflow amount on the given window
          type: number
        window_end:
          description: End time of the given window
          type: string
        window_start:
          description: Start time of the given window
          type: string
    models.CategoricalAttributeFilter:
      type: object
      required:
        - allowed_values
        - blocked_values
      properties:
        allowed_values:
          description: Allowed values
          type: array
          items:
            type: string
          example:
            - '[''0002'']'
        blocked_values:
          description: Blocked values
          type: array
          items:
            type: string
    models.CategorizeTransactionsRequest:
      type: object
      properties:
        transactions:
          description: List of transactions to be categorized
          type: array
          items:
            $ref: '#/components/schemas/models.Transaction'
    models.CategorizeTransactionsResponse:
      type: object
      properties:
        categorized_transactions:
          description: Categorized transactions
          type: array
          items:
            $ref: '#/components/schemas/models.TransactionCategory'
    models.CategoryCashflow:
      description: >-
        Amount percentage for a given category, related to either the total
        inflow or outflow
      type: object
      properties:
        amount:
          description: Aggregate amount for the given category
          type: number
        name:
          description: Human-friendly category name
          type: string
        percentage:
          description: Absolute amount flow for the category
          type: number
        taxonomy_path:
          description: Human-friendly category taxonomy path
          type: string
    models.CategoryMetadata:
      type: object
      properties:
        category:
          description: >-
            The category of the transaction represented by a unique identifier
            in the Hyperplane's Taxonomy.
          type: string
        score:
          description: >-
            A float between 0 and 1 representing a confidence on the predicted
            category. The higher the number, the greater the confidence.
          type: string
    models.ClientResponse:
      type: object
      properties:
        access_key_id:
          type: string
          example: 823e064a-4cb7-11ee-be56-0242ac120002
        is_disabled:
          type: boolean
          example: false
    models.FacetWeightObject:
      type: object
      required:
        - name
        - weight
      properties:
        name:
          description: Name of the facet
          type: string
          example: international_traveler
        weight:
          description: Weight of the facet
          type: number
          example: 0.5
    models.InputLabelSummary:
      type: object
      required:
        - num_input_labels
        - num_input_users
        - num_matched_labels
        - num_training_users
      properties:
        label_weight_counts:
          description: >-
            Counts of given labels, broken down by label and weight. The keys
            are stringified pairs of (label_value, weight_value).
          type: object
          additionalProperties:
            type: integer
        monthly_counts:
          description: >-
            For each month (shown in YYYY-MM format), the number of labels
            given.
          type: object
          additionalProperties:
            type: integer
        monthly_positive_rates:
          description: >-
            For each month (shown in YYYY-MM format), what is the rate of
            positive labels given.
          type: object
          additionalProperties:
            type: number
        num_input_labels:
          description: Number of labels that were provided by the user.
          type: integer
        num_input_users:
          description: Number of distinct users that were provided by the user
          type: integer
        num_matched_labels:
          description: Number of data rows that will be used in training
          type: integer
        num_training_users:
          description: Number of distinct users that will be used in training
          type: integer
    models.ListPersonasResponse:
      description: Response of users linked to a given persona
      type: object
      required:
        - personas
      properties:
        personas:
          type: array
          items:
            $ref: '#/components/schemas/models.PersonaCreateResponse'
    models.Location:
      description: Location where the transaction happened
      type: object
      properties:
        city:
          description: City name
          type: string
        city_code:
          description: IBGE city code
          type: string
        country:
          description: Country name
          type: string
        full_address:
          description: >-
            Full address (e.g., Av. Lúcio Costa 1234, Copacabana, Rio de
            Janeiro, Brasil)
          type: string
        latitude:
          description: Location latitude
          type: number
        longitude:
          description: Location longitude
          type: number
        postal_code:
          description: Postal code (i.e., CEP, e.g., '22620-171')
          type: string
        primary_address:
          description: Primary address (e.g., Av. Lúcio Costa, 1234)
          type: string
        state:
          description: State name
          type: string
        type:
          description: Type of location (e.g., personal, home, business, ...)
          type: string
    models.LookalikeLabel:
      type: object
      required:
        - user_id
      properties:
        timestamp:
          description: >-
            Timestamp to filter the features available to the model. Should
            reflect when the model is called: email sent date, loan initialized
            date, etc. If None, all user features will be used
          type: string
        user_id:
          description: UserID is the unique identifier for the user
          type: string
    models.MerchantInfo:
      description: Inferred merchant info after transaction enrichment
      type: object
      properties:
        business_name:
          description: Merchant business name
          type: string
        category:
          description: Merchant category
          type: string
        cnae:
          description: Merchant CNAE
          type: string
        cnpj:
          description: Merchant CNPJ
          type: string
        name:
          description: Merchant name
          type: string
    models.NumericalAttributeFilter:
      description: Definition of a filter on an attribute of numerical type.
      type: object
      required:
        - max_value
        - min_value
      properties:
        max_value:
          description: Max attribute value
          type: number
          example: 100000
        min_value:
          description: Min attribute value
          type: number
          example: 0
    models.PaginationMetadata:
      type: object
      required:
        - next_page
        - page_size
      properties:
        next_page:
          description: Next page number
          type: integer
          example: 2
        page_size:
          description: Number of elements per page
          type: integer
          example: 100
    models.PercentileScore:
      description: Percentile and associated score.
      type: object
      properties:
        percentile:
          description: Percentile for which the score is being fetched
          type: number
          example: 0.1
        score:
          description: Score calculated for the given percentile
          type: number
          example: 0.5
    models.PersonaCreateRequest:
      description: >-
        Defines a persona. Stores various weighted facets including their
        interests, demographics, location, company affinity, as well as
        predefined personas.
      type: object
      required:
        - persona_name
      properties:
        company_facets:
          description: >-
            Optional list of behavioral facet component objects. Each object
            outlines how a user's likelihood

            to consume from a particular company's products and how much it
            contributes to the persona definition. If left

            empty, no company-based scoring is done. Company facets can be found
            by listing personas of facet type

            'company'. Facet name must be a valid company facet in the persona
            taxonomy.
          type: array
          items:
            $ref: '#/components/schemas/models.FacetWeightObject'
        demographic_facets:
          description: >-
            Optional list of interest facet component objects. Defines how much
            each demographic attribute

            (location, affluence, household composition, etc.)  weighs in the
            persona. If left empty, no demographic-based

            scoring is done. Demographic facets can be found by listing personas
            of facet type 'demographic'. Facet name

            must be a valid demographic facet in the persona taxonomy.
          type: array
          items:
            $ref: '#/components/schemas/models.FacetWeightObject'
        interest_facets:
          description: >-
            Optional list of interest facet component objects. Each object
            represents how much an interest

            weighs in the persona. If left empty, no interest-based scoring is
            done. Interests can be found

            by listing personas of facet type 'interest'. Facet name must be a
            valid interest in the persona taxonomy.
          type: array
          items:
            $ref: '#/components/schemas/models.FacetWeightObject'
        locations:
          description: >-
            Optional list of zip codes or city ids to filter users by. If left
            empty, no location-based filtering is done.
          type: array
          items:
            type: string
        persona_name:
          description: >-
            A name for describing this persona. Used for easy human-friendly
            identification.
          type: string
          example: Young Professional
        pre_defined_personas:
          description: >-
            Optional list of pre-defined persona facet component objects. Each
            object outlines how a pre-defined

            persona ('Car Owners' or 'International Travelers') contributes to
            the persona definition. If left

            empty, no predefined personas are incorporated into the persona
            definition. Pre-defined personas have

            been optimized for financial use cases and have been validated at
            scale. They can be found by listing

            personas of facet type 'pre_defined_persona'. Facet name must be a
            valid pre-defined persona facet in

            the persona taxonomy.
          type: array
          items:
            $ref: '#/components/schemas/models.FacetWeightObject'
    models.PersonaCreateResponse:
      type: object
      required:
        - creation_datetime
        - persona_id
        - persona_name
      properties:
        creation_datetime:
          description: Creation datetime of persona
          type: string
          example: '2020-01-01T00:00:00'
        persona_id:
          description: Unique identifier for the persona
          type: string
          example: '1'
        persona_name:
          description: Name of the persona
          type: string
          example: Young Professional
    models.PersonaDetailsResponse:
      type: object
      required:
        - creation_datetime
        - definition
        - persona_id
        - persona_score_statistics
      properties:
        creation_datetime:
          description: Creation datetime of persona
          type: string
          example: '2020-01-01T00:00:00'
        definition:
          $ref: '#/components/schemas/models.PersonaCreateRequest'
        persona_id:
          description: Unique identifier for the persona
          type: string
          example: '1'
        persona_score_statistics:
          $ref: '#/components/schemas/models.PersonaScoreStatistics'
      x-konfig-properties:
        definition:
          description: The persona definition used to create this persona
        persona_score_statistics:
          description: Statistical attributes about the persona score distribution
    models.PersonaScorePercentiles:
      description: Percentile scores for users scored for a particular persona.
      type: object
      properties:
        percentile_10:
          type: number
          example: 0.1
        percentile_20:
          type: number
          example: 0.2
        percentile_30:
          type: number
          example: 0.3
        percentile_40:
          type: number
          example: 0.4
        percentile_50:
          type: number
          example: 0.5
        percentile_60:
          type: number
          example: 0.6
        percentile_70:
          type: number
          example: 0.7
        percentile_80:
          type: number
          example: 0.8
        percentile_90:
          type: number
          example: 0.9
    models.PersonaScoreStatistics:
      description: >-
        Statistical attributes about the score distribution for a particular
        persona.
      type: object
      required:
        - maximum_user_score
        - minimum_user_score
        - persona_score_threshold
        - score_average
        - score_percentiles
        - score_standard_deviation
        - total_users_above_threshold
        - total_users_with_non_zero_score
      properties:
        maximum_user_score:
          description: Highest persona score assigned to a user for this persona
          type: number
          example: 0.5
        minimum_user_score:
          description: Lowest persona score assigned to a user for this persona
          type: number
          example: 0.5
        persona_score_threshold:
          description: >-
            Score threshold used to determine whether a user belongs to this
            persona
          type: number
          example: 0.5
        score_average:
          description: Average score over all scored users in this persona
          type: number
          example: 0.5
        score_percentiles:
          $ref: '#/components/schemas/models.PersonaScorePercentiles'
        score_standard_deviation:
          description: Standard deviation over all scored users in this persona
          type: number
          example: 0.5
        total_users_above_threshold:
          description: >-
            Total number of users who meet or exceed the score threshold to be
            considered part of this persona.
          type: integer
          example: 1000
        total_users_with_non_zero_score:
          description: Total number of users who have received a score for this persona.
          type: integer
          example: 1000
      x-konfig-properties:
        score_percentiles:
          description: >-
            Percentile distribution of scores for users who have been assigned a
            score for this persona
    models.PersonaUser:
      description: User associated with a given persona
      type: object
      required:
        - id
      properties:
        id:
          description: Unique identifier for the user
          type: string
          example: '1'
        score:
          description: Relevance score of user in this persona. In range `[0,1]`
          type: number
          example: 0.5
    models.PersonaUsersResponse:
      description: Response of users linked to a given persona
      type: object
      required:
        - users
      properties:
        users:
          description: Top users belonging to this persona
          type: array
          items:
            $ref: '#/components/schemas/models.PersonaUser'
    models.PostPersonaUsersRequest:
      description: Extra information for filtering users
      type: object
      required:
        - blocklist
        - branch
      properties:
        birth_date:
          $ref: '#/components/schemas/models.TimestampAttributeFilter'
        blocklist:
          description: List of user ids to not be included in the response
          type: array
          items:
            type: string
          example:
            - '[''1234'']'
        branch:
          $ref: '#/components/schemas/models.CategoricalAttributeFilter'
        cbo_code:
          $ref: '#/components/schemas/models.CategoricalAttributeFilter'
        declared_monthly_income:
          $ref: '#/components/schemas/models.NumericalAttributeFilter'
        job_title:
          $ref: '#/components/schemas/models.CategoricalAttributeFilter'
      x-konfig-properties:
        birth_date:
          description: Filter birth date based on a date range
        branch:
          description: Filter branch based on a list of allowed values
        cbo_code:
          description: Filter cbo code based on a list of allowed values
        declared_monthly_income:
          description: Filter declared monthly income based on a numeric range
        job_title:
          description: Filter job title based on a list of allowed values
    models.TagCategoricalAttributeFilter:
      type: object
      required:
        - allowed_values
        - blocked_values
        - tag_name
      properties:
        allowed_values:
          description: Allowed values
          type: array
          items:
            type: string
          example:
            - '[''0002'']'
        blocked_values:
          description: Blocked values
          type: array
          items:
            type: string
        tag_name:
          description: Tag name
          type: string
    models.TimestampAttributeFilter:
      description: Definition of a filter on an attribute of timestamp type.
      type: object
      required:
        - max_value
        - min_value
      properties:
        max_value:
          description: Max attribute value
          type: string
          example: '2020-01-01T00:00:00'
        min_value:
          description: Min attribute value
          type: string
          example: '2000-01-01T00:00:00'
    models.TopLevelCategoryCashflow:
      description: >-
        Amount percentage for a given top level category. As well as
        subcategories division
      type: object
      properties:
        amount:
          description: Aggregate amount for the given category
          type: number
        categories:
          description: Detailed predicted categories under the top-level
          type: array
          items:
            $ref: '#/components/schemas/models.CategoryCashflow'
        name:
          description: Human-friendly category name
          type: string
        percentage:
          description: Absolute amount flow for the category
          type: number
    models.Transaction:
      type: object
      properties:
        description:
          description: >-
            The raw text description of the transaction (do not clean or
            transform this).

            It usually includes some information about the payment method,
            processor,

            merchant, and in cases of transfer might include CNPJ or other
            reference numbers.

            Some examples:
               - Pag*Mariaivaneidede
               - Ifd*Puro Acai Beira Ma
               - TED BCO 1 AGE 4598  CTA 291412  - RETIRADA EM C/C
          type: string
        account_id:
          description: A unique identifier for the account within the bank or institution.
          type: string
        account_type:
          description: 'One of the following: checking, saving, credit card or investment.'
          type: string
        amount:
          description: >-
            The monetary value of a transaction. This is always a positive
            value.
          type: number
        bank_id:
          description: >-
            The name of the bank that is originating the transaction. For credit
            cards, this is the issuing bank.
          type: string
        currency:
          description: 'Currency enum based on ISO 4217. Eg: BRL, USD, MXN.'
          type: string
        location_city:
          description: >-
            The city in which the transaction happened. e.g. São Paulo, Mexico
            City, San Francisco.
          type: string
        location_country:
          description: >-
            The country in which the transaction happened in ISO 3166-1 alpha-3
            format. e.g. BRA (for transaction in Brazil), ESP (for transaction
            in Spain).
          type: string
        location_state:
          description: 'The state in which the transaction happened. Eg: SP, CA.'
          type: string
        transaction_datetime:
          description: Time when the transaction was performed.
          type: string
        transaction_flow:
          description: >-
            One of the following options: outflow (for spending) or inflow (for
            earning).
          type: string
        transaction_id:
          description: >-
            A unique identifier for each transaction to identify the transaction
            within your bank or institution.
          type: string
        transaction_metadata:
          $ref: '#/components/schemas/models.TransactionMetadata'
        user_id:
          description: A unique identifier for the user within the bank or institution.
          type: string
      x-konfig-properties:
        transaction_metadata:
          description: >-
            A map used to store additional context about a transaction that
            might be useful for cleaning and understanding.
    models.TransactionCategory:
      type: object
      properties:
        description:
          description: >-
            The raw text description of the transaction (do not clean or
            transform this).

            It usually includes some information about the payment method,
            processor,

            merchant, and in cases of transfer might include CNPJ or other
            reference numbers.

            Some examples:
               - Pag*Mariaivaneidede
               - Ifd*Puro Acai Beira Ma
               - TED BCO 1 AGE 4598  CTA 291412  - RETIRADA EM C/C
          type: string
        account_id:
          description: A unique identifier for the account within the bank or institution.
          type: string
        account_type:
          description: 'One of the following: checking, saving, credit card or investment.'
          type: string
        amount:
          description: >-
            The monetary value of a transaction. This is always a positive
            value.
          type: number
        bank_id:
          description: >-
            The name of the bank that is originating the transaction. For credit
            cards, this is the issuing bank.
          type: string
        category_metadata:
          $ref: '#/components/schemas/models.CategoryMetadata'
        currency:
          description: 'Currency enum based on ISO 4217. Eg: BRL, USD, MXN.'
          type: string
        location_city:
          description: >-
            The city in which the transaction happened. e.g. São Paulo, Mexico
            City, San Francisco.
          type: string
        location_country:
          description: >-
            The country in which the transaction happened in ISO 3166-1 alpha-3
            format. e.g. BRA (for transaction in Brazil), ESP (for transaction
            in Spain).
          type: string
        location_state:
          description: 'The state in which the transaction happened. Eg: SP, CA.'
          type: string
        transaction_datetime:
          description: Time when the transaction was performed.
          type: string
        transaction_flow:
          description: >-
            One of the following options: outflow (for spending) or inflow (for
            earning).
          type: string
        transaction_id:
          description: >-
            A unique identifier for each transaction to identify the transaction
            within your bank or institution.
          type: string
        transaction_metadata:
          $ref: '#/components/schemas/models.TransactionMetadata'
        user_id:
          description: A unique identifier for the user within the bank or institution.
          type: string
      x-konfig-properties:
        category_metadata:
          description: Predicted category and the confidence of the prediction
        transaction_metadata:
          description: >-
            A map used to store additional context about a transaction that
            might be useful for cleaning and understanding.
    models.TransactionEnrichmentResponse:
      type: object
      properties:
        description:
          description: Transaction description
          type: string
        amount:
          description: Amount of transaction
          type: number
        category:
          description: Category enum of transaction
          type: string
        category_name:
          description: Category human-readable name of transaction
          type: string
        currency:
          description: Transaction currency
          type: string
        current_installment:
          description: Current installment. If 0, it is not an installment
          type: integer
        date:
          description: Date of transaction
          type: string
        installment_start_date:
          description: First installment date, that is, the purchase date
          type: string
        merchant_info:
          $ref: '#/components/schemas/models.MerchantInfo'
        number_of_installments:
          description: Number of installments
          type: integer
        total_installed_amount:
          description: Sum of amounts for all installments
          type: number
        transaction_id:
          description: Unique transaction id
          type: string
        transaction_location:
          $ref: '#/components/schemas/models.Location'
        transaction_status:
          description: Transaction status
          type: string
        transfer_metadata:
          $ref: '#/components/schemas/models.TransferMetadata'
      x-konfig-properties:
        merchant_info:
          description: Contains metadata about the merchant, if available.
        transaction_location:
          description: Location where the transaction happened
        transfer_metadata:
          description: >-
            Contains metadata about the payment method, the sender, and the
            receiver.
    models.TransactionEnrichmentStatisticsResponse:
      description: General statistics for a given transaction enrichment module
      type: object
      required:
        - transaction_count
        - user_reach
      properties:
        transaction_count:
          description: Number of transactions in the module
          type: integer
          example: 10000
        user_reach:
          description: Number of distinct users in the module
          type: integer
          example: 1000
    models.TransactionEnrichmentUser:
      type: object
      required:
        - first_transaction_date
        - last_transaction_date
        - user_id
      properties:
        first_transaction_date:
          description: Date for first transaction registered for a given user.
          type: string
          example: '2020-01-01T00:00:00Z'
        last_transaction_date:
          description: Date for last transaction registered for a given user.
          type: string
          example: '2020-01-01T00:00:00Z'
        user_id:
          description: Unique user identifier
          type: string
          example: '123456'
    models.TransactionEnrichmentUsersResponse:
      description: Page of users of a given module
      type: object
      required:
        - pagination_metadata
        - users
      properties:
        pagination_metadata:
          $ref: '#/components/schemas/models.PaginationMetadata'
        users:
          description: List of users related to the transactions
          type: array
          items:
            $ref: '#/components/schemas/models.TransactionEnrichmentUser'
      x-konfig-properties:
        pagination_metadata:
          description: Pagination metadata needed to know the next call
    models.TransactionMetadata:
      type: object
      properties:
        account_balance:
          description: Current account balance after this transaction.
          type: number
        current_installment:
          description: What installment this payment corresponds to.
          type: integer
        location_latitude:
          description: >-
            A number between [“-90.0”, “90.0”] indicating the latitude of the
            location where the transaction happened.
          type: number
        location_longitude:
          description: >-
            A number between [“-180.0”, “180.0”] indicating the longitude of the
            location where the transaction happened.
          type: number
        mcc:
          description: MCC code for the merchant.
          type: integer
        number_of_installments:
          description: How many installments will this purchase be payed off in.
          type: integer
        transaction_status:
          description: 'Example: “Approved”, “Pending”, “Rejected”, “Rejected - Fraud”, …'
          type: string
        transfer_payment_method:
          description: 'The method used for the transfer. Eg: “DOC”, “TED”, “PIX”'
          type: string
        transfer_receiver_document_name:
          description: >-
            The name of the document that identifies the entity receiving the
            transfer. e.g. “CPF”, “CNPJ”.
          type: string
        transfer_receiver_document_number:
          description: >-
            A document number identifying the receiver of the transfer (e.g.
            CPF, CNPJ).
          type: string
        transfer_receiver_name:
          description: >-
            The name of the entity receiving the money. e.g. “João da Silva”,
            “Padaria São João”.
          type: string
        transfer_reference_number:
          description: A control number used to uniquely identify a transfer.
          type: string
        transfer_sender_document_name:
          description: >-
            The name of the document used by the sender to issue the transfer.
            e.g. “CPF”, “CNPJ”.
          type: string
        transfer_sender_document_number:
          description: >-
            A document number identifying the sender of the transfer (e.g. CPF,
            CNPJ).
          type: string
        transfer_sender_name:
          description: >-
            The name of the entity sending the money. e.g. “João da Silva”,
            “Padaria São João”.
          type: string
    models.TransferMetadata:
      description: Metadata related to the money transfer and involved parties
      type: object
      properties:
        payment_method:
          description: Transfer payment method
          type: string
        reason:
          description: Transfer inferred reason
          type: string
        receiver:
          $ref: '#/components/schemas/models.TransferParty'
        reference_number:
          description: Transfer reference number
          type: string
        sender:
          $ref: '#/components/schemas/models.TransferParty'
      x-konfig-properties:
        receiver:
          description: Transfer party that receives the money
        sender:
          description: Transfer party that sends the money
    models.TransferParty:
      description: Attributes related to the sender or receiver of a given transaction
      type: object
      properties:
        account_number:
          description: Party account number
          type: string
        branch_number:
          description: Party branch number
          type: string
        document_name:
          description: Party document name
          type: string
        document_number:
          description: Party document number
          type: string
        name:
          description: Party name
          type: string
        routing_number:
          description: Party routing number
          type: string
        routing_number_ISPB:
          description: Party ISPB routing number
          type: string
    models.UserCashflowHistoryResponse:
      description: Historic of cashflows for a given user
      type: object
      required:
        - user_id
        - windows
      properties:
        user_id:
          description: User identifier
          type: string
          example: '123456'
        windows:
          description: Windows with calculated flows
          type: array
          items:
            $ref: '#/components/schemas/models.CashflowWindowStatistics'
    models.UserCashflowPerCategoryResponse:
      type: object
      properties:
        inflow_categories:
          description: Inflow discriminated by category
          type: array
          items:
            $ref: '#/components/schemas/models.TopLevelCategoryCashflow'
        outflow_categories:
          description: Outflow discriminated by category
          type: array
          items:
            $ref: '#/components/schemas/models.TopLevelCategoryCashflow'
        user_id:
          description: User identifier
          type: string
    models.UserMetadata:
      type: object
      required:
        - user_id
      properties:
        user_id:
          description: UserID is the unique identifier for the user
          type: string
    models.UserPersonaScore:
      description: User associated with a given persona
      type: object
      required:
        - persona_id
        - persona_name
      properties:
        persona_id:
          description: Unique identifier for the persona
          type: string
          example: '1'
        persona_name:
          description: Name of the persona
          type: string
          example: Young Professional
        persona_score:
          description: Relevance score of user in this persona. In range `[0,1]`
          type: number
          example: 0.5
    models.UserPersonasResponse:
      description: Response of personas linked to a given user
      type: object
      required:
        - persona_scores
        - user_id
      properties:
        persona_scores:
          description: Ranked list of personas for this user
          type: array
          items:
            $ref: '#/components/schemas/models.UserPersonaScore'
        user_id:
          description: Unique identifier for the user
          type: string
          example: '1'
    models.UserScore:
      type: object
      required:
        - score
        - user_id
      properties:
        score:
          description: Model inference score for the user
          type: number
        user_id:
          description: UserID is the unique identifier for the user
          type: string
    models.UserTransactionsResponse:
      description: Historic of enriched transactions of a given user
      type: object
      required:
        - enriched_transactions
        - pagination_metadata
        - user_id
      properties:
        enriched_transactions:
          description: List of enriched transactions
          type: array
          items:
            $ref: '#/components/schemas/models.TransactionEnrichmentResponse'
        pagination_metadata:
          $ref: '#/components/schemas/models.PaginationMetadata'
        user_id:
          description: User identifier
          type: string
          example: '123456'
      x-konfig-properties:
        pagination_metadata:
          description: Pagination metadata needed to know the next call
    models.UserTransactionsStatisticsResponse:
      description: Transaction statistics for a given user
      type: object
      required:
        - transaction_count
      properties:
        average_transaction_value:
          description: Average transaction value
          type: number
          example: 100
        median_transaction_value:
          description: Median transaction value
          type: number
          example: 100
        transaction_count:
          description: Number of transactions
          type: integer
          example: 100
    AutoMlServiceGetRunStatusResponse:
      type: string
    AutoMlServiceGetStatusBatchScoresResponse:
      type: string
    PersonasGetFacetAttributesResponse:
      type: array
      items:
        $ref: '#/components/schemas/models.UserPersonasResponse'
    HealthCheckStatusResponse:
      type: string
    PersonasDeleteCustomPersonaResponse:
      type: string
    StatisticsGetLatestMonthDataResponse:
      type: string
    EnrichedTransactionsGetUserCashflowStatisticsResponse:
      type: array
      items:
        $ref: '#/components/schemas/models.AccountCashflowOverview'
x-readme:
  explorer-enabled: true
  proxy-enabled: true
_id: 65aeebbcf3190d004197ed8f