Extract & Authenticate - Results API

Overview

The Extract & Authenticate API allows you to retrieve the outcome of previously submitted requests for financial document processing. This endpoint returns comprehensive document parsing and authentication results, including parsed financial data and validity checks.

Key Features

• 🔍 Document Parsing – Extract structured data from financial statements
• 🛡️ Authentication – Validate document authenticity and user information
• 📊 Financial Analytics – Access transaction data and account summaries
• ⚡ Secure Access – Pre-signed URLs with time-limited access

Product Differentiation

Use the productCode field to distinguish between responses:

• PA: Raw parsed data only (See Extract & Authenticate Section)
• PAS: Basic scored data with recommendations (See KamoaLite Section)
• PARS: Advanced financial analysis and profiling (See Score360 Section)

---

Endpoint

GET https://api.kamoa.io/score/results/{requestId}

Example Request

curl -X GET "https://api.kamoa.io/score/results/your-request-id" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

---

Request Details

Component	Value
Base URL	https://api.kamoa.io
Endpoint	/score/results/{requestId}
Method	GET
Path Parameter	requestId - UUID from initial submit

Required Headers

Header	Value	Description
Authorization	Bearer {token}	JWT token for authentication
Content-Type	application/json	Request content type

---

Response Format

Success Response Structure

{
  "parsedUrls": ["https://secure-bucket.s3.amazonaws.com/.../parsed.json?signature=..."],
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "productCode": "PA"
}

Response Fields

Field	Type	Description	Notes
parsedUrls	string[]	Pre-signed URLs to access parsed data	⏰ Expires in 1 hour
requestId	string	Unique request identifier (UUID format)	Use for tracking and support
productCode	string	Product identifier (always "PA")	Indicates Parsed Account data

---

Working with Parsed Data

Step 1: Extract the Pre-signed URL

// Extract URL from API response
const response = {
  "parsedUrls": ["https://secure-bucket.s3.amazonaws.com/.../parsed.json?signature=..."],
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "productCode": "PA"
};

const dataUrl = response.parsedUrls[0];

Step 2: Fetch the Parsed Data

JavaScript/Node.js Example

async function fetchParsedData(signedUrl) {
    try {
        const response = await fetch(signedUrl, {
            method: 'GET',
            timeout: 30000
        });

        if (!response.ok) {
            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }

        const data = await response.json();

        if (data.status === 'success' && data.code === 200) {
            console.log('✅ Data retrieved successfully');
            console.log(`📊 Account: ${data.data.header.name}`);
            console.log(`📈 Transactions: ${data.data.transactions.length}`);
            return data;
        }

        console.warn('⚠️ Unexpected response format');
        return null;

    } catch (error) {
        console.error('❌ Error fetching data:', error.message);
        return null;
    }
}

Step 3: Important Considerations

⚠️ Critical Reminders

• Pre-signed URLs expire after 10 minutes (600 seconds)
• No additional authentication required for pre-signed URLs
• Always implement proper error handling
• URLs are single-use and time-sensitive

---

Parsed Data Structure

Complete JSON Response Schema

{
  "status": "success",
  "code": 200,
  "data": {
    "logs": { /* Document metadata */ },
    "meta": { /* File information */ },
    "header": { /* Account details */ },
    "transactions": [ /* Transaction array */ ],
    "validity": { /* Validation results */ }
  }
}

Real Example Response

