Submit Inbound Notification

Use this endpoint to submit verification responses from external parties. The system processes responses through various channels (email, forms, fax) 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://api.theary.ai/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": "[email protected]",
      "to": "[email protected]",
      "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

required

Sender email address

string

required

Recipient email address (e.g., [email protected])

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
Channel Types:

EMAIL - Email responses
EFORM - Electronic forms
MICROSOFT_GRAPH - Office 365
FAX_WEBHOOK - Fax responses
TICKETING / JITBIT - Ticketing 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://api.theary.ai/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": "[email protected]",
      "to": "[email protected]",
      "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://api.theary.ai/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": "[email protected]",
      "to": "[email protected]",
      "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"
}

Auto-Generated IDs

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

curl -X POST "https://api.theary.ai/background-check/v1/inbound/notifications" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "EMAIL",
    "messageData": {
      "from": "[email protected]",
      "to": "[email protected]",
      "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

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
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

API Reference

Service API

Orders API

Batches API

Inbound API

Files API

Webhooks

Schemas

Submit Inbound Notification

Submit Inbound Notification

Authentication

Quick Example

Request Parameters

Optional Fields

Optional Fields

Attachments

Response

Classification Types

Examples

Employment Verification

Education Form Submission

Auto-Generated IDs

Error Responses

How It Works

Common Use Cases

Best Practices

Troubleshooting

Next Steps

API Reference

Service API

Orders API

Batches API

Inbound API

Files API

Webhooks

Schemas

​Submit Inbound Notification

​Authentication

​Quick Example

​Request Parameters

​Optional Fields

​Optional Fields

​Attachments

​Response

​Classification Types

​Examples

​Employment Verification

​Education Form 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

Auto-Generated IDs

Error Responses

How It Works

Common Use Cases

Best Practices

Troubleshooting

Next Steps