Getting Started with Get Income API

Overview

The Get Income API extract income insights from a user's bank transactions. The API identifies salary and non-salary income, calculates stability metrics, and provides month-by-month breakdowns.

Key Capabilities:

Detect All Income Types Find more than just salary. The API identifies 15 income types including gig work (Uber, Careem), rental income, government benefits, bonuses, and investments. This complete picture helps you assess total earning capacity, not just employment income.

Track Income Over Time See income trends across 3, 6, 9, or 12-month periods. We show you which months had income, which had gaps, and whether income is growing or declining. This historical view reveals seasonal patterns and employment stability.

Get Employer Information We extract employer names from salary transactions when available. This helps you verify employment without contacting the employer directly.

Income Types

The API automatically identifies and classifies 15 different income types across two main categories:

Salary Income (2 types)

EMPLOYMENT Regular employment salary from an employer. This is the most common income type, covering monthly or periodic salary payments. The API detects these through payroll keywords in English and Arabic, bank-provided payroll flags, and recurring payment patterns.

RETIREMENT Pension and retirement benefits, including payments from GOSI (General Organization for Social Insurance) and other pension systems. Helps verify retirement income for credit assessments.

Non-Salary Income (12 types)

HOUSING_BENEFIT Government housing support from the Real Estate Development Fund (REDF). This Saudi government program provides housing assistance to citizens. Important for understanding total government support received.

GIG_ECONOMY Income from rideshare and delivery platforms like Uber and Careem. Covers on-demand work through digital platforms. Essential for assessing modern workforce participants.

UNEMPLOYMENT Unemployment benefits from the Hafiz program (Saudi unemployment support system). Indicates temporary income support during job transitions.

RENTAL Income from property rentals, including residential and commercial properties. Shows passive income streams and property ownership.

CASH_DEPOSIT Cash deposits made into bank accounts. Can indicate cash-based income sources, informal earnings, or business revenue.

BONUS Performance bonuses, rewards, and one-time incentive payments from employers or other sources. Adds to total compensation but may not be regular.

TRANSFER_FROM_OWN_APPLICATION Transfers from the user's own payment apps, such as STC Pay. These are transfers from digital wallets or payment services owned by the same person.

STUDENT_STIPEND University and college student allowances. Includes educational grants, scholarships, and student support payments. Relevant for student loan applications.

INVESTMENTS Dividend income and stock returns. Covers investment portfolio income, stock dividends, and capital gains distributions. Indicates financial assets.

CITIZEN_ACCOUNT Payments from the Saudi citizen account program. This government benefit program provides financial support to eligible Saudi citizens.

SOCIAL_SECURITY Social security benefits from the Ministry of Human Resources. Government welfare and social support payments.

SIDE_BUSINESS E-commerce platform income, particularly from platforms like Salla. Covers entrepreneurial and small business income from online sales.

Common Use Cases

• Credit Scoring: Assess income stability and calculate debt-to-income ratios
• Loan Applications: Verify applicant income and employment automatically
• Risk Assessment: Identify income volatility and employment gaps
• KYC Compliance: Validate income sources and employment status
• Tenant Screening: Verify rental applicants' ability to pay

API Reference

Before using the APIs

Before you use the API you will need to ensure that you have an entity_id with both accounts and transactions permissions. You can see how to do this in our guide on creating an entity.

Request Structure

Request Parameters

Request Example

{
  "entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "start_date": "2024-06-01", -optional 
  "income_type": "ALL", -optional  
  "estimated_monthly_income": 5000.00 --optional 
}

Response Structure

The API returns two main sections: salary and non_salary. Each section contains same structure with transaction details, monthly breakdowns, and stability metrics.

Response example

