A Practical Guide to Testing FrankieOne v2 APIs

Never use real customer data in testing environments. FrankieOne handles sensitive personally identifiable information (PII) for KYC/AML verification. Always use testbed data in UAT/Sandbox environments. Real customer data must only be processed in Production with appropriate controls.

Document Overview

This guide explains how to use Postman or Bruno to explore and test FrankieOne’s v2 APIs, helping you understand how our platform works before integrating it into your application. API Version: This guide focuses on v2 APIs (recommended for all new integrations)

What You’ll Learn

What Postman and Bruno are and why they’re useful
How to choose the right tool for your team
How to access FrankieOne’s v2 API collection
How to set up your environment
How to create entities using v2 payloads
How to run verification checks
How to view results in the FrankieOne Portal
Common testing scenarios with v2
Troubleshooting tips

Who Should Read This

Developers evaluating FrankieOne
Technical teams planning integration
Anyone wanting to understand FrankieOne’s v2 APIs
Teams testing verification workflows

Choosing Your API Client
Getting Started
Setting Up Your Environment
Understanding the v2 API Collection
Using Testbed Data
Running Your First v2 API Call
Viewing Results in the Portal
Common Testing Scenarios
Understanding API Responses
Best Practices
Troubleshooting
Next Steps
FAQs

Choosing Your API Client

What Are API Clients?

API clients are tools that allow you to send API requests without writing code, see responses in real-time, and test different scenarios easily. Think of them as: A visual interface for interacting with APIs—like a web browser for APIs instead of websites.

Postman vs Bruno

Feature	Postman	Bruno
Price	Free tier (with limits)	Completely free and open-source
Storage	Cloud-based	Local filesystem
Account Required	Yes (for full features)	No
Collaboration	Postman cloud	Git version control
Offline Use	Limited	Full support
Collection Format	JSON	Bru (plain text)
Learning Curve	Beginner-friendly	Beginner-friendly

Which Should You Choose?

Choose Postman if you:

Want cloud sync across devices
Prefer a polished, feature-rich interface
Need built-in team collaboration features
Are already familiar with Postman

Choose Bruno if you:

Want to version control your API collections with Git
Prefer data stored locally (privacy-focused)
Don’t want to create an account
Work offline frequently
Want a lightweight, fast tool

Both tools work equally well with FrankieOne’s v2 APIs. Choose based on your team’s preferences.

Getting Started

Step 1: Install Your Chosen Tool

Postman
Bruno

Download:

Visit: https://www.postman.com/downloads/
Choose your operating system (Windows, Mac, Linux)
Download and install
Create a free account (optional but recommended)

Alternative: Use Postman Web (browser-based) at https://web.postman.co

Download:

Visit: https://www.usebruno.com/downloads
Choose your operating system (Windows, Mac, Linux)
Download and install
No account required

Alternative (Command Line):

# macOS (Homebrew)
brew install bruno

# Windows (Chocolatey)
choco install bruno

# Linux (Snap)
snap install bruno

Step 2: Get FrankieOne’s v2 API Collection

Where to get the collection:

Download directly: FrankieOne Developer Resources — look for the v2 API collection file (.json)
Contact your FrankieOne representative if the collection is not available on the resources page

The collection includes pre-configured v2 API requests, example payloads for all v2 endpoints, and requests organized by functionality.

Step 3: Import the Collection

Postman
Bruno

Click “Import” (top left)
Choose file or drag and drop
Select the FrankieOne v2 collection file
Click “Import”

Result: Collection appears in left sidebar, ready to use.

Step 4: Get Your API Credentials

You’ll need:

Credential	Description
Customer ID	Also called Account ID or X-Frankie-CustomerID
Customer Child ID	Optional - for sub-account isolation (if configured)
API Key	Authentication token
Environment	UAT/Sandbox for testing

How to Get Them:

Contact your FrankieOne representative
Request UAT/Sandbox access
Ask about Customer Child ID (if you have sub-accounts)
Receive credentials via secure channel
Keep credentials secure

Environments:

Environment	Base URL	Purpose
UAT	`https://api.uat.frankie.one`	User Acceptance Testing—for testing before production
Sandbox	`https://api.uat.frankie.one`	Development and testing
Production	`https://api.frankie.one`	Live use only (not for testing)

Quick Authentication Reference

Here’s exactly how your authentication headers should look in every v2 API request:

api_key: machine_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Frankie-CustomerID: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
X-Frankie-CustomerChildID: your-child-id    (optional - only if configured)
Content-Type: application/json

Do not commit API keys to source control. Store credentials in environment variables and add environment files to .gitignore.

Understanding Customer Child ID

What is Customer Child ID? X-Frankie-CustomerChildID is an optional header used for sub-account isolation within your main FrankieOne account. When to Use It:

Scenario	Use CustomerChildID?
Single account, no sub-divisions	❌ No - leave blank
Multiple business units or brands	✅ Yes - if configured by FrankieOne
White-label implementations	✅ Yes - if configured by FrankieOne
Reseller/partner accounts	✅ Yes - if configured by FrankieOne

How It Works: Key Points:

CustomerChildID is configured by FrankieOne - you cannot create child IDs via API
All entities created with a specific CustomerChildID are isolated to that sub-account
Reporting and data access are separated by CustomerChildID
If you don’t have sub-accounts, leave this header blank or omit it

Important: If you have CustomerChildID configured, you must use the correct value in the header. Using the wrong CustomerChildID or omitting it when required may result in entities being created in the wrong sub-account or authentication errors.

To Get Your CustomerChildID:

Contact your FrankieOne representative
Ask if you have sub-accounts configured
Receive CustomerChildID values if applicable
Add to your environment variables

Setting Up Your Environment

What Are Environments?

Environments store variables like your API base URL, Customer ID, and API Key. They let you:

Switch between UAT and Production easily
Keep credentials secure
Reuse variables across all requests
Share collections without exposing keys

Required Variables for v2 API

Variable	Value	Description
`baseUrl`	`https://api.uat.frankie.one`	UAT API endpoint
`customerId`	`your-customer-id`	Your Customer ID (also called X-Frankie-CustomerID)
`customerChildId`	`your-customer-child-id`	Optional: Customer Child ID for sub-account isolation
`apiKey`	`your-api-key`	Your API Key
`basePath`	`compliance/v1.2`	API version path
`entityId`	(will be populated after creating entity)	Entity ID for subsequent requests

