> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.withpersona.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server. # Changelog > Review backwards-compatible and breaking changes to the Persona API. ## About Below is a log of changes to the Persona API. Updates that affect only products or features in beta or limited release may not be reflected. Each change can be described as either a breaking change or an ongoing change. * **Breaking changes = new API version**: When we make any backwards-incompatible changes, we release a new version of the API. In addition to being assigned a new API version, these changes are marked in the changelog with the πŸ’₯ symbol. You're in charge of when you get breaking changesβ€”you get them when you upgrade your API version. [Learn how to try out and upgrade to newer API versions](/versioning). * **Ongoing changes**: Ongoing changes are backwards-compatible, and are added on an ongoing basis. You don't need to update your API version to get these updates. > **SDK changelogs** > > Each Persona SDK has a separate changelog: [Android SDK](/android-sdk-v2-changelog), [iOS SDK](/ios-sdk-v2-changelog), [React Native SDK](/react-native-sdk-v2-changelog), [Javascript SDK](/embedded-flow-changelog), [Inlined React SDK](/inlined-react-changelog), [Inlined Vue SDK](/inlined-vue-changelog) ## Key 🌱 New feature πŸƒ Improvement πŸ”§ Fix πŸ’₯ Breaking change πŸ”’ Security-related ## September 29, 2026 ### Inquiries * πŸƒ **Add GPS-derived country code to Inquiry Sessions**: Inquiry Session resources now include a `gps-country-code` attribute alongside the existing `gps-latitude`, `gps-longitude`, and `gps-precision` attributes. The value is the uppercase two-letter ISO 3166-1 alpha-2 country code Persona derives by reverse-geocoding the session's GPS coordinates, such as `"US"`. It's available wherever Inquiry Sessions appear, including the [retrieve an Inquiry Session](https://docs.withpersona.com/api-reference/inquiry-sessions/retrieve-an-inquiry-session) and [list all Inquiry Sessions](https://docs.withpersona.com/api-reference/inquiry-sessions/list-all-inquiry-sessions) endpoints, sessions included in [Inquiry](https://docs.withpersona.com/api-reference/inquiries/retrieve-an-inquiry) responses, and the `inquiry-session.*` and `inquiry.*` webhook payloads that carry session data. The attribute is `null` when the session has no GPS coordinates, when reverse geocoding returns no country or fails, and on older sessions recorded before Persona stored this value. * πŸ”’ **GPS data is now cleared when an Inquiry Session is redacted**: Redacting an Inquiry Session now clears its GPS coordinates, precision, geocoded country and region values, and the stored raw geocoder response, including from the stored copies of previously delivered webhook bodies and events. Inquiry Sessions redacted before this change retain their GPS data. ### Verifications * πŸƒ **Expose per-side capture method for Government ID Verifications**: Government ID Verifications now include a `capture-methods` object reporting how each side of the ID was captured independently, e.g. `{"front": "api", "back": null}`. The existing `capture-method` attribute is unchanged. See the [Retrieve a Verification](https://docs.withpersona.com/api-reference/verifications/retrieve-a-verification) endpoint for details. ## August 24, 2026 ### Inquiry Templates * 🌱 **Add endpoint to list all Inquiry Template Versions**: You can now retrieve every version of an Inquiry Template via the [list all Inquiry Template Versions endpoint](https://docs.withpersona.com/api-reference/inquiry-templates/list-all-inquiry-template-versions). Pass the required `filter[inquiry-template-id]` to get all published versions plus the current draft, each with its status, the change description entered at publish time, `last-updater`, whether it is the template's `live` version, enabled locales, theme settings, and `published-at`, `created-at`, and `updated-at` timestamps. Results are cursor-paginated, and the parent Inquiry Template is returned as an included relationship. This endpoint requires the Inquiry Template read permission and a production API key β€” for security reasons, Inquiry Template Versions are not available in Sandbox. ### Workflows * 🌱 **Add endpoint to list all Workflow Versions**: You can now retrieve every version of a Workflow via the [list all Workflow Versions endpoint](https://docs.withpersona.com/api-reference/workflows/list-all-workflow-versions). Pass the required `filter[workflow-id]` to get all published versions plus the current draft, newest first, each with its status, change description, `trigger-type`, `last-updater`, and the `inputs` and `outputs` a run of that version accepts and returns. Archived versions are not returned, and `description` is `null` on draft versions until one is set. The `live`, `rollout-label`, and `rollout-percentage` attributes are relative to the environment of the API key you use: a version live in Production is not live in Sandbox, and two versions report `live: true` while a rollout is in progress. Results are cursor-paginated, and the parent Workflow is returned as an included relationship. This endpoint requires the Workflows API product feature and the Workflow read permission. ## August 18, 2026 ### Reports * πŸƒ **Add document enrichment status to Business Registrations Lookup reports**: Registry records in Business Registrations Lookup report responses now include `documents-status`. This field is `pending`, `completed`, or `errored`, and is `null` when document enrichment was not requested. Use it to distinguish enrichment still in progress from a completed result with no usable documents. See the [Retrieve a Report](https://docs.withpersona.com/api-reference/reports/retrieve-a-report) endpoint for details. ### Verifications * 🌱 **Add investigation lock endpoints for Verifications**: You can now protect a Verification from redaction while it is under investigation. [Investigation-lock a Verification](https://docs.withpersona.com/api-reference/verifications/investigation-lock-a-verification) to block redaction, and investigation-unlock it to remove the lock. While locked, redaction requests are rejected with a `409 Conflict`. Both endpoints require the Verification write permission and return the full Verification object. ### Webhooks * πŸƒ **Webhook deliveries now send a Persona `User-Agent`**: Outbound webhook requests identify themselves as `Persona/1.0 (+https://docs.withpersona.com/webhooks)`. ## July 15, 2026 ### Verifications * 🌱 **Add check metadata and extracted identity to Business Website Verifications**: Business Website Verifications now expose two additional sets of data: 1. **Check metadata** β€” The `business_website_backlink_detection` check now includes `backlink-count` (number of root domains linking to the site) and `backlink-threshold` (configured minimum to pass) in its `metadata` object. These values are captured at check-run time and remain stable even after raw verification data expires. 2. **Extracted identity** β€” A new top-level `extracted-identity` attribute exposes the business names, addresses, phone numbers, and email addresses found on the website as clean, flat arrays. Each entry includes the extracted `value` and the `source` URL it was found on. This data was previously only accessible nested inside the `identity_comparison` check. See the [Retrieve a Verification](https://docs.withpersona.com/api-reference/verifications/retrieve-a-verification) endpoint for details. * πŸ“ **Clarification β€” malicious website detection signals are in `reasons`**: The `business_website_malicious_website_detection` check surfaces its IPQS and Google Web Risk detection signals (e.g. `malware`, `phishing`, `spam-source`) in the `reasons` array rather than `metadata`. If you are looking for which threat types were detected, inspect `checks[].reasons` on this check. ## June 22, 2026 ### Reports * 🌱 **Add ownership information to Business Associated Persons Reports**: Business Associated Persons Reports now include an `ownership_information` object containing an `owners` array. Each owner includes its type (person or business), name, birthdate, address, and roles. See the [Retrieve a Report](https://docs.withpersona.com/api-reference/reports/retrieve-a-report) endpoint for details. ## June 15, 2026 ### API Logs * πŸƒ **Add `redacted_at` attribute to API Logs**: API Logs now include a `redacted_at` attribute which indicates when an API Log has been redacted. ### Reports * 🌱 **Add `phone_city`, `phone_subdivision`, and `phone_country_code` to Phone Risk Reports**: Phone Risk Reports now expose phone location data. ## June 9, 2026 ### Accounts * 🌱 **Add endpoints to add and remove Account relations**: You can now specify an object ID and relation key to control Account relations via the [add relation endpoint](https://docs.withpersona.com/api-reference/accounts/add-relation) and the [remove relation endpoint](https://docs.withpersona.com/api-reference/accounts/remove-relation). ### Inquiries * 🌱 **Add endpoint to search Inquiries**: You can now use complex queries to search for Inquiries via the [search endpoint](https://docs.withpersona.com/api-reference/inquiries/search-inquiries). Using search is a faster alternative to using the [list all Inquiries](https://docs.withpersona.com/api-reference/inquiries/list-all-inquiries) endpoint. It is not appropriate for read-after-write flows because the data is not immediately available to search. ### Relays * 🌱 **Add new Relay API for privacy-preserving identity claims**: You can now create a Relay and read its claim through the API. Relay returns an anonymized identity claim (such as age-over-18 or live-human-presence) without exposing the underlying PII. * [Create a Relay](https://docs.withpersona.com/api-reference/relay/create-a-relay) returns the `relay-token`, `relay-secret`, and session access token needed to redeem the claim. * [Generate a Relay claim](https://docs.withpersona.com/api-reference/relay/generate-a-relay-claim) returns the claim payload. It is authenticated with a Privacy Pass token (RFC 9577) and requires the `Persona-Relay-Secret` header. * [Create a Privacy Pass](https://docs.withpersona.com/api-reference/relay/create-a-privacy-pass) blind-signs a client-provided token (Blind RSA, RFC 9578) so it can be redeemed anonymously when generating a claim. ### Transactions * 🌱 **Add endpoints to add and remove Transaction relations**: You can now specify an object ID and relation key to control Transaction relations via the [add relation endpoint](https://docs.withpersona.com/api-reference/transactions/add-relation) and the [remove relation endpoint](https://docs.withpersona.com/api-reference/transactions/remove-relation). ## June 1, 2026 ### Cases * 🌱 **Add endpoint to remove attached objects from Cases**: You can now remove attached objects such as `inquiries`, `accounts`, and `reports` from `cases` via [the remove-objects endpoint](https://docs.withpersona.com/api-reference/cases/remove-persona-objects). ## May 4, 2026 ### Account Types and Case Templates * 🌱 **New endpoints to retrieve Account Types and Case Templates by ID**: You can now retrieve a specific [Account Type](/api-reference/account-types/retrieve-an-account-type) or [Case Template](/api-reference/case-templates/retrieve-a-case-template) by its public ID. Both responses include a `field-schemas` array under `data.attributes`, where each entry describes one configured field (`type`, `key`, `label`, `config`) so you can programmatically validate that your application's fields match what's configured in Persona. The new endpoints require the `account_type.read` and `case_template.read` permissions, respectively. API keys created after the rollout date automatically include both permissions; API keys with explicit permission lists must add `account_type.read` and/or `case_template.read` before they can call the new endpoints. ### Filings * πŸ”’ **Filing endpoints now require the `filing.write` permission**: Creating, updating, and adding objects to Filings now require API keys to have the `filing.write` permission. Existing API keys have been backfilled with this permission, and newly created API keys include `filing.write` by default. API keys with a narrow custom permission set must include `filing.write` to call these endpoints. ## April 27, 2026 ### Government ID Documents and Verifications * πŸƒ **Surface address county name extractions**: Government IDΒ [Document](https://docs.withpersona.com/api-reference/documents/retrieve-a-government-id-document#response.body.data.attributes.native-name-first)Β andΒ [Verification](https://docs.withpersona.com/api-reference/verifications/retrieve-a-verification#response.body.data.Government-ID-Verification.attributes.native-name-first)Β resources now includeΒ `address_county`. ## April 13, 2026 ### Documents * πŸƒ **Stop backfilling `extraction-responses` into `extraction-results`**: For API versions before `2021-08-18`, the `extraction-results` attribute on Document responses was being synthetically computed from `extraction-responses`. This backwards-compatibility behavior has been removed. If you are on an API version before `2021-08-18` and rely on `extraction-results`, please use the `extraction-responses` attribute instead. * πŸƒ **Remove non-GET Document endpoint documentation**: The create, update, and submit endpoints for Documents have been removed from the API reference. These endpoints are deprecated in favor of [Transactions](https://docs.withpersona.com/api-reference/transactions). The GET endpoints (retrieve and list) remain available. ## March 30, 2026 ### Events * πŸƒ **Add `related-txn-id` field to Relation Event contexts**: `added-relation` and `removed-relation` events send `related-account-id` in their event context. When the relation points to a Transaction, the context will now use `related-txn-id` to specify the related object. ## January 28, 2026 ### Webhooks * πŸ’₯ **Webhook Event payloads no longer include related objects by default**: Newly created webhooks will have an empty `included` array in their event payloads. To receive related objects, configure the allowlist on the webhook's Payload Configuration tab. Existing webhooks are not affected. ## January 18, 2026 ### Inquiries * πŸƒ **Add optional session tokens or one time links to [Inquiry creation responses](https://docs.withpersona.com/api-reference/inquiries/create-an-inquiry#response.body.meta)**: The Inquiry create response can now return a session token or a one time link if you pass in certain flags. If you pass in `auto-create-inquiry-session` as true, the response includes a `meta.session-token` attribute. If you pass in `auto-create-one-time-link` as true, the response includes `meta.one-time-link` and `meta.one-time-link-short` attributes. * πŸƒ **[Inquiry creation](https://docs.withpersona.com/api-reference/inquiries/create-an-inquiry#response.body.meta) iOS App Attestation improvement**: Inquiry create requests now accept `meta.ios_app_attest_team_id` and `meta.ios_app_attest_bundle_id` to allow iOS App Attestation on multiple apps on a single Inquiry Template. The properties override the template level configs and accepts either credential or both as overrides. ### Reports * πŸƒ **Add Instagram URL and username to Social Media Reports**: The response attributes for Social Media Reports now include an `instagram_url` and `instagram_username` attribute to represent the linked Instagram account. See the [Retrieve a Report](https://docs.withpersona.com/api-reference/reports/retrieve-a-report) endpoint for details. ## January 12, 2026 ### Reports * πŸƒ **Add position topics, start dates, and end dates to Politically Exposed Person Reports**: The `positions` attribute in Politically Exposed Person Reports now exposes position topics as well as the start and end dates indicating the duration each position was held. See the [Retrieve a Report](https://docs.withpersona.com/api-reference/reports/retrieve-a-report) endpoint for details. ### Events * πŸƒ **Add `context` attribute to Events and Webhook Events**: Events and Webhook Event resources now include a **`context`** [**attribute**](https://docs.withpersona.com/api-reference/events/retrieve-an-event#response.body.data.attributes.context) that can hold additional information for certain event types. To start, the `account.added-relation` and `account.removed-relation` events will have `relation-schema-key` and `target-account-id` attributes within `context`. ## December 16, 2025 ### Accounts * 🌱 **Add endpoint to search Accounts**: You can now use complex queries to search for Accounts via [the search endpoint](https://docs.withpersona.com/api-reference/accounts/search-accounts). Using search is a faster alternative to using the [list all Accounts endpoint](https://docs.withpersona.com/api-reference/accounts/list-all-accounts). It is not appropriate for read-after-write flows because the data is not immediately available to search. ### Cases * 🌱 **Add endpoint to search Cases**: You can now use complex queries to search for Cases via [the search endpoint](https://docs.withpersona.com/api-reference/cases/search-cases). Using search is a faster alternative to using the [list all Cases endpoint](https://docs.withpersona.com/api-reference/cases/list-all-cases). It is not appropriate for read-after-write flows because the data is not immediately available to search. ### Reports * 🌱 **Add endpoint to retrieve Report history**: You can now retrieve the full audit history of the report, including the scheduled and ad-hoc report runs + report actions from [a dedicated endpoint](https://docs.withpersona.com/api-reference/reports/list-report-history). ## December 8, 2025 ## API version: 2025-12-08 ### Reports * πŸ’₯ **Stop returning Report run-history:** Report responses no longer include the run-history attribute. **Migration:** Clients should call the [List Report history](https://docs.withpersona.com/2025-10-27/api-reference/reports/list-report-history) endpoint to retrieve the run history of a Report by its ID. ## October 27, 2025 ### Government ID Documents and Verifications * πŸƒ **Surface non-Latin name extractions**: Government ID [Document](https://docs.withpersona.com/api-reference/documents/retrieve-a-government-id-document#response.body.data.attributes.native-name-first) and [Verification](https://docs.withpersona.com/api-reference/verifications/retrieve-a-verification#response.body.data.Government-ID-Verification.attributes.native-name-first) resources now include `native_name_first`, `native_name_middle`, `native_name_last`, and `native_name_title`. ## API version: 2025-10-27 This version improves performance and consistency across endpoints for different products. ### Cross-API * πŸ’₯ **Stop returning full relationship representations by default:** All endpoints no longer return fully serialized relationship objects within the `included` array by default. To receive full representations, clients must now explicitly pass the `include` query parameter (for example, `?include=account,inquiry`). **Migration:** When upgrading to this version, update any client code that relied on implicit relationship inclusion to add the appropriate `include` query parameter for the relationships you need. See the [inclusion of related resources](https://docs.withpersona.com/response-body#specify-related-resources) guide for more details. * πŸ’₯ **Stop applying key inflection to `data.attributes.fields`:** For endpoints returning Cases, Transactions, or Inquiries, key inflection no longer applies to field names within `data.attributes.fields`. Keys now appear using the original inflection scheme configured for the field on the corresponding Case template, Inquiry template, or Transaction type. **Migration:** Update any client code that accesses custom field keys to use their configured inflection style instead of the previously transformed keys. Review [API key inflection](https://docs.withpersona.com/api-key-inflection) and the [Fields integration guide](https://docs.withpersona.com/integration-guide-understanding-a-persona-api-payload#fields) for reference. * πŸƒ **Sparse fieldset improvements:** Two improvements now apply to how [sparse fieldsets](https://docs.withpersona.com/response-body#specify-attributes) work with the `fields[TYPE]` query parameter: 1. **Parent type filtering:** When you specify a parent resource type in a sparse fieldset, the filtering now automatically applies to all related subtypes. Example: If you filter by `fields[report]=status`, the filtering now also applies to all specific report types like `report/business-lookup`, `report/watchlist`, etc. 2. **Inflection normalization:** Attribute names in the value of the `fields` parameter are now normalized, meaning you can use kebab-case, snake\_case, or camelCase interchangeably. Previously, you had to match the inflection of the attribute keys exactly to what would be returned in the response. ### Accounts * πŸ’₯ **Remove Persona-provided PII fields from Account response:** Persona-provided PII fields (e.g. `name_first`, `name_last`, `birthdate`) are now only accessible in `data.attributes.fields`. **Migration:** Clients should access the `data.attributes.fields` object from the Account resource. Field keys will not be inflected. * πŸ’₯ **Don't return full Account resource for HTTP 409 responses:** In some cases for older API versions, a full Account resource would be returned with an HTTP 409 (Conflict) response. This is now consistent: all 4xx response bodies include an error detail instead of a full Account resource. ### Cases * πŸ’₯ **Ignore custom fields from Case create and update requests:** Customer-defined fields are no longer valid top-level parameters for Case create and update requests. They can now only be specified in `data.attributes.fields`. **Migration:** Client requests should pass their values under `data.attributes.fields` instead of at the top level. This object should be a map where the keys are field keys and values are the intended field value. Field keys should not be inflected. * πŸ’₯ **Require `status` to be passed in `meta` when setting Case status:** The set status on Case endpoint request body now requires the `status` value to be passed in `meta` instead of in `data.attributes`. Passing `status` within `data.attributes` is no longer accepted. **Migration:** Update all client requests that call the [set status on Case endpoint](https://docs.withpersona.com/api-reference/cases/set-status-for-a-case) to include `status` inside the `meta` object. ### Inquiries * πŸ’₯ **Ignore Persona-provided fields and custom fields from Inquiry create and update requests:** Persona-provided PII fields and customer-defined fields are no longer valid top-level parameters for Inquiries create and update requests. They can now only be specified in `data.attributes.fields`. **Migration:** Client requests should pass their values under `data.attributes.fields` instead of at the top level. This object should be a map where the keys are field keys and values are the intended field value. Field keys should not be inflected. Commonly used attributes that may need to be moved include `name_first`, `name_last`, `country_code`, and address fields. As a special case, the top-level attribute `country_code` previously corresponded to the Persona-provided field `selected_country_code`. Users of this attribute should instead pass `data.attributes.fields.selected_country_code`. * πŸ’₯ **Remove Persona-provided PII fields from Inquiry response:** Persona-provided PII fields (e.g. `name_first`, `name_last`, `birthdate`) are now only accessible in `data.attributes.fields`. **Migration:** Clients should access the `data.attributes.fields` object from the Inquiry resource. This object is a map where the keys are field keys and values are a map with keys `type`, which specifies the data type, and `value`, which specifies the collected value. Field keys are not inflected. ### List Items * πŸ’₯ **Remove `inquiry_matches` attribute from List Item response:** List Item resources no longer include the `inquiry_matches` attribute. In previous versions, this was always an empty array. ### Reports * πŸ’₯ **Remove `legal_entity_type` field from individual registry records:** Individual registry records no longer include the `legal_entity_type` field in Business Registrations Lookup Reports (BRRs). This field has historically been `null` for individual registry records and continues to be populated at the top level of the Report based on domestic registration data. ### Transactions * πŸ’₯ **Limit size of `related-objects` relationship in Transaction responses:** The amount of `related-objects` that can be returned as part of a Transaction resource is now limited to 100. Transactions can *have* more than 100 related objects, but only the first 100 are present on Transaction responses. ### Verifications * πŸ’₯ **Deprecate `database_business_ai_identity_comparison` check**: The `database_business_ai_identity_comparison` check is now deprecated. All AI-powered identity comparison results are now available in `database_business_identity_comparison`. This consolidation simplifies data retrieval by unifying AI and rules-based comparison outputs under a single check type. ### Workflow Runs * πŸ’₯ **Require fields to be passed in `data.attribute.fields` when creating Workflow Runs:** The [create a Workflow Run endpoint](https://docs.withpersona.com/api-reference/workflows/create-a-workflow-run) request body now requires fields to be passed in `data.attributes.fields` instead of `meta.params` or `data.attributes`. **Migration:** Client requests should pass their values under `data.attributes.fields` instead of at the top level or through `meta.params`. This object should be a map where the keys are field keys and values are the intended field value. The schema is defined by the trigger payload schema on your Workflow Version. ## October 20, 2025 ### Accounts * 🌱 **Add endpoint to run an Account action**: You can now [run an account action](https://docs.withpersona.com/api-reference/accounts/run-account-action) via API. ### User Audit Logs * πŸƒ **Add `context.inquiry_id` attribute to User Audit Logs**: [User Audit Log](https://docs.withpersona.com/api-reference/user-audit-logs/retrieve-a-user-audit-log) resources now include a `context.inquiry_id` [attribute](https://docs.withpersona.com/api-reference/user-audit-logs/retrieve-a-user-audit-log#response.body.data.attributes.context) to retrieve the `inquiry-id` of an inquiry created via dashboard. ## September 29, 2025 ### Tags * πŸ’₯ **Active tags limited to 1000 per organization:** API requests that would create additional tags receive a 422 response code if the organization has at least 1000 tags currently active. ### Verifications * πŸƒ **Add `non-domiciled` to the list of possible ID designations:** `non-domiciled` is now among the list of possible ID designations. _Showing the 20 most recent of 94 entries. Append `/llms.txt` to the changelog URL for the complete index._