Versioning

Compatibility commitments

The RandaVerify API is unversioned at the URL level today (https://api.randaverify.com/verify-nin — no /v1/). Until we introduce versioning, we follow these rules:

• Additive changes (new optional fields on a response, new endpoints, new accepted enums) ship without notice.
• Breaking changes (removed fields, renamed fields, removed endpoints, narrower input acceptance) are not made to the existing surface. If we need to break, we will introduce /v2/ and run both in parallel for at least 90 days.
• Bug fixes that align an endpoint’s behaviour with this documentation are not considered breaking, even if they alter your runtime behaviour. Treat the docs as the contract.

Field stability

The field names listed in Conventions → field-name casing are stable. We may add new fields to a verification response at any time; we will not remove or rename existing ones.

Reason keys

The reason key values from /nimc-reasons are owned by NIMC, not RandaVerify. NIMC occasionally adds, removes, or renames keys. Always fetch the list at runtime rather than hard-coding the strings. See Verification reasons.

Deprecation notices

Deprecations will be communicated by:

1. Email to every integrator on the affected endpoint, with at least 90 days’ notice.
2. A new entry on the Changelog.
3. A Sunset HTTP header on responses from the deprecated endpoint.

When we ship /v2/

If and when we introduce a versioned surface, this page will explain the migration path and the parallel-run timeline.