> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Testing Tips

> Getting Started with Postman or Bruno for FrankieOne v2 API

# A Practical Guide to Testing FrankieOne v2 APIs

<Warning>
  **Never use real customer data in testing environments.** FrankieOne handles sensitive personally identifiable information (PII) for KYC/AML verification. Always use [testbed data](https://docs.frankieone.com/docs/test-data) in UAT/Sandbox environments. Real customer data must only be processed in Production with appropriate controls.
</Warning>

## 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

***

## Table of Contents

1. [Choosing Your API Client](#choosing-your-api-client)
2. [Getting Started](#getting-started)
3. [Setting Up Your Environment](#setting-up-your-environment)
4. [Understanding the v2 API Collection](#understanding-the-v2-api-collection)
5. [Using Testbed Data](#using-testbed-data)
6. [Running Your First v2 API Call](#running-your-first-v2-api-call)
7. [Viewing Results in the Portal](#viewing-results-in-the-portal)
8. [Common Testing Scenarios](#common-testing-scenarios)
9. [Understanding API Responses](#understanding-api-responses)
10. [Best Practices](#best-practices)
11. [Troubleshooting](#troubleshooting)
12. [Next Steps](#next-steps)
13. [FAQs](#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?

<CardGroup cols={2}>
  <Card title="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
  </Card>

  <Card title="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
  </Card>
</CardGroup>

<Note>
  Both tools work equally well with FrankieOne's v2 APIs. Choose based on your team's preferences.
</Note>

***

## Getting Started

### Step 1: Install Your Chosen Tool

<Tabs>
  <Tab title="Postman">
    **Download:**

    * Visit: [https://www.postman.com/downloads/](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](https://web.postman.co)
  </Tab>

  <Tab title="Bruno">
    **Download:**

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

    **Alternative (Command Line):**

    ```bash theme={null}
    # macOS (Homebrew)
    brew install bruno

    # Windows (Chocolatey)
    choco install bruno

    # Linux (Snap)
    snap install bruno
    ```
  </Tab>
</Tabs>

### Step 2: Get FrankieOne's v2 API Collection

<Note>
  **Where to get the collection:**

  * **Download directly:** [FrankieOne Developer Resources](https://docs.frankieone.com/docs/introduction/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.
</Note>

### Step 3: Import the Collection

<Tabs>
  <Tab title="Postman">
    1. Click **"Import"** (top left)
    2. Choose file or drag and drop
    3. Select the FrankieOne v2 collection file
    4. Click **"Import"**

    **Result:** Collection appears in left sidebar, ready to use.
  </Tab>

  <Tab title="Bruno">
    1. Click **"Import Collection"**
    2. Select **"Postman Collection"**
    3. Choose the FrankieOne v2 collection file (.json)
    4. Select a folder location to store the collection
    5. Click **"Import"**

    **Result:** Bruno converts the collection to Bru format and stores it locally.

    <Tip>
      Since Bruno stores collections as files, you can immediately add them to Git for version control.
    </Tip>
  </Tab>
</Tabs>

### 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:**

1. Contact your FrankieOne representative
2. Request UAT/Sandbox access
3. Ask about Customer Child ID (if you have sub-accounts)
4. Receive credentials via secure channel
5. 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:

```text theme={null}
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
```

<Warning>
  **Do not commit API keys to source control.** Store credentials in environment variables and add environment files to `.gitignore`.
</Warning>

### 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:**

```mermaid theme={null}
graph TD
    A[Main Customer Account] --> B[CustomerID: main-account-123]
    B --> C[Child 1: Brand A]
    B --> D[Child 2: Brand B]
    B --> E[Child 3: Region APAC]
    C --> F[CustomerChildID: brand-a]
    D --> G[CustomerChildID: brand-b]
    E --> H[CustomerChildID: apac]
    
    style A fill:#e1f5ff,stroke:#333,stroke-width:2px
    style B fill:#d4edda,stroke:#333,stroke-width:2px
    style C fill:#fff3cd,stroke:#333,stroke-width:1px
    style D fill:#fff3cd,stroke:#333,stroke-width:1px
    style E fill:#fff3cd,stroke:#333,stroke-width:1px
```

**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

<Warning>
  **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.
</Warning>

**To Get Your CustomerChildID:**

1. Contact your FrankieOne representative
2. Ask if you have sub-accounts configured
3. Receive CustomerChildID values if applicable
4. 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

<Tabs>
  <Tab title="Postman">
    **Step 1: Create New Environment**

    1. Click **"Environments"** (left sidebar)
    2. Click **"+"** to create new
    3. 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**

    1. Click **"Save"**
    2. Select environment from dropdown (top right)
  </Tab>

  <Tab title="Bruno">
    **Step 1: Open Environment Settings**

    1. Click the **gear icon** (Environments)
    2. Click **"Create Environment"**
    3. Name it: `FrankieOne v2 UAT`

    **Step 2: Add Variables**

    ```text theme={null}
    baseUrl: https://api.uat.frankie.one
    basePath: compliance/v1.2
    customerId: your-customer-id
    customerChildId: your-customer-child-id
    apiKey: your-api-key
    entityId:
    ```

    <Note>
      **customerChildId** is optional and used for sub-account isolation. Leave blank if not applicable.
    </Note>

    **Step 3: Activate Environment**

    1. Click **"Save"**
    2. Select `FrankieOne v2 UAT` from the environment dropdown

    <Tip>
      Environment files are stored as `.bru` files in your collection's `environments/` folder. You can edit them directly in any text editor.
    </Tip>
  </Tab>
</Tabs>

### Using Variables in Requests

Both Postman and Bruno use the same syntax for variables:

```text theme={null}
{{variableName}}
```

**Example v2 Request URL:**

```text theme={null}
{{baseUrl}}/{{basePath}}/v2/individuals
```

**Example Headers:**

```text theme={null}
api_key: {{apiKey}}
X-Frankie-CustomerID: {{customerId}}
X-Frankie-CustomerChildID: {{customerChildId}}
Content-Type: application/json
```

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

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:

```text theme={null}
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:**

```text theme={null}
POST {{baseUrl}}/{{basePath}}/v2/individuals

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

```json theme={null}
{
  "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"
      }
    ]
  }
}
```

<Note>
  **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](https://docs.frankieone.com/docs/kyc-v-2-api/individuals/create-individual) and [Execute Workflow](https://docs.frankieone.com/docs/kyc-v-2-api/individual-workflows/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](https://docs.frankieone.com/docs/kyc-v-2-api/individual-workflows/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.)
</Note>

***

## 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

<Warning>
  **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.
</Warning>

**Full testbed data reference:** [FrankieOne Testbed Data Guide](https://docs.frankieone.com/docs/test-data)

### 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          |

<Info>
  **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.
</Info>

### 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](https://docs.frankieone.com/docs/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                                               |

<AccordionGroup>
  <Accordion title="PASS Example (JAMES TESTONE) - v2 Format">
    ```json theme={null}
    {
      "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)
  </Accordion>

  <Accordion title="PEP Match Example (JAMES G TESTELEVEN) - v2 Format">
    ```json theme={null}
    {
      "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
  </Accordion>

  <Accordion title="SANCTION Match Example (BRUCE TESTNINETEEN) - v2 Format">
    ```json theme={null}
    {
      "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
  </Accordion>
</AccordionGroup>

<Note>
  **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.
</Note>

<Note>
  Use the actual testbed names (TESTONE, TESTTWO, etc.) — do not use fictional names like "John Smith". See the [full v2 testbed examples](https://docs.frankieone.com/docs/test-data) for all scenarios including international documents.
</Note>

<Note>
  **Important: Document Type Values in v2**

  Use **`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:

  ```json theme={null}
  {
    "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:

  ```json theme={null}
  {
    "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):

  ```json theme={null}
  {
    "type": "NATIONAL_ID",
    "class": "IDENTITY",
    "primaryIdentifier": "123456789",
    "country": "USA"
  }
  ```

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

  ```json theme={null}
  {
    "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`:

  ```json theme={null}
  {
    "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`
</Note>

<Note>
  **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)
</Note>

***

## Running Your First v2 API Call

### Overview: Create Individual Entity (v2)

This walkthrough demonstrates:

1. Creating an individual entity using v2 API
2. Understanding the v2 response
3. Saving the entity ID for subsequent requests

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

<Tabs>
  <Tab title="Postman">
    1. Expand **"Individuals (v2)"** folder in left sidebar
    2. Click **"Create Individual"**
    3. Request details appear on right
  </Tab>

  <Tab title="Bruno">
    1. Expand **"Individuals (v2)"** folder in left sidebar
    2. Click **"Create Individual"**
    3. Request details appear in main panel
  </Tab>
</Tabs>

### Step 2: Review the v2 Request

**URL:**

```text theme={null}
POST {{baseUrl}}/{{basePath}}/v2/individuals
```

**Headers:**

```text theme={null}
api_key: {{apiKey}}
X-Frankie-CustomerID: {{customerId}}
X-Frankie-CustomerChildID: {{customerChildId}}
Content-Type: application/json
```

<Note>
  **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
</Note>

**Body (JSON) - v2 Format:**

```json theme={null}
{
  "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": "judy.testtwo@example.com",
        "isPreferred": true
      }
    ],
    "phoneNumbers": [
      {
        "type": "MOBILE",
        "number": "+61412345678",
        "isPreferred": true
      }
    ],
    "consents": [
      {
        "type": "GENERAL"
      },
      {
        "type": "DOCS"
      },
      {
        "type": "CREDITHEADER"
      },
      {
        "type": "UNDER18"
      }
    ]
  }
}
```

<Note>
  **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.
</Note>

<Note>
  **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
</Note>

### Step 3: Send the Request

<Tabs>
  <Tab title="Postman">
    * Click the blue **"Send"** button (top right)
    * Wait for response (usually 1-3 seconds)
    * Response appears in bottom panel
  </Tab>

  <Tab title="Bruno">
    * Click **"Send"** or press `Cmd/Ctrl + Enter`
    * Wait for response (usually 1-3 seconds)
    * Response appears in right panel
  </Tab>
</Tabs>

### Step 4: Review the Response

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

  * [Create Individual](https://docs.frankieone.com/docs/kyc-v-2-api/individuals/create-individual) — returns the individual object
  * [Create and Execute Workflow](https://docs.frankieone.com/docs/kyc-v-2-api/individual-workflows/create-and-execute-workflow) — returns `individual`, `serviceProfile`, and `workflowResult` in one response
</Note>

**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](https://docs.frankieone.com/docs/interpreting-workflows-v2).

### Step 5: Save the Entity ID

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

<Tabs>
  <Tab title="Postman">
    **Manual Method:**

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

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

    ```javascript theme={null}
    const response = pm.response.json();
    pm.environment.set("entityId", response.entityId);
    console.log("Entity ID saved:", response.entityId);
    ```
  </Tab>

  <Tab title="Bruno">
    **Manual Method:**

    1. Copy `entityId` from response
    2. Click gear icon and select your environment
    3. Add/update: `entityId: abc123-def456-ghi789-jkl012`
    4. Save

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

    ```javascript theme={null}
    const response = res.getBody();
    bru.setEnvVar("entityId", response.entityId);
    ```
  </Tab>
</Tabs>

<Check>
  **Success!** You've created a v2 individual entity.
</Check>

***

## 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:**

1. Expand **"Individual Workflows (v2)"** folder
2. Click **"Execute Workflow"**

**URL:**

```text theme={null}
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`  | `DEFAULT`                | 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:**

```json theme={null}
{
  "comment": {
    "text": "Initial verification workflow"
  }
}
```

Or if updating individual data and executing workflow:

```json theme={null}
{
  "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:

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

<Note>
  Workflow execution is asynchronous. Check the Portal or poll the individual's details to see when results are available.
</Note>

***

## 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](https://portal.uat.frankie.one/login) |
| Production  | [https://portal.frankie.one/login](https://portal.frankie.one/login)         |

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

### Finding Your Individual

**Method 1: Search by Name**

1. Click **"Entities"** in navigation
2. Enter customer name in search
3. Click on individual to view

**Method 2: Search by Entity ID**

1. Copy `entityId` from your API response
2. Paste into search bar
3. Click on individual

**Method 3: View Recent**

1. Click **"Entities"**
2. Sort by **"Most Recent"**
3. 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:

1. Send API request via Postman/Bruno
2. Refresh Portal (or wait for auto-refresh)
3. 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

***

<Note>
  For additional country-specific testing scenarios (Medicare, SSN, Aadhaar, China National ID, international passports), see the [UAT Test Data](https://docs.frankieone.com/docs/test-data) page which includes complete v2 payloads for all supported document types.
</Note>

***

## 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

<Note>
  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:

  * [Create Individual](https://docs.frankieone.com/docs/kyc-v-2-api/individuals/create-individual)
  * [Create and Execute Workflow](https://docs.frankieone.com/docs/kyc-v-2-api/individual-workflows/create-and-execute-workflow)
</Note>

**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](https://docs.frankieone.com/docs/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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "individual": {
    "name": {...},
    "dateOfBirth": {...}
    // schemaVersion: 2 can be included but is not required
  }
}
```

<Note>
  `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.
</Note>

### 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:**

```json theme={null}
{
  "dateOfBirth": {
    "year": "1990",
    "month": "01",
    "day": "15"
  }
}
```

**Incorrect (v1 format):**

```json theme={null}
{
  "dateOfBirth": "1990-01-15"
}
```

### 4. Structure Documents Correctly

**Correct v2 Format:**

```json theme={null}
{
  "documents": {
    "IDENTITY": [
      {
        "type": "PASSPORT",
        ...
      }
    ]
  }
}
```

**Incorrect:**

```json theme={null}
{
  "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

<Warning>
  **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](https://docs.frankieone.com/docs/test-data) which provides predictable, repeatable results.
</Warning>

### 7. Check Both API Response and Portal

Complete testing workflow:

1. Send request in Postman/Bruno
2. Check API response
3. View in Portal
4. Verify both match
5. Understand complete picture

### 8. Version Control (Bruno)

Since Bruno stores collections as files:

```bash theme={null}
cd "FrankieOne v2 API"
git init
git add .
git commit -m "Initial FrankieOne v2 API collection"
```

<Warning>
  Add your environment files to `.gitignore` to avoid committing credentials:

  ```
  # .gitignore
  environments/*.bru
  ```
</Warning>

### 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`)                                  |

<Note>
  **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`)
</Note>

***

### 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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: [support@frankieone.com](mailto:support@frankieone.com)
* Include: Entity ID, full request/response, error messages, screenshots

**Documentation:**

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

***

## Next Steps

### After Testing v2 APIs

1. **Understand the v2 APIs**
   * Review all v2 endpoints
   * Test various scenarios
   * Document requirements

2. **Plan Your Integration**
   * Determine which v2 APIs you need
   * Design workflow
   * Plan error handling
   * Consider migration from v1 if applicable

3. **Review Documentation**
   * v2 API reference
   * Integration guides
   * Security guidelines
   * Best practices

4. **Start Development**
   * Use your test collection as reference
   * Implement in your application
   * Follow v2 payload structure
   * Handle v2 responses correctly

5. **Move to Production**
   * Complete UAT testing
   * Get production credentials
   * Update environment variables
   * Deploy

***

## FAQs

### General

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I mix v1 and v2?">
    No. Choose one API version and use it consistently throughout your integration.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can I use real customer data for testing?">
    **No.** Always use testbed data. Never use real customer data in testing environments.
  </Accordion>
</AccordionGroup>

### v2 Specific

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Why do dates use objects instead of strings?">
    v2's object format provides:

    * More explicit structure
    * Better validation
    * Clearer parsing
    * Support for partial dates
  </Accordion>

  <Accordion title="Can I include multiple documents?">
    Yes. v2 supports multiple documents per category:

    ```json theme={null}
    {
      "documents": {
        "IDENTITY": [
          {"type": "PASSPORT", ...},
          {"type": "DRIVERS_LICENSE", ...}
        ]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Tool-Specific

<AccordionGroup>
  <Accordion title="Can I share my collection with my team?">
    * **Postman:** Export and share, or use Postman team workspaces
    * **Bruno:** Share via Git repository (add environment files to `.gitignore`)
  </Accordion>

  <Accordion title="Can I switch from Postman to Bruno?">
    Yes. Bruno can import Postman collections directly (v2.1 format).
  </Accordion>

  <Accordion title="Which tool is better for CI/CD?">
    Both support automation:

    * **Postman:** Newman CLI for running collections
    * **Bruno:** Bruno CLI (`bru run`) for running collections
  </Accordion>

  <Accordion title="How do I auto-save entityId?">
    Use post-response scripts:

    **Postman:**

    ```javascript theme={null}
    const response = pm.response.json();
    pm.environment.set("entityId", response.entityId);
    ```

    **Bruno:**

    ```javascript theme={null}
    const response = res.getBody();
    bru.setEnvVar("entityId", response.entityId);
    ```
  </Accordion>
</AccordionGroup>

### FrankieOne-Specific

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How long do test entities stay in UAT?">
    Check with FrankieOne for specific retention policies. Generally, test data may be periodically cleaned.
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="Can I configure workflows via API?">
    **No.** Workflows are configured by FrankieOne. You can only **execute** workflows via API.
  </Accordion>
</AccordionGroup>

***

## 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:**

```json theme={null}
{
  "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

<Steps>
  <Step title="Install your tool">
    Install Postman or Bruno
  </Step>

  <Step title="Get the v2 collection">
    Download FrankieOne v2 API collection
  </Step>

  <Step title="Import">
    Import collection into your tool
  </Step>

  <Step title="Get credentials">
    Get API credentials from FrankieOne (UAT)
  </Step>

  <Step title="Configure environment">
    Set up environment variables
  </Step>

  <Step title="Review v2 structure">
    Understand v2 payload format
  </Step>

  <Step title="First v2 API call">
    Create your first individual (v2)
  </Step>

  <Step title="Save entityId">
    Auto-save or manually save entity ID
  </Step>

  <Step title="View in Portal">
    View results in Portal
  </Step>

  <Step title="Execute workflow">
    Test workflow execution
  </Step>

  <Step title="Test scenarios">
    Test different v2 scenarios
  </Step>

  <Step title="Document findings">
    Document your findings and questions
  </Step>

  <Step title="Plan integration">
    Plan your v2 API integration
  </Step>
</Steps>

***

## Additional Resources

### FrankieOne

| Resource             | URL                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------- |
| Website              | [https://frankieone.com](https://frankieone.com)                                         |
| v2 API Documentation | [https://docs.frankieone.com](https://docs.frankieone.com)                               |
| Testbed Data         | [https://docs.frankieone.com/docs/test-data](https://docs.frankieone.com/docs/test-data) |
| Support              | [support@frankieone.com](mailto:support@frankieone.com)                                  |

### Postman

| Resource        | URL                                                                    |
| --------------- | ---------------------------------------------------------------------- |
| Download        | [https://www.postman.com/downloads](https://www.postman.com/downloads) |
| Learning Center | [https://learning.postman.com](https://learning.postman.com)           |
| Documentation   | [https://learning.postman.com/docs](https://learning.postman.com/docs) |

### Bruno

| Resource      | URL                                                                      |
| ------------- | ------------------------------------------------------------------------ |
| Download      | [https://www.usebruno.com/downloads](https://www.usebruno.com/downloads) |
| Documentation | [https://docs.usebruno.com](https://docs.usebruno.com)                   |
| GitHub        | [https://github.com/usebruno/bruno](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