Submit Inbound Notification

curl --request POST \
  --url https://sandbox.theary.com/background-check/v1/inbound/notifications \
  --header 'Content-Type: application/json' \
  --data '
{
  "messageId": "<string>",
  "threadId": "<string>",
  "messageData": {
    "id": "<string>",
    "threadId": "<string>",
    "from": "<string>",
    "to": "<string>",
    "timestamp": "<string>",
    "subject": "<string>",
    "body": {},
    "attachments": [
      {}
    ]
  },
  "channel": "<string>",
  "metadata": {}
}
'

{
  "messageId": "msg_001",
  "success": false,
  "failureReasons": ["Search not found for reference number"],
  "metadata": {
    "errorCode": "SEARCH_NOT_FOUND"
  },
  "processedAt": "2024-01-15T10:30:00.000Z"
}

POST

background-check

inbound

notifications

Submit Inbound Notification

curl --request POST \
  --url https://sandbox.theary.com/background-check/v1/inbound/notifications \
  --header 'Content-Type: application/json' \
  --data '
{
  "messageId": "<string>",
  "threadId": "<string>",
  "messageData": {
    "id": "<string>",
    "threadId": "<string>",
    "from": "<string>",
    "to": "<string>",
    "timestamp": "<string>",
    "subject": "<string>",
    "body": {},
    "attachments": [
      {}
    ]
  },
  "channel": "<string>",
  "metadata": {}
}
'

{
  "messageId": "msg_001",
  "success": false,
  "failureReasons": ["Search not found for reference number"],
  "metadata": {
    "errorCode": "SEARCH_NOT_FOUND"
  },
  "processedAt": "2024-01-15T10:30:00.000Z"
}

Submit Inbound Notification

Use this endpoint to submit verification responses from external parties. The system processes responses through various channels (email, forms, fax, and generic JSON) and automatically extracts verification details using AI.

Authentication

Bearer Token Required - Include your JWT token in the Authorization header.

Quick Example

curl -X POST "https://sandbox.theary.com/background-check/v1/inbound/notifications" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "msg_001",
    "threadId": "thread_001",
    "channel": "EMAIL",
    "messageData": {
      "id": "msg_001",
      "threadId": "thread_001",
      "from": "hr@company.com",
      "to": "verifications@theary.com",
      "subject": "Employment Verification - John Doe",
      "body": {
        "text": "John Doe worked here from 2020-01-15 to 2023-12-31 as Software Engineer."
      },
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
  }'

Request Parameters

Optional Fields

messageId

string

Unique identifier for this message. If not provided, the system will auto-generate one using the format msg_<timestamp>_<random>. You can also provide it in messageData.id - the system will use the top-level messageId if present, otherwise messageData.id, otherwise auto-generate.

threadId

string

Thread identifier to link related messages. If not provided, the system will use the messageId as the threadId. You can also provide it in messageData.threadId - the system will use the top-level threadId if present, otherwise messageData.threadId, otherwise use the messageId.

messageData

object

required

Message content and metadata

Show properties

string

Message ID (optional - will be auto-generated if not provided and matches top-level messageId)

threadId

string

Thread ID (optional - will be auto-generated if not provided and matches top-level threadId)

from

string

Sender email address. Required for non-JSON channels; optional for JSON channel requests.

string

Recipient email address (e.g., verifications@theary.com). Required for non-JSON channels; optional for JSON channel requests.

timestamp

string

required

ISO 8601 timestamp (e.g., 2024-01-15T10:30:00.000Z)

subject

string

Email subject line

body

object

Message content with text and/or html fields

attachments

array

File attachments (PDFs are supported and will be processed for text extraction). Each attachment should have: - id (string) - Unique attachment identifier - name (string) - Attachment filename - contentType (string) - MIME type (e.g., “application/pdf”) - size (number) - File size in bytes - content (string, optional) - Base64-encoded file content (required for PDF processing)

Optional Fields

channel

string

Communication channel (defaults to STANDARD)
Available Values: EMAIL, EFORM, MICROSOFT_GRAPH, FAX_WEBHOOK, TICKETING, JITBIT, JSON
Channel Types:

EMAIL - Email responses
EFORM - Electronic forms
MICROSOFT_GRAPH - Office 365
FAX_WEBHOOK - Fax responses
TICKETING / JITBIT - Ticketing systems
JSON - Generic structured JSON payloads from upstream systems

metadata

object

Additional context data

Attachments

Attachments are supported for PDF files. PDFs are automatically processed to extract text content, which is then used during message classification and verification data extraction. Supported Format:

PDF files (application/pdf) - Fully supported with text extraction
Other file types may be included but will not be processed

Attachment Processing:

PDFs are processed using document extraction tools
Extracted text is included in the message analysis
Processing errors are logged but do not block message processing

Response

messageId

string

Echo of the submitted message ID

success

boolean

Whether processing succeeded

classification

object

AI-powered message classification
Fields:

type - Classification type (see Classification Types below)
confidence - Score from 0 to 1 indicating classification confidence
- reasoning - Explanation of the classification decision

