Yapily Platform API

openapi: 3.0.1
info:
  title: Yapily Platform API
  description: Manage Applications, Users, Application Management, Constraints, and Webhooks for the Yapily Open Banking platform.
  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: The `Application` is the base entity that is used to interact with the API and contains a collection of `Institution`
    objects. You can have multiple Applications associated with your account e.g. a production application with live access
    to each `Institution` and a development application with access to sandboxes.
  name: Application
- description: Application Management endpoints help with creating and managing client sub-applications.
  name: Application Management
- description: The Users endpoints are used to manage each user (otherwise known as the PSU) in Yapily. Each user belongs
    to an Application and as a consequence, so do each `Consent` created for a particular `User`.
  name: Users
- description: The constraints endpoints can be used to retrieve institution specific data requirements and rules that will
    apply when performing other operations.
  name: Constraints
- description: Webhook endpoints
  name: Webhooks
- description: "The Notifications endpoints provide an interactive way for user to receive notifications according to different\
    \ event-types. This feature is currently in private beta. Please reach out if you require access. \n\n"
  name: Notifications
paths:
  /users:
    get:
      description: Retrieves all users created in your application for a specified applicationUserId using the filter[applicationUserId]
        query parameter. If filter[applicationUserId] is not provided, the response will include up to 50,000 users.
      operationId: getUsers
      parameters:
      - description: __Optional__. Filter records based on the list of `applicationUserId` users provided.
        in: query
        name: filter[applicationUserId]
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json;charset=UTF-8:
              examples:
                Example Response:
                  $ref: '#/components/examples/users_example-response'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApplicationUser'
          description: Ok
        default:
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/error-response-code-401'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Error Response
      summary: Get Users
      tags:
      - Users
    post:
      description: Create a new user in your application
      operationId: addUser
      requestBody:
        content:
          application/json;charset=UTF-8:
            examples:
              Create User Example Request:
                $ref: '#/components/examples/create-user-example-request'
            schema:
              $ref: '#/components/schemas/NewApplicationUser'
        required: true
      responses:
        '201':
          content:
            application/json;charset=UTF-8:
              examples:
                Example Response:
                  $ref: '#/components/examples/create-user_example-response'
              schema:
                $ref: '#/components/schemas/ApplicationUser'
          description: Created
        default:
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/error-response-code-401'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Error Response
      summary: Create User
      tags:
      - Users
  /users/{userUuid}:
    patch:
      description: Update the users information
      operationId: patchUser
      parameters:
      - description: __Mandatory__. The Yapily generated UUID for the user.
        in: path
        name: userUuid
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ApplicationUserPatchRequest'
      responses:
        '201':
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApplicationUser'
          description: Created
        default:
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Error Response
      summary: Update User
      tags:
      - Users
    delete:
      description: Delete a user from your application along with any sub-resources (including consent resources on institution
        APIs if they exist)
      operationId: deleteUser
      parameters:
      - description: __Mandatory__. The Yapily generated UUID for the user.
        in: path
        name: userUuid
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json;charset=UTF-8:
              examples:
                Example Response:
                  $ref: '#/components/examples/delete-user_example-response'
              schema:
                $ref: '#/components/schemas/ApiResponseOfUserDeleteResponse'
          description: Ok
        default:
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/error-response-code-401'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Error Response
      summary: Delete User
      tags:
      - Users
    get:
      description: Get a specific user using the user UUID
      operationId: getUser
      parameters:
      - description: __Mandatory__. The Yapily generated UUID for the user.
        in: path
        name: userUuid
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          content:
            application/json;charset=UTF-8:
              examples:
                Example Response:
                  $ref: '#/components/examples/user_example-response'
              schema:
                $ref: '#/components/schemas/ApplicationUser'
          description: Ok
        default:
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/error-response-code-401'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Error Response
      summary: Get User
      tags:
      - Users
  /notifications/event-subscriptions:
    post:
      tags:
      - Notifications
      summary: Create Event Subscription
      description: Used to subscribe to notifications relating to a specified event type.
      operationId: createEventSubscription
      x-beta: true
      parameters:
      - $ref: '#/components/parameters/SubAppHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventSubscriptionRequest'
      responses:
        '201':
          description: Event subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfEventSubscriptionResponse'
        '400':
          description: Bad request for missing required properties
        '401':
          description: Unauthorized
        '409':
          description: Event subscription already exist for the application
      x-mint:
        content: '<Info>Learn more: [Webhooks & Notifications](/tools-and-services/webhooks/introduction)</Info>'
    get:
      tags:
      - Notifications
      summary: Get Event Subscriptions
      description: Get all event subscriptions that your application is subscribed to
      operationId: getEventSubscriptions
      x-beta: true
      parameters:
      - description: The sub-application ID for which all event subscriptions will be returned
        in: header
        name: sub-application
        required: false
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Event subscriptions for the application
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiListResponseOfEventSubscriptionResponse'
        '401':
          description: Unauthorized
  /notifications/event-subscriptions/{eventTypeId}:
    get:
      tags:
      - Notifications
      summary: Get Event Subscription
      description: Used to get details of your subscription to a specified event type.
      operationId: getEventSubscriptionById
      x-beta: true
      parameters:
      - $ref: '#/components/parameters/EventTypeId'
      - $ref: '#/components/parameters/SubAppHeader'
      responses:
        '200':
          description: Event subscription data found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfEventSubscriptionResponse'
        '401':
          description: Unauthorized
        '404':
          description: Event subscription not found
    delete:
      tags:
      - Notifications
      summary: Delete Event Subscription
      description: Used to unsubscribe to notifications relating to a specified event type.
      operationId: deleteEventSubscriptionById
      x-beta: true
      parameters:
      - $ref: '#/components/parameters/EventTypeId'
      - description: The sub-application ID for which event type will be deleted
        in: header
        name: sub-application
        required: false
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Event subscription deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfEventSubscriptionDeleteResponse'
        '401':
          description: Unauthorized
        '404':
          description: Event subscription not found
  /institutions/constraints/payments:
    get:
      description: Retrieve institution specific constraints for payment authorisation and submission requests
      operationId: getPaymentConstraintsRulesByInstitution
      x-beta: true
      parameters:
      - description: Unique Id(s) of the `Institution`(s) to retrieve the Payment Constraints for. Multiple institutionIds
          need to be separated by `,`
        name: institutionIds
        required: true
        in: query
        schema:
          type: array
          items:
            type: string
      - description: Country code of the `Institution`(s). Ensure that the country code matches the respective institutionIds;
          any mismatch will result in an HTTP 404 error response.
        in: query
        name: institutionCountryCode
        required: true
        schema:
          type: string
      - description: Type of payment to retrieve payment constraints for
        in: query
        name: paymentType
        required: true
        schema:
          type: string
          enum:
          - DOMESTIC_PAYMENT
          - DOMESTIC_INSTANT_PAYMENT
          - DOMESTIC_VARIABLE_RECURRING_PAYMENT
          - DOMESTIC_SCHEDULED_PAYMENT
          - DOMESTIC_PERIODIC_PAYMENT
          - INTERNATIONAL_PAYMENT
          - INTERNATIONAL_SCHEDULED_PAYMENT
          - INTERNATIONAL_PERIODIC_PAYMENT
      - description: The path on the API that is associated with the operation for which constraints are to be retrieved
        in: query
        name: endpointPath
        required: false
        schema:
          type: string
      - description: The HTTP method that is associated with the operation for which constraints are to be retrieved
        in: query
        name: endpointMethod
        required: false
        schema:
          type: string
          enum:
          - POST
          - PATCH
          - PUT
          - GET
          - DELETE
      responses:
        '200':
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiListResponseOfPaymentConstraints'
          description: Ok
        '400':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/400-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Bad Request.
        '401':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/401-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Either authentication credentials were not supplied, or they were invalid.
        '404':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/404-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Not Found.
        '500':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/500-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Unexpected Error
      summary: Get Payment Constraints Rules
      tags:
      - Constraints
      x-mint:
        content: '<Info>Learn more: [Payment Constraints](/payments/payment-resources/payment-constraints) for institution-specific
          requirements</Info>'
  /institutions/constraints/data:
    get:
      description: Get Data Constraints Rules against an Institution for Account Authorisation requests
      operationId: getAccountConstraintsRulesByInstitution
      x-beta: true
      parameters:
      - description: Unique Id(s) of the `Institution`(s) to retrieve the Data Constraints for. Multiple institutionIds need
          to be separated by `,`
        name: institutionIds
        required: true
        in: query
        schema:
          type: array
          items:
            type: string
      - description: Country code of the `Institution`(s). Ensure that the country code matches the respective institutionIds;
          any mismatch will result in an HTTP 404 error response.
        in: query
        name: institutionCountryCode
        required: true
        schema:
          type: string
      - description: The path on the API that is associated with the operation for which constraints are to be retrieved
        in: query
        name: endpointPath
        required: false
        schema:
          type: string
      - description: The HTTP method that is associated with the operation for which constraints are to be retrieved
        in: query
        name: endpointMethod
        required: false
        schema:
          type: string
          enum:
          - POST
          - PATCH
          - PUT
          - GET
          - DELETE
      responses:
        '200':
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiListResponseOfDataConstraints'
          description: Ok
        '400':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/400-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Bad Request.
        '401':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/401-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Either authentication credentials were not supplied, or they were invalid.
        '404':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/404-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Not Found.
        '500':
          content:
            application/json;charset=UTF-8:
              examples:
                500 Error Response:
                  $ref: '#/components/examples/500-error-response'
              schema:
                $ref: '#/components/schemas/ApiResponseError'
          description: Unexpected Error
      summary: Get Data Constraints Rules
      tags:
      - Constraints
  /applications:
    post:
      description: Creates a sub-application under the given root application id provided in the authentication token. The
        sub-application can use the root's credentials to call the API
      summary: Creates a Sub-application for the Root Application Id Provided in the Authentication Token
      x-beta: true
      operationId: createSubApplication
      requestBody:
        description: The sub-application to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationRequest'
            examples:
              Create Sub-application Request:
                $ref: '#/components/examples/application-request'
      responses:
        '201':
          content:
            application/json;charset=UTF-8:
              examples:
                Create Sub-application Response:
                  $ref: '#/components/examples/application-response'
              schema:
                $ref: '#/components/schemas/ApiResponseOfApplicationResponse'
          description: Sub-application was successfully created
        '400':
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/application-error-response-code-400'
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
          description: There are validation errors
        '401':
          description: Either authentication credentials were not supplied, or they were invalid.
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/error-response-code-401'
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden from accessing the requested Application.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Application with given root id not found.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: An unexpected error occurred.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Application Management
      x-mint:
        content: '<Info>Learn more: [Application Management](/getting-started/application-management)</Info>'
    get:
      description: Retrieves sub-applications for the root application provided in the authentication token. If a sub-application
        is provided in the authentication token, it will return an empty list.
      summary: Retrieve Sub-applications for the Root Application Provided in the Authentication Token.
      x-beta: true
      operationId: searchApplications
      parameters:
      - $ref: '#/components/parameters/SearchApplicationsParameters'
      responses:
        '200':
          description: The sub-applications that are returned as part of the search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiListOfApplicationResponse'
              examples:
                Get Applications Response:
                  $ref: '#/components/examples/application-responses'
        '400':
          description: There are validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Either authentication credentials were not supplied, or they were invalid.
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/error-response-code-401'
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden from accessing the requested Application.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: An unexpected error occurred.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Application Management
  /applications/{applicationId}:
    get:
      description: Retrieves an application by the id provided in the path
      x-beta: true
      operationId: getApplicationById
      parameters:
      - in: path
        name: applicationId
        required: true
        schema:
          type: string
          format: uuid
        description: The id of the application being fetched
      responses:
        '200':
          content:
            application/json;charset=UTF-8:
              examples:
                Get Application By Id Response:
                  $ref: '#/components/examples/application-response'
              schema:
                $ref: '#/components/schemas/ApiResponseOfApplicationResponse'
          description: Application was successfully fetched
        '401':
          description: Either authentication credentials were not supplied, or they were invalid.
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/error-response-code-401'
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden from accessing the requested Application.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Application with given id not found.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: An unexpected error occurred.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Application Management
      summary: Get Application Details
    put:
      description: Updates the application properties for the application with the given ID in the path
      x-beta: true
      operationId: updateApplication
      parameters:
      - in: path
        name: applicationId
        required: true
        schema:
          type: string
          format: uuid
        description: The id of the application being updated
      requestBody:
        description: The application to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationRequest'
            examples:
              Update Application Request:
                $ref: '#/components/examples/application-request'
      responses:
        '200':
          content:
            application/json;charset=UTF-8:
              examples:
                Update Application Response:
                  $ref: '#/components/examples/application-response'
              schema:
                $ref: '#/components/schemas/ApiResponseOfApplicationResponse'
          description: Application was successfully updated
        '400':
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/application-error-response-code-400'
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
          description: There are validation errors
        '401':
          description: Either authentication credentials were not supplied, or they were invalid.
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/error-response-code-401'
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden from accessing the requested Application.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: An unexpected error occurred.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Application Management
      summary: Update an Application
    delete:
      description: Deletes the application with the given ID in the path
      x-beta: true
      operationId: deleteApplication
      parameters:
      - in: path
        name: applicationId
        required: true
        schema:
          type: string
          format: uuid
        description: The id of the application being deleted
      responses:
        '204':
          description: Application was successfully deleted
        '401':
          description: Either authentication credentials were not supplied, or they were invalid.
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/error-response-code-401'
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden from accessing the requested Application.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Application with given id not found.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: An unexpected error occurred.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Application Management
      summary: Delete an Application
  /applications/{applicationId}/vrp:
    post:
      description: Create application vrp configuration
      summary: Create Application Vrp Configuration by Application Id
      x-beta: true
      operationId: createApplicationVRPConfigurationByApplicationId
      parameters:
      - in: path
        name: applicationId
        required: true
        schema:
          type: string
          format: uuid
        description: The id of the application that vrp configuration being created for
      requestBody:
        description: The vrp configuration to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VrpConfiguration'
      responses:
        '201':
          description: Application vrp configuration was successfully created
        '400':
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/application-error-response-code-400'
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
          description: There are validation errors
        '401':
          description: Either authentication credentials were not supplied, or they were invalid.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              examples:
                401 Error Response:
                  $ref: '#/components/examples/401-error-response'
        '403':
          description: Forbidden from accessing the requested Application.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              examples:
                403 Error Response:
                  $ref: '#/components/examples/403-error-response'
        '404':
          description: VRP Configuration with given application id not found.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              examples:
                404 Error Response:
                  $ref: '#/components/examples/404-error-response'
        '500':
          description: An unexpected error occurred.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              examples:
                500 Error Response:
                  $ref: '#/components/examples/500-error-response'
      tags:
      - Application Management
    put:
      description: Update application vrp configuration
      summary: Update Application Vrp Configuration by Application Id
      x-beta: true
      operationId: updateApplicationVRPConfigurationByApplicationId
      parameters:
      - in: path
        name: applicationId
        required: true
        schema:
          type: string
          format: uuid
        description: The id of the application that vrp configuration being created for
      requestBody:
        description: The vrp configuration to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VrpConfiguration'
      responses:
        '201':
          description: Application vrp configuration was successfully updated
        '400':
          content:
            application/json;charset=UTF-8:
              examples:
                Error Response:
                  $ref: '#/components/examples/application-error-response-code-400'
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
          description: There are validation errors
        '401':
          description: Either authentication credentials were not supplied, or they were invalid.
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              examples:
                401 Error Response:
                  $ref: '#/components/examples/401-error-response'
        '403':
          description: Forbidden from accessing the requested Application.
          content:
            application/json;charset=UTF-8:


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