API reference · Platform & integration

Referrals

GET/referral/attribution/{reference}Get a referral
GET/referral/attributionsSearch referrals
POST/referral/claimAdd a referral code after signing up
GET/referral/code/{code}Check a referral code
POST/referral/inviteInvite a friend by SMS or email
POST/referral/invite/unsubscribeStop invites to an address
GET/referral/meGet my referral code
GET/referral/me/earningsMy referral earnings statement
GET/referral/me/invitesList my invites
GET/referral/me/referralsList the people I referred
GET/referral/me/referrerSee who referred me
GET/referral/programRead the referral programme

GET Get a referral

GET /referral/attribution/{reference}

One referral with every check that was run on it, how it was reviewed, and what it has earned, is waiting to be paid, and has been paid.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: GenericResponseReferralAttributionRecordResponse

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

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "PENDING_QUALIFICATION",
    "source": "REGISTRATION",
    "referrerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "refereeUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "codeReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "programVersion": 0,
    "flagged": true,
    "statusReason": "string",
    "attributionReason": "string",
    "attributedBy": "string",
    "attributedAt": "2026-09-25T10:00:00Z",
    "qualifiesBy": "2026-09-25T10:00:00Z",
    "qualifiedAt": "2026-09-25T10:00:00Z",
    "earnsUntil": "2026-09-25T10:00:00Z",
    "closedAt": "2026-09-25T10:00:00Z",
    "reviewOutcome": "CLEARED",
    "reviewReason": "string",
    "reviewedBy": "string",
    "reviewedAt": "2026-09-25T10:00:00Z",
    "revokedBy": "string",
    "fraudCaseReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "checks": [
      {
        "checkType": "SAME_DEVICE",
        "outcome": "FLAG",
        "detail": "both parties signed in from the same device",
        "checkedAt": "2026-09-25T10:00:00Z"
      }
    ],
    "earnings": [
      {
        "currencyCode": "NGN",
        "pending": 412.5,
        "released": 3187.25,
        "carriedForward": 0.0
      }
    ]
  },
  "description": "Referral fetched"
}

Responses

Status	When
`200`	Referral fetched
`404`	Referral not found

GET Search referrals

GET /referral/attributions

Every referral in the tenant, newest first, including refused and revoked ones. Filter by either party, by status, or to flagged referrals waiting for review.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`referrerUserReference`	Optional
`refereeUserReference`	Optional
`status`	Optional
`flagged`	Optional
`page`	0
`size`	20

Example

Response: GenericResponsePagerReferralAttributionRecordResponse

curl -X GET "https://api.bridgemoni.com/referral/attributions?page=value&size=20" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "content": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "status": "PENDING_QUALIFICATION",
        "source": "REGISTRATION",
        "referrerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "refereeUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "codeReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "programVersion": 0,
        "flagged": true,
        "statusReason": "string",
        "attributionReason": "string",
        "attributedBy": "string",
        "attributedAt": "2026-09-25T10:00:00Z",
        "qualifiesBy": "2026-09-25T10:00:00Z",
        "qualifiedAt": "2026-09-25T10:00:00Z",
        "earnsUntil": "2026-09-25T10:00:00Z",
        "closedAt": "2026-09-25T10:00:00Z",
        "reviewOutcome": "CLEARED",
        "reviewReason": "string",
        "reviewedBy": "string",
        "reviewedAt": "2026-09-25T10:00:00Z",
        "revokedBy": "string",
        "fraudCaseReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "checks": [
          {
            "checkType": "SAME_DEVICE",
            "outcome": "FLAG",
            "detail": "both parties signed in from the same device",
            "checkedAt": "2026-09-25T10:00:00Z"
          }
        ],
        "earnings": [
          {
            "currencyCode": "NGN",
            "pending": 412.5,
            "released": 3187.25,
            "carriedForward": 0.0
          }
        ]
      }
    ],
    "page": "1",
    "size": "1",
    "totalPages": "1",
    "totalElements": "1"
  },
  "description": "Referrals fetched"
}

Responses

Status	When
`200`	Referrals fetched

POST Add a referral code after signing up

POST /referral/claim

Credits the person who invited the caller, if the caller did not enter their code at sign-up. Allowed only within the programme's claim window after sign-up, and only once.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: ReferralClaimRequest · Response: GenericResponseReferralAttributionResponse

curl -X POST "https://api.bridgemoni.com/referral/claim" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "K7QM4XRD"
}'

