DocumentationAPI Reference
DocumentationAPI ReferenceOpenAPIStatus
DocumentationAPI ReferenceOpenAPIStatus

API Changelog

About

Below is a log of changes to the Persona API. 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 :boom: 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

:seedling: New feature
:leaves: Improvement
:wrench: Fix
:boom: Breaking change
:lock: Security-related

December 4, 2023

Transactions

  • :leaves: Add external-id to Transactions Create a Transaction can now take in an identifier that gets indexed and can be used for look-up.

November 27, 2023

Reports

  • :leaves: Add phone_number parameter to Report creation Report can now take in phone numbers.

November 13, 2023

Inquiries

  • :seedling: Account creation opt-out on Inquiry creation: meta.auto-create-account on Create an Inquiry lets you skip creating an Account
  • :seedling: Choose Account Type on Inquiry creation: meta.auto-create-account-type-id parameter on Create an Inquiry allows setting a custom Account Type.
  • :leaves: 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

  • :seedling: 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

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

October 23, 2023

Inquiries

API Keys & Webhooks

October 16, 2023

Inquiries

:boom: 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

:wrench: 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

  • :leaves: 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

  • :seedling: 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

  • :seedling: 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

  • :wrench: 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

  • :seedling: 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

  • :seedling: 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

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

Reports

  • :leaves: 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

  • :seedling: 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

  • :seedling: 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

  • :boom: 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
  • :seedling: 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

  • :leaves: 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

  • :seedling: 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

  • :seedling::lock: 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.
  • :leaves: 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

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

  • :wrench: 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

  • :leaves: 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

  • :seedling: 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

  • :leaves: 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

  • :leaves: 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

  • :seedling: 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.
  • :seedling: 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.
  • :leaves: 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

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

  • :seedling: 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.
  • :leaves: 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.
  • :wrench: 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

  • :seedling: 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

  • :seedling: 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

  • :wrench: 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

  • :wrench: 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

  • :seedling: 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

  • :boom: :lock: 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.

  • :boom: 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

:boom: Format of Generic Document responses: Generic Document responses will no longer include the extraction_results field. Use extraction_responses instead.

Inquiries

:boom: 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

:boom: 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

:boom: 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.

:boom: 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

:boom: 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

:boom: 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.

Updated 2 days ago