API Intake

API Intake lets you pipe JSON objects or raw text from any external source into Sayify, and the AI does the rest. Unlike the public Intake Page where humans fill out forms, API Intake is a machine-to-machine webhook endpoint that accepts structured JSON, nested JSON, or plain text payloads, runs AI extraction, and feeds the results into your existing inbox, alerts, and integration pipeline.

Think of it as a universal AI funnel: send JSON or a raw string, get structured CRM data back.

---

Why API Intake?

Most teams have data flowing through dozens of tools — form builders, chat widgets, e‑commerce platforms, helpdesks, CRMs. The data is unstructured, inconsistent, and scattered.

API Intake solves this by giving you a single webhook URL that:

1. Accepts JSON or raw text - No schema requirements. Send a JSON object for structured data, or a plain string for unstructured messages.
2. AI‑extracts structured data — Gemini AI reads the payload and pulls out names, emails, sentiment, urgency, topics, and custom fields.
3. Creates an Inbox case — Every payload becomes a reviewable case with AI summary, sentiment, and priority.
4. Fires alerts & workflows — The same alert rules, workflow engine, and integration pipeline used by form submissions.
5. Delivers results back — Optional callback URL gets the AI extraction results POSTed back to your system.

---

How It Works

Your System Sayify Your Pipeline
────────── ────── ─────────────
 │ │ │
 │ POST /v1/intake/{id}/ │ │
 │ + JSON/raw payload │ │
 │ + Bearer token │ │
 ├─────────────────────────►│ │
 │ │ 202 Accepted (instant) │
 │◄─────────────────────────┤ │
 │ │ │
 │ │ ┌──────────────────────┐ │
 │ │ │ Celery Worker │ │
 │ │ │ │ │
 │ │ │ 1. AI Extraction │ │
 │ │ │ 2. Contact Resolution │ │
 │ │ │ 3. Create InboxCase │ │
 │ │ │ 4. Fire Alerts │ │
 │ │ │ 5. Workflow Rules │ │
 │ │ │ 6. Auto-Actions │ │
 │ │ │ 7. RAG Embedding │ │
 │ │ └──────────┬───────────┘ │
 │ │ │ │
 │ │ ├─► Inbox │
 │ │ ├─► Slack │
 │ │ ├─► Webhook │
 │ │ └─► Destinations │
 │ │ │
 │ POST callback_url │ │
 │ (AI results) │ │
 │◄─────────────────────────┤ │

1. You POST a JSON object or raw string payload to your API Intake endpoint with a Bearer API key.
2. Sayify returns 202 Accepted instantly — no waiting for AI processing.
3. In the background, a Celery worker runs AI extraction, creates an InboxCase, fires alerts, and executes workflow rules.
4. If you provided a callback URL, Sayify POSTs the extraction results back to you.

---

Endpoint Reference

POST /api/v1/intake/{link_uuid}/

Send a JSON object or raw text payload for AI processing. JSON objects are recommended for structured and nested data. Non-object payloads are stored as { "payload": value } before AI extraction.

Authentication: Bearer token (API Key)

curl -X POST https://sayify.pro/api/v1/intake/ea92fd15-7563-447f-a75d-0d61570f4c73/ \
 -H "Authorization: Bearer sk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789xyz" \
 -H "Content-Type: application/json" \
 -d '{
 "name": "Jane Doe",
 "email": "jane@example.com",
 "message": "I'\''d like to learn more about your enterprise plan.",
 "source": "website_chat"
 }'

Headers:

Header	Required	Description
Authorization	Yes	Bearer sk_live_... - Your workspace API key.
Content-Type	Recommended	Use application/json for JSON objects, or text/plain for raw text.
X-Callback-URL	No	Optional URL where Sayify will POST AI extraction results after processing.

Request Body: Any JSON object or raw string. There are no required fields. For nested data, send a normal JSON object; do not stringify nested JSON unless you intentionally want the whole value treated as raw text.

Response (202 Accepted):

{
 "status": "processing",
 "session_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "message": "Payload accepted. AI processing has started.",
 "contact_uuid": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
 "callback_url": "https://your-server.com/webhook/callback"
}