Creating Your Environment

Postman
Bruno

Step 1: Create New Environment

Click “Environments” (left sidebar)
Click ”+” to create new
Name it: FrankieOne v2 UAT

Step 2: Add Variables

Variable	Initial Value	Current Value
`baseUrl`	`https://api.uat.frankie.one`	`https://api.uat.frankie.one`
`customerId`	`your-customer-id`	`your-customer-id`
`customerChildId`	`your-customer-child-id` (optional)	`your-customer-child-id` (optional)
`apiKey`	`your-api-key`	`your-api-key`
`basePath`	`compliance/v1.2`	`compliance/v1.2`
`entityId`

Step 3: Activate Environment

Click “Save”
Select environment from dropdown (top right)

Step 1: Open Environment Settings

Click the gear icon (Environments)
Click “Create Environment”
Name it: FrankieOne v2 UAT

Step 2: Add Variables

baseUrl: https://api.uat.frankie.one
basePath: compliance/v1.2
customerId: your-customer-id
customerChildId: your-customer-child-id
apiKey: your-api-key
entityId:

customerChildId is optional and used for sub-account isolation. Leave blank if not applicable.

Step 3: Activate Environment

Click “Save”
Select FrankieOne v2 UAT from the environment dropdown

Environment files are stored as .bru files in your collection’s environments/ folder. You can edit them directly in any text editor.

Using Variables in Requests

Both Postman and Bruno use the same syntax for variables:

{{variableName}}

Example v2 Request URL:

{{baseUrl}}/{{basePath}}/v2/individuals

Example Headers:

api_key: {{apiKey}}
X-Frankie-CustomerID: {{customerId}}
X-Frankie-CustomerChildID: {{customerChildId}}
Content-Type: application/json

X-Frankie-CustomerChildID is optional. Include it only if you have sub-accounts or child entities configured by FrankieOne.

The tool automatically replaces {{variableName}} with the actual value from your environment.

Understanding the v2 API Collection

v2 API Structure

FrankieOne’s v2 API collection is organized by entity type and functionality:

FrankieOne v2 API Collection
│
├── Individuals (v2)
│   ├── Create Individual
│   ├── Get Individual
│   ├── Update Individual
│   └── Search Individuals
│
├── Individual Workflows (v2)
│   ├── Execute Workflow
│   └── Workflow Examples
│
├── Individual Documents (v2)
│   ├── Create Document
│   ├── Upload Document Image
│   └── Get Document
│
├── Individual Actions (v2)
│   ├── Get IDV Token
│   ├── Process IDV OCR
│   └── Process IDV Biometrics
│
├── Organizations (v2)
│   ├── Create Organization
│   ├── Get Organization
│   └── Update Organization
│
└── Service Profiles (v2)
    ├── Get Service Profiles
    └── Search Service Profiles

Key v2 Endpoints

Category	Endpoint	Purpose
Individuals	`POST /v2/individuals`	Create an individual entity
	`GET /v2/individuals/{entityId}`	Retrieve individual details
	`PATCH /v2/individuals/{entityId}`	Update individual information
Workflows	`POST /v2/individuals/{entityId}/serviceprofiles/{serviceName}/workflows/{workflowName}/execute`	Execute verification workflow
Documents	`POST /v2/individuals/{entityId}/documents`	Create/upload document
IDV	`POST /v2/individuals/{entityId}/actions/idv/token`	Get IDV token for SDK
	`POST /v2/individuals/{entityId}/actions/idv/ocr`	Submit document for OCR
	`POST /v2/individuals/{entityId}/actions/idv/process`	Process biometric verification

Sample Request and Response

Here’s a complete example of creating an individual and what you’ll get back, so you can quickly validate your setup is working: Request:

POST {{baseUrl}}/{{basePath}}/v2/individuals

Headers:
  api_key: {{apiKey}}
  X-Frankie-CustomerID: {{customerId}}
  Content-Type: application/json

