Introvy × Avionté — Technical Integration Docs

01 / overview

Company Overview

Introvy Solutions Inc is a candidate workflow and preparation platform built for staffing firms. Introvy automates the post-screening candidate experience — turning Avionté pipeline events into structured, AI-powered workflows that improve candidate readiness, submission quality, and recruiter efficiency.

Company

Introvy Solutions Inc

Headquarters

New Lenox, IL / Chicago, IL

Technical Contact

Brad Beiermann, CTO — brad@introvy.ai

Setup Contact

Tony Barczak, CEO — hello@introvy.ai

Support

support@introvy.ai

Avionté Contact

Jordan Cox — Jordan.Cox@avionte.com

02 / product

Product Overview

Introvy integrates with Avionté BOLD Front Office via webhook events. When a recruiter moves a candidate in Avionté, Introvy fires the appropriate candidate workflow, enriches the event through the Avionté API, and writes completion results back to the Avionté Talent record.

Avionté remains the system of record throughout. All Introvy output is written back as structured Talent Activity notes.

This integration requires an API subscription. Please reach out to your Avionté account manager to review eligibility.

Supported Workflows

Workflow	Trigger	Candidate Deliverable	Shareable?
Video Submission	Pipelined	Structured video responses + AI summary	✓ Yes
Research Brief	Online / Onsite / Pre-screen Interview Scheduled	AI-generated company and role prep brief	Internal only
Practice Audio	Online / Onsite / Pre-screen Interview Scheduled	5-question audio rehearsal with AI feedback	Internal only
Practice Video	Online / Onsite / Pre-screen Interview Scheduled	2-question video rehearsal with AI coaching	Internal only
Thank You	Selected, Pre-screen Interview Completed, AI Interview Completed	Candidate follow-up message	✓ Yes

Stage names listed above reflect Introvy's default certified mapping based on stages validated in the Avionté sandbox. Complete stage-to-workflow mapping is documented in Section 4. Customer-specific stages may be confirmed and mapped during onboarding.

03 / architecture

Integration Diagram

Avionté BOLD Front Office ↓ Webhook POST — job_pipeline_talent_added / job_pipeline_talent_updated ↓ Payload: { EventName, FrontOfficeTenantId, Resource: { PipelineId, CorrelationId } } Introvy Webhook Receiver — https://api.introvy.ai/api/webhooks/avionte ↓ Validate X-Payload-Signature header ↓ Resolve org by FrontOfficeTenantId → organization_ats_config.field_mappings ↓ Deduplicate by CorrelationId (unique index on agent_jobs) ↓ Return HTTP 200 immediately — async processing begins agent_jobs Queue — Supabase Postgres ↓ Background worker polls queue Introvy MCP Worker — Render ↓ POST /front-office/v1/pipeline/multi-query → talentId, jobId, stage, recruiter ↓ GET /front-office/v1/talent/{talentId} → candidate name, email ↓ GET /front-office/v1/job/{jobId} → job title, company, description ↓ GET /front-office/v1/user/{userId} → recruiter email ↓ Stage router maps pipelineStage → apply_video / interview_prep / thank_you Introvy Workflow Engine ↓ AI generates role-specific questions from job description ↓ Recruiter review email sent → recruiter approves ↓ Candidate receives workflow link by email ↓ Candidate records responses → AI processes transcript Write-back → Avionté Talent Activity ↓ POST /front-office/v1/talent/{talentId}/activity ↓ Notes: workflow label, candidate name, role/company, AI summary, review URL, timestamp ↓ Retried if AI transcript not yet ready — eventually consistent

04 / api grid

API Call Grid

All outbound calls use OAuth2 client credentials (grant_type=client_credentials). Bearer tokens are cached in memory with a 2-minute expiry buffer and refreshed automatically. All requests include Tenant, x-api-key, Authorization, and RequestId headers.

Direction	Method	Endpoint	Purpose	Key Fields	Write?
Avionté → Introvy	POST	/api/webhooks/avionte	Receive pipeline event, trigger workflow	EventName, FrontOfficeTenantId, Resource, CorrelationId	No
Introvy → Avionté	POST	/authorize/token	OAuth2 client credentials — bearer token (1h TTL)	client_id, client_secret, scope	No
Introvy → Avionté	POST	/front-office/v1/pipeline/multi-query	Enrich pipeline event: get talentId, jobId, stage, recruiter	[PipelineId]	No
Introvy → Avionté	GET	/front-office/v1/talent/{id}	Fetch candidate name and email for workflow delivery	firstName, lastName, emailAddress	No
Introvy → Avionté	GET	/front-office/v1/job/{id}	Fetch job title, company, description for AI questions	title, companyName, description	No
Introvy → Avionté	GET	/front-office/v1/user/{id}	Fetch recruiter email to route review notifications	userId, emailAddress	No
Introvy → Avionté	GET	/front-office/v1/talent/activity-types	Discover valid activity typeIds. Defaults to typeId 7 "Note"	typeId, name	No
Introvy → Avionté	POST	/front-office/v1/talent/{id}/activity	Write workflow completion note to candidate Talent record	activityDate, talentId, notes, typeId, userId, name	YES

