Getting Started - Financial Segments

Introduction

Financial Segments enable you to analyze and group users based on financial criteria such as balances, income, spending behavior, or insurance data.

Segments are created asynchronously and can be retrieved once processing is complete.
All created segments are automatically deleted after 14 days.

Typical use cases include:

• Identifying high-value customers

• Detecting users with financial risk (e.g. overdraft behavior)

• Analyzing income and spending patterns

• Building financial insights for personalization or scoring

Prerequisites

Before using Financial Segments, ensure the following:

• You have valid API credentials (client_id and client_secret)

• A user exists in the system

• At least one account has been imported (e.g. via finAPI WebForm or Open Banking)

• Transaction and balance data are available and up to date

TL:TR

• Call a Create Segment endpoint (POST)

• Receive a jobId

• Poll the Retrieve endpoint (GET) using the jobId

• Process the result once ready

Used Endpoints

Each segment follows the same pattern:

General Workflow

Step 1 – Create a Segment

Each segment is created via a POST request.

Example:

POST /segments/highBalance
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "callbackURL": "https://your-callback-url",
  "accountType": "checking",
  "threshold": 5000
}

Response:

{
  "jobId": "2342342-c345354-345a343"
}

Step 2 – Retrieve Segment Result

Use the jobId to fetch the result:

GET /segments/highBalance/{jobId}
Authorization: Bearer <access_token>

Possible responses:

Example response:

{
  "durationInMonth": 6,
  "creationDate": "2026-03-25",
  "users": [
    {
      "userId": "756cba12-330c-4eef-8124-8cef876a4493",
      "accounts": [
        {
          "accountId": "4e760145-2e65-4242-ac33-488943528c93",
          "amount": 1426.84
        }
      ]
    }
  ],
  "totalElements": 1
}

Step 3 – Handle Asynchronous Processing

Segments are processed asynchronously. You have two options:

Option A – Polling

Repeatedly call the GET endpoint until status = 200.

Option B – Callback (recommended)

Provide a callbackURL in the request.
The system will notify your backend once the segment is ready.

Paging

Segment results may be large. Use paging parameters when retrieving results:

• number → page number

• size → page size