Bridge
Contact us
API reference · Moving money

Beneficiaries

Saved recipients with bulk import and validation. About beneficiaries Live

GET List the caller's beneficiaries

GET /beneficiary

Every filter is optional. Identifiers are masked here - the full destination is returned only on the save that created a beneficiary and on a single read of it.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Query parameters

NameDefault
kindOptional
statusOptional
groupReferenceOptional
modeOptional
searchOptional
page0
size20
organizationReferenceOptional

Example

Response: BeneficiaryPageResponse

curl -X GET "https://api.bridgemoni.com/beneficiary?kind=value&status=value&groupReference=value&mode=value&search=value&page=0&size=20&organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Beneficiaries retrieved

POST Save a beneficiary

POST /beneficiary

Saves a counterparty so it can be paid again without re-typing it. The counterparty's name is never supplied by the caller - it is resolved and returned, which is the point of saving one. Saving a counterparty you have already saved returns the existing beneficiary and a 200, not a conflict: a double tap on a phone is a network artefact rather than a mistake. A newly saved beneficiary starts inside a cooling-off window and the holder is notified that it was added.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Example

Request body: SaveBeneficiaryRequest · Response: BeneficiaryResponse

curl -X POST "https://api.bridgemoni.com/beneficiary" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "BRIDGE_USER",
    "alias": "Ada Obi",
    "favourite": true,
    "groupReferences": [
      "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e"
    ],
    "organizationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "identifierType": "ACCOUNT_NUMBER",
    "identifier": "March payroll",
    "communityReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "accountNumber": "March payroll",
    "msisdn": "March payroll",
    "providerCode": "provider code",
    "providerName": "Ada Obi",
    "countryCode": "NG",
    "currencyCode": "NGN",
    "productCode": "Ada Obi",
    "customerIdentifier": "March payroll",
    "cardToken": "March payroll",
    "cardScheme": "Ada Obi",
    "cardLast4": "Ada Obi",
    "cardExpiryMonth": 1,
    "cardExpiryYear": 1,
    "cryptoAddress": "March payroll",
    "cryptoNetwork": "Ada Obi"
  }'

Responses

StatusWhen
200Beneficiary saved

GET List the caller's beneficiary groups

GET /beneficiary/group

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Query parameters

NameDefault
organizationReferenceOptional

Example

Response: List<BeneficiaryGroupResponse>

curl -X GET "https://api.bridgemoni.com/beneficiary/group?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Beneficiary groups retrieved

POST Create a beneficiary group

POST /beneficiary/group

Names are unique per holder, ignoring case - otherwise a picker shows "Family" twice and neither entry is obviously the right one.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Query parameters

NameDefault
organizationReferenceOptional

Example

Request body: BeneficiaryGroupRequest · Response: BeneficiaryGroupResponse

curl -X POST "https://api.bridgemoni.com/beneficiary/group?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Obi",
    "description": "March payroll"
  }'

Responses

StatusWhen
200Beneficiary group created

DELETE Delete a beneficiary group

DELETE /beneficiary/group/{reference}

Deletes the folder, never its contents. A beneficiary that was only in this group becomes ungrouped and is otherwise untouched - tidying a picker must never be a way to lose a payee.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Response: Void

curl -X DELETE "https://api.bridgemoni.com/beneficiary/group/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Beneficiary group deleted

PUT Rename or re-describe a beneficiary group

PUT /beneficiary/group/{reference}

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Request body: BeneficiaryGroupRequest · Response: BeneficiaryGroupResponse

curl -X PUT "https://api.bridgemoni.com/beneficiary/group/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Obi",
    "description": "March payroll"
  }'

Responses

StatusWhen
200Beneficiary group updated

POST Import several beneficiaries

POST /beneficiary/import

Saves up to fifty counterparties in one request. Each row is exactly a single save - the same resolution, deduplication, cooling-off window and limits - so an import can never produce a payee a single save would have refused. One bad row does not fail the batch: the response reports every row's outcome in the order they were sent, and a 200 means the request was well formed rather than that every row succeeded. The row cap is a security bound, not a performance one: every row is a name enquiry with the institution that holds the account.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Example

Request body: ImportBeneficiariesRequest · Response: ImportBeneficiariesResponse

curl -X POST "https://api.bridgemoni.com/beneficiary/import" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaries": [
      {
        "kind": "BRIDGE_USER",
        "alias": "Ada Obi",
        "favourite": true,
        "groupReferences": [
          "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e"
        ],
        "organizationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "identifierType": "ACCOUNT_NUMBER",
        "identifier": "March payroll",
        "communityReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "accountNumber": "March payroll",
        "msisdn": "March payroll",
        "providerCode": "provider code",
        "providerName": "Ada Obi",
        "countryCode": "NG",
        "currencyCode": "NGN",
        "productCode": "Ada Obi",
        "customerIdentifier": "March payroll",
        "cardToken": "March payroll",
        "cardScheme": "Ada Obi",
        "cardLast4": "Ada Obi",
        "cardExpiryMonth": 1,
        "cardExpiryYear": 1,
        "cryptoAddress": "March payroll",
        "cryptoNetwork": "Ada Obi"
      }
    ],
    "organizationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e"
  }'

Responses

StatusWhen
200Import processed

POST Save a beneficiary from a payment receipt

POST /beneficiary/payment

Saves the payee of a payment already made, using the saveBeneficiaryToken that payment's response carried. For the holder who did not decide at the time - the same operation as the saveBeneficiary flag, reached from the receipt instead. Where the money went is not a parameter: it comes out of the signed token, so what gets saved is provably what the payment reached rather than something the caller described. The token lasts fifteen minutes and is usable only by the holder who made the payment. Redeeming the same token twice returns the same beneficiary rather than a second one.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Example

