Quick Reference Card
api_version: v2
base_urls:
uat: https://api.uat.frankie.one
production: https://api.frankie.one
auth_headers:
api_key: required
X-Frankie-CustomerID: required (UUID)
X-Frankie-CustomerChildID: optional (UUID)
X-Frankie-Channel: optional (api|portal|smartui|custom)
X-Frankie-Username: optional (email for audit)
rate_limits:
execute_workflow: 20 TPS
tracked_by: CustomerID + CustomerChildID combination
session_urls:
uat: https://backend.kycaml.uat.frankiefinancial.io/auth/v1/machine-session
production: https://backend.kycaml.frankiefinancial.io/auth/v1/machine-session
1. Complete Endpoint Reference
Individual Management
| Method | Endpoint | Purpose |
|---|
POST | /v2/individuals | Create individual entity |
GET | /v2/individuals/{entityId} | Get individual with all profiles |
PATCH | /v2/individuals/{entityId} | Update individual data |
DELETE | /v2/individuals/{entityId} | Delete individual |
Workflow Operations
| Method | Endpoint | Purpose |
|---|
GET | /v2/workflows | List available workflows |
POST | /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute | Execute workflow |
GET | /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/results | Get workflow results |
System
| Method | Endpoint | Purpose |
|---|
GET | /ruok | Health check |
2. Field Enumerations (Complete)
Document Types
### Valid Identity & Supporting Document Types
These document types **can be submitted** as part of identity or supporting evidence.
| Document Type | Description |
|--------------|------------|
| `OTHER` | Generic document type. Unspecified. |
| `DRIVERS_LICENSE` | Driver's license. |
| `PASSPORT` | Passport. |
| `VISA` | Visa document (not Visa payment card). |
| `IMMIGRATION` | Immigration card. |
| `NATIONAL_ID` | Any national ID card. |
| `TAX_ID` | Any national tax identifier. |
| `NATIONAL_HEALTH_ID` | National health program ID (e.g. Medicare, NHS). |
| `CONCESSION` | State-issued concession card. |
| `HEALTH_CONCESSION` | State-issued health-specific concession card. |
| `PENSION` | State-issued pension ID. |
| `MILITARY_ID` | Military identification card. |
| `BIRTH_CERT` | Birth certificate. |
| `CITIZENSHIP` | Citizenship certificate. |
| `MARRIAGE_CERT` | Marriage certificate. |
| `DEATH_CERT` | Death certificate. |
| `NAME_CHANGE` | Name change confirmation document. |
| `UTILITY_BILL` | Regulated utility bill (electricity, gas, etc.). |
| `BANK_STATEMENT` | Bank or card statement. |
| `BANK_ACCOUNT` | Bank account document. |
| `INTENT_PROOF` | Proof of intent (photo, video, or scanned letter). |
| `ATTESTATION` | Document of attestation (e.g. Statutory Declaration). |
---
### ❌ Internal or Manual Supporting Documents
The following document types are internal or manual review supporting documents.
| Document Type | Reason |
|--------------|-------|
| `SELF_IMAGE` | Used only for biometric comparison. |
| `DEVICE` | Device identifier, not an identity document. |
| `VEHICLE_REGISTRATION` | Not a valid identity document. |
| `PROOF_OF_ADDRESS` | Address evidence must use specific document types. |
| `HOUSE_REGISTRATION` | Not supported. |
| `YELLOW_HOUSE_REGISTRATION` | Not supported (Thor Ror 13). |
| `WORK_PERMIT` | Not accepted as a supporting identity document. |
| `EMPLOYMENT_CERTIFICATE` | Not accepted. |
| `NOTARY_PUBLIC_ID` | Not accepted. |
---
### Business & Corporate Document Types (KYB)
These document types are used **only for business verification (KYB)**.
| Document Type | Description |
|--------------|------------|
| `EXTERNAL_ADMIN` | Appointed administrator details. |
| `CHARGES` | Charges laid against a company or director. |
| `PRE_ASIC` | Pre-ASIC documentation. |
| `ANNUAL_RETURN` | Company annual return. |
| `REPORT` | Frankie-generated report. |
| `TRUST_DEED` | Corporate trust deed. |
| `DEED_OF_VARIATION` | Deed of variation document. |
| `REGISTER_OF_UNIT_HOLDERS` | Register of unit holders. |
| `PARTNERSHIP_AGREEMENT` | Partnership agreement documents. |
| `ADMIN_CHANGE` | Change of administrator. |
| `COMPANY_REPORT` | Registry-filed company report. |
| `ORGANIZATION_PROFILE` | Organization profile document. |
| `ORGANIZATION_OWNERSHIP` | Organization ownership structure. |
---
### Special Document Types
These document types have **special system-level purposes**.
| Document Type | Description |
|--------------|------------|
| `CHECK_RESULTS` | Results of checks completed outside Frankie workflows. |
| `AVIATION_SECURITY_ID` | Aviation Security Identification Card. |
| `MARITIME_SECURITY_ID` | Maritime Security Identification Card. |
---
### Available Enum Values (LLM Reference)
```text
OTHER, DRIVERS_LICENSE, PASSPORT, VISA, IMMIGRATION, NATIONAL_ID,
TAX_ID, NATIONAL_HEALTH_ID, CONCESSION, HEALTH_CONCESSION, PENSION,
MILITARY_ID, BIRTH_CERT, CITIZENSHIP, MARRIAGE_CERT, DEATH_CERT,
NAME_CHANGE, UTILITY_BILL, BANK_STATEMENT, BANK_ACCOUNT, INTENT_PROOF,
ATTESTATION, SELF_IMAGE, DEVICE, VEHICLE_REGISTRATION, PROOF_OF_ADDRESS,
HOUSE_REGISTRATION, YELLOW_HOUSE_REGISTRATION, WORK_PERMIT,
EMPLOYMENT_CERTIFICATE, NOTARY_PUBLIC_ID, EXTERNAL_ADMIN, CHARGES,
PRE_ASIC, ANNUAL_RETURN, REPORT, TRUST_DEED, DEED_OF_VARIATION,
REGISTER_OF_UNIT_HOLDERS, PARTNERSHIP_AGREEMENT, ADMIN_CHANGE,
COMPANY_REPORT, CHECK_RESULTS, AVIATION_SECURITY_ID,
MARITIME_SECURITY_ID, ORGANIZATION_PROFILE, ORGANIZATION_OWNERSHIP
Document Classes
IDENTITY - Primary identity documents
SUPPORTING - Supporting documents (utility bills, etc.)
REPORT - Generated reports
OTHER - Other document types
Address Types
RESIDENTIAL - Home address
BUSINESS - Business/work address
POSTAL - Mailing address
PREVIOUS - Former address
OTHER - Other address type
OTHER,
RESIDENTIAL,
BUSINESS,
POSTAL,
REGISTERED_OFFICE,
PLACE_OF_BUSINESS,
OFFICIAL_CORRESPONDANCE,
PLACE_OF_BIRTH,
OFFICE_LOCALITY,
AUTHORITATIVE_RESIDENTIAL
Address Status
CURRENT - Current active address
PREVIOUS - Previous address
UNVERIFIED - Not yet verified
Phone Types
MOBILE - Mobile phone
HOME - Home landline
WORK - Work phone
OTHER - Other phone type
Email Types
PERSONAL - Personal email
WORK - Work email
BUSINESS - Business email
OTHER - Other email type
Gender Values
MALE
FEMALE
NON_BINARY
OTHER
UNSPECIFIED
Name Types (for alternateNames)
ALIAS - Also known as
PREVIOUS - Former name (maiden name, etc.)
OTHER - Other name type
3. Workflow Response Enumerations
Workflow Execution State
IN_PROGRESS - Workflow is executing
COMPLETED - Workflow finished successfully
CANCELED - Workflow was canceled
TERMINATED - Workflow was terminated early
ERROR - Workflow encountered error
TIMEOUT - Workflow timed out
Workflow Status (Overall Result)
PASS - Verification successful
FAIL - Verification failed
REVIEW - Manual review required
UNCHECKED - Not yet determined
IN_PROGRESS - Still processing
BLOCKED - Processing blocked
INCOMPLETE - Missing required data
Service Profile State
INIT - Just created
AUTO - Automatically assigned
ACTIVE - Profile is active
ARCHIVED - No longer active
BLOCKLISTED - Blocked from actions
INACTIVE - Not currently in use
DELETED - Soft deleted
DUPLICATE - Duplicate of another
Risk Levels
LOW - Minimal risk (score 1-10)
MEDIUM - Moderate risk (score 11-25)
HIGH - Significant risk (score 26-50)
UNACCEPTABLE - Unacceptable risk (score 51+)
UNKNOWN - Cannot determine
4. Issue Categories & Severities
Issue Categories
KYC - Identity verification issues
AML - Anti-money laundering flags
BAD_DATA - Invalid or malformed data
DOCUMENT - Document-related issues
DUPLICATE - Duplicate entity detected
FRAUD - Fraud indicators
IDV - Identity document verification
WATCHLIST - Watchlist/sanctions match
DECEASED - Deceased person match
ACTIVITY - Suspicious activity
SYSTEM - System/technical errors
Issue Severities
INFO - Informational only
WARNING - Non-blocking warning
REVIEW - Requires manual review
BLOCK - Blocks further processing
CRITICAL - Critical issue found
ERROR - Error encountered
Common Issue Codes
NOT_FOUND - Person not found in data sources
BAD_DATA_ID - Invalid document identifier
SERVICE_ERROR - External service error
SERVICE_TIMEOUT - Timeout with the request
PEP / SANCTION - Sanctions/PEP match found
LIVENESS_DETECTION - Biometric liveness failed
DATA_VALIDATION - Document data validation failure
DATA_COMPARISON - Document mismatch with other sources
DENY_LIST - Visa deny list
...
| Category | Issue Type | Severity | Meaning |
|---|
| AML | PEP | REVIEW | Politically Exposed Person detected |
| AML | SANCTION | BLOCK | Sanctions list match |
| AML | MEDIA | REVIEW | Adverse media detected |
| AML | WATCHLIST | REVIEW | Watchlist match |
| ACTIVITY | ACTIVITY_AML | REVIEW | AML-related suspicious activity |
| ACTIVITY | ACTIVITY_FRAUD | REVIEW | Fraud-related suspicious activity |
| ACTIVITY | ACTIVITY_DEVICE | REVIEW | Device-related suspicious activity |
| BAD_DATA | BAD_DATA_NAME | WARNING | Name missing or unusable |
| BAD_DATA | BAD_DATA_DOB | WARNING | Date of birth missing or unusable |
| BAD_DATA | BAD_DATA_DEVICE | WARNING | Device data missing or unusable |
| BAD_DATA | BAD_DATA_ADDRESS | WARNING | Address missing or unusable |
| BAD_DATA | BAD_DATA_ID | WARNING | Identity document missing or unusable |
| BAD_DATA | BAD_DATA_EMAIL | WARNING | Email missing or unusable |
| BAD_DATA | BAD_DATA_MOBILE | WARNING | Mobile number missing or unusable |
| BLOCKLISTED | MATCHED_INTERNAL | BLOCK | Internal blocklist match |
| BLOCKLISTED | MATCHED_SHARED | BLOCK | Shared blocklist match |
| BLOCKLISTED | MATCHED_EXTERNAL | BLOCK | External blocklist match |
| DECEASED | DECEASED | BLOCK | Person is deceased |
| DEVICE | DEVICE_FRAUD_MATCH | REVIEW | Device fraud detected |
| DEVICE | DEVICE_INVALID | WARNING | Device invalid or unverifiable |
| DOCUMENT | DATA_VALIDATION | REVIEW | Document data validation failure |
| DOCUMENT | DATA_CONSISTENCY | REVIEW | Document data inconsistent |
| DOCUMENT | DATA_COMPARISON | REVIEW | Document mismatch with other sources |
| DOCUMENT | VISUAL_AUTHENTICITY | REVIEW | Document failed visual authenticity |
| DOCUMENT | IMAGE_INTEGRITY | REVIEW | Document image integrity issue |
| DOCUMENT | OCR | REVIEW | OCR mismatch with user data |
| DOCUMENT | COMPROMISED_DOCUMENT | BLOCK | Document is compromised |
| DOCUMENT | LIVENESS_DETECTION | REVIEW | Liveness detection failed |
| DOCUMENT | DOCUMENT_COMPARISON | REVIEW | Multiple documents mismatch |
| DOCUMENT | DOCUMENT_CHECK_INCOMPLETE | INFO | Document check incomplete |
| DUPLICATE | DUPLICATE | REVIEW | Duplicate entity detected |
| EXPIRY | REQUIRES_KYC | WARNING | KYC expired |
| EXPIRY | REQUIRES_IDV | WARNING | IDV expired |
| EXPIRY | REQUIRES_AML | WARNING | AML expired |
| EXPIRY | REQUIRES_VISA | WARNING | Visa verification expired |
| FRAUD | FRAUD_LIST | BLOCK | Known fraud list match |
| FRAUD | FRAUD_CHECK | REVIEW | Generic fraud detected |
| FRAUD | FRAUD_DEVICE | REVIEW | Device-based fraud detected |
| FRAUD | FRAUD_IP_ADDRESS | REVIEW | IP-based fraud detected |
| FRAUD | FRAUD_EMAIL_ADDRESS | REVIEW | Email-based fraud detected |
| FRAUD | FRAUD_PHONE_NUMBER | REVIEW | Phone-based fraud detected |
| FRAUD | FRAUD_INCOMPLETE | INFO | Fraud check incomplete |
| KYC | PARTIAL | REVIEW | Partial KYC success |
| KYC | NOT_FOUND | REVIEW | No identity match found |
| KYC | KYC_INCOMPLETE | INFO | KYC incomplete |
| SYSTEM | SERVICE_TIMEOUT | ERROR | All providers timed out |
| SYSTEM | SERVICE_ERROR | ERROR | Provider or internal system error |
| VISA | DENY_LIST | BLOCK | Visa deny list match |
| VISA | VISA_FAILED | REVIEW | Visa verification failed |
| BIOMETRICS | LIVENESS_DETECTION | REVIEW | Biometric liveness failed |
| BIOMETRICS | DOCUMENT_COMPARISON | REVIEW | Selfie vs document mismatch |
| BIOMETRICS | BIOMETRICS_INCOMPLETE | INFO | Biometrics incomplete |
| WATCHLIST | INTERNAL_MATCH | REVIEW | Internal watchlist match |
| RISK | RISK_THRESHOLD_HIGH | REVIEW/BLOCK | High risk |
| RISK | RISK_THRESHOLD_UNACCEPTABLE | REVIEW/BLOCK | Unacceptable risk |
Risk Factors
FrankieOne calculates an overall risk assessment by evaluating multiple risk factors across identity, AML, fraud, behavior, and workflow integrity.
Each factor contributes to the final risk level (LOW, MEDIUM, HIGH, UNACCEPTABLE) returned in workflow results.
All risk factors, weightings, thresholds, and scoring are configurable per customer. The examples below illustrate typical categories and signals, not fixed scoring rules.
Core Risk Factors (Overview)
| Factor | Description |
|---|
entity_type | Individual or organisation being verified |
entity_age | Age group derived from date of birth |
document_type | Type of identity document provided |
jurisdiction_risk | Risk associated with country of nationality, residence, birth, or document issuance |
pep_level | Politically Exposed Person classification |
sanctions_hits | Sanctions list match severity |
adverse_media | Presence of negative media |
idv_results | Document, facial, and OCR verification outcomes |
fraud_signals | Device, IP, email, phone, and session behavior |
behavioral_signals | Relationship length and workflow attempt patterns |
workflow_integrity | Duplicate entities or internal blocklists |
Assessing Risk
Risk Categories & Signals
Entity Profile Risk
| Risk Factor | Handler | Values |
|---|
| Entity Type | entity_age | Under 18, Under 25, Adult 25+, Senior 65+ |
| Entity Type | entity_type | Individual, Organisation |
| Document Type | document_type_lookup | Passport, Driver License, National ID, Visa, Birth Certificate, Tax ID, etc. |
| Nationality Risk | jurisdiction_lookup | Country-based |
| Residential Country Risk | jurisdiction_lookup | Country-based |
| Birth Country Risk | jurisdiction_lookup | Country-based |
| Document Issuing Country Risk | jurisdiction_lookup | Country-based |
AML & Screening Risk
| Risk Factor | Handler | Values |
|---|
| Sanctions Hits | num_sanctions | Low, Medium, High |
| PEP Level | pep_level_lookup | Level 1–4 |
| PEP Origin | pep_origin_lookup | Local, Foreign |
| Adverse Media | has_adverse_media | TRUE / FALSE |
| Watchlist Match | on_watchlist | TRUE / FALSE |
Identity Verification (IDV) Risk
| Risk Factor | Handler |
|---|
| Document Verification Result | idv_document_result |
| Facial Comparison Result | idv_facial_comparison_result |
| OCR Consistency Result | idv_ocr_comparison_result |
Onboarding Fraud Risk
| Risk Factor | Handler | Values |
|---|
| Device Risk | fraud_device | LOW, MEDIUM, HIGH, UNACCEPTABLE, UNKNOWN |
| IP Address Risk | fraud_ip_address | LOW, MEDIUM, HIGH, UNACCEPTABLE, UNKNOWN |
| Email Risk | fraud_email | LOW, MEDIUM, HIGH, UNACCEPTABLE, UNKNOWN |
| Phone Risk | fraud_phone_number | LOW, MEDIUM, HIGH, UNACCEPTABLE, UNKNOWN |
| Session Count | fraud_count_session | ≤2, 3–5, >5 |
Behavioral & Integrity Risk
| Risk Factor | Handler | Values |
|---|
| Relationship Length | relationship_length | New, Short, Established, Credible |
| Workflow Attempts | workflow_attempts_counter | Low, Multiple, High |
Workflow Logic Risk
| Risk Factor | Handler | Impact |
|---|
| Potential Duplicate | unresolved_duplicates | Review or block |
| Confirmed Duplicate | true_positive_duplicates | Block |
| Internal Matchlist | on_matchlist_internal | Block |
Custom Risk Factors
| Risk Factor | Handler |
|---|
| Customer-defined attributes | custom_attribute_lookup |
How Risk Is Used
- Risk factors are evaluated during workflow execution
- Results contribute to:
riskLevelriskScore- Issue categories and severities
- Outcomes may trigger:
- Step-up verification
- Manual review
- Workflow termination
Risk scoring models vary by jurisdiction, industry, and customer configuration. Always validate behavior in UAT before production rollout.
6. OneSDK Events (Complete)
Lifecycle Events
oneSdk.on('ready', () => {}) // SDK initialized
oneSdk.on('loading', () => {}) // Component loading
oneSdk.on('mounted', () => {}) // Component mounted to DOM
oneSdk.on('unmounted', () => {}) // Component removed from DOM
Result Events
oneSdk.on('results:success', (data) => {}) // Verification passed
oneSdk.on('results:partial', (data) => {}) // Partial success, review needed
oneSdk.on('results:pending', (data) => {}) // Still processing
oneSdk.on('results:fail', (data) => {}) // Verification failed
// Legacy format (also supported)
oneSdk.on('form:result:success', (data) => {})
oneSdk.on('form:result:failed', (data) => {})
oneSdk.on('form:result:pending', (data) => {})
oneSdk.on('form:result:partial', (data) => {})
oneSdk.on('form:input:changed', (field, value) => {})
oneSdk.on('form:input:valid', (field) => {})
oneSdk.on('form:input:invalid', (field, errors) => {})
oneSdk.on('form:submitted', (data) => {})
oneSdk.on('form:step:changed', (step) => {})
Document Events
oneSdk.on('document:uploaded', (docInfo) => {})
oneSdk.on('document:captured', (docInfo) => {})
oneSdk.on('document:error', (error) => {})
Biometric Events
oneSdk.on('biometric:started', () => {})
oneSdk.on('biometric:captured', (data) => {})
oneSdk.on('biometric:error', (error) => {})
Error Events
oneSdk.on('error', (error) => {
// error.code, error.message, error.details
})
Catch-All
oneSdk.on('*', (eventName, eventData) => {
console.log(eventName, eventData);
})
7. Error Codes
Authentication Errors (AUTH-*)
| Code | Message | Resolution |
|---|
AUTH-0001 | Missing credentials | Add api_key and X-Frankie-CustomerID headers |
AUTH-0002 | Unauthorized | Check API key is valid |
AUTH-0003 | Forbidden | Check CustomerID has access |
AUTH-0004 | Token expired | Generate new session token |
Validation Errors (API-*)
| Code | Message | Resolution |
|---|
API-0400 | Bad request | Check request body format |
API-0404 | Not found | Check endpoint URL and entityId |
API-0409 | Conflict | Entity already exists |
API-0422 | Unprocessable entity | Validate field values |
API-0429 | Rate limited | Reduce request frequency |
System Errors (SYS-*)
| Code | Message | Resolution |
|---|
SYS-1000 | Internal error | Retry request |
SYS-1063 | Report generation failed | Contact support |
SYS-1100 | Service unavailable | Check status page |
Workflow Errors (WF-*)
| Code | Message | Resolution |
|---|
WF-0001 | Workflow not found | Check workflowName spelling |
WF-0002 | Workflow not available | Workflow not enabled for account |
WF-0003 | Missing required data | Add required fields for workflow |
8. Workflow Requirements Matrix
| Workflow | Document Required | Address Required | DOB Required | Name Required |
|---|
*-IDOnly | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |
*-TwoPlus | ❌ No | ✅ Yes | ✅ Yes | ✅ Yes |
*-TwoPlusID | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
*-OnePlusOne | ✅ Yes | ❌ No | ✅ Yes | ✅ Yes |
*-AgeVerify | ❌ No | ❌ No | ✅ Yes | ✅ Yes |
*-AddressVerify | ❌ No | ✅ Yes | ❌ No | ✅ Yes |
Document Requirements by Workflow Type
IDOnly Workflows:
{
"documents": {
"IDENTITY": [{
"type": "PASSPORT|DRIVERS_LICENSE|NATIONAL_ID",
"country": "AUS",
"primaryIdentifier": "required"
}]
}
}
{
"addresses": [{
"type": "RESIDENTIAL",
"country": "AUS",
"streetNumber": "required", //unless in streetName address line 1
"streetName": "required", //can have address line 1
"locality": "required", //generally required city/town/locality
"subdivision": "required", //generally required state/region/subdivision
"postalCode": "required"
}]
}
9. Complete Request/Response Examples
Create Individual + Execute Workflow
Request:
POST /v2/individuals HTTP/1.1
Host: api.uat.frankie.one
api_key: your-api-key
X-Frankie-CustomerID: your-customer-id
Content-Type: application/json
{
"individual": {
"name": {
"givenName": "Jane",
"middleName": "",
"familyName": "Smith"
},
"dateOfBirth": {
"year": "1990",
"month": "05",
"day": "15"
},
"addresses": [{
"type": "RESIDENTIAL",
"country": "AUS",
"streetNumber": "123",
"streetName": "Main",
"streetType": "Street",
"locality": "Sydney",
"subdivision": "NSW",
"postalCode": "2000"
}],
"documents": {
"IDENTITY": [{
"type": "PASSPORT",
"country": "AUS",
"primaryIdentifier": "PA1234567"
}]
}
},
"serviceName": "KYC",
"workflowName": "AUS-Basic1V-IDOnly"
}
{
"individual": {
"entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"entityType": "INDIVIDUAL",
"name": {
"nameId": "uuid",
"givenName": "Jane",
"familyName": "Smith",
"displayName": "Jane Smith"
},
"dateOfBirth": {
"dateOfBirthId": "uuid",
"year": "1990",
"month": "05",
"day": "15",
"normalized": "1990-05-15"
},
"createdAt": "2026-01-27T00:00:00.000Z"
},
"serviceProfiles": [{
"serviceProfileId": "uuid",
"entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"serviceName": "KYC",
"state": "INIT"
}],
"requestId": "01HN9XHZN6MGXM9JXG50K59Q85"
}
Execute Workflow
Request:
POST /v2/individuals/3fa85f64-5717-4562-b3fc-2c963f66afa6/serviceprofiles/KYC/workflows/AUS-Basic1
V-IDOnly/execute HTTP/1.1
Host: api.uat.frankie.one
api_key: your-api-key
X-Frankie-CustomerID: your-customer-id
Content-Type: application/json
{}
{
"requestId": "01HN9XHZN6MGXM9JXG50K59Q86",
"workflowExecutionId": "01HN9XHZN6MGXM9JXG50K59Q87"
}
Get Results
Request:
GET /v2/individuals/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1
Host: api.uat.frankie.one
api_key: your-api-key
X-Frankie-CustomerID: your-customer-id
{
"individual": { ... },
"serviceProfiles": [{
"serviceName": "KYC",
"state": "ACTIVE",
"workflowSummaries": [{
"workflowName": "AUS-Basic1V-IDOnly",
"workflowExecutionId": "01HN9...",
"workflowExecutionState": "COMPLETED",
"status": "PASS",
"steps": {
"order": ["START", "MATCHLIST", "KYC"],
"passed": ["START", "MATCHLIST", "KYC"],
"failed": [],
"incomplete": []
},
"issues": [],
"riskAssessment": {
"riskLevel": "LOW",
"riskScore": 7
}
}]
}]
}
10. Webhook Payload Schemas
WorkflowComplete Event
{
"version": "2.0",
"notificationType": "EVENT",
"function": "WorkflowComplete",
"functionResult": "SUCCESS",
"requestId": "01HN9...",
"entityId": "3fa85f64-...",
"entityType": "INDIVIDUAL",
"entityCustomerReference": "your-ref-123",
"serviceName": "KYC",
"workflowExecutionId": "01HN9...",
"workflowName": "AUS-Basic1V-IDOnly",
"overallStatus": "PASS",
"message": "Workflow completed successfully",
"channel": "api"
}
EntityRiskChanged Event
{
"version": "2.0",
"notificationType": "EVENT",
"function": "EntityRiskChanged",
"functionResult": "SUCCESS",
"entityId": "3fa85f64-...",
"serviceName": "KYC",
"previousRiskLevel": "LOW",
"newRiskLevel": "MEDIUM",
"riskScore": 18
}
11. Australian Document Identifiers
Licence Number Formats
| State | Format | Length | Example |
|---|
| ACT | Numeric | Up to 10 | 123456789 |
| NT | Numeric | Up to 10 | 123456789 |
| QLD | Numeric | 8-9 | 12345678 |
| NSW | Alphanumeric | 6-8 | N49187 |
| SA | Alphanumeric | 6 | ABC123 |
| TAS | Alphanumeric | 6-8 | A12345 |
| VIC | Numeric | Up to 10 | 123456789 |
| WA | Numeric | 7 | 1234567 |
| State | Format | Length | Example |
|---|
| ACT | Alphanumeric | 10 | ABC1234567 |
| NT | Numeric | 6-8 | 123456 |
| QLD | Alphanumeric | 10 | ABC1234567 |
| NSW | Numeric | 10 | 1234567890 |
| SA | Alphanumeric | 9 | ABC123456 |
| TAS | Alphanumeric | 9 | ABC123456 |
| VIC | Alphanumeric | 8 | ABC12345 |
| WA | Alphanumeric | 8-10 | ABC123456 |
- Australian: 2 letters + 7 digits (e.g., PA1234567)
- International: Varies by country
Medicare Card
- 10 digits + IRN (1 digit)
- Format: XXXX XXXXX X/X
12. Testing in UAT
Test Data Behavior
- UAT environment connects to test data sources
- Fake document numbers will return
NOT_FOUND or BAD_DATA_ID
- Use FrankieOne-provided test credentials for realistic responses
Expected Test Results
| Scenario | Expected Status | Issues |
|---|
| Valid real ID | PASS | None |
| Fake ID number | FAIL | BAD_DATA_ID |
| Missing ID for IDOnly | 400 Error | Validation error |
| Expired document | FAIL | DOCUMENT_EXPIRED |
13. Rate Limiting
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706316000
Retry-After: 60
Best Practices
- Implement exponential backoff
- Cache workflow list (changes infrequently)
- Batch operations where possible
- Use webhooks instead of polling
14. SDK Installation
NPM
npm install @frankieone/one-sdk
CDN
<script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
Initialization
const oneSdk = await OneSDK({
session: sessionTokenFromBackend,
mode: "development", // or "production"
recipe: {
form: {
provider: { name: 'react' } // or 'vanilla'
}
}
});
OpenAPI & Swagger Specification
| Item | Status | How to Resolve |
|---|
| OpenAPI / Swagger spec | Available | Access via https://docs.frankieone.com/docs/introduction/resources |
The OpenAPI specifications are published as separate resources.
Use the KYC v2 spec for individual, workflow, document, and results APIs.
Use the Core v2 spec for shared operations such as workflow discovery and audit access.
Remaining Gaps (Contact Support)
| Item | Status | How to Resolve |
|---|
| Webhook setup | Requires manual config | Email [email protected] |
| Custom workflows | Account-specific | Contact Customer Success |
| Production credentials | Requires contract | Contact Sales |