Field	Description
status	Always "processing" - AI work runs asynchronously.
session_uuid	Unique identifier for this intake session. Use it to correlate with inbox cases.
contact_uuid	Returned if Sayify could resolve a contact from the payload (via email or phone).
callback_url	Echoed back if you provided one.

Possible Errors:

Status	Description
401	Missing, empty, or invalid/revoked API key.
404	API Intake endpoint not found or doesn't belong to this workspace.
400	Endpoint is paused, or callback URL is invalid (localhost, private IP, non-HTTP).
429	Rate limit exceeded (60 requests/minute per API key).

---

Callback Delivery

If you provide a callback URL (via the X-Callback-URL header or a callback_url field in the body), Sayify will POST the AI extraction results back to you after processing.

Callback Payload

{
 "event": "intake.processed",
 "session_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "case_uuid": "11223344-5566-7788-99aa-bbccddeeff00",
 "processed_at": "2026-04-20T10:30:15.123456Z",
 "contact": {
 "uuid": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
 "email": "jane@example.com",
 "first_name": "Jane",
 "last_name": "Doe",
 "company": ""
 },
 "extraction": {
 "ai_summary": "Enterprise plan inquiry from Jane Doe via website chat.",
 "sentiment": "positive",
 "urgency_score": 3,
 "category": "sales_inquiry",
 "extracted_data": {
 "full_name": "Jane Doe",
 "email": "jane@example.com",
 "lead_intent": "ready_to_buy",
 "lead_temperature": "warm",
 "budget_range": "enterprise",
 "recommended_action": "reply",
 "recommended_team": "sales",
 "action_required": true,
 "confidence_score": 92
 },
 "use_case_metrics": {}
 }
}

Callback Headers

Header	Description
Content-Type	application/json
User-Agent	Sayify-Webhook/1.0
X-Sayify-Signature	HMAC‑SHA256 signature for verification (sha256=...).
X-Sayify-Event	intake.processed
X-Sayify-Delivery-Id	Unique delivery identifier for idempotency.

Retry Policy

Callbacks are delivered with exponential backoff:

Attempt	Delay	Timeout
1st	Immediate	10s connect, 30s read
2nd	5 seconds	10s connect, 30s read
3rd	15 seconds	10s connect, 30s read

After 3 failed attempts, the callback is abandoned. Your data is never lost — it's safely stored in the Sayify inbox regardless of callback success.

---

Extraction Presets

When you create an API Intake endpoint, you choose an extraction preset that tells the AI what kind of data to expect and what signals to extract. Each preset includes:

• Extraction schema — The fields the AI should look for (with types, descriptions, and examples).
• Identity hints — Dot‑notation paths to find email, phone, and name fields in nested payloads.
• Sample payload — A reference example for testing.

Available Presets

Preset	Best For	Key AI Signals
Auto‑detect	Any payload — AI figures it out	urgency_level, action_required, recommended_action, recommended_team, detected_preset_type
Lead / Form Data	Typeform, Gravity Forms, HubSpot, contact forms	lead_temperature, buyer_stage, budget_range, qualification_status, timeline_urgency
Chat Transcript	Intercom, Zendesk Chat, Drift, LiveChat	conversation_intent, resolution_status, customer_frustration, escalation_needed, risk_detected
E‑commerce Event	Shopify, WooCommerce, Stripe	fraud_risk, customer_type, fulfillment_priority, high_value_order, refund_risk
Support Ticket	Freshdesk, HelpScout, Jira Service Desk	issue_category, issue_severity, priority_level, sla_risk, likely_bug_report

Tip: Presets guide the AI — they never constrain it. Even with a preset selected, the AI will still detect and extract additional useful fields beyond what the schema specifies.

Common Extracted Signals (All Presets)

Every preset includes these baseline intelligence signals:

Signal	Type	Description
summary	text	Concise human‑readable summary of the payload.
urgency_level	enum	low, medium, high, critical, unknown
action_required	boolean	Does this payload demand human follow‑up?
confidence_score	number	AI confidence in the extraction (0–100).
recommended_action	enum	reply, escalate, monitor, close, none
recommended_team	enum	sales, support, ops, engineering, unknown

