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:
| 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
Endpoint:Headers:Authorization: Bearer YOUR_API_KEY
{
"entity": {
"entityType": "INDIVIDUAL",
"givenName": "John",
"familyName": "Doe",
"dateOfBirth": "1990-03-27",
"streetNumber": "525",
"streetName": "Kent",
"city": "Manhattan",
"country": "USA"
}
}
Endpoint:Headers:api_key: YOUR_API_KEY
X-Frankie-CustomerID: YOUR_CUSTOMER_ID
{
"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 |
