API Versioning

Specifying the Version

Include the version in the API path:

https://api.frankie.one/v2/individuals

Patch versions are applied automatically—you only specify the major version in requests.

Current Versions

API	Version	Status
KYC API (Individuals)	v2	Active
KYB API (Organizations)	v2.1	Active
Legacy API	v1	Deprecated

v1 endpoints are legacy and should not be used for new integrations.

Semantic Versioning

We use Semantic Versioning to label releases:

MAJOR.MINOR.PATCH

Type	When It Changes	Impact
MAJOR	Breaking changes	May require code updates
MINOR	New features (backwards-compatible)	No changes required
PATCH	Bug fixes	No changes required

Example: v1 vs v2

v1 (Legacy)
v2 (Current)

Endpoint:

POST /v1/entity

Headers:

Authorization: Bearer YOUR_API_KEY

Request:

{
  "entity": {
    "entityType": "INDIVIDUAL",
    "givenName": "John",
    "familyName": "Doe",
    "dateOfBirth": "1990-03-27",
    "streetNumber": "525",
    "streetName": "Kent",
    "city": "Manhattan",
    "country": "USA"
  }
}

Endpoint:

POST /v2/individuals

Headers:

api_key: YOUR_API_KEY
X-Frankie-CustomerID: YOUR_CUSTOMER_ID

Request:

{
  "individual": {
    "name": {
      "givenName": "John",
      "familyName": "Doe"
    },
    "dateOfBirth": {
      "year": "1990",
      "month": "03",
      "day": "27"
    },
    "addresses": [
      {
        "type": "RESIDENTIAL",
        "status": "CURRENT",
        "streetNumber": "525",
        "streetName": "Kent",
        "locality": "Manhattan",
        "subdivision": "NY",
        "country": "USA",
        "postalCode": "10037"
      }
    ]
  }
}

Key Differences

Change	v1	v2
Endpoint	`/v1/entity`	`/v2/individuals`
Auth header	`Authorization: Bearer`	`api_key` + `X-Frankie-CustomerID`
Root object	`entity`	`individual`
Name fields	Flat (`givenName`, `familyName`)	Nested `name` object
Date of birth	String `"1990-03-27"`	Object with `year`, `month`, `day`
Address	Flat fields	Structured `addresses` array with `type` and `status`

Backwards Compatibility

Within a major version, we guarantee:

Existing endpoints continue to work
Response fields won’t be removed
Required request fields won’t be added

We may add:

New optional request fields
New response fields
New endpoints

Build your integration to ignore unknown fields in responses.

Deprecation Policy

When we deprecate a version:

Announcement — Minimum 6 months notice
Migration period — Both versions run in parallel
Sunset — Old version retired

Deprecated endpoints return a Deprecation header:

Deprecation: true
Sunset: Sat, 01 Jan 2028 00:00:00 GMT

Base URLs

Environment	URL
UAT	`https://api.uat.frankie.one`
Production	`https://api.frankie.one`

Introduction

KYC V2 API

Transaction and Activity Monitoring V2 API

KYB V2 API

Core V2 API

Specifying the Version

Current Versions

Semantic Versioning

Example: v1 vs v2

Key Differences

Backwards Compatibility

Deprecation Policy

Base URLs

Staying Informed

Release Notes

Status Page

​Specifying the Version

​Current Versions

​Semantic Versioning

​Example: v1 vs v2

​Key Differences

​Backwards Compatibility

​Deprecation Policy

​Base URLs

​Staying Informed

Release Notes

Status Page

Specifying the Version

Current Versions

Semantic Versioning

Example: v1 vs v2

Key Differences

Backwards Compatibility

Deprecation Policy

Base URLs

Staying Informed