Yapily

Yapily User Beneficiaries API

User Beneficiaries Endpoints

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.yapily.com/
📖
Documentation
https://docs.yapily.com/payments/vrps/additional-information

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/yapily/refs/heads/main/openapi/yapily-user-beneficiaries-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/yapily/refs/heads/main/json-schema/yapily-account-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/yapily/refs/heads/main/json-schema/yapily-transaction-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/yapily/refs/heads/main/json-schema/yapily-account-balance-schema.json
📊
JSONStructure
https://raw.githubusercontent.com/api-evangelist/yapily/refs/heads/main/json-structure/yapily-account-structure.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/yapily/refs/heads/main/json-ld/yapily-context.jsonld
🔗
Examples
https://raw.githubusercontent.com/api-evangelist/yapily/refs/heads/main/examples/yapily-get-account-transactions-example.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/yapily-user-beneficiaries-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

yapily-user-beneficiaries-api-openapi.yml Raw ↑ 
openapi: 3.0.1
info:
  title: Yapily Beneficiaries Application Beneficiaries User Beneficiaries API
  description: Application and User Beneficiaries endpoints for managing reusable payment counterparties.
  version: 12.4.0
  contact:
    name: Yapily Support
    url: https://docs.yapily.com/resources/support
    email: support@yapily.com
servers:
- url: https://api.yapily.com
security:
- basicAuth: []
tags:
- description: User Beneficiaries Endpoints
  name: User Beneficiaries
