# 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 parameter `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.

Endpoint: POST /people/{personId}/verifications
Version: 2025-03-26
Security: oauth2, bearerAuth, apiKeyHeader

## Path parameters:

  - `personId` (string, required)
    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)
    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 fields (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.

## Response 200 fields (application/json):

  - `message` (string)
    Description of the server action or error.

  - `status` (integer)
    HTTP status code.

  - `data` (object)
    Object describes a borrower verification process. When a borrower initiates a phone call their
identity should be verified before they are allowed to make changes to their account.

  - `data.createdAt` (string)

  - `data.deletedAt` (string)

  - `data.id` (string)

  - `data.updatedAt` (string)

  - `data.agentUserId` (string)
    An identifier of the agent performing the verification

  - `data.attempts` (array)
    Represents the attempts to answer the questions associated with this borrower verification.
The responses are intentionally not included for privacy and security. There can only be a maximum
of `maxAttempts`. There can only be one successful attempt. A successful attempt is one with
`isSuccess` set to `true`.

  - `data.attempts.createdAt` (string)

  - `data.attempts.isSuccess` (boolean)
    `true` if this attempt to answer the questions was successful.

  - `data.expiresAt` (string)

  - `data.maxAttempts` (integer)
    The maximum number of times an attempt can be made to answer all the questions. If `maxAttempts`
are made without success, then this verification's status is set to `failed`.

  - `data.object` (string)
    Enum: "verification"

  - `data.personId` (string)
    An identifier of the borrower

  - `data.questions` (array)
    The questions that were generated and must be answered.

  - `data.questions.category` (string)
    The category of questions to include.
- `inBorrowerPortal` indicates the answer to this question can
be found in the borrower portal.
- `knownToBorrower` indicates the answer to this question
is not found in borrower portal (and therefore must be known by the borrower).
- `presetSecret` indicates the answer to this question was preconfigured by the borrower previously.
    Enum: "inBorrowerPortal", "knownToBorrower", "presetSecret"

  - `data.questions.id` (string)

  - `data.questions.memo` (string)
    The text of the memo for the agent

  - `data.questions.text` (string)
    The text of the question

  - `data.status` (string)
    The status of the verification.
- `pending` - Verification is pending and answers can still be provided.
- `succeeded` - Verification was successfully completed.
- `failed` - Verification failed—the maximum number of answer attempts was reached.
- `insufficientKnowledge` - Verification could not be created because there is not enough information about the person to generate questions.
- `expired` - Verification timed out and was expired.
    Enum: "failed", "pending", "succeeded", "expired", "insufficientKnowledge"

## Response 400 fields (application/json):

  - `message` (string)
    A description of the error.

  - `status` (integer)
    HTTP status code.

## Response 429 fields (application/json):

  - `message` (string)
    Description of the server action or error.

  - `status` (integer)
    HTTP status code.

  - `data` (object)

  - `data.nextVerificationOkAt` (string)