> ## Documentation Index > Fetch the complete documentation index at: https://docs.mnai.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Beneficiary by ID > Returns the beneficiary details for the authenticated Meridian account. ## OpenAPI ````yaml /products/meridian-accounts/api-reference/meridian-accounts.json get /v1/beneficiaries/{beneficiaryId} openapi: 3.1.1 info: title: Meridian API version: '1.0' description: API documentation for Meridian services contact: name: Meridian url: https://mnai.com email: support@mnai.com license: name: Proprietary url: https://mnai.com servers: - url: https://sandbox-api.va.meridianpay.com description: Sandbox - url: https://api.va.mnai.com description: Production security: [] paths: /v1/beneficiaries/{beneficiaryId}: get: tags: - Beneficiaries summary: Get Beneficiary by ID description: Returns the beneficiary details for the authenticated Meridian account. operationId: getBeneficiary parameters: - name: X-Meridian-Api-Key in: header description: >- Server-to-server (HMAC) requests only. Partner API key issued by Meridian during provisioning. schema: type: string example: your-api-key - name: X-Meridian-Timestamp in: header description: >- Server-to-server (HMAC) requests only. Current time in milliseconds since the Unix epoch. Must be within 60 seconds of the request. schema: type: string example: '1749566400000' - name: X-Meridian-Program-Id in: header description: >- Server-to-server (HMAC) requests only. Identifies the program context for the request. schema: type: string example: your-program-id - name: X-Meridian-User-Id in: header description: >- Server-to-server (HMAC) requests only. Identifies the Meridian user targeted by the request. Required for MULTI_USER integrations; omit for SINGLE_USER. schema: type: string example: user_123 - name: beneficiaryId in: path description: >- ID of the beneficiary — the `id` returned by `POST /v1/beneficiaries` or `GET /v1/beneficiaries`. required: true schema: type: string responses: '200': description: The beneficiary details for the authenticated account content: application/json: schema: $ref: '#/components/schemas/Beneficiary' examples: business_wallet_beneficiary: $ref: '#/components/examples/GetBeneficiaryBusinessWallet' '400': description: The requested beneficiary identifier is invalid content: application/json: schema: $ref: '#/components/schemas/MeridianError' '401': description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/MeridianError' '403': description: >- The authenticated caller is not permitted: JWT scope missing, or the partner API key lacks entitlement, user ownership, or user-type match content: application/json: schema: $ref: '#/components/schemas/MeridianError' '404': description: The requested beneficiary was not found content: application/json: schema: $ref: '#/components/schemas/MeridianError' security: - meridian-account-jwt: [] - partner-api-key: [] components: schemas: Beneficiary: type: object title: Beneficiary description: >- A beneficiary registered for the authenticated Meridian account. `type` selects the variant: `PERSON` or `BUSINESS`. required: - type properties: type: type: string description: Beneficiary type discriminator enum: - PERSON - BUSINESS discriminator: propertyName: type mapping: PERSON: $ref: '#/components/schemas/PersonBeneficiaryResponse' BUSINESS: $ref: '#/components/schemas/BusinessBeneficiaryResponse' MeridianError: type: object title: MeridianError description: >- Represents an error response from the Meridian API, including validation errors and an optional error code. required: - message properties: validationErrors: type: array description: >- An array of validation errors that occurred during the processing of the request. This field is optional and may be empty if there are no validation errors. items: $ref: '#/components/schemas/ValidationError' errorCode: type: string description: >- Machine-readable code identifying the failure. Absent when the failure is fully described by `validationErrors`. Clients should tolerate codes added in the future. enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - INVALID_REQUEST - INTERNAL_ERROR - INFORMATION_REQUEST_NOT_EDITABLE - INVALID_USER_TYPE - SINGLE_USER_KEY_NOT_ALLOWED - USER_ID_HEADER_REQUIRED - USER_ID_HEADER_NOT_ALLOWED - PDF_PAGE_LIMIT_EXCEEDED - PDF_PASSWORD_PROTECTED - PDF_UNREADABLE message: type: string description: >- A human-readable message describing the error. This field is required and should provide a clear explanation of the error that occurred. PersonBeneficiaryResponse: title: Person Beneficiary Response description: A person beneficiary allOf: - $ref: '#/components/schemas/Beneficiary' - type: object required: - id - counterpartyId - createdAt - updatedAt properties: id: type: string description: Unique identifier of the beneficiary example: uscp-01JMERBENEF001 counterpartyId: type: string description: Identifier of the underlying counterparty example: uscp-01JMERBENEF001 createdAt: type: string description: Timestamp when the beneficiary was created example: '2026-04-30T14:00:00Z' format: date-time updatedAt: type: string description: Timestamp when the beneficiary was last updated example: '2026-04-30T14:00:00Z' format: date-time firstName: type: - string - 'null' description: First name of the beneficiary lastName: type: - string - 'null' description: Last name of the beneficiary dateOfBirth: type: - string - 'null' description: Date of birth of the beneficiary format: date displayName: type: - string - 'null' description: Display name of the beneficiary email: type: - string - 'null' description: Email address of the beneficiary phoneNumber: type: - string - 'null' description: Phone number of the beneficiary address: oneOf: - $ref: '#/components/schemas/BeneficiaryAddress' - type: 'null' relationshipToUser: type: - string - 'null' description: Beneficiary's relationship to the account owner example: THIRD_PARTY enum: - SELF - THIRD_PARTY - null BusinessBeneficiaryResponse: title: Business Beneficiary Response description: A business beneficiary allOf: - $ref: '#/components/schemas/Beneficiary' - type: object required: - id - counterpartyId - createdAt - updatedAt properties: id: type: string description: Unique identifier of the beneficiary example: uscp-01JMERBENEF001 counterpartyId: type: string description: Identifier of the underlying counterparty example: uscp-01JMERBENEF001 createdAt: type: string description: Timestamp when the beneficiary was created example: '2026-04-30T14:00:00Z' format: date-time updatedAt: type: string description: Timestamp when the beneficiary was last updated example: '2026-04-30T14:00:00Z' format: date-time name: type: - string - 'null' description: Legal name of the beneficiary displayName: type: - string - 'null' description: Display name of the beneficiary email: type: - string - 'null' description: Email address of the beneficiary phoneNumber: type: - string - 'null' description: Phone number of the beneficiary address: oneOf: - $ref: '#/components/schemas/BeneficiaryAddress' - type: 'null' relationshipToUser: type: - string - 'null' description: Beneficiary's relationship to the account owner example: THIRD_PARTY enum: - SELF - THIRD_PARTY - null ValidationError: type: object title: ValidationError description: >- Represents a validation error that occurred during the processing of a request to the Meridian API. One of the following types of validation errors may be present: InvalidFormat, InvalidValue, MissingValue, UnprocessableValue, UnexpectedVerificationError, MissingRequestBody, MissingPathParameter, MissingQueryParameter, or NotFound. Each validation error includes a reference to the field that caused the error and a message describing the error. required: - type properties: type: type: string description: Identifies which ValidationError this is. enum: - InvalidFormat - InvalidValue - MissingPathParameter - MissingQueryParameter - MissingRequestBody - MissingValue - NotFound - UnexpectedVerificationError - Unknown - UnprocessableValue discriminator: propertyName: type mapping: InvalidFormat: $ref: '#/components/schemas/InvalidFormat' InvalidValue: $ref: '#/components/schemas/InvalidValue' MissingPathParameter: $ref: '#/components/schemas/MissingPathParameter' MissingQueryParameter: $ref: '#/components/schemas/MissingQueryParameter' MissingRequestBody: $ref: '#/components/schemas/MissingRequestBody' MissingValue: $ref: '#/components/schemas/MissingValue' NotFound: $ref: '#/components/schemas/NotFound' UnexpectedVerificationError: $ref: '#/components/schemas/UnexpectedVerificationError' Unknown: $ref: '#/components/schemas/Unknown' UnprocessableValue: $ref: '#/components/schemas/UnprocessableValue' BeneficiaryAddress: type: object title: Beneficiary Address description: >- Address of the beneficiary's bank. Required by RouteFusion for non-US bank countries; a missing field is reported as a field-level validation error on submission. required: - addressLine1 - city - postalCode - countryCode properties: addressLine1: type: string description: First line of the address example: 221B Baker Street city: type: string description: City example: London postalCode: type: string description: Postal or ZIP code example: NW1 6XE countryCode: type: string description: ISO 3166-1 alpha-2 country code example: GB addressLine2: type: - string - 'null' description: Second line of the address stateProvince: type: - string - 'null' description: State or province InvalidFormat: title: InvalidFormat description: The provided value exists, but its format is invalid for the field. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. InvalidValue: title: InvalidValue description: >- The provided value is syntactically valid, but not accepted for the field. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. MissingPathParameter: title: MissingPathParameter description: A required path parameter was not supplied. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. MissingQueryParameter: title: MissingQueryParameter description: A required query parameter was not supplied. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. MissingRequestBody: title: MissingRequestBody description: >- The request body is missing or does not contain the required non-null fields. allOf: - $ref: '#/components/schemas/ValidationError' - type: object properties: message: type: string description: A human-readable explanation of the validation failure. fieldRef: type: string description: The field or parameter that triggered the validation error. MissingValue: title: MissingValue description: A required value for the field was not provided. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. NotFound: title: NotFound description: The referenced principal object was not found. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. UnexpectedVerificationError: title: UnexpectedVerificationError description: A downstream verification step failed while checking the value. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. Unknown: title: Unknown description: >- A validation error occurred but the specific field could not be determined. allOf: - $ref: '#/components/schemas/ValidationError' - type: object properties: message: type: string description: A human-readable explanation of the validation failure. fieldRef: type: string description: The field or parameter that triggered the validation error. UnprocessableValue: title: UnprocessableValue description: The provided value cannot be processed into a valid result. allOf: - $ref: '#/components/schemas/ValidationError' - type: object required: - fieldRef properties: fieldRef: type: string description: The field or parameter that triggered the validation error. message: type: string description: A human-readable explanation of the validation failure. examples: GetBeneficiaryBusinessWallet: value: id: uspay-z2oaq71hlo7fhvck2xw0nidg counterpartyId: uspay-z2oaq71hlo7fhvck2xw0nidg createdAt: '2026-09-09T20:39:30Z' updatedAt: '2026-09-09T20:39:30Z' name: Nimbus Settlement Ltd displayName: Nimbus Settlement Ltd email: treasury@nimbus-settlement.com address: addressLine1: 25 Sir John Rogerson's Quay city: Dublin stateProvince: County Dublin postalCode: D02 XY45 countryCode: IE relationshipToUser: THIRD_PARTY type: BUSINESS securitySchemes: meridian-account-jwt: scheme: bearer bearerFormat: JWT description: >- Bearer token authentication, for client-server calls. Send the access token issued by `POST /v1/auth/token` as `Authorization: Bearer {token}`. The token carries its own program and user context, so the `X-Meridian-*` headers are not required. See [Authentication](/products/meridian-accounts/guides/authentication-overview). type: http partner-api-key: name: X-Meridian-Signature in: header description: >- Meridian HMAC header authentication, for server-to-server calls. Required headers: - `X-Meridian-Api-Key` - `X-Meridian-Timestamp` - `X-Meridian-Program-Id` - `X-Meridian-User-Id` (MULTI_USER integrations only) - `X-Meridian-Signature` `X-Meridian-Signature` is the HMAC SHA-256 signature of the canonical request string, computed per request. See [Authentication](/products/meridian-accounts/guides/authentication-overview) for how to construct it. type: apiKey ````