> ## 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 Batch Order > Create multiple verification orders in one request (not a persisted batch) # Create Batch Orders Batch create submits multiple orders in one request. Each order is independent — persist every returned `verificationOrderId` and track work with individual order endpoints. Submits an array of verification requests. The server creates each order in parallel and returns a synthetic `batchId` plus per-order results. This is **not** an atomic transaction: if the request fails after some orders succeed, you may have **partial creates**. Persist each returned `verificationOrderId` / `searchIds` and reconcile. If **any** order throws during validation or creation, the whole request fails. ## Request Non-empty array of objects with the **same shape** as [Create order](/api-reference/endpoints/create-order) (`applicant`, `businessContext`, `searchTypes`, optional `history`, `webhookConfig`, `defaultSearchConfig`, etc.). ## Response `true` when all orders in the batch were created without error Client-facing id generated for this request (**not** stored server-side for later GET list/batch) Count of orders returned in `orders` Array of per-order results (same shapes as single create) ## Example Request Each element in `orders` must match [Verification request](/api-reference/schemas/verification-request). Minimal employment-oriented example (two orders): ```bash cURL theme={null} curl -sS -X POST "https://sandbox.theary.ai/background-check/v1/batches" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "orders": [ { "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 } ] }, "businessContext": { "entityName": "Acme Corp", "appliedJobTitle": "Senior Software Engineer", "worksiteCity": "San Francisco", "worksiteState": "CA", "proposedSalary": 100000, "positionLevel": "STANDARD", "securityClearanceRequired": false, "industrySector": "TECHNOLOGY" }, "searchTypes": [{ "searchType": "EMPLOYMENT" }], "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" } ] } }, { "applicant": { "firstName": "Jane", "lastName": "Doe", "ssn": "987-65-4321", "birthday": "1992-08-20", "phone": "+1-555-987-6543", "email": "jane.doe@example.com", "signedReleaseFileUrl": "https://example.com/signed-release-2.pdf", "addresses": [ { "addressType": "home", "addressLine1": "100 Market St", "addressLine2": null, "addressCity": "San Francisco", "addressState": "CA", "addressZipCode": "94105", "addressCountry": "US", "startDate": "2020-06-01", "endDate": null } ] }, "businessContext": { "entityName": "Acme Corp", "appliedJobTitle": "Engineer", "worksiteCity": "Austin", "worksiteState": "TX", "proposedSalary": 120000, "positionLevel": "STANDARD", "securityClearanceRequired": false, "industrySector": "TECHNOLOGY" }, "searchTypes": [{ "searchType": "EMPLOYMENT" }], "history": { "employment": [ { "employerName": "Acme Corp", "position": "Engineer", "employerLocation": "Austin, TX", "startDate": "2019-01-01", "endDate": "2023-01-01" } ] }, "webhookConfig": { "enabled": true, "secret": "your-webhook-secret-key", "retryAttempts": 3, "closeoutEndpoints": { "EMPLOYMENT": [ { "url": "https://your-app.com/webhooks/employment", "events": ["verification.completed"] } ] }, "fallbackEndpoint": [ { "url": "https://your-app.com/webhooks/all-events", "events": ["verification.action_required"] } ] } } ] }' ``` ## Example Response ```json theme={null} { "success": true, "batchId": "batch_1642789123_abc123def", "ordersCreated": 2, "orders": [ { "verificationOrderId": "123e4567-e89b-12d3-a456-426614174000", "searchIds": ["456e7890-e89b-12d3-a456-426614174001"] }, { "verificationOrderId": "789e4567-e89b-12d3-a456-426614174002", "searchIds": ["012e7890-e89b-12d3-a456-426614174003"] } ] } ``` ## Error responses | Status | When | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `orders` array is empty (at least one order is required). | | `400` | Any single order fails validation (same rules as [Create order](/api-reference/endpoints/create-order)). | | `401` | Missing or invalid Bearer JWT, or JWT missing the `tenant` claim. | | `500` | A mid-flight failure while creating orders in parallel. Because orders are created concurrently (see the non-atomic behavior noted above), a failure partway through can surface as a `500` after some orders have already been created — reconcile using the persisted per-order results before retrying. | ```json theme={null} { "statusCode": 400, "message": ["Batch must contain at least one order"], "error": "Bad Request" } ``` ```json theme={null} { "statusCode": 401, "message": "Unauthorized" } ``` ## Notes * There is no batch list/get/delete API — track and cancel work with [List orders](/api-reference/endpoints/list-orders), [Get order](/api-reference/endpoints/get-order), and [Delete order](/api-reference/endpoints/delete-order). * For webhook shapes see [WebhookConfig](/api-reference/schemas/webhook-config) and [WebhookTarget](/api-reference/schemas/webhook-target). ## OpenAPI ````yaml POST /background-check/v1/batches 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/batches: post: tags: - Background Check Batches summary: Create batch of verification orders description: Creates multiple verification orders in a single batch operation operationId: create-batch parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchRequestDto' examples: batch: value: orders: - 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' - 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: >- Batch created. Each order returns a verificationOrderId and searchIds. If one order fails validation, the whole request fails. content: application/json: schema: type: object properties: batchId: type: string description: Request correlation ID for the batch orders: type: array items: $ref: '#/components/schemas/CreateOrderResponse' '400': description: Validation failed for one or more orders in the batch content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid Bearer JWT content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: BatchRequestDto: type: object properties: orders: description: Array of verification orders to process in batch example: - {} type: array items: $ref: '#/components/schemas/VerificationRequestDto' required: - orders title: Batch 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 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 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 ````