---

Identity Resolution

Sayify automatically scans your payload for contact identity fields — email addresses, phone numbers, and names — to resolve or create a CRM contact.

How It Works

1. Identity hints — The preset defines dot‑notation paths to check first (e.g. customer.email, ticket.requester.email).
2. Fallback scan — If hints miss, Sayify scans common top‑level keys: email, phone, first_name, last_name, name, company.
3. Contact resolution — If an email or phone is found, Sayify resolves it against your workspace contacts. Existing contacts are enriched; new contacts are created.

Supported Identity Fields

Path Searched	Detected As
email, e_mail, email_address, user_email, customer_email	Email
phone, phone_number, mobile, tel, telephone	Phone
first_name, firstname, fname	First Name
last_name, lastname, lname	Last Name
name, full_name, customer_name	Full Name (auto‑split)
company, company_name, organization, org	Company

For nested payloads, use dot‑notation in your preset's identity_hints — e.g. customer.email will walk into { "customer": { "email": "..." } }.

---

Security

SSRF Protection

Callback URLs are validated against internal/private IP ranges. The following are blocked:

• localhost, 127.0.0.0/8, 0.0.0.0/8
• Private ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
• Link‑local: 169.254.0.0/16, fe80::/10
• IPv6 loopback: ::1/128, fc00::/7

Only http:// and https:// schemes are accepted.

Rate Limiting

API Intake is rate‑limited to 60 requests per minute per API key. Exceeding this returns 429 Too Many Requests.

API Key Security

• Keys are hashed in the database — the plain‑text key is only shown once at creation.
• Keys are workspace‑scoped — a key from Workspace A cannot access Workspace B endpoints.
• Revoked keys are rejected immediately.

---

Use Cases

1. Typeform → Sayify AI Triage

Scenario: You collect leads through Typeform but want AI‑powered lead scoring and routing.

How:

1. Create an API Intake endpoint with the Lead / Form Data preset.
2. In Typeform, add a webhook pointing to your Sayify intake URL.
3. Every Typeform submission is automatically analysed by AI — scoring lead temperature, buyer stage, and qualification status.
4. Set up alert rules to notify your sales team on Slack when a hot lead comes in.

// Typeform sends this:
{
 "form_id": "abc123",
 "answers": [
 { "field": { "ref": "name" }, "text": "Marcus Chen" },
 { "field": { "ref": "email" }, "email": "marcus@acme.io" },
 { "field": { "ref": "budget" }, "text": "$5k-10k/year" },
 { "field": { "ref": "timeline" }, "text": "This quarter" }
 ]
}

// Sayify AI extracts:
{
 "full_name": "Marcus Chen",
 "email": "marcus@acme.io",
 "lead_temperature": "hot",
 "budget_range": "high",
 "timeline_urgency": "this_quarter",
 "buyer_stage": "decision",
 "qualification_status": "qualified",
 "recommended_action": "reply",
 "recommended_team": "sales"
}

---

2. Intercom Chat Export → Support Intelligence

Scenario: Your support team uses Intercom. You want to automatically detect escalation‑worthy conversations, frustrated customers, and unresolved issues.

How:

1. Create an API Intake endpoint with the Chat Transcript preset.
2. Use Intercom's webhook or Zapier to forward closed conversations to your intake URL.
3. AI evaluates each transcript for frustration level, resolution status, and escalation needs.
4. Configure alert rules for urgent_detected and negative_sentiment to auto‑escalate.

// Intercom sends this:
{
 "conversation_id": "conv_8x92ka",
 "customer": { "name": "Sarah Kim", "email": "sarah@startup.co" },
 "agent": { "name": "Alex R." },
 "messages": [
 { "role": "customer", "text": "I can't export my reports as PDF" },
 { "role": "agent", "text": "I can help with that. Which report?" },
 { "role": "customer", "text": "The monthly analytics report. It just shows a blank page." }
 ],
 "status": "resolved",
 "tags": ["pdf", "export", "bug"]
}

