Overview

The Contextualize Data API is Zyntro's AI-powered data ingestion endpoint. It accepts raw, unstructured contact data in any format — JSON, CSV, plain text, pasted email threads, business card scans, lead form dumps — and uses a high-reasoning AI model to intelligently map, infer, and structure it into a fully contextualized Zyntro CRM contact.

The API handles the entire pipeline: field mapping, entity detection, custom field population, pipeline stage assignment, note extraction, communication history parsing, profile generation, contact creation, and webhook dispatch.

How It Works

The Processing Pipeline

1. Authentication — Validates your API key and establishes your user database connection
2. Wallet Check — Looks up the current processing cost from the credit_pricing table and verifies sufficient balance
3. Context Gathering — Fetches your brand manifest, CRM field schema (including all custom fields), pipeline stages, and regional defaults
4. AI Processing — Sends the raw data along with your full CRM context to Claude Opus, which returns structured contact data, entity data, notes, communication history, and a profile synopsis
5. Field Mapping — Maps AI output to exact database column names using the field map, populates standard fields and custom fields for both contacts and entities
6. Contact Creation — Creates the contact (and entity for B2B) via upsert mode — existing contacts matched by email are updated, not duplicated
7. Data Insertion — Saves extracted notes, communication history entries, and AI-generated profile data
8. Webhook Dispatch — Fires any registered new_contact webhooks with the created contact details

What the AI Does

• B2B vs B2C Detection — Automatically infers whether the contact is business or consumer based on email domains, company names, and contextual signals
• Entity Creation — For B2B contacts, creates the company entity with name, label, location, website, tags, and entity custom fields
• Custom Field Population — Fills in your brand's custom fields by drawing inference from the raw data, even when those fields aren't explicitly present in the source
• Pipeline Stage Assignment — Assigns the most appropriate pipeline stage based on engagement signals, communication history, and contact status indicators
• Note Extraction — Parses HTML notes into structured entries with dates, authors, and clean content
• Communication History — Extracts messages and conversations with sentiment analysis and actionable insights
• Profile Generation — Produces a contact synopsis including pain points, motivations, emotional drivers, and relationship state
• Phone Formatting — Normalizes phone numbers to E.164 format with inferred country codes
• Timezone Inference — Infers IANA timezone from city and country data

Request

Endpoint: https://app.zyntrohq.com/apis/public/crm/contextualizeData.php

Method: POST

Content-Type: application/json

Request Fields

Sample Request

{
  "api_key": "your_zyntro_api_key",
  "org_id": "your-org-uuid",
  "brand_id": 1,
  "member_id": "your-member-uuid",
  "raw_data": {
    "name": "Jane Smith",
    "email": "[email protected]",
    "phone": "+1 555-123-4567",
    "company": "Acme Corp",
    "title": "VP of Marketing",
    "city": "San Francisco",
    "notes": "Met at SaaStr 2025. Interested in AI content automation. Currently using HubSpot but unhappy with reporting. Budget cycle starts Q3."
  },
  "source": "Conference Lead - SaaStr 2025",
  "instructions": "B2B SaaS leads from a conference. Treat all contacts as warm leads.",
  "enrich": 0
}

Raw Data Format Examples

The raw_data field is deliberately format-agnostic. Here are examples of what you can send:

JSON Object (structured):

{
  "raw_data": {
    "name": "Dan Bradman",
    "email": "[email protected]",
    "company": "Brad Investments",
    "title": "Head of Real Estate",
    "city": "Nottingham",
    "country": "United Kingdom"
  }
}

Plain Text (unstructured):

{
  "raw_data": "Met Dan at the property expo. He runs real estate at Brad Investments in Nottingham. Email is [email protected]. Interested in our AI content tools for property listings. Said to follow up in Q3."
}

CSV Row:

{
  "raw_data": "Dan Bradman,[email protected],Brad Investments,Head of Real Estate,Nottingham,UK"
}

Email Thread:

{
  "raw_data": "From: Dan Bradman <[email protected]>\nTo: [email protected]\nSubject: Re: AI Marketing Tools\n\nHi, I saw your demo at the expo. We're a property investment firm in Nottingham and I'd like to learn more about your content automation features. Can we schedule a call next week?\n\nBest,\nDan Bradman\nHead of Real Estate, Brad Investments"
}

Response

Success Response

{
  "status": "success",
  "data": {
    "contact_id": "4a8fd116-*************-6fd0f6cc7c32",
    "entity_id": "09f1edc1-***-***-***-f94cf5f05271",
    "action": "created",
    "client_type": "B2B",
    "notes_saved": 0,
    "comms_saved": 7,
    "profiles_saved": 1,
    "cost": 0.80,
    "reasoning": "AI explanation of how the data was interpreted, what inferences were drawn, and any assumptions made."
  },
  "message": "Contact contextualized and created successfully"
}

Response Fields

Error Responses

// Missing required fields
{"status": "error", "message": "api_key is required, raw_data is required"}

// Invalid API key
{"status": "error", "message": "Invalid or inactive API key"}

// Insufficient balance
{"status": "error", "message": "Insufficient wallet balance. Required: $0.80"}

// AI processing failure
{"status": "error", "message": "LLM processing failed: [error details]"}

// Contact creation failure
{"status": "error", "message": "Contact creation failed: [error details]"}

What Gets Created

Contact Record

All standard CRM fields are populated where data is available or inferable:

• Name, email, phone (E.164 formatted), address fields
• Country and country code (ISO 2-letter)
• Timezone (IANA format, inferred from location if not provided)
• Pipeline stage (assigned based on engagement signals)
• Source attribution
• All brand-specific custom fields the AI can infer values for

Entity Record (B2B only)

When the AI detects a B2B contact, it automatically creates a company entity with:

• Entity name, label, location, website (inferred from email domain)
• Tags relevant to the business
• Entity custom fields

Notes

Any notes found in the raw data are parsed into structured entries with date, author, and clean text content.

Communication History

Email threads, messages, and conversation data are extracted as communication history entries with sentiment analysis and actionable insights.

Contact Profile

The AI generates a profile synopsis including:

• Summary of who the contact is
• Identified pain points
• Key motivations and emotional drivers
• Current state of the relationship

Webhooks

After successful processing, the API fires all registered webhooks for the new_contact event. The webhook payload includes:

{
  "event": "new_contact",
  "data": {
    "contact_id": "uuid",
    "entity_id": "uuid or null",
    "contact_name": "Full Name",
    "contact_email": "[email protected]",
    "source": "contextualizeData",
    "data_source": "Your source label",
    "action": "created",
    "client_type": "B2B"
  }
}

Pricing

Each call to this API is charged from your organization's wallet. The rate is configured in the credit_pricing table under crp_name = data_contextualizer. The wallet balance is checked before processing — if insufficient, the request is rejected with no charge.

Best Practices

• Send everything you have. The AI is built for messy, incomplete data. More raw context means better inference — don't pre-clean or pre-filter.
• Use descriptive sources. The source field feeds into attribution reporting. "Conference Lead - SaaStr 2025" is far more useful than "Manual".
• Leverage the instructions field. Tell the AI what it can't see — industry context, lead temperature, data quality caveats, or special handling rules.
• Trust the upsert. If a contact with the same primary email already exists, it will be updated rather than duplicated. You don't need to check for duplicates first.
• Custom fields are automatic. The AI maps to your brand's custom fields by inference. The more custom fields you've defined with clear labels and hints, the better the AI fills them.
• Review the reasoning. The reasoning field in the response explains every inference and assumption the AI made — use it to verify accuracy and improve your instructions for future calls.

Business Use Cases