{
  "code": "K7QM4XRD"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "PENDING_QUALIFICATION",
    "source": "REGISTRATION",
    "referrerDisplayName": "Tolu A.",
    "attributedAt": "2026-09-25T10:00:00Z",
    "qualifiesBy": "2026-09-25T10:00:00Z",
    "qualifiedAt": "2026-09-25T10:00:00Z",
    "earnsUntil": "2026-09-25T10:00:00Z"
  },
  "description": "Referral recorded"
}

Responses

Status	When
`200`	Referral recorded
`400`	That referral code cannot be used
`409`	You have already been referred; It is too late to add a referral code

GET Check a referral code

GET /referral/code/{code}

For the tenant's backend, before a customer submits sign-up. Answers valid or not valid only: it never names the code's owner and never says why a code cannot be used. Rate limited per caller.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`code`

Example

Response: GenericResponseReferralCodeCheckResponse

curl -X GET "https://api.bridgemoni.com/referral/code/value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "code": "K7QM4XRD",
    "valid": true,
    "model": "REVENUE_SHARE",
    "termMonths": 12
  },
  "description": "Referral code checked"
}

Responses

Status	When
`200`	Referral code checked
`429`	Too many requests

POST Invite a friend by SMS or email

POST /referral/invite

Sends the tenant's invite message, carrying the caller's first name and initial, their code and share link. The caller adds no text of their own. The answer is the same whether or not a message was actually sent: a person who is already a customer, or who has opted out of invites, gets nothing, and the caller is not told, so this endpoint cannot be used to find out who banks here. If the friend signs up with that number or address without typing a code, the first person to invite them is credited.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: ReferralInviteRequest · Response: GenericResponseReferralInviteResponse

curl -X POST "https://api.bridgemoni.com/referral/invite" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "SMS",
  "destination": "2348030000001"
}'

{
  "channel": "SMS",
  "destination": "2348030000001"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "channel": "SMS",
    "destinationMasked": "234803****001",
    "status": "SENT",
    "sentAt": "2026-09-25T10:00:00Z",
    "expiresAt": "2026-09-25T10:00:00Z",
    "joinedAt": "2026-09-25T10:00:00Z"
  },
  "description": "Invite sent"
}

Responses

Status	When
`200`	Invite sent
`400`	That is not a number or address we can invite; Invites cannot be sent that way here
`403`	You cannot refer others yet
`409`	You have already invited them
`429`	You have sent as many invites as you can for now
`503`	The invite could not be sent

POST Stop invites to an address

POST /referral/invite/unsubscribe

For the tenant's backend, called from its own unsubscribe page with the token from an invite email. Stops invites to that address from every referrer in the tenant, permanently. An unknown token gets the same answer.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: ReferralInviteUnsubscribeRequest · Response: GenericResponseReferralInviteUnsubscribeResponse

curl -X POST "https://api.bridgemoni.com/referral/invite/unsubscribe" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "string"
}'

{
  "token": "string"
}

{
  "data": {
    "suppressed": true
  },
  "description": "Unsubscribed from invites"
}

Responses

Status	When
`200`	Unsubscribed from invites

GET Get my referral code

GET /referral/me

The caller's referral code, share link and referrals by status. The caller is resolved from the session; there is no way to name another customer. A code is issued on the first call by an eligible customer and stays the same after that. A customer below the programme's KYC tier gets eligible=false and the tier they need.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Example

Response: GenericResponseReferralSummaryResponse

curl -X GET "https://api.bridgemoni.com/referral/me" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "eligible": true,
    "requiredTier": 1,
    "code": "K7QM4XRD",
    "shareUrl": "https://app.example.com/r/K7QM4XRD",
    "programSummary": "Earn 10% of the fees your referrals pay for 12 months",
    "rate": 0.1,
    "termMonths": 12,
    "referrals": {
      "PENDING_QUALIFICATION": 2,
      "ACTIVE": 5
    },
    "earnings": [
      {
        "currencyCode": "NGN",
        "pending": 412.5,
        "released": 3187.25,
        "carriedForward": 0.0
      }
    ]
  },
  "description": "Referral summary fetched"
}

Responses

Status	When
`200`	Referral summary fetched
`404`	There is no referral programme here; No account holder for this session

GET My referral earnings statement

GET /referral/me/earnings

Earnings per referee per month between two dates, and the payouts made in that time. A month is the finest grain shown, so a statement never reveals what anyone spent. At most a year at a time. Trial-mode figures are not shown - nothing was owed.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`from`	Optional
`to`	Optional

Example

Response: GenericResponseReferralStatementResponse

