Migrating from 2.0

This guide covers everything you need to upgrade an integration from Foxentry API 2.0 to 2.1. It lists every breaking change, the additive (non-breaking) features, before/after examples, and a field-by-field reference.

Action required. Version 2.1 is now the default. Integrations that do not pin a version will receive 2.1 automatically. If you are not ready to migrate, pin 2.0 explicitly (see Selecting a version). The breaking changes are limited to two endpoints — POST /phone/validate and POST /name/validate — but two of them are silent (no error is returned), so review them carefully.

At a glance

If your integration does not call /phone/validate or /name/validate, upgrading to 2.1 requires no code changes — only confirming the version header.

Selecting a version

The API version is selected with the api-version request header.

curl https://api.foxentry.com/phone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "api-version: 2.1" \
  -H "Content-Type: application/json" \
  -d '{ "request": { "query": { "numberFull": "+420607123456" } } }'

The header is optional, and its default changed in this release:

Recommendations

• Pin the version explicitly on every request. Relying on the default means a server-side default change can alter your integration's behaviour without a deploy on your side.
• Not ready to migrate? Send api-version: 2.0. Version 2.0 remains available to pinned clients.
• Verify what you received. Every response echoes the resolved version in the Foxentry-Api-Version response header. Assert on it in your tests.

Breaking changes

POST /phone/validate

Request — query

The combined number field was renamed.

The alternative form (separate prefix + number) is unchanged.

Request — options

numberFormat replaces the boolean toggle with an explicit output format. The four values map to standard telephony notations:

Default: e164.

Before (2.0)

{
  "request": {
    "query": { "numberWithPrefix": "+420607123456" },
    "options": {
      "validationType": "basic",
      "defaultPrefix": "+420",
      "formatNumber": false
    }
  }
}

After (2.1)

{
  "request": {
    "query": { "numberFull": "+420607123456" },
    "options": {
      "validationType": "basic",
      "preferredPrefixes": ["+420"],
      "numberFormat": "e164"
    }
  }
}

Response — result.data

The number field was renamed to match the request:

The result.data.format object was fully renamed:

⚠️ Silent breaking change — format.national was reused. The key national exists in both versions but its meaning changed: in 2.0 it was the unformatted number (775111222); in 2.1 it is the grouped number (775 111 222). Code reading format.national will keep working without an error and silently return different data. Audit every reference to the format object.

Before (2.0)

"format": {
  "national": "775111222",
  "nationalFormatted": "775 111 222",
  "international": "+420775111222",
  "internationalFormatted": "+420 775 111 222"
}

After (2.1)

"format": {
  "raw": "775111222",
  "national": "775 111 222",
  "e164": "+420775111222",
  "e123": "+420 775 111 222"
}

Response — nullability

result.data.country.code and result.data.country.prefix are now nullable (string | null). Handle null when the country cannot be resolved.

POST /name/validate

Request — options

The 2.0 depth/smart-mode controls were removed and replaced by the unified correctionMode field (consistent with the other validation endpoints), plus a new dataLanguage field.

correctionMode values:

dataLanguage (en / cs / sk / pl, default cs) controls the language of salutations and inflected name forms (e.g. the Czech vocative pane inženýre).

Mapping the old behaviour

Before (2.0)

"options": {
  "dataScope": "full",
  "acceptDegrees": false,
  "acceptContext": false,
  "validationDepth": "strict",
  "smartMode": true
}

After (2.1)

"options": {
  "dataScope": "full",
  "acceptDegrees": false,
  "acceptContext": false,
  "correctionMode": "full",
  "dataLanguage": "cs"
}

Response — details was relocated

The details object moved one level deeper, from the result root into the data object:

⚠️ Silent breaking change. No error is returned if you read the old path; the field is simply absent. Update all reads from result.details to result.data.details. The internal structure of details is unchanged, except that details[].nameDays is no longer required and may be omitted.

New features (additive)

These are safe to ignore until you choose to adopt them.

POST /name/validate — vocative (5th case) forms in result.data:

All three are string | null.

POST /name/validate — result.dataTypes reports which queried components were judged valid vs. invalid:

"dataTypes": {
  "valid":   ["name", "surname"],
  "invalid": []
}

Possible members: name, surname, nameSurname, context, degreesBefore, degreesAfter.

Field reference (breaking changes only)

Migration checklist

All integrations

• Send the api-version header explicitly on every request.
• Assert on the Foxentry-Api-Version response header in your tests.
• Decide your cutover strategy: pin 2.0 until ready, or migrate to 2.1.

/phone/validate

• Request: rename numberWithPrefix → numberFull.
• Request: remove defaultPrefix; move to preferredPrefixes.
• Request: replace formatNumber (boolean) with numberFormat (raw / national / e123 / e164).
• Response: rename data.numberWithPrefix → data.numberFull.
• Response: remap the data.format object — re-check every use of format.national (meaning changed).
• Response: handle null for data.country.code and data.country.prefix.

/name/validate

• Request: remove validationDepth and smartMode.
• Request: add correctionMode (and optionally dataLanguage).
• Response: move reads from result.details → result.data.details.
• Response: handle a possibly-absent details[].nameDays.
• Optional: adopt dataTypes and the vocative* fields.