Yapily Data Plus API

Transaction enrichment endpoints providing merchant detection, MCC categorisation, and spending insights across consumer and business accounts.

Yapily Data Plus API is one of 9 APIs that Yapily publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include Enrichment, Categorisation, Merchant Detection, Insights, and Open Banking. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.

OpenAPI Specification

yapily-data-plus-api-openapi.yml Raw ↑
openapi: 3.0.1
info:
  title: Yapily Data Plus API
  description: Transaction enrichment endpoints for categorisation, merchant detection, and spending insights across consumer
    and business accounts.
  version: 12.4.0
  contact:
    name: Yapily Support
    url: https://docs.yapily.com/resources/support
    email: [email protected]
servers:
- url: https://api.yapily.com
security:
- basicAuth: []
tags:
- description: 'Data Plus endpoints enable our customers to enrich transaction data. '
  name: Data Plus
paths:
  /accounts/{accountId}/transactions/categorisation:
    post:
      operationId: post-accounts-accountId-transactions-categorisation
      summary: Transactions and Enrichment
      description: Trigger categorisation for transactions from [AIS (see Get Transactions endpoint)](/api-reference/getTransactions)
        in the specified time range.
      tags:
      - Data Plus
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - categorisationType
              - countryCode
              properties:
                countryCode:
                  type: string
                  description: __Mandatory__. Two-letter country code in ISO 3166-1 alpha-2 format (e.g. GB)
                categorisationType:
                  type: string
                  description: __Mandatory__. Allowed values are `consumer` and `business`.
                from:
                  type: string
                  format: date-time
                  description: '__Optional__. Returned transactions will be on or after this date (yyyy-MM-dd''T''HH:mm:ss.SSSZ). '
                before:
                  type: string
                  format: date-time
                  description: __Optional__. Returned transactions will be on or before this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
            examples:
              Example:
                value:
                  countryCode: GB
                  categorisationType: consumer
                  from: '2019-08-24T14:15:22Z'
                  before: '2019-08-24T14:15:22Z'
      responses:
        '201':
          description: Created
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiResponseOfCreateTransactionsCategorisationRequest'
              examples:
                Example 1:
                  $ref: '#/components/examples/create-transactions-categorisation-response'
        '400':
          description: Validation Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Authentication Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/401-error-response'
        '500':
          description: Unexpected Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/500-error-response'
      x-mint:
        content: '<Info>Learn more: [Transaction Categorisation](/data/data-plus/categorisation)</Info>'
    parameters:
    - description: __Mandatory__. The `consent-token` containing the user's authorisation to make the request.
      example: '{consentToken}'
      in: header
      name: consent
      required: true
      schema:
        type: string
    - description: "__Conditional__. Represents the user's login ID for the `Institution` to a personal account. \n\nSee [PSU\
        \ identifiers](/open-banking-flow/user-authorisation/psu-identifiers) to see if this header is required."
      in: header
      name: psu-id
      required: false
      schema:
        type: string
    - description: "__Conditional__. Represents the user's login ID for the `Institution` to a business account. \n\nSee [PSU\
        \ identifiers](/open-banking-flow/user-authorisation/psu-identifiers) to see if this header is required."
      in: header
      name: psu-corporate-id
      required: false
      schema:
        type: string
    - description: "__Conditional__. The IP address of the PSU. \n\nSee [PSU identifiers](/open-banking-flow/user-authorisation/psu-identifiers)\
        \ to see if this header is required."
      in: header
      name: psu-ip-address
      required: false
      schema:
        type: string
    - $ref: '#/components/parameters/SubAppHeader'
    - schema:
        type: string
      name: accountId
      in: path
      required: true
      description: Unique identifier for account
  /accounts/{accountId}/transactions/categorisation/{categorisationId}:
    get:
      deprecated: true
      operationId: get-accounts-transactions-categorised
      summary: Get Categorised Transactions (deprecated)
      description: '__Deprecated__. Retrieve categorised transactions by Categorisation ID.


        Use the [other endpoint (`/transactions/categorisation/{categorisationId}`)](#operation/get-transactions-categorised)
        instead.'
      tags:
      - Data Plus
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiResponseOfGetCategorisedTransactionsRequest'
              examples:
                Example 1:
                  $ref: '#/components/examples/get-categorised-transactions-response'
        '400':
          description: Validation Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Authentication Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/401-error-response'
        '404':
          description: Categorisation ID not found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/404-error-response'
        '500':
          description: Unexpected Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/500-error-response'
    parameters:
    - description: __Mandatory__. The `consent-token` containing the user's authorisation to make the request.
      example: '{consentToken}'
      in: header
      name: consent
      required: true
      schema:
        type: string
    - schema:
        type: string
      name: accountId
      in: path
      required: true
      description: Unique identifier for account
    - schema:
        type: string
      name: categorisationId
      in: path
      required: true
      description: Unique identifier for transaction categorisation request
    - $ref: '#/components/parameters/SubAppHeader'
    - description: __Optional__. The maximum number of transaction records to be returned. Must be between 100 and 1000. If
        not specified will default to 100.
      in: query
      name: limit
      required: false
      schema:
        type: integer
        format: int32
        minimum: 100
        maximum: 1000
    - description: __Optional__. The page number to be returned. If not specified will default to 1.
      in: query
      name: page
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
  /transactions/categorisation:
    post:
      operationId: post-transactions-categorisation
      summary: Enrichment
      description: Trigger categorisation for transactions provided in the request.
      tags:
      - Data Plus
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - categorisationType
              - countryCode
              - transactions
              properties:
                countryCode:
                  type: string
                  description: __Mandatory__. Two-letter country code in ISO 3166-1 alpha-2 format (e.g. GB)
                categorisationType:
                  type: string
                  description: __Mandatory__. Allowed values are `consumer` and `business`.
                transactions:
                  type: array
                  items:
                    type: object
                    required:
                    - id
                    - date
                    - amount
                    - description
                    - countryCode
                    properties:
                      id:
                        type: string
                        description: __Mandatory__. A globally unique transaction ID.
                      date:
                        type: string
                        description: __Mandatory__. Transaction date in ISO 8601 format (eg. 2025-01-01T12:59:59.999Z)
                      amount:
                        type: object
                        required:
                        - value
                        - currency
                        properties:
                          value:
                            type: integer
                            description: __Mandatory__. Transaction money amount in cents (or equivalent). Positive amount
                              implies money in, negative amount implies money out.
                          currency:
                            type: string
                            description: __Mandatory__. Transaction currency.
                      merchant:
                        type: object
                        properties:
                          mcc:
                            type: string
                            description: __Optional__. Merchant Category Code (MCC) according to ISO 18245
                      description:
                        type: string
                        description: __Mandatory__. Transaction-specific description.
                      countryCode:
                        type: string
                        description: __Mandatory__. Transaction-specific two-letter country code in ISO 3166-1 alpha-2 format
                          (e.g. GB)
            examples:
              Example 1:
                value:
                  countryCode: GB
                  categorisationType: consumer
                  transactions:
                  - id: 06edf952-8d94-44ae-8d4e-a065b7e47300
                    date: '2025-03-01T14:15:16Z'
                    amount:
                      value: -9900
                      currency: GBP
                    description: Shopping
                    countryCode: GB
                  - id: 6a241cae-7c43-4058-bdbd-ff9d64e6c9df
                    date: '2025-04-02T07:59:59Z'
                    amount:
                      value: 1000
                      currency: USD
                    description: Refund
                    countryCode: GB
      responses:
        '201':
          description: Created
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiResponseOfCreateTransactionsCategorisationRequest'
              examples:
                Example 1:
                  $ref: '#/components/examples/create-transactions-categorisation-response'
        '400':
          description: Validation Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Authentication Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/401-error-response'
        '500':
          description: Unexpected Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/500-error-response'
      x-mint:
        content: '<Info>Learn more: [Transaction Categorisation](/data/data-plus/categorisation)</Info>'
    parameters:
    - $ref: '#/components/parameters/SubAppHeader'
  /transactions/categorisation/{categorisationId}:
    get:
      operationId: get-transactions-categorised
      summary: Get Enrichment Results
      description: 'Retrieve categorised transactions by Categorisation ID.


        Please [use webhooks](/introductionpages/data/data-plus/tutorial-categorisation/) to be notified when your transactions
        have been categorised and are ready for retrieval.


        Note that when using the [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)
        this endpoint may also return any data specified by the [Get Account Transactions endpoint](/api-reference/getTransactions);
        this endpoint''s docs mentions a non-exhaustive subset of such data.'
      tags:
      - Data Plus
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiResponseOfGetCategorisedTransactionsRequest'
              examples:
                Example 1:
                  $ref: '#/components/examples/get-categorised-transactions-response'
        '400':
          description: Validation Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Authentication Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/401-error-response'
        '404':
          description: Categorisation ID not found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/404-error-response'
        '500':
          description: Unexpected Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/500-error-response'
    parameters:
    - schema:
        type: string
      name: categorisationId
      in: path
      required: true
      description: Unique identifier for transaction categorisation request
    - $ref: '#/components/parameters/SubAppHeader'
    - description: __Optional__. The maximum number of transaction records to be returned. Must be between 100 and 1000. If
        not specified will default to 100.
      in: query
      name: limit
      required: false
      schema:
        type: integer
        format: int32
        minimum: 100
        maximum: 1000
    - description: __Optional__. The page number to be returned. If not specified will default to 1.
      in: query
      name: page
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
  /transactions/categorisation/categories/{accountType}:
    get:
      operationId: get-categorisation-accountType
      summary: Get Enrichment Labels
      description: Returns the list of categories that can be returned for a specific account type (consumer or business).
      tags:
      - Data Plus
      responses:
        '200':
          description: OK
          content:
            application/json;charset=UTF-8:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      tracingId:
                        type: string
                  data:
                    $ref: '#/components/schemas/GetCategoriesResponse'
              examples:
                Example consumer:
                  value:
                    meta:
                      tracingId: string
                    data:
                      labels:
                      - ATM/bank deposit
                      - Benefits
                      - ATM/bank withdrawal
                      - App stores
                Example business:
                  value:
                    meta:
                      tracingId: string
                    data:
                      labels:
                      - client deposit
                      - cost of goods sold - customer return
        '400':
          description: Validation Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Authentication Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/401-error-response'
        '404':
          description: Account type not found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/404-error-response'
        '500':
          description: Unexpected Error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/500-error-response'
    parameters:
    - schema:
        type: string
      name: accountType
      in: path
      required: true
      description: type of bank account (consumer or business)
    - $ref: '#/components/parameters/SubAppHeader'
components:
  schemas:
    ApiErrorResponseV2:
      type: object
      description: API Error Response
      properties:
        error:
          required:
          - tracingId
          - code
          - status
          - issues
          type: object
          properties:
            tracingId:
              type: string
              description: Unique identifier of the request, used by Yapily for support purposes
            code:
              type: integer
              format: int32
              description: Numeric HTTP status code associated with the error
            status:
              type: string
              description: Textual description of the HTTP status
            supportUrl:
              type: string
              description: Link to where further information regarding the error can be found
            source:
              type: string
              description: Source of the error. This may be YAPILY, the INSTITUTION, or the USER
            issues:
              type: array
              description: List of issues relating to the error
              items:
                required:
                - message
                - code
                type: object
                description: Detailed information regarding the issue that was experienced during processing of the request
                properties:
                  type:
                    type: string
                    description: Category of the issue
                  code:
                    type: string
                    description: 5 digit Error Code that uniquely identifies the type of issue, for full list of error codes
                      pelase check our documentation
                  message:
                    type: string
                    description: Human readable description of the issue that was experienced
    ApiResponseOfCreateTransactionsCategorisationRequest:
      type: object
      properties:
        meta:
          type: object
          properties:
            tracingId:
              type: string
        data:
          type: object
          properties:
            categorisationId:
              type: string
              format: uuid
    ApiResponseOfGetCategorisedTransactionsRequest:
      type: object
      properties:
        meta:
          type: object
          properties:
            tracingId:
              type: string
            count:
              type: integer
              description: Total number of categorised transactions available
            pageCount:
              type: integer
              description: Total number of pages available, calculated based on the limit per page sent in the request.
        data:
          type: object
          required:
          - transactions
          properties:
            transactions:
              type: array
              items:
                type: object
                required:
                - enrichment
                - date
                - description
                - transactionAmount
                properties:
                  enrichment:
                    type: object
                    description: Enrichment/Categorisation data
                    required:
                    - transactionHash
                    - categorisation
                    properties:
                      transactionHash:
                        type: object
                        description: A unique identifier for the transaction that was generated by Yapily. It is a hash of
                          some transaction attributes that is useful when no other identifier is present for instance.
                        required:
                        - hash
                        properties:
                          hash:
                            type: string
                      categorisation:
                        type: object
                        description: Categories associated with the transaction (see [categories list](/data/data-plus/categorisation-list))
                        required:
                        - categories
                        properties:
                          categories:
                            type: array
                            items:
                              type: string
                      merchant:
                        type: object
                        description: Processed merchant information
                        properties:
                          id:
                            type: string
                            description: The unique identifier for the merchant
                          name:
                            type: string
                            description: The familiar name of the merchant (eg. 'Waitrose', 'Uber')
                          logo:
                            type: string
                            description: The logo of the merchant, formatted as a URL
                  recurrence:
                    type: string
                    description: Processed type of recurrence for the transaction (eg. 'one off', 'subscription')
                  paymentProcessor:
                    type: string
                    description: Processed payment provider for the transaction (eg. 'PayPal')
                  location:
                    type: string
                    description: Processed location of the transaction/merchant derived from the transaction's description,
                      formatted as an address
                  merchant:
                    type: object
                    description: Generic merchant information
                    properties:
                      merchantCategoryCode:
                        type: string
                        description: An ISO 18245 code specifying the goods and services that the merchant provides (eg. `5411`
                          for Grocery Stores and Supermarkets)
                  id:
                    type: string
                    description: __Conditional.__ An identifier for the transaction retrieved from Yapily AIS (ie. present
                      when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation))
                  date:
                    type: string
                    format: date-time
                    description: The date and time when the transaction happened
                  description:
                    type: string
                    description: The description associated with the transaction
                  transactionAmount:
                    type: object
                    description: The amount associated with the transaction
                    required:
                    - amount
                    - currency
                    properties:
                      amount:
                        type: number
                        description: The monetary amount (a positive value implies _incoming_ transaction and a negative value
                          implies _outgoing_ transaction)
                      currency:
                        type: string
                        description: The [ISO 4217](https://www.xe.com/iso4217.php) currency code
                  bookingDateTime:
                    type: string
                    format: date-time
                    description: '__Conditional.__ The date and time when the transaction was booked


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                  valueDateTime:
                    type: string
                    format: date-time
                    description: '__Conditional.__ The date and time when the funds either cease to be available (for _outgoing_
                      transactions) or become available to the account owner (for _incoming_ transactions)


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                  status:
                    type: string
                    description: '__Conditional.__ The status of the transaction. Enum: `BOOKED`, `PENDING`


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                  amount:
                    type: number
                    description: '__Conditional.__ The monetary amount (a positive value implies _incoming_ transaction and
                      a negative value implies _outgoing_ transaction)


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                  currency:
                    type: string
                    description: '__Conditional.__ The [ISO 4217](https://www.xe.com/iso4217.php) currency code


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                  reference:
                    type: string
                    description: '__Conditional.__ The reference associated with the transaction


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                  transactionInformation:
                    type: array
                    description: '__Conditional.__ Other details associated with the transaction. This is narrative data,
                      caught as unstructured text.


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                    items:
                      type: string
                  proprietaryBankTransactionCode:
                    type: object
                    description: '__Conditional.__ A transaction code that is proprietary to the issuer institution


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                    properties:
                      code:
                        type: string
                      issuer:
                        type: string
                  isoBankTransactionCode:
                    type: object
                    description: '__Conditional.__ The ISO 20022 codes specifying the type of the transaction (eg. domain
                      of ''Payments'', family of ''Issued Credit Transfers'', and sub-family of ''Domestic Credit Transfer'')


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                    properties:
                      domainCode:
                        type: object
                        description: The domain of the transaction
                        properties:
                          code:
                            type: string
                            description: Unique identifier of the ISO code
                          name:
                            type: string
                            description: Name of the ISO code
                      familyCode:
                        type: object
                        description: The family of the transaction
                        properties:
                          code:
                            type: string
                            description: Unique identifier of the ISO code
                          name:
                            type: string
                            description: Name of the ISO code
                      subFamilyCode:
                        type: object
                        description: The sub-family of the transaction
                        properties:
                          code:
                            type: string
                            description: Unique identifier of the ISO code
                          name:
                            type: string
                            description: Name of the ISO code
                  balance:
                    type: object
                    description: '__Conditional.__ The account balance around the time of the transaction (the exact timing
                      is dictated by the balance type)


                      This may be present when using [Transactions and Categorisation endpoint](/api-reference/post-accounts-accountId-transactions-categorisation)'
                    properties:
                      type:
                        type: string
                        description: 'Enum: `CLOSING_AVAILABLE`, `CLOSING_BOOKED`, `CLOSING_

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/yapily/refs/heads/main/openapi/yapily-data-plus-api-openapi.yml