{
  "salary": {
    "currency": "SAR",
    "total": {
      "amount": 35000.00,
      "count": 7,
      "first_date_time": "2024-06-15T08:30:00Z",
      "last_date_time": "2024-12-15T09:15:00Z",
      "average_monthly_amount": 5000.00,
      "average_monthly_count": 1.00,
      "average_monthly_received_value": 5000.00,
      "minimum_monthly_amount": {
        "month": 6,
        "year": 2024,
        "amount": 5000.00
      },
      "maximum_monthly_amount": {
        "month": 12,
        "year": 2024,
        "amount": 5000.00
      }
    },
    "monthly_totals": [
      {
        "month": 12,
        "year": 2024,
        "amount": 5000.00,
        "count": 1,
        "is_complete": false
      },
      {
        "month": 11,
        "year": 2024,
        "amount": 5000.00,
        "count": 1,
        "is_complete": true
      },
      {
        "month": 10,
        "year": 2024,
        "amount": 5000.00,
        "count": 1,
        "is_complete": true
      }
    ],
    "transactions": [
      {
        "account_id": "acc-12345678-1234-1234-1234-123456789012",
        "transaction_id": "txn-001",
        "transaction_information": "Monthly Salary Transfer - ABC Company",
        "booking_date_time": "2024-12-15T09:15:00Z",
        "amount": 5000.00,
        "income_source": {
          "type": "EMPLOYMENT",
          "name": "ABC Company"
        }
      },
      {
        "account_id": "acc-12345678-1234-1234-1234-123456789012",
        "transaction_id": "txn-002",
        "transaction_information": "Salary Transfer November",
        "booking_date_time": "2024-11-15T09:15:00Z",
        "amount": 5000.00,
        "income_source": {
          "type": "EMPLOYMENT",
          "name": "ABC Company"
        }
      }
    ],
    "income_factors": {
      "delta_min_max": 0.00,
      "average_monthly_income_change": 0.00,
      "periods": [
        {
          "period": "P3M",
          "average_income": {
            "currency": "SAR",
            "amount": 5000.00
          },
          "income_variation": 0.00
        },
        {
          "period": "P6M",
          "average_income": {
            "currency": "SAR",
            "amount": 5000.00
          },
          "income_variation": 0.00
        }
      ]
    }
  },
  "non_salary": {
    "currency": "SAR",
    "total": {
      "amount": 4500.00,
      "count": 3,
      "first_date_time": "2024-07-20T14:30:00Z",
      "last_date_time": "2024-11-18T16:45:00Z",
      "average_monthly_amount": 642.86,
      "average_monthly_count": 0.43,
      "average_monthly_received_value": 1500.00,
      "minimum_monthly_amount": {
        "month": 7,
        "year": 2024,
        "amount": 1200.00
      },
      "maximum_monthly_amount": {
        "month": 11,
        "year": 2024,
        "amount": 1800.00
      }
    },
    "monthly_totals": [
      {
        "month": 12,
        "year": 2024,
        "amount": 0.00,
        "count": 0,
        "is_complete": false
      },
      {
        "month": 11,
        "year": 2024,
        "amount": 1800.00,
        "count": 1,
        "is_complete": true
      },
      {
        "month": 10,
        "year": 2024,
        "amount": 0.00,
        "count": 0,
        "is_complete": true
      },
      {
        "month": 9,
        "year": 2024,
        "amount": 1500.00,
        "count": 1,
        "is_complete": true
      },
      {
        "month": 8,
        "year": 2024,
        "amount": 0.00,
        "count": 0,
        "is_complete": true
      },
      {
        "month": 7,
        "year": 2024,
        "amount": 1200.00,
        "count": 1,
        "is_complete": true
      },
      {
        "month": 6,
        "year": 2024,
        "amount": 0.00,
        "count": 0,
        "is_complete": true
      }
    ],
    "transactions": [
      {
        "account_id": "acc-12345678-1234-1234-1234-123456789012",
        "transaction_id": "txn-101",
        "transaction_information": "Uber Trip Payments",
        "booking_date_time": "2024-11-18T16:45:00Z",
        "amount": 1800.00,
        "income_source": {
          "type": "GIG_ECONOMY",
          "name": null
        }
      },
      {
        "account_id": "acc-12345678-1234-1234-1234-123456789012",
        "transaction_id": "txn-102",
        "transaction_information": "Performance Bonus Q3",
        "booking_date_time": "2024-09-25T10:00:00Z",
        "amount": 1500.00,
        "income_source": {
          "type": "BONUS",
          "name": null
        }
      },
      {
        "account_id": "acc-12345678-1234-1234-1234-123456789012",
        "transaction_id": "txn-103",
        "transaction_information": "Citizen Account Deposit",
        "booking_date_time": "2024-07-20T14:30:00Z",
        "amount": 1200.00,
        "income_source": {
          "type": "CITIZEN_ACCOUNT",
          "name": null
        }
      }
    ],
    "income_factors": {
      "delta_min_max": 600.00,
      "average_monthly_income_change": 25.00,
      "periods": [
        {
          "period": "P3M",
          "average_income": {
            "currency": "SAR",
            "amount": 600.00
          },
          "income_variation": 848.53
        },
        {
          "period": "P6M",
          "average_income": {
            "currency": "SAR",
            "amount": 750.00
          },
          "income_variation": 754.98
        }
      ]
    }
  }
}

