Skip to main content

​
Applicant Schema

The Applicant object contains all personal information about the individual being verified in a background check.

​
Supported Fields

FieldRequiredTypeRules and behavior
firstNameYesstringApplicant first name. Example: "John".
lastNameYesstringApplicant last name. Example: "Smith".
ssnYesstringSocial Security Number in XXX-XX-XXXX format. Example: "123-45-6789".
birthdayNostringBirthday in YYYY-MM-DD format. Example: "1990-05-15".
phoneNostringApplicant phone number.
emailNostringApplicant email address. Must be valid when provided.
signedReleaseFileUrlNostringSigned release PDF source: HTTPS URL, GCS URI (gs://), or base64-encoded PDF (optionally data:application/pdf;base64,...). Max 10MB for inline base64. See Signed release file.
addressesNoAddressDto[]Applicant address history. Omit or send [] when no home address is available. See AddressDto.
applicantAliasNoApplicantAliasDto[]Alternate names or aliases for the applicant. See ApplicantAliasDto.
addresses is optional on order creation. See Create order — field reference for the full request contract.

​
Signed release file

signedReleaseFileUrl is optional. When provided, the signed release PDF is attached to outbound verification requests (email or fax, depending on tenant policy). You can supply the file in three ways:
MethodInputStored on search
External URLhttps://example.com/signed-release.pdfSame HTTPS URL
GCS uploadgs://.../releaseForms/...pdf from Generate upload URLSame GCS URI
Inline base64Raw base64 or data:application/pdf;base64,...Uploaded to cloud storage at order creation; searches store the resulting gs:// URI
Inline base64 must decode to a valid PDF (starts with %PDF) and must not exceed 10MB. Production accepts HTTPS URLs only (not http://).
  1. GET /files/release-form/generate-upload-url → signedUrl, fileUri
  2. PUT the PDF to signedUrl with Content-Type: application/pdf
  3. Set applicant.signedReleaseFileUrl to fileUri

​
Inline base64 example

{
  "applicant": {
    "firstName": "John",
    "lastName": "Smith",
    "ssn": "123-45-6789",
    "signedReleaseFileUrl": "JVBERi0xLjQK..."
  }
}

​
Complete Example

{
  "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
    },
    {
      "addressType": "home",
      "addressLine1": "123 Main Street",
      "addressLine2": "Apt 4B",
      "addressCity": "New York",
      "addressState": "NY",
      "addressZipCode": "10001",
      "addressCountry": "US",
      "startDate": "2020-01-01",
      "endDate": "2021-01-01"
    }
  ],
  "applicantAlias": [
    {
      "firstName": "Jonathan",
      "lastName": "Smith",
      "middleName": "Michael",
      "suffix": "Jr."
    }
  ]
}

​
Validation Rules

  • SSN Format: Must follow XXX-XX-XXXX pattern
  • Email Format: Must be a valid email address
  • Date Format: All dates must be in YYYY-MM-DD format
  • Address Requirement: Exactly one address must be current (endDate: null)
  • Signed release file: Must be a valid HTTPS URL (production), GCS URI (gs://), or base64-encoded PDF (max 10MB). Inline base64 is uploaded to cloud storage at order creation; searches store the resulting gs:// URI.