API Reference

Base URL: https://risk.sayele.co/api/v1

Authentication

All API requests from your backend must include an API key. Get keys from the back-office Admin → API Keys section.

x-api-key: rg_live_your_key_here

Authorization: Bearer rg_live_your_key_here

Use rg_test_ keys for sandbox testing. Production keys begin with rg_live_.

Errors

All errors return { error: string } with appropriate HTTP status codes: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 422 (validation), 500 (server error).

Rate limits

Starter: 100 req/min. Growth: 1000 req/min. Enterprise: custom. Rate limit headers are included in every response.

Versioning

The current version is v1. Breaking changes will be announced with 90 days notice and a new version path.

Overview

POST/auth/login

Exchange email + password for a session token (sets httpOnly cookie). All back-office endpoints require this session. API calls from your backend should use an API key instead.

Parameters

Field	Type	Req	Description
email	string	yes	User email
password	string	yes	User password

Response

{
  "id": "user_01...",
  "email": "admin@acme.co",
  "name": "Alice"
}

Subjects

GET/subjects

List subjects for your tenant. Paginated, newest first. Optionally filter by verification_status or risk_band.

Auth: API key or session

Parameters

Field	Type	Req	Description
page	number	no	Page number (default 1)
limit	number	no	Results per page (max 100, default 20)
verification_status	string	no	Filter: not_started \| in_progress \| verified \| rejected
risk_band	string	no	Filter: low \| medium \| high \| critical

Response

