Submit Assessment

Submit bank statements and supporting documents to create an affordability assessment.

Endpoint

POST /api/v1/assess

Request body

{
  "bank_statements": [
    {
      "document": "JVBERi0xLjQK...",
      "filename": "statement-jan-2024.pdf"
    }
  ],
  "supporting_documents": {
    "payslips": [
      {
        "document": "JVBERi0xLjQK...",
        "filename": "payslip-jan-2024.pdf",
        "period": "2024-01"
      }
    ],
    "credit_report": {
      "document": "JVBERi0xLjQK...",
      "filename": "credit-report.pdf"
    },
    "id_document": {
      "document": "JVBERi0xLjQK...",
      "filename": "id.pdf"
    },
    "rental_agreement": {
      "document": "JVBERi0xLjQK...",
      "filename": "lease.pdf"
    }
  },
  "assessment_type": "individual",
  "currency_code": "ZAR",
  "webhook_url": "https://your-app.com/webhooks/assessment",
  "external_reference": "loan-app-12345"
}

Parameters

Document encoding

All documents must be Base64-encoded. In JavaScript:

const fs = require('fs');
const document = fs.readFileSync('statement.pdf');
const base64 = document.toString('base64');

Response

The API returns immediately with a job ID:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "assessment_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "processing",
  "external_reference": "loan-app-12345",
  "estimated_time": "120-300s",
  "poll_url": "/api/v1/assess/550e8400-e29b-41d4-a716-446655440000"
}

Processing time

Assessments typically complete in 2-5 minutes depending on:

• Number of documents
• Document complexity (pages, transaction count)
• Current system load

Example

curl -X POST https://oqui.io/api/v1/assess \
  -H "Authorization: Bearer ckiq_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "bank_statements": [{
      "document": "'$(base64 -w0 statement.pdf)'",
      "filename": "statement.pdf"
    }],
    "external_reference": "loan-12345"
  }'

Error responses

Failure model

Processing failures are handled as follows:

• Bank statement fails: Assessment fails, no charge
• Classification fails: Assessment fails, no charge
• Payslip fails (if provided): Assessment fails, no charge
• Credit report fails (if provided): Assessment fails, no charge
• ID document fails: Assessment continues with warning
• Rental agreement fails: Assessment continues with warning

You're only charged for successful assessments.

Next step

Once you've submitted an assessment, get the results.