> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Beneficiaries

[@qonto/embed-sdk](../README) / beneficiaries

# Variable: beneficiaries

> `const` **beneficiaries**: `object`

The beneficiaries namespace contains all the client-side functions related to beneficiary operations.
This version uses proxy-based authentication (proxyEndpointDescriptor)
and is designed for browser environments.

For server-side operations using access tokens, import from `'@qonto/embed-sdk/server/beneficiaries'`.

It can be accessed like this:

```ts theme={null}
import { beneficiaries } from `'@qonto/embed-sdk/beneficiaries'`;
```

Then, the beneficiaries object contains the functions to perform beneficiary operations:

```ts theme={null}
await beneficiaries.getBeneficiaries({
  operationSettings: { proxyEndpointDescriptor }
});
await beneficiaries.getBeneficiary({
  beneficiarySettings: { beneficiaryId: '...' },
  operationSettings: { proxyEndpointDescriptor }
});
```

Note: The `trustBeneficiaries` function requires UI elements and is only
available in the client-side version.

## Type declaration

### addBeneficiary()

> **addBeneficiary**: (`addBeneficiaryParams`) => `Promise`\<[`Beneficiary`](../interfaces/Beneficiary)>

Adds a new beneficiary in the current user's account.

**Client-side only** - Uses proxy-based authentication.
For server-side operations, import from `'@qonto/embed-sdk/server/beneficiaries'`.

#### Parameters

##### addBeneficiaryParams

[`BeneficiaryClientParams`](../-internal-/interfaces/BeneficiaryClientParams)\<[`NewBeneficiary`](../-internal-/type-aliases/NewBeneficiary)>

An object containing:

* `beneficiarySettings`: An object with the new beneficiary details. Requires at
  least the `name` and `iban` properties to be present.
* `operationSettings`: An object with operation-level settings such as
  `proxyEndpointDescriptor` (required),
  `idempotencyKey`, and other optional parameters.

#### Returns

`Promise`\<[`Beneficiary`](../interfaces/Beneficiary)>

A promise that resolves to the created beneficiary.

#### Throws

`InvalidParametersError` If any required property is missing or invalid,
or if proxyEndpointDescriptor is not provided.

#### Throws

`EmbedApiError` If the API request fails or returns an error.

### getBeneficiaries()

> **getBeneficiaries**: (`getBeneficiariesParams?`) => `Promise`\<[`GetBeneficiariesResponse`](../-internal-/interfaces/GetBeneficiariesResponse)>

Fetches the list of beneficiaries for the current user.

**Client-side only** - Uses proxy-based authentication.
For server-side operations, import from `'@qonto/embed-sdk/server/beneficiaries'`.

#### Parameters

##### getBeneficiariesParams?

[`BeneficiaryClientParams`](../-internal-/interfaces/BeneficiaryClientParams)\<`never`>

An object containing:

* `operationSettings`: An object with operation-level settings such as
  `proxyEndpointDescriptor` (required),
  `paginationSettings`, and other optional parameters.

#### Returns

`Promise`\<[`GetBeneficiariesResponse`](../-internal-/interfaces/GetBeneficiariesResponse)>

A promise that resolves to an array of beneficiaries and a `meta`
object containing pagination state.

#### Throws

`InvalidParametersError` If proxyEndpointDescriptor is not provided.

#### Throws

`EmbedApiError` If the API request fails or returns an error.

### getBeneficiary()

> **getBeneficiary**: (`getBeneficiaryParams`) => `Promise`\<[`Beneficiary`](../interfaces/Beneficiary)>

Fetches a single beneficiary of the current user by ID.

**Client-side only** - Uses proxy-based authentication.
For server-side operations, import from `'@qonto/embed-sdk/server/beneficiaries'`.

#### Parameters

##### getBeneficiaryParams

[`BeneficiaryClientParams`](../-internal-/interfaces/BeneficiaryClientParams)\<\{ `beneficiaryId`: `string`; }>

An object containing:

* `beneficiarySettings`: An object with the `beneficiaryId` property (string).
* `operationSettings`: An object with operation-level settings such as
  `proxyEndpointDescriptor` (required).

#### Returns

`Promise`\<[`Beneficiary`](../interfaces/Beneficiary)>

A promise that resolves to a beneficiary.

#### Throws