05 / fields

Field Transfer Matrix

Sensitive talent fields are stripped at the Avionté API client before any data is used or stored: taxIdNumber, birthday, race, disability, veteranStatus, addresses, bankAccount, salary, resume. All write-back notes are redacted for secrets before transmission.

Field	Source	Destination	Purpose	Stored?
EventName	Avionté webhook	Router	Filter actionable events	No
FrontOfficeTenantId	Avionté webhook	Org lookup	Multi-tenant routing	No
CorrelationId	Avionté webhook	agent_jobs.event_id	Deduplication	Yes
PipelineId	Avionté Resource	Pipeline API call	Lookup pipeline context	Temp
pipelineStage	Avionté pipeline API	Stage router	Map to workflow action	No
talentId	Avionté pipeline API	Introvy task	Candidate lookup + write-back target	Yes
firstName, lastName	Avionté talent API	Workflow engine	Candidate name in emails and notes	Yes
emailAddress	Avionté talent API	Workflow delivery	Send workflow link to candidate	Yes
jobId	Avionté pipeline API	Introvy task	Job context for questions and notes	Yes
job title, company	Avionté job API	AI question gen	Personalize questions and write-back notes	Yes
job description	Avionté job API	AI question gen	Generate role-specific questions only — not stored	No
recruiter email	Avionté user API	Review notification	Route recruiter approval email	Yes
Workflow review URL	Introvy	Avionté talent activity	Write completion link back to Avionté	Yes
AI summary	Introvy AI	Avionté talent activity	Write candidate response summary to Avionté	Yes

06 / webhook

Webhook Architecture

Production Endpoint

POST https://api.introvy.ai/api/webhooks/avionte

// Required headers sent by Avionté:
Content-Type:        application/json
X-Payload-Signature: {shared_secret}  // validated by Introvy — required

// Payload structure:
{
  "EventName":           "job_pipeline_talent_added",
  "FrontOfficeTenantId": 2446,
  "CorrelationId":       "fdf15e02-b9bd-4c4f-8af3-35f5afc6ed7e",
  "Resource":            "{\"PipelineId\": 86621900, \"CorrelationId\": \"...\"}"
}

// Responses (always immediate — processing is async):
HTTP 200  { "ok": true, "inserted": true, "job_id": "uuid" }
HTTP 200  { "ok": true, "inserted": false, "note": "duplicate" }
HTTP 200  { "ok": true, "inserted": false, "note": "event_ignored" }
HTTP 401  { "error": "unauthorized" }  // invalid or missing signature

Supported Events

Event	Fires When	Actionable?
job_pipeline_talent_added	Candidate added to job pipeline	Yes
job_pipeline_talent_updated	Candidate pipeline stage changes	Yes
All other event types	Any other Avionté event	Ignored — 200

Deduplication

Every event carries a CorrelationId stored as agent_jobs.event_id with a unique partial index. Duplicate events — including Avionté retries — return {"inserted": false, "note": "duplicate"} without queuing a second job. Avionté retries up to 4 times; all retries are handled safely.

Unknown Stage Handling

The webhook handler does not know the pipeline stage at receive time. The stage name (pipelineStage) is only available after the worker calls POST /front-office/v1/pipeline/multi-query. Stage routing and unknown stage dropping happens in the worker, not the webhook. Unknown stages are logged with provider, raw stage string, and normalized form, then silently dropped — never retried. The webhook queues all events that pass event-name and org-resolution checks; the stage router is the gate in the async worker.

07 / write-back

Write-back Architecture

After workflow completion, Introvy posts a structured Talent Activity note to the candidate's Avionté record using POST /front-office/v1/talent/{talentId}/activity.

Activity Note Payload

{
  "activityDate": "2026-06-01T13:13:00Z",
  "talentId":     223481876,
  "typeId":       7,          // "Note" — auto-discovered from /talent/activity-types
  "userId":       121449556,  // pipelinedUser from pipeline API — recruiter attribution
  "name":         "Introvy Video Submission",
  "notes":        "[Introvy] Video Submission completed\nReview at: https://www.introvy.ai/submission/{token}\nSummary: {AI summary}\nCompleted: 2026-06-01T13:13:00Z"
}

Write-back Timing & Retry

The AI transcript summary is generated asynchronously after candidate submission — typically 30–120 seconds. If a write-back is attempted before AI processing completes, Introvy returns retry: true and defers. The write-back retries automatically until the full summary is available.

Redaction

All notes are scanned and redacted before transmission. Patterns stripped: SSNs, bearer tokens, API keys, subscription keys, client secrets, passwords, bank routing numbers, account numbers, and detected secret strings.

08 / security

Security Overview

Shared Secret Validation

Introvy validates X-Payload-Signature on every inbound request
Timing-safe comparison — prevents timing attacks
Required for certified integration environments
Unauthorized requests return 401 immediately

OAuth2 Authentication

