DocumentationAPI Reference
API ChangelogOpenAPI SpecStatus
API ChangelogOpenAPI SpecStatus

API Changelog

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.
  • 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.

Key

🌱 New feature
🍃 Improvement
🔧 Fix
💥 Breaking change
🔒 Security-related

July 25, 2024

Database Verifications

  • 🍃 Add new attributes to Database Verifications: To support verifying information that's attached to government sources, we've added three new document specific attributes to Database Verifications:
    • document-issuing-subdivision: the subdivision in which the document was issued.
    • document-expiry-date: the date when the document will expire.
    • document-issuing-date: the date when the document was issued.

July 1, 2024

Inquiries

  • 🍃 Add is-vpn to Inquiry Sessions: Inquiry Session resources (such as those returned by the retrieve an Inquiry Session API) now include an attribute is-vpn that indicates whether the session used a VPN.

June 17, 2024

Cases

  • 🌱 Add Case Queue to Cases create and update endpoints: You can now add or remove a Case from a Case Queue via the create a Case and update a Case APIs with the case-queue-id parameter. Case objects in all API responses will now include case-queue in data.relationships.

May 14, 2024

Document Verifications

  • 🍃 Add document-type Document Verifications: Document Verifications now include a document-type attribute. document-type refers to the classification of the submitted document, such as bank_statement or credit_card_statement.

Inquiries

  • 🍃 Asynchronous redaction of related resources: Previously, the Inquiry redaction API would redact the Inquiry as well as any related resources (Accounts, Verifications, etc.) synchronously. Now it will redact the Inquiry synchronously and redact any related resources asynchronously. The inquiry.redacted event will only be emitted after all objects are redacted. This should improve performance.

April 29, 2024

Webhooks

  • 🌱 Fully custom HTTP headers: You can now configure Webhooks to send with fully custom HTTP headers. Previously, you could only choose custom header keys from a pre-set list. This feature is only enabled for enterprise customers.
  • 🍃 Support HTTP 204 responses: Webhook events will now advance from pending to completed when your server returns an HTTP 204 status.

Accounts & Transactions

  • 🍃 Asynchronous redaction of related resources: Previously, the Account and Transaction redaction APIs would redact the primary object (Account or Transaction) as well as any related resources (Inquiries, Verifications, etc.) synchronously. Now these APIs will redact the primary object synchronously and redact any related resources asynchronously. The account.redacted and transaction.redacted events will only be emitted after all objects are redacted. This should improve performance.

April 15, 2024

Cases

  • 🍃 Expand updater types and IDs to support Case assignment policies: Case API responses can now include case-assignment-policy as an updater-type and Case assignment policy IDs can be populated in updater-id.

Transactions

  • 🌱 Redact Transaction API: We've added a new API to redact a Transaction. See the API reference guide.

April 8, 2024

Inquiry Sessions

  • 🍃 Add Device relationship to Inquiry Session: Inquiry Sessions will now include information related to the Device that created the session within data.relationships.

Inquiries

  • 🌱 Create an Inquiry with an alternate initial step: You can now pass in initial-step-name when you call the Create an Inquiry API. This allows you to create an inquiry that starts on a different initial step other than the one defined on your Inquiry Template.
  • 🍃 Database and Document Verifications support when simulating Inquiries: You can now create passed or failed Database and Document Verifications when using the Inquiries perform simulate actions API. For more info on the types of Verifications supported, see the guide.

April 1, 2024

Inquiries

  • 🌱 Set tags on Inquiry creation and update: You can now pass in a set of tags to be added to the Inquiry when you call the Create an Inquiry or Update an Inquiry APIs.

March 25, 2024

Inquiries

  • 🌱 Create passed or failed Verifications when simulating Inquiries: We've added two new actions to the Inquiries perform simulate actions API that allow you to simulate specific Verification statuses. For more info on testing integrations using sandbox inquiries, see the guide.

March 4, 2024

Devices

  • 🌱 List and retrieve APIs for Devices: We've added a new set of APIs to allow to you to retrieve device data. See the API reference guide.

