Migrating to version 2

Identity verification now uses the /v2/ namespace. This guide covers what changed from version 1 and how to move an existing integration across.

Version 1 was never publicly documented

Version 1 verification endpoints were never published in our public API documentation. Definitions were sent to individual integrators on request, which means Annature has a record of who is currently built against version 1. For that reason, version 1 endpoints will be removed without notice once we have confirmed that those existing integrators have upgraded. Do not start a new integration against version 1. We are not tracking new consumers of these deprecated, undocumented endpoints, and they will be deleted without notice.

Object model

Identity verification 2.0 rebuilt the underlying resources. Those changes made it difficult to keep the existing endpoints intact, so we started fresh with version 2 rather than stretching the original object further. Several terms were retired in that rebuild — specifically verified and unverified. Annature no longer returns its own pass/fail result for a verification. Version 2 is a passthrough of the results provided by our vendors, Stripe Identity and ComplyCube. Outcomes that require review are exposed on warning. Completion is recorded as completed.

{
  "id": "9d2e4b8c1a7f53e06c4b9d2a8e1f0c57",
  "name": "Ted Annature",
  "email": "ted@annature.com.au",
  "mobile": "+61422000000",
  "type": "enhanced",
  "status": "sent",
  "warning": "document_expired",
  "account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
  "group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
  "shared": true,
  "biometrics": true,
  "tax": false,
  "created": "2026-08-24T00:00:00Z",
  "verified": "2026-08-24T00:00:00Z",
  "unverified": null,
  "cancelled": "2026-08-24T00:00:00Z",
  "metadata": {
    "customer_id": "12345"
  }
}

{
  "id": "9d2e4b8c1a7f53e06c4b9d2a8e1f0c57",
  "name": "Ted Annature",
  "email": "ted@annature.com.au",
  "mobile": "+61422000000",
  "mobile_otp": "+61422000000",
  "message": "Lorem ipsum dolor sit amet.",
  "message_sms": "Lorem ipsum dolor sit amet: {{token}}",
  "status": "completed",
  "account_id": "c64ce66b70b21c03bfd5dfa0ab14b730",
  "group_id": "a5a885caee6286a54ad7bbd4ab5400e9",
  "shared": true,
  "warning": "document_expired",
  "muted": false,
  "screening": true,
  "biometrics": true,
  "created": "2026-08-24T00:00:00Z",
  "cancelled": "2026-08-24T00:00:00Z",
  "completed": "2026-08-24T00:00:00Z",
  "purging": "2026-08-24T00:00:00Z",
  "purged": "2026-08-24T00:00:00Z",
  "metadata": {
    "customer_id": "12345"
  }
}

Property changes

This table highlights every property that was removed, changed, or added between version 1 and version 2.

Property	Status	Description
`type`	Removed	Version 1 used `standard` and `enhanced` to decide whether AML & CTF screening ran with the verification. That product split is gone — screening is now its own `screening` boolean.
`tax`	Removed	No longer supported.
`verified`	Removed	Version 1 treated completion as a pass/fail result. Both `verified` and `unverified` have been replaced by a single `completed` timestamp. Check `warning` when a completed request needs review.
`unverified`	Removed	Retired with `verified`. Annature no longer returns its own unverified result.
`certificate`	Removed	Download URLs no longer come back on retrieve. Use the new Retrieve reports endpoint instead.
`mobile`	Changed	In version 1 this was used only for OTP. We split that out to better match the recipient object, and `mobile` now sends an SMS with a link to start the verification.
`status`	Changed	The `verified` and `unverified` statuses are gone. A finished request is now `completed`.
`warning`	Changed	Still the place to look when something needs review, but the value is now a passthrough of Stripe Identity error codes rather than Annature interpreting the result.
`mobile_otp`	Added	Dedicated property for SMS two-factor authentication — this is the role `mobile` used to play.
`message`	Added	Lets you customise the verification email. Version 1 always sent a fixed default.
`message_sms`	Added	Lets you customise the SMS body when a `mobile` number is supplied.
`muted`	Added	Silences Annature’s emails and SMS for the verification, so you can generate access links yourself.
`screening`	Added	Set to `true` to run AML & CTF screening checks. This is the replacement for `"type": "enhanced"`.
`completed`	Added	Timestamp for when the individual finished the verification. Replaces `verified`.
`purging`	Added	When third-party identity documents and PII are scheduled to be purged, based on your organisation’s retention settings.
`purged`	Added	When that third-party data was actually purged.

Standard vs enhanced

Version 1 used a type property on create:

standard — base identity verification
enhanced — the same verification, plus AML & CTF screening

Version 2 removes type. Every verification is a base identity verification. To run AML & CTF screening checks, pass "screening": "true" when creating a verification.

Other breaking changes

These will break an existing version 1 integration if you only change the path to /v2/.

Mobile numbers

On version 1, mobile was stored and used as the OTP number. Version 1 create did not send an SMS with a verification link. On version 2, mobile sends the verification link via SMS, and mobile_otp is the OTP number. If your version 1 integration passed mobile for two-factor authentication, map that value to mobile_otp on version 2.

Reports and certificates

GET /v1/verifications/:id returned a certificate download URL (and accepted endpoint_duration). GET /v2/verifications/:id no longer returns reports. Use Retrieve reports for certificate, multibureau, and screening URLs. Reports are not available immediately on completion — listen for the Verification reports webhook instead of polling.

List filters

GET /v1/verifications accepted verified_before and verified_after. GET /v2/verifications uses completed_before and completed_after.

Group assignment

POST /v1/verifications create left group_id empty unless it was supplied in the request. POST /v2/verifications inherits the sending account’s group when group_id is omitted. Supply a group_id to override, or the verification will sit in the account’s group. POST /v1/verifications always set shared to true when the sending account had share by default enabled, even if you passed shared: false. POST /v2/verifications respects an explicit shared: false when the account only has share by default. Force sharing still overrides to true. A verification cannot be shared unless it belongs to a group.

Resending

POST /v1/verifications/:id/resend sent email only. POST /v2/verifications/:id/resend also resends the SMS when a mobile number is set.

New endpoints

Endpoint	Purpose
`GET /v2/verifications/:id/reports`	Download URLs for certificate, multibureau, and screening reports
`POST /v2/verifications/:id/purge`	Purge identity documents and PII stored with third-party providers

Webhooks

The verification_completed payload now includes completed. verified is still sent for backwards compatibility and is deprecated. A new verification_reports event is sent when downloadable reports are ready.

​Version 1 was never publicly documented

​Object model

​Property changes

​Standard vs enhanced

​Other breaking changes

​Mobile numbers

​Reports and certificates

​List filters

​Group assignment

​Sharing defaults

​Resending

​New endpoints

​Webhooks