// Sayify AI extracts:
{
 "customer_name": "Sarah Kim",
 "customer_email": "sarah@startup.co",
 "conversation_intent": "support",
 "issue_resolved": true,
 "likely_bug_report": true,
 "customer_frustration": "medium",
 "recommended_team": "engineering",
 "recommended_action": "escalate"
}

---

3. Shopify Order Webhook → Fraud & VIP Detection

Scenario: You want to automatically flag high‑value orders, potential fraud, and VIP customers from your Shopify store.

How:

1. Create an API Intake endpoint with the E‑commerce Event preset.
2. Configure Shopify's webhook to send orders/create events to your intake URL.
3. AI analyses each order for fraud risk, customer type, and fulfillment priority.
4. High‑risk orders trigger alerts; VIP orders get auto‑tagged for white‑glove treatment.

// Shopify sends this:
{
 "id": "ord_4521",
 "email": "buyer@example.com",
 "customer": { "first_name": "Jamie", "last_name": "Park" },
 "total_price": "1499.99",
 "currency": "USD",
 "line_items": [
 { "title": "Pro Studio Kit", "quantity": 1, "price": "1299.99" },
 { "title": "Premium Warranty", "quantity": 1, "price": "200.00" }
 ],
 "financial_status": "paid",
 "shipping_address": { "country": "US", "city": "Austin" }
}

// Sayify AI extracts:
{
 "order_id": "ord_4521",
 "customer_email": "buyer@example.com",
 "customer_name": "Jamie Park",
 "total_amount": 1499.99,
 "high_value_order": true,
 "customer_type": "first_time",
 "fraud_risk": "low",
 "fulfillment_priority": "expedited",
 "recommended_action": "fulfill"
}

---

4. Freshdesk Ticket → SLA‑Aware Triage

Scenario: Your helpdesk receives tickets from multiple channels. You want AI to classify severity, detect bugs, and route to the right support tier.

How:

1. Create an API Intake endpoint with the Support Ticket preset.
2. Connect Freshdesk via automation rule or Zapier to forward new tickets.
3. AI classifies each ticket by category, severity, and priority level.
4. SLA‑risk tickets are auto‑escalated; bug reports are routed to engineering.

// Freshdesk sends this:
{
 "ticket": {
 "id": "TKT-2847",
 "subject": "Voice recording not saving on mobile Safari",
 "description": "When I try to record on iPhone Safari, nothing saves. Tried clearing cache.",
 "priority": "high",
 "requester": { "name": "David Liu", "email": "david@bigcorp.com" },
 "tags": ["mobile", "safari", "recording", "bug"]
 }
}

// Sayify AI extracts:
{
 "ticket_id": "TKT-2847",
 "subject": "Voice recording not saving on mobile Safari",
 "requester_email": "david@bigcorp.com",
 "issue_category": "bug",
 "issue_severity": "major",
 "priority_level": "high",
 "likely_bug_report": true,
 "escalation_needed": true,
 "sla_risk": true,
 "customer_emotion": "neutral",
 "recommended_team": "engineering",
 "recommended_action": "escalate"
}

---

5. Custom App → Real‑Time AI Pipeline with Callback

Scenario: Your internal app generates events (user signups, feature usage, churn signals). You want AI analysis returned to your app for real‑time decisioning.

How:

1. Create an API Intake endpoint with the Auto‑detect preset.
2. POST your event data with an X-Callback-URL header.
3. Sayify processes the payload and POSTs AI results back to your callback URL.
4. Your app receives structured intelligence without building any ML pipeline.

curl -X POST https://sayify.pro/api/v1/intake/{link_uuid}/ \
 -H "Authorization: Bearer sk_live_..." \
 -H "Content-Type: application/json" \
 -H "X-Callback-URL: https://your-app.com/api/sayify-callback" \
 -d '{
 "event": "user_signup",
 "user": {
 "name": "Alex Rivera",
 "email": "alex@startup.io",
 "plan": "enterprise",
 "team_size": 50,
 "referred_by": "g2_review"
 },
 "metadata": {
 "ip_country": "US",
 "signup_source": "demo_request"
 }
 }'