{
  "data": [
    {
      "subject_id": "subj_01...",
      "external_ref": "cust-123",
      "type": "individual",
      "pii": { "name": "Jane Smith", "email": "jane@example.com" },
      "tier": 1,
      "status": "active",
      "risk_band": "low",
      "verification_status": "verified",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 20
}

POST/subjects

Create a new subject. The pii object accepts any key-value pairs — common fields: name, email, dob, nationality, phone, address.

Auth: API key or session

Parameters

Field	Type	Req	Description
external_ref	string	no	Your internal customer/user ID
type	string	no	individual (default) or business
pii	object	yes	PII fields: name, email, dob, nationality, phone, etc.
tier	number	no	Risk tier 0–4 (default 1)

Response

{
  "subject_id": "subj_01...",
  "external_ref": "cust-123",
  "type": "individual",
  "pii": { "name": "Jane Smith", "email": "jane@acme.co" },
  "tier": 1,
  "verification_status": "not_started",
  "created_at": "2025-01-15T10:30:00Z"
}

GET/subjects/:id

Get a subject by ID, including latest documents, screening result, risk score, and consents.

Auth: API key or session

Response

{
  "subject_id": "subj_01...",
  "pii": { "name": "Jane Smith" },
  "risk_band": "low",
  "verification_status": "verified",
  "latest_risk_score": { "score": 320, "band": "low", "decision": "approve" },
  "latest_screening": { "overall": "clear" },
  "documents": [...]
}

PATCH/subjects/:id

Update a subject's verification status, risk band, tier, or lifecycle status.

Auth: API key or session

Parameters

Field	Type	Req	Description
verification_status	string	no	not_started \| in_progress \| verified \| rejected
risk_band	string	no	low \| medium \| high \| critical
tier	number	no	0–4
status	string	no	pending \| active \| suspended \| archived

Response

{
  "id": "subj_01...",
  "verificationStatus": "verified",
  "riskBand": "low",
  "tier": 1,
  "status": "active"
}

Documents

POST/documents

Upload a document for a subject. Provide base64-encoded images or file references. Triggers OCR and authenticity checks automatically.

Auth: API key or session

Parameters

Field	Type	Req	Description
subject_id	string	yes	Subject to attach document to
type	string	yes	passport \| national_id \| driving_licence \| utility_bill
country	string	no	ISO 3166-1 alpha-2 country code
images	array	yes	Array of { side: 'front'\|'back', data: base64string, format: 'jpeg'\|'png' }

Response

{
  "id": "doc_01...",
  "type": "passport",
  "status": "pending",
  "country": "GH",
  "created_at": "2025-01-15T10:30:00Z"
}

GET/documents/:id

Get document metadata and extracted fields.

Auth: API key or session

Response

{
  "id": "doc_01...",
  "type": "passport",
  "status": "verified",
  "country": "GH",
  "expiry": "2030-05-14",
  "extractedFields": { "document_number": "G1234567", "surname": "SMITH" },
  "authenticity": { "genuine": true }
}

GET/documents/:id/view

Get short-lived presigned URLs (15 min) to view document images stored in object storage.

Auth: API key or session

Response

{
  "id": "doc_01...",
  "type": "passport",
  "status": "verified",
  "images": [
    { "side": "front", "format": "jpeg", "url": "https://..." },
    { "side": "back",  "format": "jpeg", "url": "https://..." }
  ]
}

PATCH/documents/:id

Manually update a document's verification status. Used by compliance reviewers.

Auth: API key or session

Parameters

Field	Type	Req	Description
status	string	yes	pending \| verified \| rejected
reason	string	no	Reason for rejection (max 500 chars)

Response

{
  "id": "doc_01...",
  "status": "rejected",
  "manualReviewRef": "Expired document"
}

Risk & Credit

POST/risk/score

Run risk scoring for a subject. Uses the active risk model for your tenant. Returns a score, band, decision, and factor breakdown. Automatically creates a case if the decision is reject or review.

Auth: API key or session

Parameters

Field	Type	Req	Description
subject_id	string	yes	Subject to score
factors	object	no	Optional factor overrides e.g. { pep: true, country_risk: 'high' }

Response

{
  "id": "rs_01...",
  "score": 720,
  "band": "high",
  "decision": "reject",
  "factors": [
    { "name": "country_risk", "contribution": 40, "value": "high" },
    { "name": "pep", "contribution": 60, "value": true }
  ],
  "reason_codes": ["COUNTRY_HIGH_RISK", "PEP_MATCH"]
}

POST/credit/score

Run credit scoring for a subject using the active scorecard. Returns grade, score, decision, PD estimate, and adverse action codes.

Auth: API key or session

Parameters

Field	Type	Req	Description
subject_id	string	yes	Subject to score
data	object	yes	Input variables matching the scorecard's features (e.g. age, income, loan_amount)

Response

{
  "id": "cs_01...",
  "score": 680,
  "grade": "B",
  "decision": "approve",
  "pd": 0.023,
  "adverse_action_codes": [],
  "scorecard": { "name": "Retail v2", "version": 3 }
}

GET/credit/score/:subjectId

Get the latest credit score for a subject.

Auth: API key or session

Response

{
  "score": 680,
  "grade": "B",
  "decision": "approve",
  "computed_at": "2025-01-15T10:30:00Z"
}

Cases

GET/cases

List cases. Filter by status, priority, queue, or assignee.

Auth: API key or session

Parameters

Field	Type	Req	Description
status	string	no	open \| under_review \| pending_info \| escalated \| resolved \| closed
priority	string	no	low \| medium \| high \| critical
queue	string	no	Filter by queue name

Response

{
  "data": [
    {
      "id": "case_01...",
      "type": "kyc_review",
      "status": "open",
      "priority": "high",
      "subject_id": "subj_01...",
      "sla_due": "2025-01-16T10:30:00Z",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

POST/cases

Manually open a case for a subject.

Auth: API key or session

Parameters

Field	Type	Req	Description
subject_id	string	yes	Subject this case relates to
type	string	yes	kyc_review \| aml_alert \| fraud_investigation \| credit_review \| edd \| complaint
priority	string	no	low \| medium \| high \| critical (default medium)
queue	string	no	Compliance queue name

Response

{
  "id": "case_01...",
  "type": "kyc_review",
  "status": "open",
  "priority": "medium",
  "created_at": "2025-01-15T10:30:00Z"
}

POST/cases/:id/notes

Add an investigation note to a case. Notes are stored in the audit trail.

Auth: API key or session

Parameters

Field	Type	Req	Description
content	string	yes	Note text (max 2000 chars)
visibility	string	no	internal (default) \| shared

Response

{
  "id": "note_uuid",
  "author": "Alice",
  "content": "Contacted customer to request additional ID.",
  "visibility": "internal",
  "created_at": "2025-01-15T10:30:00Z"
}

Screening

POST/screening

Run sanctions, PEP, and adverse media screening for a subject. Returns an overall result and individual hits.

Auth: API key or session

Parameters

Field	Type	Req	Description
subject_id	string	yes	Subject to screen
lists	array	no	Specific list IDs to screen against (default: all active lists)
fuzzy_threshold	number	no	Matching threshold 0–100 (default 85)

Response

{
  "id": "sr_01...",
  "overall": "potential_match",
  "hits": [
    {
      "id": "hit_01...",
      "list_name": "UN Sanctions",
      "match_score": 92,
      "entity_name": "Jane M. Smith",
      "entity_type": "individual",
      "disposition": "pending"
    }
  ]
}

POST/screening/hits/:hitId/dispose

Dispose a screening hit — true match or false positive.

Auth: Session (compliance reviewer)

Parameters

Field	Type	Req	Description
disposition	string	yes	true_match \| false_positive
reason	string	no	Reviewer notes

Response

{
  "id": "hit_01...",
  "disposition": "false_positive",
  "disposed_at": "2025-01-15T11:00:00Z"
}

Onboarding

POST/onboarding/sessions

Create an onboarding session. Returns a session token the applicant uses to complete their flow via the hosted UI or Web SDK.

Auth: API key

Parameters

Field	Type	Req	Description
flow_id	string	yes	ID of the onboarding flow to run
channel	string	no	web \| mobile \| api (default web)
subject	object	no	Pre-fill subject data: { pii: { name, email, ... } }
external_ref	string	no	Your internal reference (customer ID)
metadata	object	no	Arbitrary key-value pairs stored on the session

Response

{
  "session_id": "sess_01...",
  "token": "eyJ...",
  "url": "https://risk.sayele.co/onboard/sess_01...",
  "expires_at": "2025-01-15T12:30:00Z"
}

GET/onboarding/sessions/:id

Get the current state of an onboarding session.

Auth: API key or session token

Response

{
  "session_id": "sess_01...",
  "status": "in_progress",
  "current_step": "document_upload",
  "subject_id": "subj_01...",
  "started_at": "2025-01-15T10:30:00Z",
  "steps": [
    { "id": "pii_collection", "status": "completed" },
    { "id": "document_upload", "status": "in_progress" },
    { "id": "biometric_check", "status": "pending" }
  ]
}

POST/onboarding/sessions/:id/steps/:stepId/submit

Submit data for a step in the onboarding flow. The required fields depend on the step type.

Auth: Session token (applicant)

Parameters

Field	Type	Req	Description
data	object	yes	Step-specific payload — see flow configuration for field definitions

Response

{
  "step_id": "pii_collection",
  "status": "completed",
  "next_step": "document_upload"
}

Webhooks

GET— Events reference

Sayele Risk sends POST requests to your webhook endpoints on the following events. All payloads include: event, timestamp, tenant_id, and data.

Response

// subject.created
{ "event": "subject.created", "data": { "subject_id": "...", "external_ref": "..." } }

// subject.verified
{ "event": "subject.verified", "data": { "subject_id": "...", "verification_status": "verified" } }

// onboarding.session.completed
{ "event": "onboarding.session.completed", "data": { "session_id": "...", "subject_id": "..." } }

// case.created
{ "event": "case.created", "data": { "case_id": "...", "type": "kyc_review", "priority": "high" } }

// case.sla.breached
{ "event": "case.sla.breached", "data": { "case_id": "...", "sla_due": "..." } }

// screening.potential_match
{ "event": "screening.potential_match", "data": { "subject_id": "...", "hits": 1 } }

// monitoring.alert
{ "event": "monitoring.alert", "data": { "alert_id": "...", "rule": "...", "severity": "high" } }