curl -X GET "https://api.bridgemoni.com/referral/me/earnings?from=value&to=value" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "from": "2026-09-25",
    "to": "2026-09-25",
    "lines": [
      {
        "month": "2026-10",
        "refereeDisplayName": "Kemi O.",
        "currencyCode": "NGN",
        "commission": 1240.0,
        "capped": true
      }
    ],
    "releases": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "currencyCode": "NGN",
        "amount": 980.0,
        "walletAccountNumber": "******0199",
        "paidAt": "2026-09-25T10:00:00Z"
      }
    ]
  },
  "description": "Referral earnings fetched"
}

Responses

Status	When
`200`	Referral earnings fetched
`400`	That period cannot be shown

GET List my invites

GET /referral/me/invites

Newest first, with the destination masked. Reads SENT, JOINED or EXPIRED only.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`page`	0
`size`	20

Example

Response: GenericResponsePagerReferralInviteResponse

curl -X GET "https://api.bridgemoni.com/referral/me/invites?page=value&size=20" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "content": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "channel": "SMS",
        "destinationMasked": "234803****001",
        "status": "SENT",
        "sentAt": "2026-09-25T10:00:00Z",
        "expiresAt": "2026-09-25T10:00:00Z",
        "joinedAt": "2026-09-25T10:00:00Z"
      }
    ],
    "page": "1",
    "size": "1",
    "totalPages": "1",
    "totalElements": "1"
  },
  "description": "Invites fetched"
}

Responses

Status	When
`200`	Invites fetched

GET List the people I referred

GET /referral/me/referrals

Newest first. Each shows a first name and an initial, the referral's status and what it has earned - never a phone number or anything they spent. Refused referrals are not listed: they never became yours.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Query parameters

Name	Default
`page`	0
`size`	20

Example

Response: GenericResponsePagerReferralRefereeResponse

curl -X GET "https://api.bridgemoni.com/referral/me/referrals?page=value&size=20" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "content": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "refereeDisplayName": "Kemi O.",
        "status": "PENDING_QUALIFICATION",
        "source": "REGISTRATION",
        "attributedAt": "2026-09-25T10:00:00Z",
        "qualifiesBy": "2026-09-25T10:00:00Z",
        "earnsUntil": "2026-09-25T10:00:00Z",
        "earned": {
          "NGN": 1240.0
        }
      }
    ],
    "page": "1",
    "size": "1",
    "totalPages": "1",
    "totalElements": "1"
  },
  "description": "Referrals fetched"
}

Responses

Status	When
`200`	Referrals fetched

GET See who referred me

GET /referral/me/referrer

The referral the caller signed up under, with the referrer's first name and initial. Empty when the caller was not referred, or their code could not be used.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Example

Response: GenericResponseReferralAttributionResponse

curl -X GET "https://api.bridgemoni.com/referral/me/referrer" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "status": "PENDING_QUALIFICATION",
    "source": "REGISTRATION",
    "referrerDisplayName": "Tolu A.",
    "attributedAt": "2026-09-25T10:00:00Z",
    "qualifiesBy": "2026-09-25T10:00:00Z",
    "qualifiedAt": "2026-09-25T10:00:00Z",
    "earnsUntil": "2026-09-25T10:00:00Z"
  },
  "description": "Referrer fetched"
}

Responses

Status	When
`200`	Referrer fetched

GET Read the referral programme

GET /referral/program

The current version.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Example

Response: GenericResponseReferralProgramResponse

curl -X GET "https://api.bridgemoni.com/referral/program" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "version": 3,
    "status": "OFF",
    "model": "REVENUE_SHARE",
    "rate": 0,
    "basisTypes": [
      "string"
    ],
    "termMonths": 0,
    "holdDays": 0,
    "perRefereeCapAmount": 0,
    "perReferrerMonthlyCapAmount": 0,
    "maxQualifiedReferralsPerMonth": 0,
    "referrerMinTier": 0,
    "refereeQualifyingTier": 0,
    "qualificationWindowDays": 0,
    "claimWindowDays": 0,
    "shareUrlTemplate": "string",
    "currencyCode": "string",
    "effectiveFrom": "2026-09-25T10:00:00Z",
    "inviteChannels": [
      "SMS"
    ],
    "inviteValidityDays": 0,
    "invitesPerDay": 0,
    "invitesPerMonth": 0,
    "unsubscribeUrlTemplate": "string",
    "enforcedFrom": "2026-10-01"
  },
  "description": "Referral programme fetched"
}

Responses

Status	When
`200`	Referral programme fetched
`404`	There is no referral programme here

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