> ## Documentation Index > Fetch the complete documentation index at: https://documentation.theary.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Order > Create a background check order # Create Order Creates one background check order. Use sandbox to validate request shape and move the same contract to production with production credentials. Supported `searchType` values: **`EMPLOYMENT`** and **`EDUCATION`**. ## Request body field reference ### Top-level body | Field | Required | Type | Description | | | --------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `applicant` | Yes | `object` | Person being verified (identity, optional contact, addresses, aliases). See [Applicant](/api-reference/schemas/applicant). | | | `businessContext` | Yes | `object` | Hiring context for the role (employer, title, worksite, salary) — not the applicant home address. See [Business context](/api-reference/schemas/business-context). | | | `searchTypes` | Yes | `object[]` | Searches to run. Values: \`EMPLOYMENT | EDUCATION\` only. At least one search is recommended. See [Search type](/api-reference/schemas/search-type). | | `history` | No | `object` | Employment and/or education records to verify. See [History](/api-reference/schemas/history). | | | `webhookConfig` | No | `object` | Per-order webhook routing and signing; overrides organization-level webhook config. See [Webhook config](/api-reference/schemas/webhook-config). | | | `defaultSearchConfig` | No | `object` | Order-level policy defaults (channels, outbound, timing, `thirdPartyBan`, etc.). Fully replaced per search when `searchTypes[].searchConfig` is set. See [Search config](/api-reference/schemas/search-config). | | ### `applicant` | Field | Required | Type | Description | | ---------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `firstName` | Yes | `string` | Applicant legal first name. Example: `"John"`. | | `lastName` | Yes | `string` | Applicant legal last name. Example: `"Smith"`. | | `ssn` | Yes | `string` | Social Security Number. Conventionally `XXX-XX-XXXX` (example: `"123-45-6789"`). Required as a non-empty string; pattern is not API-enforced. | | `birthday` | No | `string` | Date of birth in `YYYY-MM-DD` format. Example: `"1990-05-15"`. | | `phone` | No | `string` | Applicant phone number for contact during verification. Example: `"+1-555-123-4567"`. | | `email` | No | `string` | Applicant email address. Must be valid when provided. | | `signedReleaseFileUrl` | No | `string` | Signed release PDF: HTTPS URL, `gs://` URI, or base64-encoded PDF (max 10MB). See [Signed release file](/api-reference/schemas/applicant#signed-release-file). | | `addresses` | No | `object[]` | Optional address history. Omit or send `[]` when no home address is available. See [Address](/api-reference/schemas/address). | | `applicantAlias` | No | `object[]` | Alternate or former names (AKA). See [Applicant alias](/api-reference/schemas/applicant-alias). | ### `applicant.addresses[]` (when non-empty) | Field | Required | Type | Description | | ---------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `addressType` | Yes | `string` | Address category. Convention for home history: `"home"`. | | `addressLine1` | Yes | `string` | Street address line 1. | | `addressLine2` | No | `string` | Apartment, suite, unit, or other secondary line. | | `addressCity` | Yes | `string` | City. | | `addressState` | Yes | `string` | Two-letter US state code. Example: `"CA"`. | | `addressZipCode` | Yes | `string` | ZIP or postal code (1–10 characters). | | `addressCountry` | No | `string` | Two-letter country code. Defaults to `US` when omitted. | | `startDate` | Yes | `string` | Start of residence in `YYYY-MM-DD` format. | | `endDate` | No | `string` | End of residence in `YYYY-MM-DD` format. `null` or omitted = current address. Exactly **one** entry must be current when the array is non-empty. | ### `applicant.applicantAlias[]` | Field | Required | Type | Description | | ------------ | -------- | -------- | ------------------------------------------- | | `firstName` | Yes | `string` | Alias first name. | | `lastName` | Yes | `string` | Alias last name. | | `middleName` | No | `string` | Alias middle name. | | `suffix` | No | `string` | Name suffix such as `Jr.`, `Sr.`, or `III`. | ### `businessContext` | Field | Required | Type | Description | | --------------------------- | -------- | --------- | ------------------------------------------------------------------------------- | | `entityName` | Yes | `string` | Employer the candidate is applying to. Example: `"Acme Corp"`. | | `appliedJobTitle` | Yes | `string` | Job title the candidate is applying for. Example: `"Senior Software Engineer"`. | | `worksiteCity` | Yes | `string` | City of the proposed worksite (not applicant home). Example: `"San Francisco"`. | | `worksiteState` | Yes | `string` | Two-letter state code for the proposed worksite. Example: `"CA"`. | | `proposedSalary` | Yes | `number` | Proposed salary as a number. Example: `100000`. | | `positionLevel` | No | `string` | Common values: `EXECUTIVE`, `STANDARD`, `SENSITIVE` (not enum-enforced). | | `securityClearanceRequired` | No | `boolean` | Whether the role requires security clearance. | | `industrySector` | No | `string` | Industry sector for regulatory context. Example: `"TECHNOLOGY"`. | ### `searchTypes[]` | Field | Required | Type | Description | | ------------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `searchType` | Yes | `string` | Search type to run: `EMPLOYMENT` or `EDUCATION`. | | `externalSearchId` | No | `string` | Client correlation ID for webhook idempotency and reconciliation. | | `questionnaireUrl` | No | `string` | Optional direct link to the online questionnaire for this search. | | `questionnaireAccessCode` | No | `string` | Optional access code for the online questionnaire. | | `verificationQuestions` | No | `object[]` | Custom verification questions for this search (max 50). See [Verification question](/api-reference/schemas/verification-question). | | `searchConfig` | No | `object` | Per-search policy overrides. When present (even as `{}`), fully replaces `defaultSearchConfig` for this search. See [Search config](/api-reference/schemas/search-config). | ### Search policy fields Use `defaultSearchConfig` for order-wide defaults, or `searchTypes[].searchConfig` for one search. See [Search config](/api-reference/schemas/search-config) for the full nested table. | Field | Type | Description | | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `thirdPartyBan` | `string[]` | Canonical vendor codes to suppress for this search, such as `TALX_WORK_NUMBER` or `NSCH`. Max **50**; `UNKNOWN` is rejected. See [Third-party ban](/guides/third-party-ban). | | `channels` | `object` | Channel enablement, preferred channel, allowed destinations, and blocked destinations. | | `timing` | `object` | SLA, outbound window, and business-hours overrides. | | `outbound` | `object` | Attempt caps, third-party deferral, terminal-inbound outbound cancel, and `contactHints`. | | `research` | `object` | Research controls such as `skipResearch`. | | `inbound` | `object` | Manual-review and auto-complete behavior for inbound responses. | | `escalation` | `object` | Auto-escalation, escalation webhook URL, and broad third-party event suppression. | | `notifications` | `object` | Notification suppression, raw inbound inclusion, and webhook override routing. | | `qaDestinations` | `object` | **Non-production only.** Redirect this search's outbound to test email/phone/fax. Validated in every environment, ignored in production. See [Search config](/api-reference/schemas/search-config#qadestinations). | ### `history` | Field | Required | Type | Description | | ------------ | -------- | ---------- | -------------------------------------------------------------------------------------------------- | | `employment` | No | `object[]` | Employment records to verify. See [Employment history](/api-reference/schemas/employment-history). | | `education` | No | `object[]` | Education records to verify. See [Education history](/api-reference/schemas/education-history). | ### `history.employment[]` | Field | Required | Type | Description | | ------------------ | -------- | -------- | --------------------------------------------------------------------------- | | `employerName` | Yes | `string` | Employer or company name. Example: `"Tech Corp"`. | | `position` | Yes | `string` | Job title held. Example: `"Software Engineer"`. | | `employerLocation` | No | `string` | Work location. Example: `"San Francisco, CA"`. | | `employerEmail` | No | `string` | Employer contact email for verification. Must be valid when provided. | | `employerPhone` | No | `string` | Employer contact phone for verification. | | `employerFax` | No | `string` | Employer contact fax for verification. | | `startDate` | No | `string` | Employment start date in `YYYY-MM-DD` format. | | `endDate` | No | `string` | Employment end date in `YYYY-MM-DD` format. Omit or `null` for current job. | ### `history.education[]` | Field | Required | Type | Description | | ------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------- | | `institutionName` | Yes | `string` | Educational institution name. Example: `"University of California"`. | | `qualification` | Yes | `string` | Credential earned. Example: `"Bachelor of Science in Computer Science"`. | | `fieldOfStudy` | Yes | `string` | Major or field of study. Example: `"Computer Science"`. | | `institutionLocation` | No | `string` | Institution location. Example: `"Berkeley, CA"`. | | `startDate` | No | `string` | Attendance start date in `YYYY-MM-DD` format. | | `endDate` | No | `string` | Attendance end date in `YYYY-MM-DD` format (use when the applicant attended but did not graduate). | | `graduationDate` | No | `string` | Graduation or completion date in `YYYY-MM-DD` format. Optional if the applicant did not graduate. | | `institutionContactEmail` | No | `string` | Institution contact email for verification. Must be valid when provided. | | `institutionContactPhone` | No | `string` | Institution contact phone for verification. | ### Field validation notes | Field | Constraint | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `applicant.ssn` | Required, non-empty string. The API accepts any non-empty value (no pattern enforcement). Conventionally `XXX-XX-XXXX`. | | `businessContext.positionLevel` | Free-text string. Common values are `EXECUTIVE`, `STANDARD`, `SENSITIVE`, but the API does not enforce an enum. Use consistent values across your integration for downstream reporting. | | `businessContext.industrySector` | Free-text string. Examples: `TECHNOLOGY`, `HEALTHCARE`, `FINANCE`. Not enum-enforced. | | `businessContext.proposedSalary` | Must be a number (`100000`, not `"100000"`). | | `webhookConfig.retryAttempts` | Integer. Default: `3`. Maximum: `10`. Values outside this range may produce unexpected behavior. | | All date fields | `YYYY-MM-DD` format. Invalid formats return `400`. | ### Conditional requirements * **`applicant.addresses` is optional.** Employment and education verification use `businessContext.worksite*` and history locations, not home address. * **If `addresses` is non-empty:** exactly one current address (`endDate: null` or omitted); `startDate` must be before `endDate` on historical rows. * **Do not send** `addresses: [{}]` — omit the field instead of sending partial address objects. ## Minimal example (no home address) ```json theme={null} { "searchTypes": [{ "searchType": "EMPLOYMENT" }], "applicant": { "firstName": "John", "lastName": "Smith", "ssn": "123-45-6789" }, "businessContext": { "entityName": "Acme Corp", "appliedJobTitle": "Senior Software Engineer", "worksiteCity": "San Francisco", "worksiteState": "CA", "proposedSalary": 100000 }, "history": { "employment": [ { "employerName": "Tech Corp", "position": "Software Engineer", "employerLocation": "San Francisco, CA", "startDate": "2020-01-15", "endDate": "2023-06-30" } ] } } ``` ## Full example (with home address) Use this JSON body to create a single employment verification order with optional applicant home address. ```json theme={null} { "searchTypes": [ { "searchType": "EMPLOYMENT", "externalSearchId": "client-emp-001", "questionnaireUrl": "https://verify.example.com/form/abc123", "questionnaireAccessCode": "ACCESS123" } ], "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", "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": "Acme Corp", "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", "employerLocation": "San Francisco, CA", "employerEmail": "hr@techcorp.com", "employerPhone": "+1-555-123-4567", "employerFax": "+1-555-987-6543", "startDate": "2020-01-15", "endDate": "2023-06-30" } ] }, "webhookConfig": { "enabled": true, "secret": "webhook-secret-for-hmac-validation", "retryAttempts": 3, "fallbackEndpoint": "https://your-app.com/webhooks/verification" } } ``` ## Example request Replace `YOUR_JWT_TOKEN` with a sandbox Bearer JWT that includes your organization's `tenant` claim. The body below is the [minimal employment example](#minimal-example-no-home-address); swap in the [full example](#full-example-with-home-address) when you need addresses, aliases, or webhooks. ```bash cURL theme={null} curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/orders" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "searchTypes": [{ "searchType": "EMPLOYMENT" }], "applicant": { "firstName": "John", "lastName": "Smith", "ssn": "123-45-6789" }, "businessContext": { "entityName": "Acme Corp", "appliedJobTitle": "Senior Software Engineer", "worksiteCity": "San Francisco", "worksiteState": "CA", "proposedSalary": 100000 }, "history": { "employment": [ { "employerName": "Tech Corp", "position": "Software Engineer", "employerLocation": "San Francisco, CA", "startDate": "2020-01-15", "endDate": "2023-06-30" } ] } }' ``` ```bash cURL (from file) theme={null} # Save the minimal or full JSON example as order.json, then: curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/orders" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ --data @order.json ``` ```javascript JavaScript theme={null} const response = await fetch('https://sandbox.theary.ai/background-check/v1/orders', { method: 'POST', headers: { Authorization: 'Bearer YOUR_JWT_TOKEN', 'Content-Type': 'application/json', Accept: 'application/json', }, body: JSON.stringify({ searchTypes: [{ searchType: 'EMPLOYMENT' }], applicant: { firstName: 'John', lastName: 'Smith', ssn: '123-45-6789', }, businessContext: { entityName: 'Acme Corp', appliedJobTitle: 'Senior Software Engineer', worksiteCity: 'San Francisco', worksiteState: 'CA', proposedSalary: 100000, }, history: { employment: [ { employerName: 'Tech Corp', position: 'Software Engineer', employerLocation: 'San Francisco, CA', startDate: '2020-01-15', endDate: '2023-06-30', }, ], }, }), }) if (!response.ok) { throw new Error(`Create order failed: ${response.status} ${await response.text()}`) } const { verificationOrderId, searchIds } = await response.json() ``` ```python Python theme={null} import requests payload = { "searchTypes": [{"searchType": "EMPLOYMENT"}], "applicant": { "firstName": "John", "lastName": "Smith", "ssn": "123-45-6789", }, "businessContext": { "entityName": "Acme Corp", "appliedJobTitle": "Senior Software Engineer", "worksiteCity": "San Francisco", "worksiteState": "CA", "proposedSalary": 100000, }, "history": { "employment": [ { "employerName": "Tech Corp", "position": "Software Engineer", "employerLocation": "San Francisco, CA", "startDate": "2020-01-15", "endDate": "2023-06-30", } ] }, } response = requests.post( "https://sandbox.theary.ai/background-check/v1/orders", headers={ "Authorization": "Bearer YOUR_JWT_TOKEN", "Content-Type": "application/json", "Accept": "application/json", }, json=payload, timeout=30, ) response.raise_for_status() data = response.json() verification_order_id = data["verificationOrderId"] search_ids = data["searchIds"] ``` ## Optional search policy override Use `defaultSearchConfig` for order-wide defaults. Add `searchConfig` inside a `searchTypes[]` entry only when that search needs different behavior; per-search config replaces the order default for that search. ```json theme={null} { "defaultSearchConfig": { "thirdPartyBan": ["TALX_WORK_NUMBER"], "channels": { "email": true, "voice": true, "fax": false, "preferredChannel": "EMAIL" }, "outbound": { "maxAttemptsPerMethod": 3, "maxTotalAttempts": 8 } }, "searchTypes": [ { "searchType": "EMPLOYMENT", "searchConfig": { "thirdPartyBan": ["TALX_WORK_NUMBER", "TRUEWORK"], "channels": { "email": true, "voice": false, "fax": false, "preferredChannel": "EMAIL" }, "outbound": { "contactHints": [ { "email": "hr@techcorp.com", "priority": "HIGH" } ] } } } ] } ``` For client-specific third-party restrictions, see [Third-party ban](/guides/third-party-ban) for supported vendor codes, multiple-value examples, and deferral behavior. ## Example response ```json theme={null} { "verificationOrderId": "123e4567-e89b-12d3-a456-426614174000", "searchIds": ["456e7890-e89b-12d3-a456-426614174001"] } ``` Next, prefer [webhooks](/webhooks/integration) for completion. To poll results, call [Get order searches](/api-reference/endpoints/get-order-searches) (not [Get order](/api-reference/endpoints/get-order) — that returns order status only, without verification outcomes). ## Error responses | Status | When | | ------ | ----------------------------------------------------------------- | | `400` | Validation failed (invalid field shapes or unsupported values). | | `401` | Missing or invalid Bearer JWT, or JWT missing the `tenant` claim. | ```json theme={null} { "statusCode": 400, "message": ["searchType must be EMPLOYMENT or EDUCATION"], "error": "Bad Request" } ``` ```json theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ## OpenAPI ````yaml POST /background-check/v1/orders openapi: 3.0.0 info: title: SNH AI Background Check API description: >- AI-powered agentic background verification service for employment and education checks. version: '1.0' contact: {} servers: - url: https://sandbox.theary.ai description: Sandbox - url: https://api.theary.ai description: Production - url: http://localhost:3000 description: Local development security: - bearerAuth: [] tags: [] paths: /background-check/v1/orders: post: tags: - Background Check Orders summary: Create single verification order description: Creates a new background check order for verification operationId: create-order parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerificationRequestDto' examples: employment: value: searchTypes: - searchType: EMPLOYMENT externalSearchId: '12345678' questionnaireUrl: https://verify.example.com/form/abc123 questionnaireAccessCode: ACCESS123 searchConfig: channels: email: true voice: false preferredChannel: EMAIL blockedDestinations: - hr-noreply@company.com timing: searchSlaMinutes: 2880 outboundWindowMinutes: 120 businessHours: timezone: America/Chicago startTime: '09:00' endTime: '16:00' allowedDays: - 1 - 2 - 3 - 4 - 5 outbound: maxAttemptsPerMethod: 5 maxTotalAttempts: 12 cancelOutboundOnTerminalInbound: true contactHints: - email: hr@company.com priority: HIGH research: skipResearch: false 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 - 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. businessContext: entityName: Acme Corp 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 employerLocation: San Francisco, CA employerEmail: hr@techcorp.com employerPhone: +1-555-123-4567 startDate: '2020-01-15' endDate: '2023-06-30' responses: '201': description: Order created successfully content: application/json: schema: $ref: '#/components/schemas/CreateOrderResponse' '400': description: Validation failed (invalid field shapes or unsupported values) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid Bearer JWT, or JWT missing the tenant claim content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: VerificationRequestDto: type: object properties: applicant: 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. description: >- Person being verified. Include identity, optional contact details, optional address history, and optional aliases. allOf: - $ref: '#/components/schemas/ApplicantDto' businessContext: example: entityName: Acme Corp appliedJobTitle: Senior Software Engineer worksiteCity: San Francisco worksiteState: CA proposedSalary: 100000 positionLevel: STANDARD securityClearanceRequired: false industrySector: TECHNOLOGY description: >- Hiring context for the role the applicant is applying for (employer, title, worksite, salary). This is not the applicant home address. allOf: - $ref: '#/components/schemas/BusinessContextDto' searchTypes: example: - searchType: EMPLOYMENT externalSearchId: '12345678' questionnaireUrl: https://verify.example.com/form/abc123 questionnaireAccessCode: ACCESS123 searchConfig: channels: email: true voice: false preferredChannel: EMAIL blockedDestinations: - hr-noreply@company.com timing: searchSlaMinutes: 2880 outboundWindowMinutes: 120 businessHours: timezone: America/Chicago startTime: '09:00' endTime: '16:00' allowedDays: - 1 - 2 - 3 - 4 - 5 outbound: maxAttemptsPerMethod: 5 maxTotalAttempts: 12 cancelOutboundOnTerminalInbound: true contactHints: - email: hr@company.com priority: HIGH research: skipResearch: false type: array items: $ref: '#/components/schemas/SearchTypeDto' description: >- Searches to run on this order. Only EMPLOYMENT and EDUCATION are supported. At least one search is recommended. history: example: employment: - employerName: Tech Corp position: Software Engineer employerLocation: San Francisco, CA employerEmail: hr@techcorp.com employerPhone: +1-555-123-4567 startDate: '2020-01-15' endDate: '2023-06-30' description: Employment and/or education records to verify for this order. allOf: - $ref: '#/components/schemas/HistoryDto' webhookConfig: description: >- Optional per-order webhook routing and signing. Takes precedence over organization-level webhook configuration. example: 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 allOf: - $ref: '#/components/schemas/WebhookConfigDto' defaultSearchConfig: description: >- Order-level default search policy applied to every created search that does not set searchTypes[i].searchConfig. When a per-search searchConfig is present (even as {}), it fully replaces this default for that search. example: channels: email: true voice: false preferredChannel: EMAIL blockedDestinations: - hr-noreply@company.com timing: searchSlaMinutes: 2880 outboundWindowMinutes: 120 businessHours: timezone: America/Chicago startTime: '09:00' endTime: '16:00' allowedDays: - 1 - 2 - 3 - 4 - 5 outbound: maxAttemptsPerMethod: 5 maxTotalAttempts: 12 cancelOutboundOnTerminalInbound: true contactHints: - email: hr@company.com priority: HIGH research: skipResearch: false allOf: - $ref: '#/components/schemas/SearchConfigDto' required: - applicant - businessContext - searchTypes title: Verification request CreateOrderResponse: type: object properties: verificationOrderId: type: string format: uuid description: Unique identifier for the created verification order searchIds: type: array items: type: string format: uuid description: Array of search identifiers created for this order required: - verificationOrderId - searchIds title: Create Order Response ErrorResponse: type: object properties: statusCode: type: integer description: HTTP status code example: 400 message: oneOf: - type: string - type: array items: type: string description: Error message or array of validation error messages example: Validation failed error: type: string description: HTTP status text example: Bad Request required: - statusCode - message title: Error Response ApplicantDto: type: object properties: firstName: type: string example: John description: 'Applicant legal first name. Example: "John".' lastName: type: string example: Smith description: 'Applicant legal last name. Example: "Smith".' ssn: type: string example: 123-45-6789 description: >- Social Security Number in XXX-XX-XXXX format. Example: "123-45-6789". birthday: type: string example: '1990-05-15' description: 'Date of birth in YYYY-MM-DD format. Example: "1990-05-15".' phone: type: string example: +1-555-123-4567 description: >- Applicant phone number used for contact during verification. Example: "+1-555-123-4567". email: type: string example: john.smith@example.com description: >- Applicant email address. Must be a valid email when provided. Example: "john.smith@example.com". signedReleaseFileUrl: type: string example: https://example.com/signed-release.pdf description: >- Signed release PDF attached to outbound verification requests. Accepts an HTTPS URL, GCS URI (gs://), or base64-encoded PDF (optionally as a data:application/pdf;base64,... URL). Max 10MB for inline base64. addresses: example: - 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' description: >- Applicant address history (optional for employment/education). When non-empty, exactly one address must be current (endDate null or omitted). type: array items: $ref: '#/components/schemas/AddressDto' applicantAlias: example: - firstName: Jonathan lastName: Smith middleName: Michael suffix: Jr. description: Alternate or former names (AKA) used when screening the applicant. type: array items: $ref: '#/components/schemas/ApplicantAliasDto' required: - firstName - lastName - ssn title: Applicant BusinessContextDto: type: object properties: entityName: type: string example: Acme Corp description: Name of the employer the candidate is applying to appliedJobTitle: type: string example: Senior Software Engineer description: Job title the candidate is applying for worksiteCity: type: string example: San Francisco description: >- City of the candidate's proposed worksite (not the applicant's home city). Example: "San Francisco". worksiteState: type: string example: CA description: >- Two-letter US state code for the candidate's proposed worksite. Example: "CA". proposedSalary: type: number example: 100000 description: 'Candidate''s proposed salary as a positive number. Example: 100000.' positionLevel: type: string example: STANDARD enum: - EXECUTIVE - STANDARD - SENSITIVE description: 'Proposed job level. Allowed values: EXECUTIVE, STANDARD, SENSITIVE.' securityClearanceRequired: type: boolean example: false description: Whether the role requires security clearance. industrySector: type: string example: TECHNOLOGY description: 'Industry sector for regulatory context. Example: "TECHNOLOGY".' required: - entityName - appliedJobTitle - worksiteCity - worksiteState - proposedSalary title: Business context SearchTypeDto: type: object properties: searchType: type: string enum: - EMPLOYMENT - EDUCATION description: >- Type of search to perform. Only EMPLOYMENT and EDUCATION are supported. example: EMPLOYMENT externalSearchId: type: string description: >- External search ID from the client system (e.g., your client search ID) example: '12345678' questionnaireUrl: type: string description: Optional direct link to the online questionnaire for this search example: https://verify.example.com/form/abc123 questionnaireAccessCode: type: string description: Optional access code required for the online questionnaire example: ACCESS123 searchConfig: description: >- Per-search policy overrides applied on top of organization policy. When present (even as an empty object), fully replaces any request-level defaultSearchConfig for this search. allOf: - $ref: '#/components/schemas/SearchConfigDto' required: - searchType title: Search type HistoryDto: type: object properties: employment: example: - employerName: Tech Corp position: Software Engineer employerLocation: San Francisco, CA employerEmail: hr@techcorp.com employerPhone: +1-555-123-4567 startDate: '2020-01-15' endDate: '2023-06-30' description: >- Employment records to verify (employer, position, dates, and optional contact details). type: array items: $ref: '#/components/schemas/EmploymentHistoryDto' education: example: - institutionName: University of California qualification: Bachelor of Science in Computer Science fieldOfStudy: Computer Science institutionLocation: Berkeley, CA startDate: '2014-08-25' endDate: '2018-05-15' graduationDate: '2018-05-15' institutionContactEmail: registrar@berkeley.edu institutionContactPhone: +1-510-642-6000 description: >- Education records to verify (institution, credential, dates, and optional contact details). type: array items: $ref: '#/components/schemas/EducationHistoryDto' title: History WebhookConfigDto: type: object properties: enabled: type: boolean description: Enable/disable webhooks for this verification request default: true example: true secret: type: string description: Secret used for HMAC-SHA256 signature generation example: webhook-secret-for-hmac-validation retryAttempts: type: number description: Number of retry attempts for failed deliveries minimum: 0 maximum: 10 default: 3 example: 3 closeoutEndpoints: description: Map of search type to closeout endpoint URL example: 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 allOf: - $ref: '#/components/schemas/CloseoutEndpointsDto' fallbackEndpoint: description: >- Fallback webhook target(s) when no search type specific endpoint is configured. Supports string URL, object, or array of objects. oneOf: - type: string - $ref: '#/components/schemas/WebhookTargetDto' - type: array items: $ref: '#/components/schemas/WebhookTargetDto' example: - url: https://client.example.com/webhooks/all-events events: - verification.action_required searchTypes: - EMPLOYMENT - EDUCATION title: Webhook config SearchConfigDto: type: object properties: thirdPartyBan: type: array description: >- Canonical third-party vendor codes banned for this search. When research or inbound detects one of these vendors, third-party routing is suppressed and manual/outbound handling continues. items: type: string enum: - TALX_WORK_NUMBER - THOMAS_AND_COMPANY - PRECHECK - VERIFYTODAY - CCCVERIFY - EXPERIAN - QUICKCONFIRM - ACT1 - CERTREE_EMP - DELTAT - DRIVERIQ - EMERALD_HEALTH_SERVICES - EMPINFO - EVADVANTAGE - GROUPONE - TENSTREET - TRUECONFIRM - TRUEWORK - TRUV - VAULT_VERIFY - VERIFENT - VERIFY_FAST - VERIFY_ADVANTAGE - VERISAFE_JOBS - VERIFICATION_MANAGER - JOBTRAX - NEED_MY_TRANSCRIPT - PARCHMENT - SCRIBORDER - AURADATA - CERTREE_EDU - CHICAGO_PUBLIC_SCHOOLS - DIPLOMA_SENDER - GRAMARCY - IEC - INDIANA_ARCHIVES - MERIDIAN_INSTITUTE - OTTAWA_UNIVERSITY - TCSG - VERIF_Y_INC - NSCH channels: description: >- Channel control — enable/disable outbound channels, set preferred channel, block/allow destinations allOf: - $ref: '#/components/schemas/SearchConfigChannelsDto' timing: description: Timing & SLA overrides for this search allOf: - $ref: '#/components/schemas/SearchConfigTimingDto' outbound: description: Fine-grained control over outbound verification attempts allOf: - $ref: '#/components/schemas/SearchConfigOutboundDto' research: description: Control the automated research phase that discovers contacts allOf: - $ref: '#/components/schemas/SearchConfigResearchDto' inbound: description: Control how inbound responses are processed for this search allOf: - $ref: '#/components/schemas/SearchConfigInboundDto' escalation: description: Escalation and reassignment controls allOf: - $ref: '#/components/schemas/SearchConfigEscalationDto' notifications: description: Per-search notification and webhook preferences allOf: - $ref: '#/components/schemas/SearchConfigNotificationsDto' qaDestinations: description: >- Override the tenant-level QA destinations (email/phone/fax) for this search. Non-production only — ignored in production where real contact destinations are used. allOf: - $ref: '#/components/schemas/SearchConfigQaDestinationsDto' title: Search config AddressDto: type: object properties: addressType: type: string example: home description: Type of address (e.g., home, work, mailing) addressLine1: type: string example: 123 Main Street description: Street address line 1 addressLine2: type: string example: Apt 4B description: Street address line 2 (apartment, suite, etc.) addressCity: type: string example: New York description: City addressState: type: string example: NY description: State (2-letter code) addressZipCode: type: string example: '10001' description: ZIP/Postal code addressCountry: type: string example: US description: Country code (2-letter code, defaults to US) startDate: type: string example: '2020-01-15' description: Start of residence in YYYY-MM-DD format. endDate: type: string example: '2023-06-30' description: >- End of residence in YYYY-MM-DD format. Omit or set null for the current address. required: - addressType - addressLine1 - addressCity - addressState - addressZipCode - startDate title: Address ApplicantAliasDto: type: object properties: firstName: type: string example: Jonathan description: First name alias lastName: type: string example: Smith description: Last name alias middleName: type: string example: Michael description: Middle name alias suffix: type: string example: Jr. description: Name suffix (Jr., Sr., III, etc.) required: - firstName - lastName title: Applicant alias EmploymentHistoryDto: type: object properties: employerName: type: string example: Tech Corp description: Name of the employer or company position: type: string example: Software Engineer description: Job title or position held employerLocation: type: string example: San Francisco, CA description: Location where the applicant worked (e.g., "San Francisco, CA") employerEmail: type: string example: hr@techcorp.com description: Employer contact email for employment verification employerPhone: type: string example: +1-555-123-4567 description: Employer contact phone number for employment verification employerFax: type: string example: +1-555-123-4567 description: Employer contact fax number for employment verification startDate: type: string example: '2020-01-15' description: Start date of employment in YYYY-MM-DD format endDate: type: string example: '2023-06-30' description: >- End date of employment in YYYY-MM-DD format. Leave null for current employment. required: - employerName - position title: Employment history EducationHistoryDto: type: object properties: institutionName: type: string example: University of California description: Name of the educational institution qualification: type: string example: Bachelor of Science in Computer Science description: >- Educational qualification or credential earned. Examples: "Bachelor of Science in Computer Science", "High School Diploma", "GED", "Certificate in Web Development", "Associate of Arts" fieldOfStudy: type: string example: Computer Science description: Field of study or major subject area institutionLocation: type: string example: Berkeley, CA description: Location of the educational institution (e.g., "Berkeley, CA") startDate: type: string example: '2014-08-25' description: Start date of attendance in YYYY-MM-DD format endDate: type: string example: '2018-05-15' description: >- End date of attendance in YYYY-MM-DD format. Use for applicants who attended but did not graduate. graduationDate: type: string example: '2018-05-15' description: >- Date of graduation or completion in YYYY-MM-DD format. Optional when the applicant did not graduate. institutionContactEmail: type: string example: registrar@berkeley.edu description: Institution contact email for education verification institutionContactPhone: type: string example: +1-510-642-6000 description: Institution contact phone number for education verification required: - institutionName - qualification - fieldOfStudy title: Education history CloseoutEndpointsDto: type: object properties: EMPLOYMENT: description: >- Employment verification webhooks. Accepts a URL string, a single webhook target object, or an array of targets. oneOf: - type: string - $ref: '#/components/schemas/WebhookTargetDto' - type: array items: $ref: '#/components/schemas/WebhookTargetDto' example: - url: https://client.example.com/webhooks/employment-closeout headers: X-Customer: acme events: - verification.completed EDUCATION: description: >- Education verification webhooks. Accepts a URL string, a single webhook target object, or an array of targets. oneOf: - type: string - $ref: '#/components/schemas/WebhookTargetDto' - type: array items: $ref: '#/components/schemas/WebhookTargetDto' example: - url: https://client.example.com/webhooks/education-closeout basicAuth: username: user password: pass events: - verification.completed - verification.notification title: Closeout endpoints WebhookTargetDto: type: object title: Webhook target required: - url properties: url: type: string description: Webhook URL example: https://client.example.com/webhooks/employment-closeout headers: type: object additionalProperties: type: string description: Custom headers to include in the webhook request example: X-Customer: acme X-Env: staging secret: type: string description: >- Optional per-webhook HMAC secret (overrides global secret if provided) basicAuth: $ref: '#/components/schemas/BasicAuthDto' events: type: array items: type: string description: >- Event types to deliver. Defaults to ["verification.completed"] when omitted. example: - verification.completed - verification.notification - verification.action_required searchTypes: type: array items: type: string enum: - EMPLOYMENT - EDUCATION description: >- Restrict which search types this webhook receives (fallback targets). enabled: type: boolean description: Enable/disable this specific webhook target default: true SearchConfigChannelsDto: type: object properties: email: type: boolean description: Enable/disable email outbound for this search voice: type: boolean description: Enable/disable voice outbound for this search fax: type: boolean description: Enable/disable fax outbound for this search preferredChannel: type: string description: >- Preferred first-attempt channel. Outbound orders channels as [preferred, ...remaining enabled]; it does NOT disable the other enabled channels. Example: { email: true, voice: true, preferredChannel: "EMAIL" } attempts email first, then voice. Has no effect if the preferred channel is disabled in `channels`. enum: - EMAIL - VOICE - FAX blockedDestinations: description: >- Specific contact destinations (emails, phone numbers, fax numbers) to never attempt. Values are normalized before comparison: emails are lowercased; phone/fax are reduced to digits (with a trailing 10-digit match for US numbers). Mutually exclusive with `allowedDestinations`. type: array items: type: string allowedDestinations: description: >- If provided, only these destinations may be contacted. Acts as a whitelist; all others are suppressed. Normalized the same way as `blockedDestinations`. Mutually exclusive with `blockedDestinations`. type: array items: type: string title: Search config channels SearchConfigTimingDto: type: object properties: searchSlaMinutes: type: number description: Maximum minutes before this search should be completed or escalated outboundWindowMinutes: type: number description: >- Minimum minutes between outbound follow-up attempts to the same destination businessHours: description: Custom business hours window for outbound attempts allOf: - $ref: '#/components/schemas/BusinessHoursOverrideDto' title: Search config timing SearchConfigOutboundDto: type: object properties: maxAttemptsPerMethod: type: number description: Max outbound attempts per channel type (email, voice, fax) maxTotalAttempts: type: number description: >- Hard cap on total outbound attempts across all channels for this search. Enforced per-contact: once the number of attempts created for a contact reaches this value, the outbound loop short-circuits before trying additional channels. Applied in addition to (not in place of) `maxAttemptsPerMethod`. cancelOutboundOnTerminalInbound: type: boolean description: >- When a terminal inbound response is received, auto-cancel remaining outbound for this search thirdPartyDeferral: type: boolean description: Defer third-party vendor outbound and try direct channels first thirdPartyDeferralHours: type: number description: Hours to defer third-party if thirdPartyDeferral is enabled contactHints: description: >- Pre-known contacts used to seed the outbound pipeline. When research.skipResearch=true the hints are the sole seed (research agent is never invoked). When research.skipResearch=false the hints are merged on top of researched contacts per history item, deduplicated by normalized destination (email/phone/fax) — duplicates are dropped in favor of the researched contact. Each hint's priority (HIGH/NORMAL/LOW) drives attempt ordering via a canonical confidence mapping (0.99 / 0.95 / 0.90). A hint may instead (or additionally) declare a thirdPartyVendor to seed a known third-party verification service; third-party hints are deduplicated against researched contacts (and one another) by canonical vendor code and thirdPartyCode. type: array items: $ref: '#/components/schemas/ContactHintDto' title: Search config outbound SearchConfigResearchDto: type: object properties: skipResearch: type: boolean description: >- When true, the research worker does not invoke the research agent (no automated research lookups). The contact plan is seeded exclusively from outbound.contactHints (required when this flag is true — validated at order create). Contact methods for tenant-disabled channels are auto-suppressed. title: Search config research SearchConfigInboundDto: type: object properties: autoCompleteOnVerification: type: boolean description: >- Automatically mark the search as COMPLETED when a terminal verification response is received requireManualReview: type: boolean description: >- Hold inbound responses for human review before finalizing — transitions to ACTION_REQUIRED instead of COMPLETED. Do not combine with autoCompleteOnVerification=false; that pair is rejected as an invalid configuration. title: Search config inbound SearchConfigEscalationDto: type: object properties: disableAutoEscalation: type: boolean description: >- Prevent all automatic escalation — the search stays in-progress until the SLA expires or the caller intervenes escalationWebhookUrl: type: string description: Override the escalation webhook URL for this search disableThirdPartyEvent: type: boolean description: >- Suppress the third-party action_required webhook when a third-party vendor is detected. Default behavior (false) emits the 3P event AND cancels remaining outbound — 3P takes precedence. When set to true, the 3P webhook is suppressed AND outbound is NOT cancelled; the workflow falls through to normal outbound on the enabled channels in `preferredChannel` order. Worked example — email-only outbound that keeps running even when a 3P is detected: channels: { email: true, voice: false, fax: false, preferredChannel: "EMAIL" } escalation: { disableThirdPartyEvent: true } Result: if research flags the contact as a third-party vendor, no 3P webhook fires and outbound still attempts email on the resolved contacts in the provided order. title: Search config escalation SearchConfigNotificationsDto: type: object properties: webhookOverride: description: Full webhook config override for this search's events allOf: - $ref: '#/components/schemas/WebhookConfigDto' suppressNotifications: type: boolean description: >- Suppress all verification.notification events (completions and action-required still fire) includeRawInboundInWebhook: type: boolean description: Include the raw inbound document content in webhook payloads title: Search config notifications SearchConfigQaDestinationsDto: type: object properties: email: type: string description: >- Override the QA email destination for this search (non-production only). All outbound emails for the search are redirected here instead of the tenant-level QA inbox. phone: type: string description: >- Override the QA phone destination for this search (non-production only). All outbound voice calls for the search are placed to this number instead of the tenant-level QA number. fax: type: string description: >- Override the QA fax destination for this search (non-production only). All outbound faxes for the search are routed to this number instead of the tenant-level QA fax number. title: Search config qa destinations BasicAuthDto: type: object title: Basic auth required: - username - password properties: username: type: string description: Basic auth username password: type: string description: Basic auth password BusinessHoursOverrideDto: type: object properties: timezone: type: string description: IANA timezone (e.g., "America/New_York") startTime: type: string description: Start of business hours window (e.g., "08:00") endTime: type: string description: End of business hours window (e.g., "17:00") allowedDays: description: Allowed days of the week (0=Sun, 1=Mon, ... 6=Sat) type: array items: type: number title: Business hours override ContactHintDto: type: object properties: name: type: string title: type: string department: type: string email: type: string description: >- Direct contact email. Each hint must include at least one of email/phone/fax OR a thirdPartyVendor. phone: type: string fax: type: string thirdPartyVendor: type: string description: >- Marks this hint as a known third-party verification vendor (e.g. The Work Number, National Student Clearinghouse). Accepts a canonical vendor code, or UNKNOWN when the contact is known to be a third party but the specific vendor cannot be named. When set, the seeded contact is flagged as third-party (usesThirdParty=true) and routed via the third-party path rather than the normal channel pipeline. By default third-party routing takes precedence over direct outbound and cancels remaining attempts; use escalation.disableThirdPartyEvent to fall through to the direct channels instead. A direct email/phone/fax may still be supplied on the same hint as a fallback. Rejected if the same vendor also appears in this search's thirdPartyBan. enum: - TALX_WORK_NUMBER - THOMAS_AND_COMPANY - PRECHECK - VERIFYTODAY - CCCVERIFY - EXPERIAN - QUICKCONFIRM - ACT1 - CERTREE_EMP - DELTAT - DRIVERIQ - EMERALD_HEALTH_SERVICES - EMPINFO - EVADVANTAGE - GROUPONE - TENSTREET - TRUECONFIRM - TRUEWORK - TRUV - VAULT_VERIFY - VERIFENT - VERIFY_FAST - VERIFY_ADVANTAGE - VERISAFE_JOBS - VERIFICATION_MANAGER - JOBTRAX - NEED_MY_TRANSCRIPT - PARCHMENT - SCRIBORDER - AURADATA - CERTREE_EDU - CHICAGO_PUBLIC_SCHOOLS - DIPLOMA_SENDER - GRAMARCY - IEC - INDIANA_ARCHIVES - MERIDIAN_INSTITUTE - OTTAWA_UNIVERSITY - TCSG - VERIF_Y_INC - NSCH - UNKNOWN thirdPartyCode: type: string description: >- Optional employer/account code at the third-party vendor (e.g. a The Work Number employer code). Maps to the seeded contact method's thirdPartyId so downstream routing can address the specific employer record. Requires thirdPartyVendor on the same hint. priority: type: string description: >- Controls attempt ordering by mapping to a canonical confidence score used by the contact prioritizer: HIGH=0.99, NORMAL=0.95, LOW=0.90. Hints outrank typical researched contacts at every tier; within hints, HIGH is tried before NORMAL before LOW. When omitted, NORMAL (0.95) is assumed. enum: - HIGH - NORMAL - LOW title: Contact hint securitySchemes: bearerAuth: scheme: bearer bearerFormat: JWT type: http ````