failureReasons

array

Error messages if failed (empty array if successful)

metadata

object

Processing details including searchId and outcome

processedAt

string

Processing completion timestamp (ISO 8601 format)

Classification Types

The classification type field can be one of the following values: Terminal Outcomes (workflow completes):

VERIFICATION - Verification confirmed with details
NO_RECORD - No employment/education record found
THIRD_PARTY - Response indicates use of third-party vendor
WRONG_ORG - Wrong organization was contacted

Non-Terminal Outcomes (workflow continues):

INFO_REQUESTED - Employer/school needs more information
INSUFFICIENT - Response incomplete or insufficient
RECEIVED - Response received but not yet fully processed
INFO_PROVIDED - Information was provided but may need follow-up

Other Outcomes:

INFO_REQUEST - General information request
AUTHORIZATION_FORM_REQUEST - Authorization form is needed
UNKNOWN - Could not determine intent
OTHER - Other classification
NEXT_CONTACT - Indicates next contact should be made

Examples

Employment Verification

curl -X POST "https://sandbox.theary.com/background-check/v1/inbound/notifications" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "emp_001",
    "threadId": "thread_abc",
    "channel": "EMAIL",
    "messageData": {
      "id": "emp_001",
      "threadId": "thread_abc",
      "from": "hr@techcorp.com",
      "to": "verifications@theary.com",
      "subject": "Re: Employment Verification - John Doe",
      "body": {
        "text": "Reference: 11111111\n\nJohn Doe was employed as Software Engineer from 2020-01-15 to 2023-12-31. Employee ID: EMP001."
      },
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
  }'

Success Response:

{
  "messageId": "emp_001",
  "success": true,
  "classification": {
    "type": "VERIFICATION",
    "confidence": 0.95,
    "reasoning": "Message contains employment verification details with dates and employee ID"
  },
  "metadata": {
    "searchId": "search_456e7890",
    "outcome": "verified"
  },
  "processedAt": "2024-01-15T10:30:05.000Z"
}

Education Form Submission

curl -X POST "https://sandbox.theary.com/background-check/v1/inbound/notifications" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "edu_001",
    "threadId": "thread_xyz",
    "channel": "EFORM",
    "messageData": {
      "id": "edu_001",
      "threadId": "thread_xyz",
      "from": "registrar@university.edu",
      "to": "verifications@theary.com",
      "subject": "Education Verification - Jane Smith",
      "body": {
        "text": "Reference: 22222222\n\nStudent: Jane Smith\nDegree: BS in Computer Science\nGraduation: 2019-05-15\nGPA: 3.8\nTranscript attached separately via email."
      },
      "timestamp": "2024-01-15T11:45:00.000Z"
    },
    "metadata": {
      "formType": "education_verification"
    }
  }'

Success Response:

{
  "messageId": "edu_001",
  "success": true,
  "classification": {
    "type": "VERIFICATION",
    "confidence": 0.95,
    "reasoning": "Electronic form with structured education verification data"
  },
  "metadata": {
    "searchId": "search_789e0123",
    "outcome": "verified"
  },
  "processedAt": "2024-01-15T11:45:03.000Z"
}

Generic JSON Submission

Use channel: "JSON" when an upstream system sends structured third-party verification data instead of an email, fax, or ticket transcript. Place the provider payload in messageData.data. messageId, threadId, messageData.from, and messageData.to are optional for JSON requests; when IDs are omitted, Theary generates them automatically. JSON payloads may contain the full employment or education history returned by the provider. When multiple records are present, Theary includes the matched search’s applicant and submitted history context in extraction so the most relevant record can be identified, extracted, and compared to the submitted applicant data.

curl -X POST "https://sandbox.theary.com/background-check/v1/inbound/notifications" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "JSON",
    "messageData": {
      "data": {
        "employmentData": [
          {
            "employer": {
              "name": "SNH AI"
            },
            "employee": {
              "firstName": "John",
              "lastName": "Smith",
              "positionTitle": "Senior Software Developer",
              "mostRecentHireDate": "2022-01-01",
              "terminationDate": "2023-01-01"
            }
          }
        ]
      },
      "timestamp": "2024-01-15T12:00:00.000Z"
    },
    "metadata": {
      "provider": "test-provider",
      "searchRefId": "EXT-DEV-1779382063270-2"
    }
  }'

Success Response:

{
  "messageId": "msg_1705320000000_abc123xyz",
  "success": true,
  "classification": {
    "type": "VERIFICATION",
    "confidence": 0.95,
    "reasoning": "Structured JSON payload contains employment verification details"
  },
  "metadata": {
    "searchId": "search_456e7890",
    "outcome": "verified"
  },
  "processedAt": "2024-01-15T12:00:03.000Z"
}

Auto-Generated IDs

When messageId or threadId are not provided, the system automatically generates them:

