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

> How FrankieOne versions APIs and maintains backwards compatibility

## Specifying the Version

Include the version in the API path:

```text theme={null}
https://api.frankie.one/v2/individuals
```

<Note>
  Patch versions are applied automatically—you only specify the major version in requests.
</Note>

## Current Versions

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

<Warning>
  v1 endpoints are legacy and should not be used for new integrations.
</Warning>

## Semantic Versioning

We use **Semantic Versioning** to label releases:

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

<Tabs>
  <Tab title="v1 (Legacy)">
    **Endpoint:**

    ```text theme={null}
    POST /v1/entity
    ```

    **Headers:**

    ```text theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```

    **Request:**

    ```json theme={null}
    {
      "entity": {
        "entityType": "INDIVIDUAL",
        "givenName": "John",
        "familyName": "Doe",
        "dateOfBirth": "1990-03-27",
        "streetNumber": "525",
        "streetName": "Kent",
        "city": "Manhattan",
        "country": "USA"
      }
    }
    ```
  </Tab>

  <Tab title="v2 (Current)">
    **Endpoint:**

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

    **Headers:**

    ```text theme={null}
    api_key: YOUR_API_KEY
    X-Frankie-CustomerID: YOUR_CUSTOMER_ID
    ```

    **Request:**

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

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

<Tip>
  Build your integration to ignore unknown fields in responses.
</Tip>

## Deprecation Policy

When we deprecate a version:

1. **Announcement** — Minimum 6 months notice
2. **Migration period** — Both versions run in parallel
3. **Sunset** — Old version retired

Deprecated endpoints return a `Deprecation` header:

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

## Staying Informed

<CardGroup cols={2}>
  <Card title="Release Notes" icon="list" href="/docs/releasenotes">
    View product changes
  </Card>

  <Card title="Status Page" icon="signal" href="https://status.frankieone.com">
    Subscribe to updates
  </Card>
</CardGroup>