Response Fields

Top-Level Structure

Income Category Object (salary/non_salary)

Total

Monthly Total Object

Transaction Details

Income Source Types

Salary Income Types

Non-Salary Income Types

Income Source

Income Factors

Income Factors Period

Understanding the Response

Average Monthly Metrics

The API provides two average calculations:

average_monthly_amount: Total income ÷ All months in range

• Includes months with zero income
• Useful for overall income assessment

average_monthly_received_value: Total income ÷ Months with income > 0

• Excludes months with zero income
• More accurate for irregular employment, contractors, and gig workers
• Better reflects actual earning capacity

Example:

Analysis Period: January - June (6 months)
Income: Jan: 5000, Feb: 0, Mar: 5200, Apr: 0, May: 5100, Jun: 0
Total: 15,300 SAR

average_monthly_amount = 15,300 ÷ 6 = 2,550 SAR
average_monthly_received_value = 15,300 ÷ 3 = 5,100 SAR  (more accurate)

Income Stability Assessment

Use these metrics to assess income stability:

1. Income Variation (income_factors.periods[].income_variation)

   • < 500: Very stable income
   • 500-2000: Moderately stable income

   • 2000: Volatile income

2. Delta Min-Max (income_factors.delta_min_max)

   • Difference between highest and lowest amounts
   • Lower values = more consistent income

3. Monthly Income Change (income_factors.average_monthly_income_change)

   • Positive: Income increasing over time
   • Negative: Income decreasing over time
   • Near zero: Stable income pattern

4. Transaction Count (total.count)

   • Higher count = more reliable data
   • Minimum 3 transactions across 3 months recommended for reliable assessment

Gap Detection

The monthly_totals array includes entries for all months in the analysis period, even months with zero income. This helps you:

• Identify employment gaps
• Detect seasonal income patterns
• Assess income consistency

The is_complete field indicates whether the full month was analyzed. Use this to distinguish between:

• Complete months with zero income (income gap)
• Partial months at the start or end of analysis (incomplete data)

A Brief Overview of Detection Methods

The API uses multiple detection methods to identify income:

1. ML models & NLP techniques: that work together to extract income insights from a user's bank transactions
2. Regional Banking Flags: Bank-provided payroll markers and indications
3. Recurring Pattern Analysis: Identifies regular income without explicit keywords using similarity algorithms
4. Amount Thresholds: Filters transactions below 100 SAR to reduce noisy inflow transactions

Best Practices

1. Start Date Selection: Use 6-month analysis period for reliable patterns (default behavior)
2. Sync vs Async: Use sync mode for user-facing applications to prevent timeouts with following the data workflow flow when all data is fully fetched.
3. Income Assessment: Combine multiple metrics (variation, count, gaps) for comprehensive assessment
4. Partial Months: Check is_complete flag when analyzing current or start month
5. Zero Income Months: Distinguish between data gaps and actual employment gaps