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. For a complete required / optional field table (top-level and nested objects), see Create order — Request body field reference.
Only EMPLOYMENT and EDUCATION are supported in searchTypes. Sending criminalCheck or history.criminal returns 400 Bad Request.

​
Supported Fields

FieldRequiredTypeRules and links
applicantYesobjectApplicant identity and contact details. See ApplicantDto.
businessContextYesobjectRole and hiring context for the requested verification. See BusinessContextDto.
searchTypesYesarraySearches to run. Supported values are EMPLOYMENT and EDUCATION. See SearchTypeDto.
historyNoobjectEmployment and education records to verify. See HistoryDto.
defaultSearchConfigNoobjectOrder-level policy defaults for searches that do not define their own searchConfig. Supports channel, timing, outbound, research, inbound, escalation, notification, and thirdPartyBan overrides. See SearchConfigDto.
webhookConfigNoobjectPer-order webhook routing and signing configuration. Takes precedence over tenant-level webhook configuration. See WebhookConfigDto.

​
Common Nested Shapes

​
searchTypes[]

[
  {
    "searchType": "EMPLOYMENT"
  },
  {
    "searchType": "EDUCATION",
    "searchConfig": {
      "thirdPartyBan": ["NSCH"]
    }
  }
]

​
webhookConfig

{
  "enabled": true,
  "secret": "webhook-secret-for-hmac-validation",
  "retryAttempts": 3,
  "closeoutEndpoints": {
    "EMPLOYMENT": "https://client.example.com/webhooks/employment-closeout",
    "EDUCATION": "https://client.example.com/webhooks/education-closeout"
  },
  "fallbackEndpoint": "https://client.example.com/webhooks/search-closeout"
}

​
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