API reference · Savings & everyday money

Savings circles

GET/savings/circleList the circles you are in
POST/savings/circleStart a savings circle
POST/savings/circle/joinJoin a savings circle with a code
GET/savings/circle/{reference}Read a savings circle
POST/savings/circle/{reference}/inviteInvite someone to a savings circle
GET/savings/circle/{reference}/leaderboardSee how the circle is doing
POST/savings/circle/{reference}/leaveLeave a savings circle
POST/savings/circle/{reference}/link-planPoint one of your plans at a circle

GET List the circles you are in

GET /savings/circle

Headers

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

Example

Response: GenericResponseListCircleResponse

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

{
  "data": [
    {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "name": {
        "name": "string"
      },
      "targetAmountPerMember": {
        "amount": "10000.00",
        "currencyCode": "NGN"
      },
      "collectiveTargetAmount": {
        "amount": "10000.00",
        "currencyCode": "NGN"
      },
      "collectiveSavedAmount": {
        "amount": "10000.00",
        "currencyCode": "NGN"
      },
      "targetDate": "2026-09-25",
      "status": "OPEN",
      "ownerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "visibility": "string",
      "maxMembers": 0,
      "memberCount": 0,
      "shareProgressByDefault": true,
      "joinCode": "string",
      "joinCodeExpiresAt": "2026-09-25T10:00:00Z",
      "creationDateTime": "2026-09-25T10:00:00Z"
    }
  ],
  "description": "Circles retrieved successfully"
}

Responses

Status	When
`200`	Circles retrieved successfully

POST Start a savings circle

POST /savings/circle

A circle is a target set together and saved for apart. Everyone keeps their own plan and their own money - a circle holds no account, takes no custody, and nobody in it can move anybody else's savings. What it adds is a shared goal and, for those who choose to share it, a board showing how everyone is doing. Returns a join code once; we keep only a hash of it, so if it is lost, issue a new one.

Headers

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

Example

Request body: CircleRequest · Response: GenericResponseCircleResponse

curl -X POST "https://api.bridgemoni.com/savings/circle" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Lagos crew 2026",
  "currencyCode": "NGN",
  "targetAmountPerMember": 500000.0,
  "collectiveTargetAmount": 5000000.0,
  "targetDate": "2026-09-25",
  "visibility": "INVITE_ONLY",
  "maxMembers": 12,
  "shareProgressByDefault": true
}'

{
  "name": "Lagos crew 2026",
  "currencyCode": "NGN",
  "targetAmountPerMember": 500000.0,
  "collectiveTargetAmount": 5000000.0,
  "targetDate": "2026-09-25",
  "visibility": "INVITE_ONLY",
  "maxMembers": 12,
  "shareProgressByDefault": true
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "name": {
      "name": "string"
    },
    "targetAmountPerMember": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveTargetAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveSavedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "targetDate": "2026-09-25",
    "status": "OPEN",
    "ownerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "visibility": "string",
    "maxMembers": 0,
    "memberCount": 0,
    "shareProgressByDefault": true,
    "joinCode": "string",
    "joinCodeExpiresAt": "2026-09-25T10:00:00Z",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Circle created successfully"
}

Responses

Status	When
`200`	Circle created successfully

POST Join a savings circle with a code

POST /savings/circle/join

Accepts the code the circle's owner shared. Joining a circle gives nobody any claim on your money - link one of your plans afterwards if you want your progress counted

Headers

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

Example

Request body: CircleJoinRequest · Response: GenericResponseCircleResponse

curl -X POST "https://api.bridgemoni.com/savings/circle/join" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "joinCode": "K7QP-2M9X"
}'

{
  "joinCode": "K7QP-2M9X"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "name": {
      "name": "string"
    },
    "targetAmountPerMember": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveTargetAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveSavedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "targetDate": "2026-09-25",
    "status": "OPEN",
    "ownerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "visibility": "string",
    "maxMembers": 0,
    "memberCount": 0,
    "shareProgressByDefault": true,
    "joinCode": "string",
    "joinCodeExpiresAt": "2026-09-25T10:00:00Z",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Joined successfully"
}

Responses

Status	When
`200`	Joined successfully

GET Read a savings circle

GET /savings/circle/{reference}

Only members can read a circle, whatever its visibility says

Headers

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

Path parameters

Name
`reference`

Example

Response: GenericResponseCircleResponse