{
  "status": "success",
  "code": 200,
  "data": {
    "logs": {
      "documentType": "M-Pesa",
      "documentIssuedBy": "mpesa-personal",
      "format": "USSD",
      "fileKey": null
    },
    "meta": {
      "creationDate": "2025-06-09 00:48:32",
      "modDate": "2025-06-09 00:48:36",
      "keywords": "M-PESA,Statement",
      "creator": "Safaricom PLC",
      "producer": "OpenPDF 1.3.26",
      "subject": "M-PESA Statement",
      "author": "Safaricom PLC",
      "title": "254712******_2025-06-09_2024-06-09_1749419312597.pdf"
    },
    "header": {
      "name": "JOHN D** O****",
      "phoneNumber": "0712******",
      "email": "user@******.com",
      "code": "ZXTDKCC3",
      "statementPeriod": "09 Jun 2024 - 09 Jun 2025",
      "requestDate": "09 Jun 2025",
      "accountNumber": null,
      "accountType": null,
      "summary": {
        "sendMoney": {
          "paidIn": 0,
          "paidOut": 277869
        },
        "receivedMoney": {
          "paidIn": 172923.35,
          "paidOut": 0
        },
        "agentDeposit": {
          "paidIn": 47200,
          "paidOut": 0
        },
        "agentWithdrawal": {
          "paidIn": 0,
          "paidOut": 44810
        },
        "lipaPayBill": {
          "paidIn": 0,
          "paidOut": 459252.06
        },
        "lipaBuyGoods": {
          "paidIn": 0,
          "paidOut": 126315
        },
        "others": {
          "paidIn": 838156.79,
          "paidOut": 208070.04
        },
        "total": {
          "paidIn": 1116948.65,
          "paidOut": 1116316.10
        }
      }
    },
    "transactions": [
      {
        "receiptNumber": "TF853****P5",
        "completionTime": "2025-06-08 20:16:21",
        "details": "Customer Transfer to - 07******106 FREDRICK O****",
        "paidIn": 0,
        "paidOut": 150,
        "balance": 393.55,
        "transactionStatus": "Completed"
      }
    ],
    "validity": {
      "hasName": true,
      "nameIsValid": false,
      "hasEmail": true,
      "emailIsValid": false,
      "hasPhoneNumber": true,
      "phoneNumberIsValid": true,
      "authorIsValid": true,
      "creatorIsValid": true,
      "notModified": true,
      "hasTransactions": true,
      "exclusionReasons": [
        "name_invalid",
        "email_invalid"
      ],
      "isValid": false
    }
  }
}

1. Document Logs

Contains metadata about the processed document.

{
  "logs": {
    "documentType": "M-Pesa",
    "documentIssuedBy": "provider-system", 
    "format": "USSD",
    "fileKey": null
  }
}

Field	Type	Description
documentType	string	Type of financial document (e.g., "M-Pesa", "Bank Statement")
documentIssuedBy	string	Issuing system or provider
format	string	Original document format (USSD, PDF, CSV, etc.)
fileKey	string | null	Internal file reference key

2. Document Metadata

File-level information extracted from the original document.

{
  "meta": {
    "creationDate": "2025-01-15 09:30:45",
    "modDate": "2025-01-15 09:35:22", 
    "keywords": "Financial,Statement",
    "creator": "Banking System",
    "producer": "DocGenerator 2.4",
    "subject": "Account Statement",
    "author": "Banking Services",
    "title": "statement_20250115.pdf"
  }
}

Field	Type	Description
creationDate	string	Document creation timestamp
modDate	string	Last modification timestamp
keywords	string	Document keywords/tags
creator	string	Document creation system
producer	string	Software used to generate document
subject	string	Document subject line
author	string	Document author
title	string	Original filename

3. Account Header

Core account information and comprehensive transaction summaries.

{
  "header": {
    "name": "JOHN D** O****",
    "phoneNumber": "0712******",
    "email": "user@******.com",
    "code": "ZXTDKCC3",
    "statementPeriod": "09 Jun 2024 - 09 Jun 2025",
    "requestDate": "09 Jun 2025",
    "accountNumber": null,
    "customerNumber": null,
    "accountType": null,
    "accountCreationDate": null,
    "branch": null,
    "currency": null,
    "openingBalance": null,
    "closingBalance": null,
    "availableBalance": null,
    "sumPaidIn": null,
    "sumPaidOut": null,
    "countPaidIn": null,
    "countPaidOut": null,
    "summary": {
      "sendMoney": {
        "paidIn": 0,
        "paidOut": 277869
      },
      "receivedMoney": {
        "paidIn": 172923.35,
        "paidOut": 0
      },
      "agentDeposit": {
        "paidIn": 47200,
        "paidOut": 0
      },
      "agentWithdrawal": {
        "paidIn": 0,
        "paidOut": 44810
      },
      "lipaPayBill": {
        "paidIn": 0,
        "paidOut": 459252.06
      },
      "lipaBuyGoods": {
        "paidIn": 0,
        "paidOut": 126315
      },
      "others": {
        "paidIn": 838156.79,
        "paidOut": 208070.04
      },
      "total": {
        "paidIn": 1116948.65,
        "paidOut": 1116316.10
      }
    }
  }
}