Reports

  • 🌱 Account creation opt-out on Report creation: meta.auto-create-account on Create a Report lets you skip creating an Account.
  • 🌱 Choose Account Type on Report creation: meta.auto-create-account-type-id parameter on Create a Report allows setting a custom Account Type.
  • 🍃 New way to set the Account's reference ID: meta.auto-create-account-reference-id parameter on Create a Report is the new preferred way to set the reference ID for the Account (instead of data.attributes.reference-id) to allow for reference IDs for different objects going forward.

February 26, 2024

Inquiries

  • 🍃 Update Inquiries regardless of status: Previously, Inquiries could only be updated when its status was created or pending. Now you can update Inquiries of any status. Updating Inquiries that are not in progress is generally not recommended, but could be valid for some use cases. For more details, see Update an Inquiry.

Verifications

  • 🌱 Add face coordinates to Selfie Verifications: Selfie Verifications now include center-photo-face-coordinates, which is composed of coordinates top-left, top-right, bottom-left, and bottom-right. This can be used to isolate only the face from the center photo associated with a Selfie Verification.

February 5, 2024

Cases

  • 🌱 Add assigner-id and assigner-type to Cases: Cases now include attributes that specify the entity that assigned a user to the case. assigner-type can be one of case-assignment-policy, user, or workflow-run and assigner-id is the ID of that entity.

January 29, 2024

Inquiries

  • 🍃 Inquiry ID length increase: Inquiry IDs (prefixed with inq_) are now 32 characters. Previously they were 28 characters.

January 22, 2024

Inquiry Sessions

  • 🌱 Add device-handoff-method to Inquiry Sessions: Inquiry Sessions now include an attribute device-handoff-method that specifies whether a device handoff took place when creating the Inquiry Session. Example values are email, sms, or qr.
  • 🌱 Add started-at and expired-at to Inquiry Sessions: Inquiry Sessions now include DateTime attributes to indicate when they were started or expired.

January 8, 2024

Cases

  • 🌱 Set SLA when updating or creating a Case: You can now set SLAs using meta.sla-expires-in-seconds on the Create a Case and Update a Case APIs.

December 18, 2023

Cross-API

  • 🌱 Choose related resources returned in included: All APIs now support an include query parameter. This can be used to choose which, if any, related resources will be fully serialized in the response. For more details, see Serialization.

November 27, 2023

Reports

  • 🍃 Add phone-number parameter to Report creation: Report can now take in phone numbers.

November 13, 2023

Inquiries

  • 🌱 Account creation opt-out on Inquiry creation: meta.auto-create-account on Create an Inquiry lets you skip creating an Account
  • 🌱 Choose Account Type on Inquiry creation: meta.auto-create-account-type-id parameter on Create an Inquiry allows setting a custom Account Type.
  • 🍃 New way to set the Account's reference ID: meta.auto-create-account-reference-id parameter on Create an Inquiry is the new preferred way to set the reference ID for the Account to look-up/creation (instead of data.attributes.reference-id) to allow for reference IDs for different objects going forward.

Reports

  • 🌱 Set recurring flag: Reports now return is-continuous as a boolean field. This will be true when a report is able to recur and is currently recurring in its runs. This, in concert with has-match, allows end users to understand which matches are from an initial / recurring run.

Webhooks

  • 🌱 Manage Webhooks via API: The new Webhook endpoints enable automatic management.
  • 🌱 Rotate Webhook Secrets: Rotate a Webhook Secret allow for automating secret rotation.

October 23, 2023

Inquiries

API Keys & Webhooks

October 16, 2023