curl -X GET "https://api.bridgemoni.com/savings/circle/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",
    "name": {
      "name": "string"
    },
    "targetAmountPerMember": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveTargetAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveSavedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "targetDate": "2026-09-25",
    "status": "OPEN",
    "ownerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "visibility": "string",
    "maxMembers": 0,
    "memberCount": 0,
    "shareProgressByDefault": true,
    "joinCode": "string",
    "joinCodeExpiresAt": "2026-09-25T10:00:00Z",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Circle retrieved successfully"
}

Responses

Status	When
`200`	Circle retrieved successfully

POST Invite someone to a savings circle

POST /savings/circle/{reference}/invite

By phone number, email address or username. Only the circle's owner may invite. The answer is the same whether or not an account exists with those details, so this cannot be used to find out who is registered.

Headers

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

Path parameters

Name
`reference`

Example

Request body: CircleInviteRequest · Response: GenericResponseCircleMemberResponse

curl -X POST "https://api.bridgemoni.com/savings/circle/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/invite" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "msisdn": "+2348000000000",
  "emailAddress": "ada@example.com",
  "username": "string"
}'

{
  "msisdn": "+2348000000000",
  "emailAddress": "ada@example.com",
  "username": "string"
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "displayName": {
      "name": "string"
    },
    "status": "INVITED",
    "savedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "progressPercent": 0,
    "position": 0,
    "shareProgress": true,
    "joinedAt": "2026-09-25T10:00:00Z"
  },
  "description": "Invitation sent successfully"
}

Responses

Status	When
`200`	Invitation sent successfully

GET See how the circle is doing

GET /savings/circle/{reference}/leaderboard

The group's combined progress, and a board of the members who chose to share theirs. A member who is not sharing still counts towards the group total but never appears on the board and is never ranked - turning sharing off hides what was already shared, not just what comes next.

Headers

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

Path parameters

Name
`reference`

Example

Response: GenericResponseCircleLeaderboardResponse

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

{
  "data": {
    "circleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "collectiveSavedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveTargetAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveProgressPercent": 0,
    "members": [
      {
        "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
        "displayName": {
          "name": "string"
        },
        "status": "INVITED",
        "savedAmount": {
          "amount": "10000.00",
          "currencyCode": "NGN"
        },
        "progressPercent": 0,
        "position": 0,
        "shareProgress": true,
        "joinedAt": "2026-09-25T10:00:00Z"
      }
    ],
    "hiddenMemberCount": 0
  },
  "description": "Leaderboard retrieved successfully"
}

Responses

Status	When
`200`	Leaderboard retrieved successfully

POST Leave a savings circle

POST /savings/circle/{reference}/leave

You keep your plan and every naira in it. Leaving only stops your progress being counted towards the group's goal

Headers

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

Path parameters

Name
`reference`

Example

Response: GenericResponseCircleResponse

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

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "name": {
      "name": "string"
    },
    "targetAmountPerMember": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveTargetAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "collectiveSavedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "targetDate": "2026-09-25",
    "status": "OPEN",
    "ownerUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "visibility": "string",
    "maxMembers": 0,
    "memberCount": 0,
    "shareProgressByDefault": true,
    "joinCode": "string",
    "joinCodeExpiresAt": "2026-09-25T10:00:00Z",
    "creationDateTime": "2026-09-25T10:00:00Z"
  },
  "description": "Left the circle successfully"
}

Responses

Status	When
`200`	Left the circle successfully

POST Point one of your plans at a circle

POST /savings/circle/{reference}/link-plan

Tells the circle which of your plans counts towards the shared goal. The plan stays entirely yours: the circle reads its balance and can never move money into or out of it, and unlinking takes nothing away from you.

Headers

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

Path parameters

Name
`reference`

Example

Request body: LinkPlanRequest · Response: GenericResponseCircleMemberResponse

curl -X POST "https://api.bridgemoni.com/savings/circle/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/link-plan" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
  "planReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "shareProgress": true
}'

{
  "planReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "shareProgress": true
}

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "displayName": {
      "name": "string"
    },
    "status": "INVITED",
    "savedAmount": {
      "amount": "10000.00",
      "currencyCode": "NGN"
    },
    "progressPercent": 0,
    "position": 0,
    "shareProgress": true,
    "joinedAt": "2026-09-25T10:00:00Z"
  },
  "description": "Plan linked successfully"
}

Responses

Status	When
`200`	Plan linked successfully

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