Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vh3.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Email Ingest

Extract structured job fields from emails sent by known FM portals (Verisae, Bellrock, Access Maintain, Greene King, and tenant-specific overrides). Resolves customers, sites, and job types against the knowledge graph, evaluates confidence, and returns a review or auto-create outcome. Use this endpoint when the sender domain is already identified as a portal. For unknown senders, use the general triage ingest path or classify first with POST /triage/classify.

​
POST /ingest/email/portal

Portal ingest — structured extraction from a known FM portal email. Request body:
FieldTypeRequiredDescription
company_idstringYesYour tenant identifier
api_keystringYesYour tenant BigChange API key (verified against company_id)
email_htmlstringYesHTML body of the email
email_textstringNoPlain-text fallback when HTML is sparse
email_subjectstringNoSubject line
email_fromstringNoSender address (used for portal detection)
email_datestringNoSend time (ISO 8601)
attachmentsarrayNoEach item: filename, content_base64, url, mime_type
preferred_type_idsarrayNoJob type IDs to boost during classification (+0.05 when plausible)
Response fields:
FieldTypeDescription
statusstringauto_created, pending_review, or unprocessable
extractionobjectParsed work order fields and confidence
resolutionobjectMatched customers, sites, types, categories, parent_candidates with scores
reasoningstringHuman-readable resolution summary
job_createdbooleanWhether a job was written to BigChange
job_idintegerCreated job ID when job_created is true
extraction_idstringPending-extraction UUID for review-queue flows
review_flagsarrayFlags requiring human attention
job_previewobjectDry-run BigChange payload when write-back is not yet live
case_idstringCase management ID when a review case was created
engineer_hintsarrayRanked engineer suggestions from contact/type history
job_optionsarraySelectable job drafts when status is pending_review
recommended_option_idstringSuggested option from job_options
surfacestringAlways portal for this endpoint
Example: 
curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/ingest/email/portal" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "email_html": "<html><body><table><tr><td>Work Order</td><td>116222840</td></tr></table></body></html>",
    "email_subject": "PureGym 449 Newhaven, Work Order 116222840",
    "email_from": "noreply@verisae.com",
    "email_date": "2026-04-18T10:00:00Z"
  }'
Use cases:
  • FM portal automation: Ingest Verisae, Bellrock, or other portal work orders without manual re-keying.
  • n8n inbound mail: Trigger after POST /triage/classify returns portal_ingest, or when the sender domain is pre-filtered upstream.
  • Review queue: When status is pending_review, use extraction_id with POST /ingest/email/confirm or POST /ingest/email/reject.
  • Quality evaluation: Inspect job_preview and resolution scores before enabling auto-create to BigChange.
Notes:
  • Requires Gemini for extraction; typical latency 3–10s.
  • api_key is verified via apiKeyCheck before any BigChange-facing step; mismatch returns 403.
  • Tenant settings (portal_ingest_enabled, disabled_portals, thresholds) gate behaviour without code changes.