All Avionté API calls use client credentials flow
Bearer tokens cached with 2-minute expiry buffer
Tokens never logged in full — first 8 chars only
Credentials stored as env vars — never in source code

Multi-Tenant Isolation

Every org routed by FrontOfficeTenantId
Row-level security at database layer (Supabase)
Multiple tenant matches → fail closed, event dropped
No cross-org data access possible

Data Protection

Sensitive talent fields stripped at API client level
Write-back notes redacted for secrets
PII retained only as required for workflow execution
All data in transit over HTTPS / TLS

Async Processing

Webhook returns HTTP 200 in under 100ms
All processing async via agent_jobs queue
Avionté never blocked waiting on Introvy
Avionté source IP: 52.200.5.50

Credential Handling

API credentials via secure SharePoint only — never email
Sandbox credentials rotated before production cert
Secrets never appear in public documentation
Shared secret provided to Jordan via separate secure channel

09 / routing

Multi-Tenant Routing

Introvy uses a single shared webhook URL for all Avionté customers. Routing is based on FrontOfficeTenantId matched against each customer's config row.

Routing Logic

Webhook arrives with FrontOfficeTenantId in payload
Query organization_ats_config WHERE ats_provider='avionte' AND is_active=true
Match FrontOfficeTenantId against field_mappings.avionte_tenant_id
   (aliases: front_office_tenant_id, tenant_id also accepted)
Zero matches  → drop event, 200, log: no_org
One match     → route to org_id, process event
Many matches  → fail closed, drop event, log: ambiguous_tenant

Customer Config SQL

INSERT INTO organization_ats_config (org_id, ats_provider, is_active, field_mappings)
VALUES (
  '[ORG_UUID]',
  'avionte',
  true,
  '{"avionte_tenant_id": "[FRONT_OFFICE_TENANT_ID]"}'
);

Each mutual customer must have this row created before their webhooks will route. AVIONTE_DEFAULT_ORG_ID is blocked in production — sandbox/local fallback only.

10 / certification

Certification Testing

Production Callback URL

URL:    https://api.introvy.ai/api/webhooks/avionte
Events: job_pipeline_talent_added, job_pipeline_talent_updated
Auth:   X-Payload-Signature header — shared secret via secure channel only

Credentials used during sandbox testing must be rotated before production certification. Do not include real credentials in shared documents or emails. The shared secret must be provided to Jordan via a secure channel separate from this documentation.

Placeholder values below are intentionally omitted from documentation. All credential values are provided separately via secure channel (SharePoint or direct secure call). Placeholders enclosed in [ ] indicate values that must be supplied through that channel.

Existing Automated Test Suite

Test File	Location	Run Command
test_avionte_client.py	introvy-mcp-server/tests/	pytest tests/test_avionte_client.py -v
test_avionte_writeback.py	introvy-mcp-server/tests/	pytest tests/test_avionte_writeback.py -v
test_avionte_webhook.js	introvy-mcp-server/tests/	node tests/test_avionte_webhook.js

11 / errors

Error Handling

Scenario	Behavior	Response
Invalid or missing X-Payload-Signature	Rejected immediately	401 Unauthorized
Non-actionable event type	Silently ignored, not queued	200 {note: "event_ignored"}
Duplicate CorrelationId	Dropped without queuing	200 {note: "duplicate"}
Unknown FrontOfficeTenantId	Dropped, logged as no_org	200 {note: "no_org"}
Multiple orgs match tenant	Fail closed, event dropped	200 {note: "ambiguous_tenant"}
Missing PipelineId in Resource	Dropped, logged	200 {note: "no_pipeline_id"}
Avionté API 404 on talent/job	Workflow attempted with available data	N/A — internal
Write-back 400 from Avionté	Logged, soft-fail — workflow send unaffected	N/A — internal
AI transcript not ready	Write-back deferred and retried until ready	N/A — internal

12 / support

Support Process

Avionté Support Channel

All issues via Zendesk at support.avionte.com. CC Jordan Cox and Jason Smith on all integration tickets.

Introvy Support

Operational: support@introvy.ai
Escalation: hello@introvy.ai

New Customer Setup

Customer submits consent ticket at support.avionte.com. Credentials via secure SharePoint. Introvy provisions org config within 1 business day.

Stage Mapping Updates

Custom stage aliases added within 1 business day. Contact hello@introvy.ai with stage name and intended workflow.

13 / marketplace

Marketplace Notes

Item	Detail
Integration type	Avionté+ Certified Integration — BOLD Front Office API
Effective date	June 1, 2026
Required subscription	Avionté API subscription required. Contact Avionté account manager to review.
UI changes in Avionté	None required — integration uses existing webhook and API model
Customer consent	Each customer must submit data-sharing consent ticket at support.avionte.com
Stage mapping	Configurable per tenant without code changes
Multi-tenant	Supported — shared endpoint, FrontOfficeTenantId routing
Avionté Branding	Certified Integration badge to be displayed per Avionté Branding Guide

Avionté Integration Docs