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": "john.smith@example.com",
    "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": "hr@techcorp.com",
        "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": "registrar@berkeley.edu",
        "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

  • 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