Inquiries

  • 💥 Disallow passing in theme-id for theme-set-id: (Note: Inquiry Theme Sets are in Beta, so this isn't relevant to most.) When calling Create an Inquiry, only use theme-id and theme-set-id for Legacy and Dynamic Flow Inquiry Templates respectively. We haven't seen any API calls that would be affected by this in the past few weeks, so this change should not affect anyone.

October 10, 2023

OAuth

  • 🔧 Use key inflection with OAuth endpoints: The Create Authorization and Create Access Token endpoints now honor the Key-Inflection header or API Key configuration. Before this fix, the endpoints were only responding with snake_case inflection.

October 2, 2023

Documents

  • 🍃 Update Fields on Generic Documents: You can update the fields of a Generic Document by setting the new fields attribute in the /update endpoint.

Verifications

  • 🌱 Added Database Standard Verifications: Added a new type of verification that allows you to validate identity attributes against non-authoritative database sources. See the API reference guide.

September 18, 2023

Documents

  • 🌱 ID Designations on Government ID Documents: ID designations will now be surfaced as a list of strings under the designations attribute. An ID designation is akin to a "tag" for an ID indicating that it belongs to a specific category of interest. For example (non-exhaustive): learners, temporary, commercial, real_id. Zero or more designations may apply for a given ID.

Reports

  • 🔧 Consolidate result.identifiers.status for Business Lookup Reports: We have collapsed the result.identifiers.status attribute's values unknown and not_applicable to just unknown. Previously the behavior for when either was returned was inconsistent.

Fields

  • 🌱 MIME type for File fields: Added mime-type as an attribute for File fields. More than one type of entity can contain this kind of field (e.g. Inquiries or Transactions).

August 28, 2023

Transactions

  • 🌱 Add, remove, and set tag APIs for Transactions: We've added a new set of APIs for Transactions. The endpoints will let you add a tag, remove a tag, and set tags on Transactions. See the API reference guide.

Verifications

  • 🌱 Redact Verification API: We've added a new API to redact a Verification. See the API reference guide.

Reports

  • 🍃 Input fields in response for Adverse Media and Watchlist Reports: APIs and webhooks that return an Adverse Media or Watchlist Report will now include all the input fields for those reports. The new fields added per Report are:
    • Adverse Media Report
      • name-middle: String. Middle name from the input if one was provided, otherwise none.
      • term: String. Combined name from input.
      • birthdate: Date. Birthdate in ISO 8601 format (YYYY-MM-DD).
      • country-code: String. The Alpha-2 country code from input.
    • Watchlist Report
      • name-first: String. First name from input.
      • name-middle: String. Middle name from input if one was provided, otherwise none.
      • name-last: String. Last name from input.
      • term: String. Combined name from input.
      • birthdate: Date. Birthdate in ISO 8601 format (YYYY-MM-DD).
      • country-code: String. The Alpha-2 country code from input.

August 21, 2023

Inquiries

  • 🌱 inquiry-template now included when retrieving an Inquiry: Retrieving an Inquiry will now return the related inquiry-template within included. It contains fields: status and name along with a relationship latest-published-version. You can compare it with the inquiry's inquiry-template-version ID to determine if the inquiry is up to date with the latest version of the template.

Reports

  • 🌱 Corporate Registration Addresses in Business Lookup Report: Business Lookup Reports now include a list of addresses associated with the business. The addresses will also include a type that will be one of the following values: site, registered_business_address, mailing, or registered_agent.

August 7, 2023

Reports

  • 💥 Deprecated Email Risk Report Attributes: Email Risk Reports created after August 10, 2023 will always return null for the following attributes:
    • email-reference-count
    • email-domain-reputation
    • email-first-seen-days
    • email-last-seen-days
    • email-data-breached
    • email-malicious-activity-detected
    • email-is-blocklisted
    • email-is-free-provider
    • email-is-spoofable
    • email-is-spf-strict
    • email-is-dmarc-enforced
  • 🌱 New Email Risk Report Attribute: Email Risk Reports created after August 10, 2023 will populate the email-estimated-age-days attribute.

July 17, 2023

Inquiries

July 10, 2023

Accounts

  • 🍃 Improved sorting for Account list API: Accounts returned when calling the list API will now be sorted by their created-at attribute in descending order.

Inquiries

  • 🌱 Configurable Inquiry one-time link expiration: The expiration interval for Inquiry one-time links can now be configured for each Inquiry Template in your dashboard. The default is 1 hour.

July 3, 2023

Cross-API

  • 🌱🔒 Configurable expiration for File URL access tokens: By default, the signed access token included in File URLs remains valid for 6 hours after the API request was made. This expiration period can now be configured per API Key. For more details, see File URLs.
  • 🍃 Field Schema for File types include set of supported MIME types: Responses that include field schemas with type FieldSchema::File will include the list of supported mime types within config under supported-mime-types.

June 26, 2023

Verifications

  • 🌱 More metadata for Government ID Verification's Disallowed Type Detection check: The Disallowed Type Detection verification check (disallowed-type-detection) now returns additional metadata fields: detected-id-class and selected-id-classes when you Retrieve a Government ID Verification.
  • 🌱 More metadata for Government ID Verification's Disallowed Country Detection check: The Disallowed Country Detection verification check (disallowed-country-detection) now returns metadata with fields: country-code, enabled-country-codes, and selected-country-code when you Retrieve a Government ID Verification.

June 12, 2023

Reports

  • 🔧 Improved error messaging for incorrectly formatted birthdates and country codes: We now return a helpful error message if birthdates are not ISO 8601 formatted (YYYY-MM-DD) or country codes are not included in the two-letter ISO 3166 standard.

June 5, 2023

Verifications

  • 🍃 Normalized address fields for Database Verification: We now return the normalized address along with a Database Verification. The address fields are prefixed with normalized-address-, e.g. normalized-address-street-1, normalized-address-street-2, and so on.

May 29, 2023

Inquiries

  • 🌱 Inquiry Session APIs: We've added a set of APIs for Inquiry Sessions. Endpoints let you list, retrieve, create, expire, and generate one-time links for Inquiry Sessions. See the API reference guides.

May 15, 2023

Reports

  • 🍃 Dismiss a Business Adverse Media Report match: You can now dismiss a Report match for the Business Adverse Media Report type. Use the existing Dismiss a Report API, and pass a Business Adverse Media Report ID.

May 8, 2023

Inquiries

  • 🌱 Short one-time links: When you Generate a one-time link, a short version of the link will now be returned, along with the full link. The short link is returned in the field meta.one-time-link-short.

Accounts

  • 🌱 Account details in fields object: Accounts have a new fields object that contains details of the Account, such as first name, last name, birthdate, etc. If you have the choice, use fields to read details about the Account, instead of attributes.

Reports

  • 🍃 Dismiss a Business Watchlist Report match: You can now dismiss a Report match for the Business Watchlist Report type. Use the existing Dismiss a Report API, and pass a Business Watchlist Report ID.

May 1, 2023

Verifications

  • 🍃 Finer-grained Documents classification: We've improved Documents classification to offer 20+ new types of Documents, with more on the way. You'll see them reflected in the document-type attribute when you Retrieve a Document.

April 24, 2023

Verifications

  • 🍃 Files and extractions returned on Documents Verification: We now return files and extractions via the files and extraction-responses attributes when you Retrieve a Document Verification.

April 17, 2023

Verifications

  • 🌱 Video URL for Selfie and Government ID Verifications: If a Selfie Verification or Government ID Verification is completed using a video selfie, the video selfie will be returned in the new video-url field in the verification's attributes.
  • 🌱 More metadata for Government ID Verification's Extraction inconsistency check: The Extraction inconsistency verification check (id-extraction-inconsistency-detection) for Government ID Verification now returns an additional metadata field: check-requirements. check-requirements is an array of objects. Each object represents a check requirement and its result.
  • 🍃 Selfie photo from Government ID Verification can be tested in Sandbox: In the Sandbox environment, the selfie-photo-url field is now set, using the front photo of the Government ID (instead of the actual selfie photo). This change allows you to test changes in Sandbox that depend on selfie-photo-url. (For example, you can use the selfie photo from a Government ID Verification as an input to a Selfie Verification.) As background, since Persona does not run real Verifications in Sandbox, we do not detect the face in the photo on a Government ID. In the past, this meant the selfie-photo-url field on a Government ID Verification was left empty.

April 10, 2023

Inquiries

  • 🍃 Resumed Inquiry persists locale from previous session: A resumed Inquiry now loads with the same locale as the previous session (if set). Previously, a resumed Inquiry would load with the locale of the current device.
  • 🍃 One-time links generated only when needed: The Generate a one-time link API now returns a previously-created but unused, unexpired link if one exists. This change prevents you from creating too many links if you accidentally call this endpoint many times.

Verifications

  • 🌱 More metadata for Government ID Verification's Allowed ID check: The Allowed ID verification check (id-disallowed-type-detection) now returns additional metadata fields when the check passes or fails: country-code, detected-id-designations, disallowed-id-designations.
  • 🍃 New defaults for Selfie Verification: Going forward, when you create a Selfie Verification, two new defaults are set. These defaults reflect what we find works best for most customers, and these settings remain configurable. The new defaults are:
    1. The Selfie Liveness verification check (selfie-liveness-detection) is enabled.
    2. The Verification requires what we call "strict selfie capture"—a set of standards that mean the selfie must be higher resolution, and the face more centered.
  • 🔧 Enable Verification types in Sandbox: The following Verification types can now be created in the Sandbox environment:
    • AAMVA
    • eCBSV Database
    • Serpro Database
    • TIN Database
    • Selfie

Transactions

  • 🌱 Update Transaction status via API: You can update the status of a Transaction by setting the new status attribute in the /update endpoint.

April 3, 2023

Inquiries

  • 🌱 Inquiry one-time links via API: There is a new API to generate Inquiry one-time links to send to end users. This API produces links that are more user-friendly for end users and more secure, compared to using the existing Resume an Inquiry API. Learn more about Inquiry one-time links and how this new API compares to other options.

March 27, 2023

Verifications

  • 🔧 Make id-valid-dates-detection not applicable to limited-term or temporary IDs: For limited-term or temporary IDs, the id-valid-dates-detection check now returns a new "Not applicable" reason: unknown-date-rules. The rules used in this check do not apply to these IDs. Before, this check would usually return a failed result for these IDs.

Cases

  • 🔧 Prevent duplicate Case objects: We've added a check to ensure an object can be attached to a Case at most once.

March 20, 2023

Transactions, Cases

  • 🌱 Transactions in Cases API: Transactions are now returned in the Cases API. Transactions that are attached to a Case appear in the new txns field under the top-level relationships field of a serialized Case.

API version: v2023-01-05

Cross-API

  • 💥 🔒 Format and access control of File URLs: The way file URLs are serialized in all API responses has changed. Each file URL now contains a signed access token, which remains valid for 6 hours after the API request was made. For details, see File URLs.

Graph

As of 2023-01-05, Graph is in closed beta. To learn more and request early access, see the the Graph product page.

  • 💥 Format of Graph Query responses: Graph Query responses will now show computed stats for the query results instead of the raw result output.

API version: v2021-08-18

Documents

  • 💥 Format of Generic Document responses: Generic Document responses will no longer include the extraction-results field. Use extraction-responses instead.

Inquiries

  • 💥 Format of Inquiry Session responses: Inquiry Session responses will no longer include the browser-fingerprint field. This value can now be found on the new device field under the top-level relationships field of a serialized Inquiry Session.

API version: v2021-07-15

Inquiries

  • 💥 Format of Inquiry responses: Inquiry responses will no longer include the reviewer field. This value can now be found on the new reviewer field under the top-level relationships field of a serialized Inquiry.

Verifications

  • 💥 Format of Database Verification responses: Database Verification responses will no longer include the following fields: smarty-streets-address-street-1, smarty-streets-address-street-2, smarty-streets-address-city, smarty-streets-address-subdivision, smarty-streets-address-postal-code, smarty-streets-validation.
  • 💥 Format of Government ID Verification responses: A new failure reason barcode_not_decoded has been added for the Government ID Verifications barcode_detection check. On older API versions, this failure reason will serialize as the existing barcode_not_detected reason.

API version: v2021-05-14

  • 💥 Format of Watchlist Report responses: Watchlist Report responses will no longer include the following fields: searched-lists, pep-list, sanction-list, fitness-probity-list, warning-list.

API version: v2021-02-21

  • 💥 Format of Government ID Verification responses: The driver-license-number and passport-number fields will now be sent under identification-number. Inspect the id-class field to determine the type of number represented by identification-number.