Contextualize Data
AI-powered data interpretation that turns raw input into structured CRM records
Accepts raw, unstructured data in any format — JSON, CSV, plain text, or mixed — and uses AI to interpret it, map it to your CRM fields, and create or update a contact record. The AI also extracts notes, communication history, and profile data from the input. This is a paid endpoint that charges credits from your wallet.
Requires a valid `api_key` and `developer_secret` in the JSON request body. Requests must originate from a whitelisted IP address.
Warning:
This endpoint consumes credits from your Zyntro wallet. Each call is charged based on the `data_contextualizer` pricing tier. Ensure your wallet has sufficient balance before calling. You can check your balance via the dashboard under **Me > Wallet**.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
api_key |
body | string |
Yes | Your Zyntro API key |
developer_secret |
body | string |
Yes | Your developer secret (zdk_XXX). Issued during developer onboarding. |
org_id |
body | string |
Yes | Your organization UUID |
brand_id |
body | integer |
Yes | Your brand ID. The AI uses your brand context to make smarter mapping decisions. |
member_id |
body | string |
Yes | The member UUID performing the action |
raw_data |
body | mixed |
Yes | The unstructured data to process. Can be a JSON object, JSON array, CSV string, plain text, or any mix. The AI will interpret whatever you send. |
source |
body | string |
No | Where this data came from (e.g., "Business Card Scan", "Email Signature", "LinkedIn Export"). Default: `External API` |
instructions |
body | string |
No | Additional instructions for the AI about how to interpret the data. For example: "This is a business card — the first line is the name, the company is on the second line." |
enrich |
body | integer |
No | Set to `1` to trigger enrichment after the contact is created. Default: `0` |
help |
body | boolean |
No | Set to `true` to receive full usage documentation instead of processing data. |
Request Body
Content-Type: application/json
Example
json
{
"org_id": "YOUR_ORG_ID",
"source": "Conference Notes",
"api_key": "YOUR_API_KEY",
"brand_id": 1,
"raw_data": "Met Jane Smith at the SaaS Connect conference. She is VP of Marketing at Acme Corp (acme.com). Email: [email protected], Phone: 555-0123. Interested in our enterprise plan for their 200-person team. Currently using HubSpot but frustrated with reporting limitations. Wants a demo next week.",
"member_id": "YOUR_MEMBER_ID",
"instructions": "Extract the contact, their company, and any buying signals as notes.",
"developer_secret": "YOUR_DEVELOPER_SECRET"
}Code Samples
bash
curl -X POST https://app.zyntrohq.com/apis/v2/public/crm/contextualizeData \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"developer_secret": "YOUR_DEVELOPER_SECRET",
"org_id": "YOUR_ORG_ID",
"brand_id": 1,
"member_id": "YOUR_MEMBER_ID",
"raw_data": "Jane Smith, VP Marketing, Acme Corp, [email protected], 555-0123",
"source": "Business Card"
}'
Tip:
The `raw_data` field is intentionally flexible. You can paste in an email signature, a business card scan, a CSV row, a JSON blob from another API, meeting notes, or even a paragraph of free-form text. The AI maps whatever it finds to your CRM fields, custom fields, and brand context.
Response
200
Data contextualized and contact created/updated
json
{
"data": {
"cost": 0.8,
"action": "created",
"entity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"reasoning": "Identified a B2B contact from conference notes. Mapped name, email, phone, company, role, and company size. Extracted buying intent (interest in enterprise plan, currently using competitor) as a note. Stored LinkedIn and technology stack data as profile enrichment.",
"contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"client_type": "B2B",
"comms_saved": 0,
"notes_saved": 1,
"profiles_saved": 1
},
"status": "success",
"message": "Contact contextualized and created successfully"
}
200
Insufficient balance
json
{
"data": [
"Insufficient wallet balance. Required: $0.80"
],
"status": "error"
}Errors
| Code | Message | Resolution |
|---|---|---|
INVALID_JSON |
Invalid JSON input The request body is not valid JSON. |
Ensure your request body is properly formatted JSON. Send `{"help": true}` for usage docs. |
MISSING_FIELDS |
api_key / org_id / brand_id / member_id / raw_data is required A required field is missing. |
Include all required fields. |
INVALID_API_KEY |
Invalid or inactive API key The API key is not valid or the account is inactive. |
Verify your API key. |
IP_NOT_WHITELISTED |
IP address not whitelisted The request originated from an IP not in the key's allowed list. |
Contact your client to add your IP to the developer key whitelist. |
INVALID_DEVELOPER_SECRET |
Invalid developer_secret The developer secret does not match any active key. |
Verify your developer secret. If lost, have your client revoke and reissue the key. |
MISSING_DEVELOPER_SECRET |
Missing developer_secret The `developer_secret` field is missing or empty. |
Include your developer secret in the request body. This is issued during developer onboarding. |
INSUFFICIENT_BALANCE |
Insufficient wallet balance. Required: $X.XX Your wallet does not have enough credits. |
Add funds via **Me > Wallet** in the dashboard. |
LLM_FAILURE |
LLM processing failed The AI could not process the data. |
Check the raw_data format and try again. Add `instructions` to help the AI interpret ambiguous data. |
CONTACT_CREATION_FAILED |
Contact creation failed The AI interpreted the data but the contact could not be created. |
Check the error details — usually a validation issue with the mapped fields. |