paths:
  /users/{userId}/beneficiaries:
    post:
      tags:
      - User Beneficiaries
      operationId: createUserBeneficiary
      summary: Create Beneficiary
      description: Creation of beneficiaries for a given application User.
      parameters:
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/SubAppHeader'
      requestBody:
        required: true
        description: The beneficiary to be created.
        content:
          application/json:
            schema:
              type: object
              description: User Beneficiary details.
              required:
              - name
              - accountIdentifier
              properties:
                name:
                  type: string
                  description: name of the beneficiary
                  example: John Doe
                accountIdentifier:
                  $ref: '#/components/schemas/AccountIdentifier'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBeneficiaryResponse'
        '400':
          description: Invalid request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Unauthorized
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '404':
          description: Not Found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '409':
          description: Conflict
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '429':
          description: Too many requests
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '500':
          description: Internal error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
      x-mint:
        content: '<Info>Learn more: [Verification of Payee](/payments/payment-resources/verification-of-payee)</Info>'
    get:
      tags:
      - User Beneficiaries
      operationId: getUserBeneficiaries
      summary: Get All Users Beneficiaries
      description: Get all users beneficiaries from an userId.
      parameters:
      - $ref: '#/components/parameters/UserIdPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: The user beneficiary response.
                properties:
                  meta:
                    $ref: '#/components/schemas/ResponseListMeta'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserBeneficiaryData'
        '400':
          description: Invalid request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Unauthorized
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '404':
          description: Not Found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '500':
          description: Internal error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
  /users/{userId}/beneficiaries/{beneficiaryId}:
    patch:
      tags:
      - User Beneficiaries
      operationId: patchUserBeneficiary
      summary: Patch User Beneficiary
      description: Patch the beneficiary details for a given application user and beneficiary
      parameters:
      - $ref: '#/components/parameters/BeneficiaryIdPath'
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/SubAppHeader'
      requestBody:
        description: The JSON Patch instructions to patch the beneficiary
        required: true
        content:
          application/json-patch+json:
            schema:
              type: array
              items:
                description: Patch details to be applied to user.
                type: object
                required:
                - op
                - path
                - value
                properties:
                  op:
                    $ref: '#/components/schemas/PatchOperation'
                  path:
                    type: string
                    description: The path to the target location
                  value:
                    type: string
                    description: The value to be added, replaced or tested
            examples:
              update-name:
                summary: Updating beneficiary name
                value:
                - op: replace
                  path: /name
                  value: John Doe
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBeneficiaryResponse'
        '400':
          description: Invalid request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Unauthorized
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '404':
          description: Not Found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '409':
          description: Conflict
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '429':
          description: Too many requests
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '500':
          description: Internal error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
    get:
      tags:
      - User Beneficiaries
      operationId: getUserBeneficiary
      summary: Get Beneficiary by Id
      description: Get user beneficiary by id.
      parameters:
      - $ref: '#/components/parameters/BeneficiaryIdPath'
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/SubAppHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBeneficiaryResponse'
        '400':
          description: Invalid request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Unauthorized
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '429':
          description: Too many requests
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '500':
          description: Internal error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
    delete:
      tags:
      - User Beneficiaries
      operationId: deleteUserBeneficiary
      summary: Delete User Beneficiary by Id.
      description: Delete user beneficiary by id.
      parameters:
      - $ref: '#/components/parameters/BeneficiaryIdPath'
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/SubAppHeader'
      responses:
        '204':
          description: No Content.
        '400':
          description: Invalid request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Unauthorized
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '429':
          description: Too many requests
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '500':
          description: Internal error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
  /users/{userId}/beneficiaries/{beneficiaryId}/approve:
    post:
      tags:
      - User Beneficiaries
      operationId: approveBeneficiary
      summary: Approve Beneficiary
      description: End-user has approved the beneficiary details
      parameters:
      - $ref: '#/components/parameters/BeneficiaryIdPath'
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/SubAppHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBeneficiaryValidationRequest'
            example:
              name: John Doe
              match:
                status: FULL_MATCH
              accountIdentifier:
                type: IBAN
                identification: GB33BUKB2020155555555
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBeneficiaryResponse'
              example:
                meta:
                  tracingId: e7b7636d-a041-4013-8a1b-34dc85b7d341
                data:
                  beneficiaryId: a5cc1d07-dd0b-469f-8ebd-f580e8314efd
                  status: VERIFIED
                  details:
                    name: John Doe
                    match:
                      status: FULL_MATCH
                    accountIdentifier:
                      type: IBAN
                      identification: GB33BUKB2020155555555
        '400':
          description: Invalid request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Unauthorized
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '404':
          description: Not Found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '429':
          description: Too many requests
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '500':
          description: Internal error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
      x-mint:
        content: '<Info>Learn more: [Verification of Payee](/payments/payment-resources/verification-of-payee)</Info>'
  /users/{userId}/beneficiaries/{beneficiaryId}/reject:
    post:
      tags:
      - User Beneficiaries
      operationId: rejectBeneficiary
      summary: Reject Beneficiary
      description: End-user has rejected the beneficiary details
      parameters:
      - $ref: '#/components/parameters/BeneficiaryIdPath'
      - $ref: '#/components/parameters/UserIdPath'
      - $ref: '#/components/parameters/SubAppHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBeneficiaryValidationRequest'
            example:
              meta:
                tracingId: e7b7636d-a041-4013-8a1b-34dc85b7d341
              data:
                beneficiaryId: a5cc1d07-dd0b-469f-8ebd-f580e8314efd
                details:
                  name: Albert
                  match:
                    status: NO_MATCH
                  accountIdentifier:
                    type: IBAN
                    identification: GB33BUKB2020155555555
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBeneficiaryResponse'
              example:
                meta:
                  tracingId: e7b7636d-a041-4013-8a1b-34dc85b7d341
                data:
                  beneficiaryId: a5cc1d07-dd0b-469f-8ebd-f580e8314efd
                  status: REJECTED
                  details:
                    name: Albert
                    match:
                      status: NO_MATCH
                    accountIdentifier:
                      type: IBAN
                      identification: GB33BUKB2020155555555
        '400':
          description: Invalid request
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '401':
          description: Unauthorized
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '404':
          description: Not Found
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
        '500':
          description: Internal error
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseV2'
              examples:
                Example-1:
                  $ref: '#/components/examples/400-error-response'
      x-mint:
        content: '<Info>Learn more: [Verification of Payee](/payments/payment-resources/verification-of-payee)</Info>'