Basic Account Information

Field	Type	Description
name	string	Account holder name
phoneNumber	string	Phone number
email	string	Email address
code	string	Internal account/statement code
statementPeriod	string	Date range covered by statement
requestDate	string	Date when statement was requested

Optional Account Fields

These fields may be null depending on the document type and provider:

Field	Type	Description
accountNumber	string | null	Bank account number
customerNumber	string | null	Customer identification number
accountType	string | null	Type of account (savings, checking, etc.)
accountCreationDate	string | null	Date account was opened
branch	string | null	Bank branch information
currency	string | null	Account currency
openingBalance	number | null	Balance at start of period
closingBalance	number | null	Balance at end of period
availableBalance	number | null	Current available balance
sumPaidIn	number | null	Total credits for period
sumPaidOut	number | null	Total debits for period
countPaidIn	number | null	Number of credit transactions
countPaidOut	number | null	Number of debit transactions

Transaction Summary Categories

The summary object provides detailed breakdowns by transaction type:

Category	Description
sendMoney	Money transfer transactions sent to others
receivedMoney	Money received from other users
agentDeposit	Cash deposits through agents
agentWithdrawal	Cash withdrawals through agents
lipaPayBill	Bill payments (utilities, services)
lipaBuyGoods	Merchant payments for goods
others	Miscellaneous transactions
total	Grand totals across all categories

Each category contains:

• paidIn: Total amount credited for this category
• paidOut: Total amount debited for this category

4. Transactions Array

Detailed transaction history with individual records.

{
  "transactions": [
    {
      "receiptNumber": "TF853****P5",
      "completionTime": "2025-06-08 20:16:21",
      "transactionDate": null,
      "valueDate": null,
      "details": "Customer Transfer to - 07******106 FREDRICK O****",
      "paidIn": 0,
      "paidOut": 150,
      "balance": 393.55,
      "transactionStatus": "Completed",
      "transactionType": null,
      "otherParty": null
    }
  ]
}

Core Transaction Fields

Field	Type	Description
receiptNumber	string	Transaction reference
completionTime	string	Transaction completion timestamp
details	string	Transaction description
paidIn	number	Credit amount (0 for debit transactions)
paidOut	number	Debit amount (0 for credit transactions)
balance	number	Account balance after transaction
transactionStatus	string	Transaction status (e.g., "Completed", "Failed")

Optional Transaction Fields

These fields may be null depending on the provider and transaction type:

Field	Type	Description
transactionDate	string | null	Date transaction was initiated
valueDate	string | null	Date transaction value was applied
transactionType	string | null	Category/type of transaction
otherParty	string | null	Other party involved in transaction

5. Document Validity

Comprehensive validation results for document authenticity and data integrity.

{
  "validity": {
    "hasName": true,
    "nameIsValid": false,
    "hasEmail": true,
    "emailIsValid": false,
    "hasPhoneNumber": true,
    "phoneNumberIsValid": true,
    "authorIsValid": true,
    "creatorIsValid": true,
    "notModified": true,
    "hasTransactions": true,
    "exclusionReasons": [
      "name_invalid",
      "email_invalid"
    ],
    "isValid": false
  }
}

Basic Validation Fields

Field	Type	Description
hasName	boolean	Whether name field is present
nameIsValid	boolean	Name validation result
hasEmail	boolean	Whether email field is present
emailIsValid	boolean	Email validation result
hasPhoneNumber	boolean	Whether phone field is present
phoneNumberIsValid	boolean	Phone validation result

Document Authenticity Checks

Field	Type	Description
authorIsValid	boolean	Document author validation
creatorIsValid	boolean	Document creator validation
notModified	boolean	Document integrity check (not tampered)
hasTransactions	boolean	Whether transaction data is present

Overall Validation Status

Field	Type	Description
exclusionReasons	string[]	List of validation failures
isValid	boolean	Overall document validity status

Common Exclusion Reasons

• name_invalid: Name format or content validation failed
• email_invalid: Email format validation failed
• phone_number_invalid: Phone number format validation failed
• document_modified: Document shows signs of modification
• insufficient_transactions: Too few transactions for analysis
• author_mismatch: Document author doesn't match expected provider

---