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
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
December 4, 2023
Transactions
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
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 AccountChoose 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 ofdata.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 betrue
when a report is able to recur and is currently recurring in its runs. This, in concert withhas-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
- Inquiries “simulate actions” Endpoint: The new Perform Simulate Actions endpoint lets you Simulate Inquiry Actions.
- Add
updated-at
to Inquiries attributes: The Inquiry model now shows when it was last modified.
API Keys & Webhooks
- Attribute Blocklist Exceptions Exclude entries from the API/Webhook Attribute Blocklists.
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 theresult.identifiers.status
attribute's valuesunknown
andnot_applicable
to justunknown
. 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.
- Adverse Media Report
August 21, 2023
Inquiries
inquiry-template
now included when retrieving an Inquiry: Retrieving an Inquiry will now return the relatedinquiry-template
withinincluded
. It contains fields:status
andname
along with a relationshiplatest-published-version
. You can compare it with the inquiry'sinquiry-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
, orregistered_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
Improved filtering for Inquiries List API: We now allow you to filter the list of your organization's inquiries by
template_id
orinquiry_template_id
.
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 withinconfig
undersupported_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 additionalmetadata
fields:detected_id_class
andselected_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 returnsmetadata
with fields:country_code
,enabled_country_codes
, andselected_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 newfields
object that contains details of the Account, such as first name, last name, birthdate, etc. If you have the choice, usefields
to read details about the Account, instead ofattributes
.
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
andextraction-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'sattributes
.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 additionalmetadata
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 onselfie-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 theselfie-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 additionalmetadata
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:
- The Selfie Liveness verification check (
selfie_liveness_detection
) is enabled. - 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.
- The Selfie Liveness verification check (
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, theid_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-levelrelationships
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
.
Updated 2 days ago