curl -X POST "https://sandbox.theary.com/background-check/v1/inbound/notifications" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "EMAIL",
    "messageData": {
      "from": "hr@company.com",
      "to": "verifications@theary.com",
      "subject": "Employment Verification - John Doe",
      "body": {
        "text": "Reference: 11111111\n\nJohn Doe worked here from 2020-01-15 to 2023-12-31 as Software Engineer."
      },
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
  }'

Error Responses

{
  "messageId": "msg_001",
  "success": false,
  "failureReasons": ["Search not found for reference number"],
  "metadata": {
    "errorCode": "SEARCH_NOT_FOUND"
  },
  "processedAt": "2024-01-15T10:30:00.000Z"
}

{
  "statusCode": 401,
  "message": "Unauthorized"
}

{
  "statusCode": 422,
  "message": [
    "messageId should not be empty",
    "messageData.from must be a valid email address",
    "messageData.timestamp must be a valid ISO 8601 date"
  ],
  "error": "Unprocessable Entity"
}

How It Works

The inbound notification processing follows these steps:

Submit - You send verification response via API
ID Generation - If messageId or threadId are not provided, they are auto-generated
Validate - System validates required fields, checks for malicious content, and extracts reference numbers
Match - Links message to active verification search by matching reference numbers in the message content
Process Attachments - PDF attachments are processed to extract text content (if present)
Analyze Contact - Determines sender type (APPLICANT, ENTITY, or UNKNOWN)
Classify & Extract - AI-powered classification extracts verification details:
- Uses OpenAI Assistant or LangChain LLM depending on configuration
- Extracts structured outcome (VERIFIED, NO_RECORD, THIRD_PARTY, INFO_REQUESTED, etc.)
- Parses verification data (dates, positions, confirmation status)
Persist Results - Saves processing results, classification, and extracted data
Update Search - Updates search status if terminal outcome (VERIFIED, NO_RECORD, THIRD_PARTY, WRONG_ORG)
Schedule Follow-up - If non-terminal outcome (INFO_REQUESTED, INSUFFICIENT), schedules next outbound attempt
Notify - Sends webhook if verification reaches terminal state

Common Use Cases

Use Case	Channel	Best For
Email from HR	`EMAIL`	Employment verification responses
University form	`EFORM`	Education verification with transcripts
Fax response	`FAX_WEBHOOK`	Legacy systems, healthcare, legal
Office 365	`MICROSOFT_GRAPH`	Enterprise email automation
Help desk	`TICKETING`	Support ticket workflows
Generic JSON	`JSON`	Structured third-party provider payloads

Best Practices

Message IDs:

Use unique identifiers (UUIDs recommended) if available
Never reuse message IDs
Optional: Omit the field entirely if you don’t have one - the system will auto-generate it
If provided, ensure it’s unique across all messages

Thread IDs:

Keep consistent for related messages in the same conversation thread
Helps track conversation history across multiple exchanges
Optional: Omit the field entirely if you don’t have one - the system will use the messageId as the threadId
Use the same threadId for all messages in the same conversation

Timestamps:

Always use ISO 8601 format
Example: 2024-01-15T10:30:00.000Z

Content:

Include all verification details in the body.text field
For JSON channel requests, include the structured provider payload in messageData.data
Include reference number: The message must contain a 7-8 digit reference number to match the message to the correct verification search. The system looks for patterns like:
- “Reference: 12345678”
- “Ref. 12345678”
- “Ticket # 12345678”
- “Case # 12345678”
- Or standalone 7-8 digit numbers
Mention attachments sent via separate channels if needed

Error Handling:

Check success field in response
Process failureReasons array for errors
Implement retry with exponential backoff for server errors

Troubleshooting

“Search not found”

Verify the message contains a valid 7-8 digit reference number in one of the supported formats:
- “Reference: 12345678”
- “Ref. 12345678”
- “Ticket # 12345678”
- “Case # 12345678”
- Or a standalone 7-8 digit number
Ensure the reference number matches an active verification search
Ensure search is still active (not completed or cancelled)
Check that the search has the INBOUND objective enabled
Check sender email matches expected contact (if applicable)

“Invalid message format”

All required fields must be present
Check timestamp is valid ISO 8601
Ensure email addresses are valid

“Validation error”

Review error messages in response
Verify data types match requirements
Ensure all required fields are present

Next Steps

Delete Batch Generate Upload URL

​Submit Inbound Notification

​Authentication

​Quick Example

​Request Parameters

​Optional Fields

​Optional Fields

​Attachments

​Response

​Classification Types

​Examples

​Employment Verification

​Education Form Submission

​Generic JSON Submission

​Auto-Generated IDs

​Error Responses

​How It Works

​Common Use Cases

​Best Practices

​Troubleshooting

​Next Steps

Submit Inbound Notification

Authentication

Quick Example

Request Parameters

Optional Fields

Optional Fields

Attachments

Response

Classification Types

Examples

Employment Verification

Education Form Submission

Generic JSON Submission

Auto-Generated IDs

Error Responses

How It Works

Common Use Cases

Best Practices

Troubleshooting

Next Steps