Request body: SaveBeneficiaryFromPaymentRequest · Response: BeneficiaryResponse

curl -X POST "https://api.bridgemoni.com/beneficiary/payment" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "saveBeneficiaryToken": "text",
    "alias": "Ada Obi",
    "favourite": true
  }'

Responses

StatusWhen
200Beneficiary saved

GET Recent beneficiaries

GET /beneficiary/recent

A bounded, unpaged picker feed. basis=ADDED answers 'who have I just added?' and is the confirmation feed after a save; basis=PAID answers 'who do I keep paying?' and is the top of a payment screen. A limit above the tenant's maximum is refused rather than clamped - a client asking for five hundred has a bug, and clamping hides it.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Query parameters

NameDefault
basisOptional
kindOptional
limitOptional
organizationReferenceOptional

Example

Response: RecentBeneficiariesResponse

curl -X GET "https://api.bridgemoni.com/beneficiary/recent?basis=value&kind=value&limit=value&organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Recent beneficiaries retrieved

DELETE Delete a beneficiary

DELETE /beneficiary/{reference}

Archives rather than removes - payment history still refers to it, and a receipt from six months ago still has to resolve a name. Saving the same counterparty again afterwards creates a genuinely new beneficiary with a fresh cooling-off window, rather than reviving this one.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Response: BeneficiaryResponse

curl -X DELETE "https://api.bridgemoni.com/beneficiary/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Beneficiary deleted

GET Read one beneficiary

GET /beneficiary/{reference}

One of only two responses that carry the destination in full, because a holder confirming they are about to pay the right account needs to see it.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Response: BeneficiaryResponse

curl -X GET "https://api.bridgemoni.com/beneficiary/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Beneficiary retrieved

PATCH Amend a beneficiary

PATCH /beneficiary/{reference}

Alias, favourite and groups only. Where money goes can never be edited: changing a destination would carry the cooling-off window, the trust level and the whole payment history onto a payee the holder has never paid. To change a destination, delete this beneficiary and save the new one.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Request body: UpdateBeneficiaryRequest · Response: BeneficiaryResponse

curl -X PATCH "https://api.bridgemoni.com/beneficiary/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Ada Obi",
    "favourite": true,
    "groupReferences": [
      "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e"
    ]
  }'

Responses

StatusWhen
200Beneficiary updated

POST Accept a changed counterparty name

POST /beneficiary/{reference}/confirm-name

Clears STALE on a beneficiary whose counterparty name changed underneath it, returning it to ACTIVE and payable. The new name must be echoed back exactly as returned: a flag could be sent by a client that never showed the holder what changed, and what changed here is who the money reaches. Its own endpoint rather than a PATCH field, because PATCH never touches verification state and this is not a cosmetic edit. Needs a validated PIN.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Request body: ConfirmBeneficiaryNameRequest · Response: BeneficiaryResponse

curl -X POST "https://api.bridgemoni.com/beneficiary/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/confirm-name?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "acceptResolvedName": "Ada Obi"
  }'

Responses

StatusWhen
200Name confirmed

POST Freeze a beneficiary

POST /beneficiary/{reference}/restrict

Stops this payee being paid until it is unfrozen. Deliberately needs no PIN: freezing only ever removes capability, and somebody who has just seen a payment they do not recognise should not have to find their PIN before they can stop the next one. Unfreezing does need one. Reachable from any live beneficiary, including a brand new one - a payee added an hour ago is the one most likely to want stopping.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Response: BeneficiaryResponse

curl -X POST "https://api.bridgemoni.com/beneficiary/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/restrict?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Beneficiary frozen

POST Mark a beneficiary trusted

POST /beneficiary/{reference}/trust

Reduces the friction of paying a counterparty you have an established relationship with. Reachable only from an ESTABLISHED beneficiary - one whose cooling-off window has passed and which you have successfully paid at least once. Trust is what a relationship earns; a payee that could be trusted on the day it was added would hand anyone holding your session the whole ladder in one request. Needs a validated PIN and an explicit confirmation echo.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Request body: TrustBeneficiaryRequest · Response: BeneficiaryResponse

curl -X POST "https://api.bridgemoni.com/beneficiary/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/trust?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmation": "text"
  }'

Responses

StatusWhen
200Beneficiary trusted

POST Unfreeze a beneficiary

POST /beneficiary/{reference}/unrestrict

Lifts a freeze you placed. A freeze placed by a compliance review is refused here and says so plainly - a holder who could lift one would make it decorative. Needs a validated PIN, because this is the direction that restores capability. The beneficiary returns to NEW and the cooling-off sweep re-establishes it on the same rules as the first time, rather than being handed back a trust level it held before you were worried about it.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Response: BeneficiaryResponse

curl -X POST "https://api.bridgemoni.com/beneficiary/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/unrestrict?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Beneficiary unfrozen

POST Re-verify a beneficiary

POST /beneficiary/{reference}/verify

Asks again whether the destination still resolves, and to the same name. This is the recovery path for a beneficiary saved while its rail was unreachable, and the detection path for a counterparty whose name has changed underneath it.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Query parameters

NameDefault
organizationReferenceOptional

Example

Response: VerifyBeneficiaryResponse

curl -X POST "https://api.bridgemoni.com/beneficiary/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/verify?organizationReference=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Beneficiary re-verified

Generated from the OpenAPI document. Branch on the HTTP status: there is no machine-readable error code on the wire. Errors