Identity Verification

Enabling Identity Verification

Identity Verification is enabled by Snappt. To turn it on for one or more of your properties, reach out to your Snappt contact.

📘
Properties must be enabled before you send invites
Invites sent for a property that doesn't have Identity Verification enabled won't work. Confirm with your Snappt contact that each property is set up before sending applicants into the identity flow.

Sending an Applicant into the Identity Flow

There are two ways to invite an applicant to verify their identity. Both take the same parameters, and both return an applicantDetailId.

POST /id-verification/send-idv-email: Snappt emails the applicant a link into the identity flow. email is required.
POST /id-verification/generate-idv-link: Snappt returns a link that you deliver to the applicant yourself. email is optional.

📘
Creating an invite does not start a verification session
The verification session starts when the applicant opens the link. Store the applicantDetailId returned in the response, since it's your handle for this invite.

Request parameters

Parameter	Required	Description
`companyShortId`		Your company's short ID
`propertyShortId`		The property's short ID
`firstName`, `lastName`	No	Auto-filled from the applicant's ID if left blank
`email`	Required for `send-idv-email` only	The applicant's email address
`integrationId`	No	Your own identifier for the applicant, such as a PMS applicant or prospect ID
`metadata`	No	A custom object that's returned to you on the `IDV_REPORT_READY` webhook

Re-inviting an applicant

Links don't expire, so an applicant can use the same link to start their verification at any time.

If you pass an integrationId, re-inviting the same applicant at the same property returns the same applicantDetailId, as long as they've already opened an earlier invite. Until they open one, each invite returns a new applicantDetailId.

🚧
Redirect URLs are no longer supported
The applicant stays on the Snappt completion page when they finish. If you previously passed a redirectUrl, you can remove it.

Retrieving Results

To get the results of an identity verification, you must subscribe to the IDV_REPORT_READY webhook. Snappt sends it when the verification reaches a final status, and it's how you receive the idVerificationId you need to retrieve the results.

🚧
IDV Report Ready Webhook
A webhook subscription is required
The applicantDetailId returned when you create the invite can't be used to look up results directly. You need the idVerificationId from the IDV_REPORT_READY webhook. Set up your webhook with POST /webhooks before sending invites.

Step 1: Receive the webhook

When the applicant finishes, Snappt sends IDV_REPORT_READY to your webhook URL. The data object includes:

Field	Description
`idVerificationId`	The ID of the completed verification
`status`	`PASS` or `FAIL`

[CONFIRM: the field(s) partners use to match the webhook to their invite, such as applicantDetailId or the metadata they passed.]

See Webhook Event Types for the full payload.

Step 2: Retrieve the verification record

Use the idVerificationId from the webhook to get the full record with GET /id-verification/applicants/{idVerificationId}.

Step 3: Download the report

Download the PDF report with GET /id-verification/applicants/{idVerificationId}/report.

📘
Missed a webhook?
You can list all of your ID verification records with GET /id-verification/applicants and find any results you didn't receive.