Skip to main content

VerificationRequestDto Schema

The VerificationRequestDto is the main request object for creating background check orders. It contains all information needed to initiate verification workflows.

Required Fields

Optional Fields

Complete Example

{
  "searchTypes": [
    {
      "searchType": "EMPLOYMENT"
    },
    {
      "searchType": "EDUCATION"
    }
  ],
  "applicant": {
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789",
    "birthday": "1990-05-15",
    "phone": "+1-555-123-4567",
    "email": "[email protected]",
    "signedReleaseFileUrl": "https://example.com/signed-release.pdf",
    "addresses": [
      {
        "addressType": "home",
        "addressLine1": "456 Oak Avenue",
        "addressLine2": null,
        "addressCity": "Los Angeles",
        "addressState": "CA",
        "addressZipCode": "90210",
        "addressCountry": "US",
        "startDate": "2021-01-01",
        "endDate": null
      }
    ],
    "applicantAlias": [
      {
        "firstName": "Jonathan",
        "lastName": "Smith",
        "middleName": "Michael",
        "suffix": "Jr."
      }
    ]
  },
  "businessContext": {
    "entityName": "Apple",
    "appliedJobTitle": "Senior Software Engineer",
    "worksiteCity": "San Francisco",
    "worksiteState": "CA",
    "proposedSalary": 100000,
    "positionLevel": "STANDARD",
    "securityClearanceRequired": false,
    "industrySector": "TECHNOLOGY"
  },
  "history": {
    "employment": [
      {
        "employerName": "Tech Corp",
        "position": "Software Engineer",
        "employerEmail": "[email protected]",
        "employerPhone": "+1-555-123-4567",
        "startDate": "2020-01-15",
        "endDate": "2023-06-30"
      }
    ],
    "education": [
      {
        "institutionName": "University of California",
        "qualification": "Bachelor of Science in Computer Science",
        "fieldOfStudy": "Computer Science",
        "graduationDate": "2018-05-15",
        "institutionContactEmail": "[email protected]",
        "institutionContactPhone": "+1-510-642-6000"
      }
    ]
  },
  "webhookConfig": {
    "enabled": true,
    "secret": "webhook-secret-for-hmac-validation",
    "retryAttempts": 3,
    "closeoutEndpoints": {
      "EMPLOYMENT": [
        {
          "url": "https://client.example.com/webhooks/employment-closeout",
          "headers": { "X-Customer": "acme" },
          "events": ["verification.completed"]
        },
        {
          "url": "https://client.example.com/webhooks/employment-notifications",
          "events": ["verification.notification"]
        }
      ],
      "EDUCATION": [
        {
          "url": "https://client.example.com/webhooks/education-closeout",
          "basicAuth": { "username": "api", "password": "secret" },
          "events": ["verification.completed"]
        }
      ]
    },
    "fallbackEndpoint": [
      {
        "url": "https://client.example.com/webhooks/all-events",
        "events": ["verification.action_required"],
        "searchTypes": ["EMPLOYMENT", "EDUCATION"]
      }
    ]
  }
}

Validation Rules

  • Conditional Requirement: CriminalCheckDto is required when searchTypes includes “CRIMINAL”
  • Jurisdictions Required: At least one jurisdiction level must be specified
  • Date Format: All dates must be in YYYY-MM-DD format
  • Address Validation: Exactly one address must be current (endDate: null)
  • Email Validation: Must be valid email format
  • SSN Format: Must follow XXX-XX-XXXX pattern

Usage

This schema is used in:

Next Steps