{
  "individual": {
    "name": {
      "givenName": "JAMES",
      "middleName": "A",
      "familyName": "TESTONE"
    },
    "dateOfBirth": {
      "year": "1950",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "country": "AUS"
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Response format depends on the endpoint you use:

Create Individual, then Execute Workflow (two-step): The create response returns the individual object. The workflow execute response returns the workflowResult. See Create Individual and Execute Workflow for full response schemas.
Create and Execute Workflow (single step): The response includes individual, serviceProfile, and workflowResult in a single payload. See Create and Execute Workflow for the full response schema.

Key fields to save:

individual.entityId — Unique identifier for this individual. You’ll need it for subsequent requests (document uploads, re-verification, monitoring).
workflowResult.result — Overall workflow outcome (e.g., PASS, FAIL, REVIEW)
workflowResult.status — Execution status (e.g., COMPLETED)
workflowResult.issues[] — Any issues flagged (e.g., BAD_DATA_ID, RISK_THRESHOLD_HIGH)
workflowResult.workflowStepResults[] — Detailed results per workflow step (KYC, AML, etc.)

Using Testbed Data

What is Testbed Data?

Testbed data is pre-configured test data that produces predictable results in the FrankieOne UAT environment. Purpose:

Test different scenarios
No real customer data needed
Consistent, repeatable results
Safe for testing

Always use testbed data for testing. Do not use fictional names like “John Smith” or “Jane Doe” — use the actual testbed names listed below for consistent, reliable results. Never use real customer PII in UAT/Sandbox environments.

Full testbed data reference: FrankieOne Testbed Data Guide

Test Scenario Types

Scenario	Result	Use Case
PASS (CLEAR)	Verification succeeds	Test successful onboarding
FAIL	Verification fails (e.g. KYC Not Found)	Test rejection flows — see tip below
REVIEW	Manual review required	Test escalation workflows
PEP	Politically Exposed Person match	Test AML screening
SANCTION	Sanctions list match	Test AML screening
PEP, SANCTION	Both PEP and sanctions match	Test combined AML scenarios

Triggering a FAIL (KYC Not Found) result: You don’t need a specific testbed record to test failure scenarios. Simply modify the name, date of birth, or address so it doesn’t match the testbed data. For example, misspell the family name or change the street number. The verification will fail because the data can’t be matched.

v2 Testbed Quick Reference

Here are the key test scenarios. For the complete set of v2 testbed payloads (including Medicare, SSN, Aadhaar, Passport, and more), see the UAT Test Data page.

Test Name	Expected Result	Use Case
JAMES TESTONE	CLEAR (PASS)	Successful verification with driver’s license
JUDY TESTTWO	CLEAR (PASS)	Successful verification
JENNY TESTEIGHT	FAIL (KYC Not Found)	KYC not found / rejection flow mispell name to trigger KYC not found
JAMES G TESTELEVEN	PEP match	PEP screening
BRUCE TESTNINETEEN	SANCTION match	Sanctions screening
STACY K TESTTWENTY	PEP + SANCTION	Combined AML screening

PASS Example (JAMES TESTONE) - v2 Format

{
  "individual": {
    "name": {
      "givenName": "JAMES",
      "middleName": "A",
      "familyName": "TESTONE"
    },
    "dateOfBirth": {
      "year": "1950",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "status": "CURRENT",
        "unitNumber": "U 1",
        "streetNumber": "35",
        "streetName": "CONN",
        "streetType": "STREET",
        "locality": "FERNTREE GULLY",
        "subdivision": "VIC",
        "postalCode": "3156",
        "country": "AUS",
        "unstructuredLongForm": "U 1/35 CONN STREET, FERNTREE GULLY, VIC 3156"
      }
    ],
    "documents": {
      "IDENTITY": [
        {
          "type": "DRIVERS_LICENSE",
          "class": "IDENTITY",
          "primaryIdentifier": "283229690",
          "secondaryIdentifier": "P5403241",
          "country": "AUS",
          "subdivision": "VIC"
        }
      ]
    },
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Expected Result: CLEAR (PASS)

PEP Match Example (JAMES G TESTELEVEN) - v2 Format

{
  "individual": {
    "name": {
      "givenName": "JAMES",
      "middleName": "G",
      "familyName": "TESTELEVEN"
    },
    "dateOfBirth": {
      "year": "1960",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "streetNumber": "23",
        "streetName": "ISA",
        "streetType": "STREET",
        "locality": "FYSHWICK",
        "subdivision": "ACT",
        "postalCode": "2609",
        "country": "AUS"
      }
    ],
    "documents": {
      "IDENTITY": [
        {
          "type": "PASSPORT",
          "class": "IDENTITY",
          "primaryIdentifier": "E55173628",
          "country": "AUS",
          "expiryDate": {
            "normalized": "2030-01-01",
            "year": "2030",
            "month": "01",
            "day": "01",
            "type": "GREGORIAN"
          }
        }
      ]
    },
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Expected Result: PEP match

SANCTION Match Example (BRUCE TESTNINETEEN) - v2 Format

{
  "individual": {
    "name": {
      "givenName": "BRUCE",
      "familyName": "TESTNINETEEN"
    },
    "dateOfBirth": {
      "year": "1968",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "country": "AUS"
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Expected Result: SANCTION match

Workflows without ID documents: The SANCTION (TESTNINETEEN) and combined PEP + SANCTION (TESTTWENTY) examples above do not include identity documents. When testing without ID documents, use a workflow that does not require ID verification, such as AUS-Basic3V-TwoPlus. If you use a workflow that expects an ID document (e.g., AUS-Basic3V-TwoPlusID or AUS-Basic1V-IDOnly), you will receive a BAD_DATA_ID error.

Use the actual testbed names (TESTONE, TESTTWO, etc.) — do not use fictional names like “John Smith”. See the full v2 testbed examples for all scenarios including international documents.

Important: Document Type Values in v2Use DRIVERS_LICENSE (American spelling with underscore), not DRIVERS_LICENCE.Valid Document Types:

DRIVERS_LICENSE ✅ (correct - American spelling)
PASSPORT
NATIONAL_ID (used for USA SSN, Aadhaar, China National ID, etc.)
NATIONAL_HEALTH_ID (used for Australian Medicare)
TAX_ID
VISA
IMMIGRATION
BIRTH_CERT
CITIZENSHIP
MARRIAGE_CERT
UTILITY_BILL
BANK_STATEMENT
CONCESSION
PENSION
MILITARY_ID
OTHER

Country-Specific Document Requirements:

Country	Document Type	Primary ID	Secondary ID	Notes
Australia	`DRIVERS_LICENSE`	License number	Card/document number	Both required
Australia	`NATIONAL_HEALTH_ID`	Medicare number (10 digits)	`supplementaryData.reference` (1-9), `subtype` (G/B/Y), `nameOnCardLine1`	All required
USA	`NATIONAL_ID`	SSN (9 digits, no dashes)	Not used	Use for Social Security Number
India	`NATIONAL_ID`	Aadhaar (12 digits)	Not used	No dashes in testbed
China	`NATIONAL_ID`	18-digit ID number	`supplementaryData.homeCountryFullName` (Chinese characters), Pinyin `givenName`/`familyName` on document	`homeCountryFullName` enables NAME_VALIDATION

Australian Driver’s License Requirements: For Australian driver’s licenses, you must include both:

primaryIdentifier - License number (e.g., “283229690”)
secondaryIdentifier - Document number / Card number (e.g., “P5403241”)

Example:

{
  "type": "DRIVERS_LICENSE",
  "class": "IDENTITY",
  "primaryIdentifier": "283229690",
  "secondaryIdentifier": "P5403241",
  "country": "AUS",
  "subdivision": "VIC"
}

Australian Medicare Card Requirements: For Australian Medicare cards, you must include:

primaryIdentifier — Medicare card number (10 digits, e.g., “6603984391”)
subtype — Card color: G (Green), B (Blue), or Y (Yellow)
subdivision — State or territory of issue (e.g., “VIC”)
expiryDate — Must include unstructured (YYYY-MM-DD) and type (“GREGORIAN”)
supplementaryData.reference — Individual reference number (1-9)
supplementaryData.nameOnCardLine1 — Name as printed on the card

Example:

{
  "type": "NATIONAL_HEALTH_ID",
  "class": "IDENTITY",
  "primaryIdentifier": "6603984391",
  "subtype": "G",
  "country": "AUS",
  "subdivision": "VIC",
  "expiryDate": {
    "year": "2030",
    "month": "01",
    "day": "01",
    "unstructured": "2030-01-01",
    "type": "GREGORIAN"
  },
  "supplementaryData": {
    "type": "NATIONAL_HEALTH_ID",
    "reference": "1",
    "nameOnCardLine1": "JAMES A TESTONE",
    "nameOnCardLine2": "null",
    "nameOnCardLine3": "null",
    "nameOnCardLine4": "null",
    "middleNameOnCard": "null"
  }
}

USA Social Security Number: Use NATIONAL_ID document type (NOT TAX_ID):

{
  "type": "NATIONAL_ID",
  "class": "IDENTITY",
  "primaryIdentifier": "123456789",
  "country": "USA"
}

India Aadhaar: Use NATIONAL_ID document type (12 digits without dashes):

{
  "type": "NATIONAL_ID",
  "class": "IDENTITY",
  "primaryIdentifier": "304365000000",
  "country": "IND"
}

China National ID: Use NATIONAL_ID document type (18 digits in production). Provide the name in Pinyin (uppercase) on the document, and the Chinese characters in supplementaryData.homeCountryFullName:

{
  "type": "NATIONAL_ID",
  "class": "IDENTITY",
  "primaryIdentifier": "110105199003077341",
  "country": "CHN",
  "givenName": "WEIMING",
  "familyName": "ZHANG",
  "dateOfBirth": "1990-03-07",
  "supplementaryData": {
    "type": "NATIONAL_ID",
    "homeCountryFullName": "张伟明"
  }
}

Common Mistakes:

❌ DRIVERS_LICENCE (British spelling)
❌ DRIVER_LICENSE (missing S)
❌ Abbreviations like DL

Important v2 Differences from v1:

Dates use objects: {year: "YYYY", month: "MM", day: "DD"}
Address fields: locality (not suburb or city), subdivision (not state), postalCode (not postcode)
Documents nested by category: documents.IDENTITY[]
Document ID field: primaryIdentifier (not idNumber)
schemaVersion: 2 may be included but is optional (it’s a response field)

Running Your First v2 API Call

Overview: Create Individual Entity (v2)

This walkthrough demonstrates:

Creating an individual entity using v2 API
Understanding the v2 response
Saving the entity ID for subsequent requests

Step 1: Select the Create Individual Request (v2)

Postman
Bruno

Expand “Individuals (v2)” folder in left sidebar
Click “Create Individual”
Request details appear on right

Step 2: Review the v2 Request

URL:

POST {{baseUrl}}/{{basePath}}/v2/individuals

Headers:

api_key: {{apiKey}}
X-Frankie-CustomerID: {{customerId}}
X-Frankie-CustomerChildID: {{customerChildId}}
Content-Type: application/json

Header Details:

api_key: Your API authentication key
X-Frankie-CustomerID: Your main customer/account ID
X-Frankie-CustomerChildID: Optional - used for sub-account isolation when configured by FrankieOne
Content-Type: Always application/json for v2 API requests

Body (JSON) - v2 Format:

{
  "individual": {
    "name": {
      "givenName": "JUDY",
      "middleName": "B",
      "familyName": "TESTTWO"
    },
    "dateOfBirth": {
      "year": "1951",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "status": "CURRENT",
        "streetNumber": "17",
        "streetName": "HUME",
        "streetType": "STREET",
        "locality": "PARKES",
        "subdivision": "NSW",
        "postalCode": "2870",
        "country": "AUS",
        "unstructuredLongForm": "17 HUME STREET, PARKES, NSW 2870"
      }
    ],
    "emailAddresses": [
      {
        "type": "PERSONAL",
        "email": "[email protected]",
        "isPreferred": true
      }
    ],
    "phoneNumbers": [
      {
        "type": "MOBILE",
        "number": "+61412345678",
        "isPreferred": true
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Example uses FrankieOne testbed data: JUDY TESTTWO is a real test record in UAT that produces CLEAR (PASS) results. Use actual testbed names for reliable testing.

v2 Key Features:

schemaVersion: 2 is optional (primarily a response field)
Dates are objects, not strings
Addresses use locality, subdivision, postalCode
Email and phone are arrays with type and preference
All wrapped in individual object

Step 3: Send the Request

Postman
Bruno

Click the blue “Send” button (top right)
Wait for response (usually 1-3 seconds)
Response appears in bottom panel

Click “Send” or press Cmd/Ctrl + Enter
Wait for response (usually 1-3 seconds)
Response appears in right panel

Step 4: Review the Response

The response structure depends on the endpoint you use. Refer to the API documentation for full response examples:

Create Individual — returns the individual object
Create and Execute Workflow — returns individual, serviceProfile, and workflowResult in one response

Key fields to look for:

Field	Importance	Description
`status`	Critical	The conclusive recommendation — base your business logic on this value
`workflowExecutionState`	Critical	Must be `COMPLETED` for the status to be final
`individual.entityId`	Critical	Unique identifier — save this for subsequent requests
`result`	Important	Original automated outcome before any manual overrides (useful for auditing)
`issues[]`	Important	Flagged issues (e.g., `BAD_DATA_ID`, `PEP`, `SANCTION`). If status is `REVIEW`, this explains why
`workflowStepResults[]`	Reference	Per-step results for KYC, AML, DECISION, etc.
`riskAssessment`	Reference	Risk score, risk level, and contributing risk factors

For a full guide on interpreting workflow responses, see Interpreting Workflows v2.

Step 5: Save the Entity ID

You’ll need the entityId for subsequent requests (document uploads, re-verification, monitoring).

Postman
Bruno

Manual Method:

Copy entityId from response
Go to your environment (click environment dropdown > Edit)
Update variable: entityId = abc123-def456-ghi789-jkl012
Save environment

Automatic Method (Post-response Script): Add this to the “Tests” tab of your Create Individual request:

const response = pm.response.json();
pm.environment.set("entityId", response.entityId);
console.log("Entity ID saved:", response.entityId);

Manual Method:

Copy entityId from response
Click gear icon and select your environment
Add/update: entityId: abc123-def456-ghi789-jkl012
Save

Automatic Method (Post-response Script): Add this to the request’s post-response script section:

const response = res.getBody();
bru.setEnvVar("entityId", response.entityId);

Success! You’ve created a v2 individual entity.

Executing a Workflow (v2)

What Are Workflows?

Workflows in FrankieOne v2 are pre-configured verification processes that can include:

KYC (Electronic verification)
IDV (Document verification)
AML (Screening)
Risk assessment

Workflows are configured by FrankieOne based on your requirements. You execute them via API but cannot configure them via API.

Step 6: Execute a Workflow

Select the Request:

Expand “Individual Workflows (v2)” folder
Click “Execute Workflow”

URL:

POST {{baseUrl}}/{{basePath}}/v2/individuals/{{entityId}}/serviceprofiles/{{serviceName}}/workflows/{{workflowName}}/execute

Required Variables:

Variable	Example Value	Description
`entityId`	From previous step	Individual’s entity ID
`serviceName`	`KYC`	Service profile name (provided by FrankieOne)
`workflowName`	See workflow table below	Workflow name (provided by FrankieOne)

Common Workflow Names:

Workflow Name	Region	Description
`AUS-Basic3V-TwoPlusID`	Australia	KYC with ID document verification
`AUS-Basic3V-TwoPlus`	Australia	KYC without ID document (name + DOB + address only)
`AUS-Basic1V-IDOnly`	Australia	ID document verification only
`USA-Basic1V-OnePlus`	USA	US identity verification (SSN)
`GLB-Basic1V-OnePlus`	Global	International identity verification (India, China, UK, etc.)

Body:

{
  "comment": {
    "text": "Initial verification workflow"
  }
}

Or if updating individual data and executing workflow:

{
  "individual": {
    "documents": {
      "IDENTITY": [
        {
          "type": "DRIVERS_LICENSE",
          "class": "IDENTITY",
          "primaryIdentifier": "283229690",
          "secondaryIdentifier": "P5403241",
          "country": "AUS",
          "subdivision": "VIC"
        }
      ]
    }
  },
  "comment": {
    "text": "Adding document and executing verification"
  }
}

Send the Request and review the response:

{
  "entityId": "abc123-def456-ghi789-jkl012",
  "workflowExecutionId": "wf-exec-12345",
  "status": "IN_PROGRESS",
  "message": "Workflow execution initiated"
}

Workflow execution is asynchronous. Check the Portal or poll the individual’s details to see when results are available.

Viewing Results in the Portal

Why Use the Portal?

Your API Client Shows	Portal Shows
API request and response	Visual representation
Technical details	Complete verification details
Raw data	Risk assessment with context
Single request view	Timeline of all events
Technical format	Analyst-friendly review interface

Use both together: Send requests in Postman/Bruno, then view detailed results in the Portal.

Accessing the Portal

Environment	URL
UAT	https://portal.uat.frankie.one/login
Production	https://portal.frankie.one/login

Login: Use credentials provided by FrankieOne (same account as API credentials).

Finding Your Individual

Method 1: Search by Name

Click “Entities” in navigation
Enter customer name in search
Click on individual to view

Method 2: Search by Entity ID

Copy entityId from your API response
Paste into search bar
Click on individual

Method 3: View Recent

Click “Entities”
Sort by “Most Recent”
Your test individual should be at top

Understanding the Portal View

Section	What You’ll See
Individual Overview	Name, overall status, risk rating, created date
Verification Checks	Workflow results, check statuses, timestamps
Risk Assessment	Overall score, risk factors, contributing elements
Timeline	Chronological view of all events and status changes
Documents	Uploaded documents and verification results (if IDV performed)

Real-Time Updates

The Portal updates in real-time:

Send API request via Postman/Bruno
Refresh Portal (or wait for auto-refresh)
See new results immediately

Common Testing Scenarios

Scenario 1: Create Individual with Minimal Data

Objective: Test minimal required fields for v2 individual creation v2 Payload:

{
  "individual": {
    "name": {
      "givenName": "PETER",
      "middleName": "C",
      "familyName": "TESTTHREE"
    },
    "dateOfBirth": {
      "year": "1952",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "country": "AUS"
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Expected Result:

Status: 201 Created
Returns entityId
Individual created successfully
Testbed result: CLEAR (PASS)

Scenario 2: Create Individual with Document

Objective: Create individual with identity document for verification v2 Payload:

{
  "individual": {
    "name": {
      "givenName": "MARY",
      "familyName": "TESTFOUR"
    },
    "dateOfBirth": {
      "year": "1953",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "streetNumber": "17",
        "streetName": "WATTLE",
        "streetType": "AVENUE",
        "locality": "WARWICK",
        "subdivision": "QLD",
        "postalCode": "4370",
        "country": "AUS"
      }
    ],
    "documents": {
      "IDENTITY": [
        {
          "type": "DRIVERS_LICENSE",
          "class": "IDENTITY",
          "primaryIdentifier": "103188691",
          "secondaryIdentifier": "QUSQP650QB",
          "country": "AUS",
          "subdivision": "QLD"
        }
      ]
    },
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Expected Result:

Individual created with document
Ready for workflow execution
Document details stored
Testbed result: CLEAR (PASS)

Scenario 3: Minor (Under 18)

Objective: Create individual under 18 years old v2 Payload:

{
  "individual": {
    "name": {
      "givenName": "Oliver",
      "middleName": "J",
      "familyName": "YOUNGTEN"
    },
    "dateOfBirth": {
      "year": "2015",
      "month": "06",
      "day": "15"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "streetNumber": "35",
        "streetName": "Conn",
        "streetType": "Street",
        "locality": "Ferntree Gully",
        "subdivision": "VIC",
        "postalCode": "3156",
        "country": "AUS"
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Key Points:

Must include UNDER18 consent
Age calculated from dateOfBirth
May require guardian information (check with FrankieOne)

Scenario 4: Individual with Custom Attributes

Objective: Store custom business data with individual v2 Payload:

{
  "individual": {
    "name": {
      "givenName": "Sarah",
      "familyName": "Johnson"
    },
    "dateOfBirth": {
      "year": "1992",
      "month": "03",
      "day": "10"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "country": "AUS"
      }
    ],
    "customAttributes": {
      "customerSegment": {
        "type": "STRING",
        "value": "premium"
      },
      "accountType": {
        "type": "STRING",
        "value": "savings"
      },
      "vipStatus": {
        "type": "BOOLEAN",
        "value": "true"
      },
      "creditLimit": {
        "type": "INTEGER",
        "value": "50000"
      }
    },
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Use Cases:

Store business-specific data
Track customer segments
Store account types
Custom workflow routing

For additional country-specific testing scenarios (Medicare, SSN, Aadhaar, China National ID, international passports), see the UAT Test Data page which includes complete v2 payloads for all supported document types.

Understanding API Responses

HTTP Status Codes

Code	Meaning	Action
`200 OK`	Success	Process response data
`201 Created`	Resource created	Save the new resource ID (entityId)
`400 Bad Request`	Invalid request	Check request format and required fields
`401 Unauthorized`	Authentication failed	Verify API key and Customer ID
`404 Not Found`	Resource not found	Verify entity ID exists
`422 Unprocessable Entity`	Validation error	Check field formats and required fields
`500 Server Error`	Server issue	Retry or contact support

Common v2 Response Fields

Response structure varies depending on whether you use Create Individual (two-step) or Create and Execute Workflow (single step). Refer to the API docs for full response schemas:

Part 1: The Overall Outcome (The Final Verdict) Start by examining the top-level fields of the workflowResult object. These provide the final, authoritative outcome of the entire workflow execution. For a full guide on interpreting workflow responses, see Interpreting Workflows v2.

Field	Importance	Description
`status`	Critical	The most important field. This is the conclusive recommendation and accounts for any manual overrides. Base your primary business logic on this value.
`workflowExecutionState`	Critical	Confirms the workflow’s technical status. Must be `COMPLETED` for the `status` to be considered final.
`result`	Important	The original, automated outcome of the workflow before any manual changes. Useful for auditing.
`issues[]`	Important	An array of problems that may require manual review. If the `status` is `REVIEW`, this array contains the specific reasons why.

Part 2: Key Fields to Save

Field	Description
`individual.entityId`	Unique identifier — save for subsequent requests (document uploads, re-verification, monitoring)
`workflowResult.workflowStepResults[]`	Detailed per-step results for KYC, AML, MATCHLIST, DECISION, etc.
`workflowResult.riskAssessment.riskLevel`	Risk level (`LOW`, `MEDIUM`, `HIGH`)
`workflowResult.riskAssessment.riskScore`	Numeric risk score

Error Response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid field value",
    "details": [
      {
        "field": "individual.dateOfBirth.year",
        "message": "Year must be a valid 4-digit year",
        "value": "90"
      }
    ]
  }
}

Common Validation Errors in v2

Error	Cause	Solution
`Invalid date format`	Using string instead of object	Use `{year, month, day}` format
`Unknown field: suburb`	Using v1 field names	Use v2 field names (`locality`, not `suburb` or `city`)
`documents must be an object`	Using array instead of nested object	Use `documents.IDENTITY: [...]` structure
`Invalid field value`	Incorrect data type or format	Check OpenAPI spec for field requirements

Best Practices

1. schemaVersion is Optional

Optional in v2:

{
  "individual": {
    "name": {...},
    "dateOfBirth": {...}
    // schemaVersion: 2 can be included but is not required
  }
}

schemaVersion is marked as readOnly in the OpenAPI specification, meaning it’s primarily a response field. While you can include it in requests, it’s not required and will be returned by the API in responses.

2. Use Correct v2 Field Names

v2 Uses:

locality (not suburb or city)
subdivision (not state)
postalCode (not postcode)
primaryIdentifier (not idNumber)

3. Use Date Objects, Not Strings

Correct v2 Format:

{
  "dateOfBirth": {
    "year": "1990",
    "month": "01",
    "day": "15"
  }
}

Incorrect (v1 format):

{
  "dateOfBirth": "1990-01-15"
}

4. Structure Documents Correctly

Correct v2 Format:

{
  "documents": {
    "IDENTITY": [
      {
        "type": "PASSPORT",
        ...
      }
    ]
  }
}

Incorrect:

{
  "document": {
    "type": "PASSPORT",
    ...
  }
}

5. Use Environment Variables

Why:

Easy to switch between UAT and Production
Keep credentials secure
Reuse across requests
Save entityId automatically

6. Use Testbed Data Only

Never use real customer data in testing environments. This is a compliance requirement for handling PII in KYC/AML systems. Always use FrankieOne’s official testbed data which provides predictable, repeatable results.

7. Check Both API Response and Portal

Complete testing workflow:

Send request in Postman/Bruno
Check API response
View in Portal
Verify both match
Understand complete picture

8. Version Control (Bruno)

Since Bruno stores collections as files:

cd "FrankieOne v2 API"
git init
git add .
git commit -m "Initial FrankieOne v2 API collection"

Add your environment files to .gitignore to avoid committing credentials:

# .gitignore
environments/*.bru

9. Test Edge Cases

Don’t just test the happy path:

Missing optional fields
Invalid data formats
Different countries
Various document types
Minors vs adults
Multiple addresses

Troubleshooting

Authentication Error (401)

Problem: Unauthorized or Invalid API key Solutions:

Check	Action
API key	Verify it’s correct and not expired
Customer ID	Confirm it matches your account
Customer Child ID	If you have sub-accounts, verify CustomerChildID is correct
Environment	Ensure correct environment is selected
Headers	Verify `api_key`, `X-Frankie-CustomerID`, and `X-Frankie-CustomerChildID` (if applicable) headers are present
Header case	Use exact header names: `X-Frankie-CustomerID` (not `x-frankie-customer-id`)

Common Authentication Issues with CustomerChildID:

Using CustomerChildID when you don’t have sub-accounts configured
Using wrong CustomerChildID value
Omitting CustomerChildID when you have sub-accounts
Typos in header name (must be exactly X-Frankie-CustomerChildID)

Date Format Error

Problem: Invalid date format or date validation errors Solutions:

Check	Action
Use objects	Dates must be objects: `{year, month, day}`
Not strings	Don’t use `"1990-01-15"` (that’s v1 format)
String values	Year, month, day are strings: `"1990"`, not `1990`
Padding	Month and day should be zero-padded: `"01"`, not `"1"`

Correct:

{
  "dateOfBirth": {
    "year": "1990",
    "month": "01",
    "day": "15"
  }
}

Field Name Error

Problem: Unknown field or field not recognized Solutions:

v1 Field (Wrong)	v2 Field (Correct)
`suburb`	`locality`
`city`	`locality`
`state`	`subdivision`
`postcode`	`postalCode`
`document`	`documents`
`idNumber`	`primaryIdentifier`
`region`	`subdivision`
`emailAddress`	`emailAddresses` (array)
`phoneNumber`	`phoneNumbers` (array)

Document Structure Error

Problem: Invalid document structure or validation errors Solutions: Correct v2 Structure:

{
  "documents": {
    "IDENTITY": [
      {
        "type": "DRIVERS_LICENSE",
        "class": "IDENTITY",
        "primaryIdentifier": "12345678",
        "country": "AUS",
        "subdivision": "NSW"
      }
    ]
  }
}

Common Mistakes:

Using document instead of documents
Not nesting under category (IDENTITY)
Using array instead of object for documents
Using idNumber instead of primaryIdentifier

Entity Not Found (404)

Problem: Entity not found Solutions:

Check	Action
Entity ID	Verify it’s correct (copy/paste carefully)
Environment	Confirm you’re using the same environment where entity was created
Entity creation	Check that the create request succeeded
URL format	Ensure URL is `/v2/individuals/{entityId}`

No Results in Portal

Problem: Can’t find individual in Portal Solutions:

Check	Action
Environment	Verify you’re logged into the correct Portal environment (UAT vs Production)
Customer ID	Confirm it matches your API credentials
Search	Try searching by entity ID instead of name
Timing	Wait a few seconds and refresh
Filters	Check if any filters are applied in Portal

Bruno-Specific Issues

Collection Not Loading:

Ensure the folder contains a valid bruno.json file
Check file permissions on the collection folder
Verify you’re opening the correct folder

Import Issues:

Bruno supports Postman Collection v2.1 format
If import fails, try exporting from Postman as Collection v2.1
Check for special characters in collection name

Environment Variables Not Working:

Ensure environment is activated (check dropdown)
Verify variable syntax: {{variableName}}
Check for typos in variable names

Getting Help

FrankieOne Support:

Contact your FrankieOne representative
Email: [email protected]
Include: Entity ID, full request/response, error messages, screenshots

Documentation:

v2 API Documentation: https://docs.frankieone.com
OpenAPI Specification: Request from FrankieOne
Testbed Data Guide: https://docs.frankieone.com/docs/test-data

Next Steps

After Testing v2 APIs

Understand the v2 APIs
- Review all v2 endpoints
- Test various scenarios
- Document requirements
Plan Your Integration
- Determine which v2 APIs you need
- Design workflow
- Plan error handling
- Consider migration from v1 if applicable
Review Documentation
- v2 API reference
- Integration guides
- Security guidelines
- Best practices
Start Development
- Use your test collection as reference
- Implement in your application
- Follow v2 payload structure
- Handle v2 responses correctly
Move to Production
- Complete UAT testing
- Get production credentials
- Update environment variables
- Deploy

FAQs

General

Should I use v1 or v2?

Use v2 for all new integrations. v2 is the current recommended version with:

Better structure for complex scenarios
Active development and support
Clearer entity type separation
More explicit field names

v1 is maintained for backward compatibility only.

Can I mix v1 and v2?

No. Choose one API version and use it consistently throughout your integration.

Do I need to pay for Postman or Bruno?

Bruno is completely free and open-source. Postman has a free tier that’s sufficient for testing FrankieOne v2 APIs.

Can I use real customer data for testing?

No. Always use testbed data. Never use real customer data in testing environments.

v2 Specific

What's different in v2 compared to v1?

Key differences:

Date format: Objects {year, month, day} instead of strings "YYYY-MM-DD"
Field names: locality (not suburb or city), subdivision (not state), postalCode (not postcode)
Documents: Nested by category documents.IDENTITY[]
Entity type: Implied by endpoint (/individuals vs /organizations)
Schema version: Optional field schemaVersion: 2 (primarily a response field)
Email/Phone: Arrays instead of single values

Is schemaVersion required?

No. schemaVersion is optional in v2 API requests. It’s marked as readOnly in the OpenAPI specification, meaning it’s primarily a response field returned by the API.You can include "schemaVersion": 2 in your request if you want, but it’s not required. The API will return this field in responses.

Why do dates use objects instead of strings?

v2’s object format provides:

More explicit structure
Better validation
Clearer parsing
Support for partial dates

Can I include multiple documents?

Yes. v2 supports multiple documents per category:

{
  "documents": {
    "IDENTITY": [
      {"type": "PASSPORT", ...},
      {"type": "DRIVERS_LICENSE", ...}
    ]
  }
}

Tool-Specific

Can I share my collection with my team?

Can I switch from Postman to Bruno?

Yes. Bruno can import Postman collections directly (v2.1 format).

Which tool is better for CI/CD?

Both support automation:

Postman: Newman CLI for running collections
Bruno: Bruno CLI (bru run) for running collections

How do I auto-save entityId?

Use post-response scripts:Postman:

const response = pm.response.json();
pm.environment.set("entityId", response.entityId);

Bruno:

const response = res.getBody();
bru.setEnvVar("entityId", response.entityId);

FrankieOne-Specific

What's the difference between UAT and Production?

UAT: Testing environment with testbed data, safe for experimentation
Production: Live environment with real customers, use only after thorough testing

Always test in UAT first.

What is Customer Child ID and do I need it?

Customer Child ID (X-Frankie-CustomerChildID) is for sub-account isolation within your main account.You need it if:

You have multiple brands or business units
You’re a reseller with multiple clients
FrankieOne has configured sub-accounts for you

You don’t need it if:

You have a single, unified account
FrankieOne hasn’t mentioned sub-accounts to you

How to know: Contact your FrankieOne representative to confirm if you have CustomerChildID configured.If you have it: Include the header in all requests:

X-Frankie-CustomerChildID: {{customerChildId}}

If you don’t: Omit the header or leave the variable blank.

How long do test entities stay in UAT?

Check with FrankieOne for specific retention policies. Generally, test data may be periodically cleaned.

What workflows are available?

Workflows are configured by FrankieOne based on your requirements. Contact your representative to:

See available workflows
Understand what each workflow does
Request custom workflows

Common examples: AUS-Basic1V-IDOnly, AUS-Enhanced-KYC-AML

Can I configure workflows via API?

No. Workflows are configured by FrankieOne. You can only execute workflows via API.

Summary

Key Takeaways

Principle	Details
Use v2 for new integrations	Current recommended version with better structure
Use correct v2 format	Objects for dates, correct field names
Choose your tool	Postman for cloud sync; Bruno for Git integration
Use testbed data	Pre-configured scenarios with predictable results
Check both views	API response + Portal for complete understanding
Test thoroughly	Various scenarios including edge cases

v2 Quick Reference

Minimal v2 Individual:

{
  "individual": {
    "name": {
      "givenName": "JAMES",
      "middleName": "A",
      "familyName": "TESTONE"
    },
    "dateOfBirth": {
      "year": "1950",
      "month": "01",
      "day": "01"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "country": "AUS"
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}

Getting Started Checklist

Install your tool

Install Postman or Bruno

Get the v2 collection

Download FrankieOne v2 API collection

Import

Import collection into your tool

Get credentials

Get API credentials from FrankieOne (UAT)

Configure environment

Set up environment variables

Review v2 structure

Understand v2 payload format

First v2 API call

Create your first individual (v2)

Save entityId

Auto-save or manually save entity ID

View in Portal

View results in Portal

Execute workflow

Test workflow execution

Test scenarios

Test different v2 scenarios

Document findings

Document your findings and questions

Plan integration

Plan your v2 API integration

Additional Resources

FrankieOne

Resource	URL
Website	https://frankieone.com
v2 API Documentation	https://docs.frankieone.com
Testbed Data	https://docs.frankieone.com/docs/test-data
Support	[email protected]

Postman

Resource	URL
Download	https://www.postman.com/downloads
Learning Center	https://learning.postman.com
Documentation	https://learning.postman.com/docs

Bruno

Resource	URL
Download	https://www.usebruno.com/downloads
Documentation	https://docs.usebruno.com
GitHub	https://github.com/usebruno/bruno

Document Version: 3.1 (v2 Focused - Updated)
Last Updated: February 2026
API Version: v2
Audience: Developers and technical teams evaluating or integrating FrankieOne v2 APIs

Onboarding Guides

Developers

​A Practical Guide to Testing FrankieOne v2 APIs

​Document Overview

​What You’ll Learn

​Who Should Read This

​Table of Contents

​Choosing Your API Client

​What Are API Clients?

​Postman vs Bruno

​Which Should You Choose?

Choose Postman if you:

Choose Bruno if you:

​Getting Started

​Step 1: Install Your Chosen Tool

​Step 2: Get FrankieOne’s v2 API Collection

​Step 3: Import the Collection

​Step 4: Get Your API Credentials

​Quick Authentication Reference

​Understanding Customer Child ID

​Setting Up Your Environment

​What Are Environments?

​Required Variables for v2 API

​Creating Your Environment

​Using Variables in Requests

​Understanding the v2 API Collection

​v2 API Structure

​Key v2 Endpoints

​Sample Request and Response

​Using Testbed Data

​What is Testbed Data?

​Test Scenario Types

​v2 Testbed Quick Reference

​Running Your First v2 API Call

​Overview: Create Individual Entity (v2)

​Step 1: Select the Create Individual Request (v2)

​Step 2: Review the v2 Request

​Step 3: Send the Request

​Step 4: Review the Response

​Step 5: Save the Entity ID

​Executing a Workflow (v2)

​What Are Workflows?

​Step 6: Execute a Workflow

​Viewing Results in the Portal

​Why Use the Portal?

​Accessing the Portal

​Finding Your Individual

​Understanding the Portal View

​Real-Time Updates

​Common Testing Scenarios

​Scenario 1: Create Individual with Minimal Data

​Scenario 2: Create Individual with Document

​Scenario 3: Minor (Under 18)

​Scenario 4: Individual with Custom Attributes

​Understanding API Responses

​HTTP Status Codes

​Common v2 Response Fields

​Common Validation Errors in v2

​Best Practices

​1. schemaVersion is Optional

​2. Use Correct v2 Field Names

​3. Use Date Objects, Not Strings

​4. Structure Documents Correctly

​5. Use Environment Variables

​6. Use Testbed Data Only

​7. Check Both API Response and Portal

​8. Version Control (Bruno)

​9. Test Edge Cases

​Troubleshooting

​Authentication Error (401)

​Date Format Error

​Field Name Error

​Document Structure Error

​Entity Not Found (404)

​No Results in Portal

​Bruno-Specific Issues

​Getting Help

​Next Steps

​After Testing v2 APIs

​FAQs

A Practical Guide to Testing FrankieOne v2 APIs

Document Overview

What You’ll Learn

Who Should Read This

Table of Contents

Choosing Your API Client

What Are API Clients?

Postman vs Bruno

Which Should You Choose?

Getting Started

Step 1: Install Your Chosen Tool

Step 2: Get FrankieOne’s v2 API Collection

Step 3: Import the Collection

Step 4: Get Your API Credentials

Quick Authentication Reference

Understanding Customer Child ID

Setting Up Your Environment

What Are Environments?

Required Variables for v2 API

Creating Your Environment

Using Variables in Requests

Understanding the v2 API Collection

v2 API Structure

Key v2 Endpoints

Sample Request and Response

Using Testbed Data

What is Testbed Data?

Test Scenario Types

v2 Testbed Quick Reference

Running Your First v2 API Call

Overview: Create Individual Entity (v2)

Step 1: Select the Create Individual Request (v2)

Step 2: Review the v2 Request

Step 3: Send the Request

Step 4: Review the Response

Step 5: Save the Entity ID

Executing a Workflow (v2)

What Are Workflows?

Step 6: Execute a Workflow

Viewing Results in the Portal

Why Use the Portal?

Accessing the Portal

Finding Your Individual

Understanding the Portal View

Real-Time Updates

Common Testing Scenarios

Scenario 1: Create Individual with Minimal Data

Scenario 2: Create Individual with Document

Scenario 3: Minor (Under 18)

Scenario 4: Individual with Custom Attributes

Understanding API Responses

HTTP Status Codes

Common v2 Response Fields

Common Validation Errors in v2

Best Practices

1. schemaVersion is Optional

2. Use Correct v2 Field Names

3. Use Date Objects, Not Strings

4. Structure Documents Correctly

5. Use Environment Variables

6. Use Testbed Data Only

7. Check Both API Response and Portal

8. Version Control (Bruno)

9. Test Edge Cases

Troubleshooting

Authentication Error (401)

Date Format Error

Field Name Error

Document Structure Error

Entity Not Found (404)

No Results in Portal

Bruno-Specific Issues

Getting Help

Next Steps

After Testing v2 APIs

FAQs

General

v2 Specific

Tool-Specific

FrankieOne-Specific