`InvalidParametersError` If the `beneficiaryId` parameter is not a string or is missing,
or if proxyEndpointDescriptor is not provided.

#### Throws

`EmbedApiError` If the API request fails or returns an error.

### trustBeneficiaries()

> **trustBeneficiaries**: (`trustBeneficiariesParams`) => `Promise`\<[`Beneficiary`](../interfaces/Beneficiary)\[]>

Trusts a list of beneficiaries in the current user's account.

**Client-side only** - This function requires UI elements (iframe/SCA) and is only available
in the client-side version. It is not available in the server-side API.

#### Parameters

##### trustBeneficiariesParams

[`BeneficiaryClientParamsWithUI`](../-internal-/interfaces/BeneficiaryClientParamsWithUI)\<\{ `beneficiaryIds`: `string`\[]; }>

An object containing:

* `beneficiarySettings`: An object with the list of beneficiary IDs to
  trust (e.g., `{ beneficiaryIds: string[] }`).
* `operationSettings`: An object with operation-level settings such as
  `accessToken`, `stagingToken`, `uiParentElementId`, and other optional
  parameters.

#### Returns

`Promise`\<[`Beneficiary`](../interfaces/Beneficiary)\[]>

A promise that resolves to an array of trusted beneficiaries.

#### Throws

`AuthenticationError` If the access token is invalid or missing.
Ensure initialize has been called before using this function if you are not
passing the access token.

#### Throws

`InvalidParametersError` If the `beneficiaryIds` parameter is not an
array of strings or is missing.

#### Throws

`EmbedApiError` If the API request fails or returns an error.

### untrustBeneficiaries()

> **untrustBeneficiaries**: (`untrustBeneficiariesParams`) => `Promise`\<[`Beneficiary`](../interfaces/Beneficiary)\[]>

Untrusts a list of beneficiaries in the current user's account.

**Client-side only** - Uses proxy-based authentication.
For server-side operations, import from `'@qonto/embed-sdk/server/beneficiaries'`.

#### Parameters

##### untrustBeneficiariesParams

[`BeneficiaryClientParams`](../-internal-/interfaces/BeneficiaryClientParams)\<\{ `beneficiaryIds`: `string`\[]; }>

An object containing:

* `beneficiarySettings`: An object with the list of beneficiary IDs to
  untrust (e.g., `{ beneficiaryIds: string[] }`).
* `operationSettings`: An object with operation-level settings such as
  `proxyEndpointDescriptor` (required).

#### Returns

`Promise`\<[`Beneficiary`](../interfaces/Beneficiary)\[]>

A promise that resolves to an array of untrusted beneficiaries.

#### Throws

`InvalidParametersError` If the `beneficiaryIds` parameter is not an
array of strings or is missing, or if proxyEndpointDescriptor is not provided.

#### Throws

`EmbedApiError` If the API request fails or returns an error.

### updateBeneficiary()

> **updateBeneficiary**: (`updateBeneficiaryParams`) => `Promise`\<[`Beneficiary`](../interfaces/Beneficiary)>

Update any of the editable properties of a beneficiary in the current user's
account by ID.

**Client-side only** - Uses proxy-based authentication.
For server-side operations, import from `'@qonto/embed-sdk/server/beneficiaries'`.

#### Parameters

##### updateBeneficiaryParams

[`BeneficiaryClientParams`](../-internal-/interfaces/BeneficiaryClientParams)\<[`EditableBeneficiaryProperties`](../-internal-/type-aliases/EditableBeneficiaryProperties)>

An object containing:

* `beneficiarySettings`: An object that contains a mandatory beneficiary ID
  and any of the editable properties of a beneficiary, which are `name`,
  `email` and `activityTag`.
* `operationSettings`: An object with operation-level settings such as
  `proxyEndpointDescriptor` (required),
  `mfaPreference`, `idempotencyKey`, and other optional parameters.

#### Returns

`Promise`\<[`Beneficiary`](../interfaces/Beneficiary)>

A promise that resolves to the updated beneficiary.

#### Throws

`InvalidParametersError` If the beneficiary ID is missing or if none of the
editable properties (`name`, `email`, `activityTag`) are provided or are of incorrect type,
or if proxyEndpointDescriptor is not provided.

#### Throws

`EmbedApiError` If the API request fails or returns an error.