Your callback URL receives the full AI extraction:

{
 "event": "intake.processed",
 "session_uuid": "...",
 "case_uuid": "...",
 "extraction": {
 "ai_summary": "Enterprise signup from Alex Rivera (50-person team) via G2 review referral.",
 "urgency_score": 7,
 "extracted_data": {
 "lead_temperature": "hot",
 "recommended_action": "reply",
 "recommended_team": "sales",
 "action_required": true
 }
 }
}

---

Setting Up API Intake

Step 1: Create an API Intake Endpoint

1. Navigate to Forms in the sidebar.
2. Click + Create API Intake (or switch to the API Intake tab).
3. Choose an extraction preset (Auto‑detect, Lead, Chat, E‑commerce, or Support Ticket).
4. Give it a name and configure alert rules.
5. Save — you'll receive the endpoint UUID.

Step 2: Get Your API Key

1. Go to API Management in the sidebar.
2. Click + Create API Key.
3. Copy the key — it's only shown once.

Step 3: Send Your First Payload

curl -X POST https://sayify.pro/api/v1/intake/{link_uuid}/ \
 -H "Authorization: Bearer sk_live_..." \
 -H "Content-Type: application/json" \
 -d '{"name": "Test User", "email": "test@example.com", "message": "Hello!"}'

Step 4: Check Your Inbox

Open the Inbox to see the AI‑processed case with extracted data, sentiment analysis, and suggested actions.

Step 5: Test from the Builder (Optional)

You can also send test payloads directly from the builder UI without needing your API key. Use the built‑in Test button with a sample payload.

---

What Happens After Ingestion

Once a payload is accepted, Sayify's async processing pipeline executes 10 steps:

Step	What Happens
1. AI Extraction	Gemini AI analyses the payload using the configured extraction schema.
2. InboxCase Creation	A new case is created with AI summary, sentiment, urgency score, and extracted data.
3. Extraction Trust Layer	Confidence scores are evaluated; low‑confidence fields are flagged for review.
4. Priority Escalation	Cases with urgency ≥ 8 or priority_level: high are auto‑promoted to high priority.
5. Activity Logging	A case.created event is logged for audit trail and timeline.
6. Contact Enrichment	The resolved contact is enriched with AI‑extracted data (company, name, etc.).
7. Contact Lifecycle	Lifecycle triggers fire (e.g. automation sequences).
8. Alert Rules	Configured alert rules are evaluated — every_submission, urgent_detected, negative_sentiment, keyword_risk.
9. Workflow Rules	The workflow rule engine evaluates and executes any matching automation rules.
10. RAG Embedding	The case is embedded for semantic search and AI‑powered querying.

---

FAQ

What JSON formats are supported?
Any valid JSON object is supported, including nested objects, arrays, and mixed types. The AI handles deeply nested structures (e.g. ticket.requester.email). For structured data, send JSON normally instead of converting the object into a string.

What if my payload isn't JSON?
If the body isn't parseable as JSON, Sayify wraps the raw text in a { "payload": "..." } object and processes it anyway.

Is there a payload size limit?
Payloads are truncated to 8,000 characters for AI processing. The full original payload is stored in the session record.

Can I use the same API key for forms and API Intake?
Yes. API keys are workspace‑scoped and work for both the Forms API and API Intake endpoints.

What's the difference between API Intake and Webhooks?

• API Intake = data coming in to Sayify from external systems.
• Webhooks = data going out from Sayify to your systems when events happen.

They work great together: ingest data via API Intake, then use webhooks to push processed results to your downstream tools.

Can I see API Intake cases in the regular Inbox?
Yes. API Intake cases appear in the same inbox as form submissions. They're tagged with source api_intake so you can filter them.

---

What's Next?

• API Authentication — How to create and manage API keys.
• Inbox — Review and manage AI‑processed cases from all sources.
• Alerts — Configure automatic notifications based on AI signals.
• Destinations — Route extracted data to external CRMs and tools.
• Webhooks — Send outbound event notifications from Sayify.
• API Endpoints — Full API reference for forms and responses.