/v3/verify endpoint with automatic enrollment of successful identities into Identity Manager.
Connect supports the
verifiedUser and humanAssurance verification type.Overview
Connect enables batch identity verification through a simple SFTP file upload process:- Upload CSV files via SFTP to dedicated directories
- Files are processed against
/v3/verifyendpoint - Successful verifications are automatically enrolled in Identity Manager
- Results return the same parameters as real-time API responses
Onboarding
Your Prove representative gives you the following information, some of which you must include in your input file. Reference the Input File Format section for more details.| Credential | Description |
|---|---|
| Enroll Key | Validates file authenticity |
| Verification Type | verifiedUser or humanAssurance |
| Directory Paths | ToProve and FromProve |
| SFTP Credentials | Authentication for file transfer |
Processing flow
The diagram shows how batch files move from your SFTP client through Prove’s SFTP server and processing to the/v3/verify endpoint, then back as output files.
Client Uploads File
Upload your CSV file via SFTP to the designated
ToProve directory using your provisioned credentials.Prove Validates Data
Records are validated for:
- Phone number format and country code
- Required fields are present
- Country code matching file region
Prove Verifies Identities
Valid records are processed against the
/v3/verify endpoint with results returned in the same format as real-time API responses.Prove Enrolls Identities
Identities that pass the Global Fraud Policy are automatically enrolled in Identity Manager.
File requirements
To ensure smooth processing and high verification accuracy, it is essential to follow Prove’s standardized file structures. This section outlines the specific formatting, geographic partitioning, and naming protocols required to successfully send batch data via SFTP.Naming convention
{client_name}_{region}_{verification_type}_YYYYMMDDHHMMSS.csv
| Component | Values | Description |
|---|---|---|
client_name | Agreed during setup | Your organization identifier |
region | US or INTL | US - US and Canada customersINTL - International customers |
verification_type | verifiedUser or humanAssurance | Verification type |
Input file format
Each batch file must follow a strict Header-Detail-Trailer structure for the system to accept it. This sequence ensures that Prove can identify your organization, validate the requested service type, and verify that the SFTP transfer did not lose any records.Header record
| Column | Sample value | Required |
|---|---|---|
| Record Type | H | ✅ Always H |
| Enroll Key | SecretKey | ✅ |
| Verification Type | verifiedUser or humanAssurance | ✅ |
Detail records
| Column | Sample value | Required | Description |
|---|---|---|---|
| Record Type | D | ✅ Always D | |
| Phone Number | +12008040444 | ✅ Including country code | |
| First Name | John | ✅ | |
| Last Name | Doe | ✅ | |
| Client Customer ID | zaq12wsx | ||
| Attribute Type | userId | ✅ If you are a partner | This field is a metadata indicator of the type of value being passed in for the consumer. |
| Issuer ID | AcmeWallet | ✅ If you are a partner | Use your company name. |
| Attribute Value | A4B1F13BCCFC | ✅ If you are a partner | This field is the unique value assigned to the consumer for the Attribute Type you pass in. It shouldn’t contain PII. |
Trailer record
| Column | Sample value | Required |
|---|---|---|
| Record Type | T | ✅ Always T |
| Number of Records | 132789 | ✅ |
There is no limit to the number of detail records you can include in a file.
Example file
Output file format
Upon completion of processing, Prove generates an output file in your designatedFromProve directory. This file mirrors the structure of your input file, but appends critical verification data, such as Assurance Levels, identity attributes, and status codes for each processed record.
Header record
| Column | Sample value | Notes |
|---|---|---|
| Record Type | H | Always H |
Detail records
| Column | Sample value | Notes |
|---|---|---|
| Record Type | D | Always D |
| Phone Number | +12008040444 | |
| First Name | John | |
| Last Name | Doe | |
| Client Customer ID | zaq12wsx | If sent in the request |
| Attribute Type | userId | |
| Issuer ID | AcmeWallet | |
| Attribute Value | A4B1F13BCCFC | |
| Assurance Level | AL2 | If successful |
| Assurance Level Reason Codes | AL2a, AL2b | If successful |
| Prove Phone Alias | 474628DC4VK83842DB25DA4B1F13BCCFC0MEK4P664Z9PCC6E6C3CB92DC40191E5E868E5E38B1AC85F6G359B74880097B63C51E7E8636B33FA344CB8E | If successful |
| ProveID | 6b942541-abab-40ed-9970-5a28217836c0 | If successful |
| Error | 200 | |
| Error Message | NA | |
| GFP Authentication Result | pass | If successful |
| GFP Risk Result | pass | If successful |
The system processes only the top-level identity and excludes extra identities from the output.
Trailer record
| Column | Sample value | Notes |
|---|---|---|
| Record Type | T | Always T |
| Number of Records | 132789 |
Error file format
Records failing validation are written to a separate error file inFromProve with error codes:
| Error Code | Description |
|---|---|
ERR_MISSING_FNAME | First name is missing |
ERR_MISSING_LNAME | Last name is missing |
ERR_MISSING_PHONE | Phone number is missing |
ERR_FORMAT_PHONE | Invalid phone number format |
ERR_PHONE_COUNTRY_NOTSUPPORTED | Phone country not supported |
ERR_DUPLICATE_RECORD_ORIGINAL_PRESERVED | Duplicate record detected |
Header record
| Column | Sample value | Notes |
|---|---|---|
| Record Type | H | Always H |
| Verification Type | verifiedUser or humanAssurance |
Detail records
| Column | Sample value | Notes |
|---|---|---|
| Record Type | D | Always D |
| Phone Number | +12008040444 | |
| First Name | John | |
| Last Name | Doe | |
| Client Customer ID | zaq12wsx | If sent in the request |
| Error Attribution | ERR_MISSING_FNAME |
Trailer record
| Column | Sample value | Notes |
|---|---|---|
| Record Type | T | Always T |
| Number of Records | 132789 |
Notifications
Email alerts
Prove can send email alerts if a file is rejected or processed successfully. Please give a distribution list to your Prove representative to ensure you receive these notifications.Success emails include data quality statistics.
Best practices
Validate data before upload
Validate data before upload
Ensure you populated all required fields and phone numbers include country codes to minimize error records.
Match record counts
Match record counts
Verify your trailer record count matches the actual number of detail records before upload to prevent rejection.
Use correct file regions
Use correct file regions
Route phone numbers to the correct regional file based on country code.
Monitor email notifications
Monitor email notifications
Set up appropriate email routing to address any file rejections or processing issues.