Verifications

A borrower verification session represents the interactions necessary for an agent to verify the identity of a human who purports to be a particular borrower. For instance, upon receiving a phone call, an agent would initiate a borrower verification, ask the questions to the borrower, and enter their responses. The agent is never shown the correct answers, so privacy risks are minimized and socially engineered security attacks are mitigated.

Start verification

Start a borrower verification session. Newly created verifications include randomly selected questions about the borrower. The human must attempt to provide correct answers to these questions in order for the borrower verification to be successful.

To check if a verification can be started now without actually starting a verification, add the query param dryRun=true to the URL. If a verification could be started now return successful (204), otherwise return an error response with nextVerificationOkAt indicating when the next verification can start.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

query Parameters
dryRun
boolean
Default: false

If true, then return successfully if the operation would complete successfully, but do not actually save the changes which would result from this operation.

Request Body schema: application/json
verificationTypeId
string

The id of the borrower verification type to use when creating the verification. If null, then use the default borrower verification type.

Responses
200

Successfully started verification

204

A verification can be started now—only occurs with dryRun=true param

400

A verification is not possible

429

A verification cannot be started now—try again later

post/people/{personId}/verifications
Request samples
application/json
{
  • "verificationTypeId": "string"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get verifications

Retrieve all verifications—optionally filtering. Note that unlike most Peach "get all" endpoints, the verifications get all endpoint returns items in a reverse chronological list, since almost all interesting verifications are those which happened in the recent past.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

query Parameters
limit
integer [ 1 .. 100 ]
Default: 25

The maximum count of results to retrieve.

startingAfter
string

Return results starting after the provided object identifier.

endingBefore
string

Return results ending before the provided object identifier.

status
Array of strings

The comma separated list of status values of verifications to include in the response. If not included, include all verifications.

Responses
200

Success

get/people/{personId}/verifications
Response samples
application/json
{
  • "count": 0,
  • "data": [
    ]
}

Get verification by ID

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

verificationId
required
string

The borrower verification unique identifier.

Responses
200

Success

get/people/{personId}/verifications/{verificationId}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Answer verification questions

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

verificationId
required
string

The borrower verification unique identifier.

Request Body schema: application/json
Array of objects

The list of answers to the questions for this verification. Ordering is not important, but the questionId must match the id of the question to which the answer corresponds. All of the answers must match the stored information about the borrower in order for the verification to be successful.

Responses
200

Created

post/people/{personId}/verifications/{verificationId}/attempts
Request samples
application/json
{
  • "answers": [
    ]
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}