FrankieOne Integration Architecture Guide

​

Purpose

• System-to-system communication patterns
• Data flow and sequencing
• Infrastructure considerations
• Security and compliance requirements
• Common integration architectures for different use cases

​

Audience

• Solution Architects — design the integration architecture
• Technical Leads — understand system boundaries and responsibilities
• Project Managers — understand technical dependencies and timelines
• Security Teams — understand data flows and security requirements

​

Contents

• Core Architecture Concepts
• Integration Pattern 1: Hybrid (API + Portal)
• Integration Pattern 2: Fully Automated (API-Only)
• Integration Pattern 3: Platform/Marketplace Model
• Technical Considerations
• Security & Compliance
• When to Consult FrankieOne
• Summary: Choosing Your Integration Approach

​

Core Architecture Concepts

​

System Boundaries

​

Key Components

​

FrankieOne API

• Protocol: HTTPS REST
• Authentication: API Key + Customer ID headers
• Base URLs:
  • V2 UAT: https://api.uat.frankie.one/v2/
  • V2 Production: https://api.frankie.one/v2/
  • V1 Production: https://api.kycaml.frankiefinancial.io/compliance/v1.2/

• Create individuals and organisations
• Execute verification workflows
• Retrieve results
• Update entity data

​

Webhooks

• Direction: FrankieOne → Your system
• Protocol: HTTPS POST
• Format: JSON
• Purpose: Asynchronous event notifications
• Retry policy: Exponential backoff (up to 50 retries over 24 hours)

​

FrankieOne Portal

• Access: Web UI (HTTPS)
• Authentication: Username/password + MFA
• Purpose: Case management, manual review, reporting
• Users: Compliance and operations teams

​

OneSDK (Optional)

• Type: Client-side JavaScript SDK
• Deployment: Embedded in web or mobile apps
• Purpose: Document capture, biometrics, form collection
• Communication: Direct to FrankieOne API using session tokens

​

Data Flow Fundamentals

• Create an entity and execute a workflow via API
• Receive an immediate response (synchronous result + IDs you’ll need later)
• FrankieOne sends webhooks if the workflow status changes (or completes asynchronously)
• Your webhook handler should acknowledge quickly and then fetch full results
• Your system applies decision logic (PASS / FAIL / REVIEW) and proceeds with onboarding

​

End-to-end flow diagram

​

Practical notes

• Always store identifiers from step 2 (e.g. requestId, entityId, and any workflow/execution IDs returned), so you can fetch results later.
• Treat webhooks as a signal, not the full truth. A best practice is:
  • Respond 200 quickly, then
  • Fetch the latest results via API, then
  • Update your database and trigger downstream actions.
• Make webhook handling idempotent (duplicate deliveries can occur).

​

Example webhook handling approach (recommended)

// Pseudocode: acknowledge fast, then process async
app.post("/frankieone-webhook", async (req, res) => {
  res.status(200).send("OK"); // respond quickly

  // enqueue for background processing
  await queue.publish({
    type: req.body.function,
    requestId: req.body.requestId,
    entityId: req.body.entityId,
    payload: req.body
  });
});

​

Integration Pattern 1: Hybrid (API + Portal)

​

Overview

• Fintech onboarding with edge-case review
• E-commerce seller verification
• Lending platforms with risk-based decisioning

​

Architecture

Your App → Your Backend → FrankieOne API
                         ↘
                          FrankieOne Portal (Manual Review)
                         ↗
                     Webhooks

​

Key Decisions

​

Where does entity data live?

• Your system remains the source of truth
• FrankieOne stores verification context
• Link records using a stable reference

{
  "customerId": "CUST-12345",
  "frankieEntityId": "entity-abc-123",
  "verificationStatus": "PENDING"
}

​

Synchronous vs Asynchronous Workflows

• Immediate response (2–10 seconds)
• Best for real-time onboarding

• Immediate acknowledgement
• Final result via webhook
• Best for high volume or long-running checks

​

Webhook Architecture (Recommended)

Load Balancer
     ↓
Webhook Endpoint (respond 200 immediately)
     ↓
Message Queue
     ↓
Worker Process (fetch results, update DB)

• HTTPS only
• Idempotent processing
• Fast response under 5s

​

Integration Pattern 2: Fully Automated (API-Only)

​

Overview

• High-volume lending platforms
• Crypto exchanges
• Enterprises with Salesforce or ServiceNow

​

Characteristics

• No operational dependency on the FrankieOne Portal
• All decisioning handled in your systems
• FrankieOne used purely as a verification engine

​

Responsibilities

• Case management system
• Review UI
• Escalation workflows
• Decision logic

• Verification execution
• Data sources
• Audit trail

​

Integration Pattern 3: Platform / Marketplace Model

​

Overview

• Marketplaces
• SaaS platforms
• White-label onboarding products

​

Parent / Child Account Model

Your Platform (Parent)
├── Customer A (Child)
│   └── End Users
├── Customer B (Child)
└── Customer C (Child)

​

API Example (Child Routing)

await frankieOneAPI.createEntity({
  headers: {
    api_key: PLATFORM_API_KEY,
    "X-Frankie-CustomerID": PLATFORM_CUSTOMER_ID,
    "X-Frankie-CustomerChildID": CUSTOMER_CHILD_ID
  },
  body: {
    individual: { ... },
    extraData: [
      { "kvpKey": "platform_customer_id", "kvpValue": "CUSTOMER-A" }
    ]
  }
});

​

Technical Considerations

​

Authentication & Secrets

• Never expose API keys client-side
• Store keys in a secrets manager
• Rotate keys regularly

​

Networking

• Outbound HTTPS (443) to FrankieOne APIs
• Inbound HTTPS (443) for webhooks
• IP allowlisting available on request

​

Error Handling

​

Security & Compliance

​

Data Protection

• All data encrypted in transit (TLS 1.2+)
• Encrypted at rest (AES-256)
• SOC 2 Type II & ISO 27001 compliant

​

Logging Guidance

• Request IDs
• Entity IDs
• Status transitions

• API keys
• Full PII
• Documents or biometrics

​

When to Consult FrankieOne

• High-volume requirements (>10k/day)
• Multi-region or data residency needs
• Complex platform or marketplace architecture
• Custom workflow or data source requirements
• Production performance issues

​

Summary: Choosing Your Integration Approach

​

Next Steps

• Identify your integration pattern
• Review architecture with FrankieOne
• Implement in UAT
• Test webhooks and failure scenarios
• Go live and monitor