components:
  schemas:
    SortEnum:
      type: string
      description: The attribute on which resources / records returned should be sorted. Valid options for the sort parameter.
      enum:
      - date
      - -date
    Next:
      type: object
      properties:
        from:
          type: string
          format: date-time
        before:
          type: string
          format: date-time
        limit:
          type: integer
          format: int32
        cursor:
          type: string
    FilterAndSort:
      type: object
      properties:
        from:
          type: string
          description: __Optional__. The earliest date and time of resources / records that should be returned.
          format: date-time
        before:
          type: string
          description: __Optional__. The latest date and time of resources / records that should be returned.
          format: date-time
        limit:
          type: integer
          description: __Optional__. The maximum number of resources / records that should be returned.
          format: int32
        sort:
          $ref: '#/components/schemas/SortEnum'
        offset:
          type: integer
          format: int32
        cursor:
          type: string
    ResponseMeta:
      type: object
      properties:
        tracingId:
          type: string
    ResponseListMeta:
      type: object
      properties:
        tracingId:
          type: string
        count:
          type: integer
          format: int32
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      properties:
        totalCount:
          type: integer
          format: int64
        self:
          $ref: '#/components/schemas/FilterAndSort'
        next:
          $ref: '#/components/schemas/Next'
    BeneficiaryMatchStatus:
      type: string
      enum:
      - FULL_MATCH
      - CLOSE_MATCH
      - NO_MATCH
      - EXEMPTED
      - VERIFICATION_CHECK_NOT_POSSIBLE
    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
    PatchOperation:
      type: string
      description: The operation to be performed
      enum:
      - add
      - replace
    AccountIdentifier:
      type: object
      description: Account's details.
      required:
      - identification
      - type
      properties:
        type:
          $ref: '#/components/schemas/AccountIdentifierType'
        identification:
          type: string
          description: Account's IBAN
          example: DE12345123451234512345123
    UserBeneficiaryMatch:
      type: object
      description: Details of the match given by the institution.
      properties:
        status:
          $ref: '#/components/schemas/BeneficiaryMatchStatus'
        closeMatchName:
          type: string
          example: John Doe
          description: the name returned by the institution, in a case of CLOSE_MATCH
    UserBeneficiaryValidationRequest:
      type: object
      description: Beneficiary request with the details of the VoP result.
      required:
      - name
      - accountIdentifier
      properties:
        name:
          type: string
          description: name of the beneficiary
          example: John Doe
        match:
          $ref: '#/components/schemas/UserBeneficiaryMatch'
        accountIdentifier:
          $ref: '#/components/schemas/AccountIdentifier'
    UserBeneficiaryData:
      type: object
      description: Beneficiary data response.
      properties:
        beneficiaryId:
          type: string
          format: uuid
          example: e7b7636d-a041-4013-8a1b-34dc85b7d341
          description: id of the beneficiary
        status:
          $ref: '#/components/schemas/BeneficiaryStatus'
        details:
          description: Beneficiary response with the details of the VoP result.
          required:
          - name
          - accountIdentifier
          properties:
            name:
              type: string
              description: name of the beneficiary
              example: John Doe
            match:
              $ref: '#/components/schemas/UserBeneficiaryMatch'
            accountIdentifier:
              $ref: '#/components/schemas/AccountIdentifier'
    UserBeneficiaryResponse:
      type: object
      description: The user beneficiary response.
      properties:
        meta:
          $ref: '#/components/schemas/ResponseMeta'
        data:
          $ref: '#/components/schemas/UserBeneficiaryData'
    BeneficiaryStatus:
      description: Status of the beneficiary check.
      type: string
      enum:
      - PENDING
      - VERIFIED
      - REJECTED
    AccountIdentifierType:
      type: string
      enum:
      - IBAN
  securitySchemes:
    basicAuth:
      description: Use HTTP Basic Authentication with your Application ID as username and Application Secret as password. Manage credentials in the [Yapily Console](https://console.yapily.com/). See [Authentication](/api-reference/authentication) for details.
      scheme: basic
      type: http