API Reference Overview
Base request format, required identifiers, and response structure for all Zyntro public APIs
Zyntro exposes a set of public REST APIs that let you interact with your CRM, calendar, forms, email, brand data, and more from external applications. Every API request follows the same foundational pattern: you send a POST request with JSON body containing your authentication credentials and a set of base identifiers that tell Zyntro which organization and brand context to operate in.
This article covers that standard format so you can make your first API call confidently, and understand the response structure you will receive from every endpoint.
Key Concepts
A unique string that authenticates your requests. Found in **Me > API & Webhooks** in the Zyntro dashboard. Every request must include this.
A secret key issued during developer onboarding (prefixed `zdk_`). Required alongside your API key for all v2 public API requests. Your client registers you as a developer and you receive this during the onboarding process.
A UUID that identifies your Zyntro organization. All data — contacts, brands, pipelines — is scoped to an organization.
A numeric identifier for the brand within your organization. Required by most endpoints since Zyntro operations are brand-scoped.
A UUID identifying the team member performing the action. Required by endpoints that create or modify records, so Zyntro can attribute the action to the correct user.
All public API endpoints follow the pattern `https://app.zyntrohq.com/apis/v2/public/{module}/{action}`, where `{module}` groups related endpoints (e.g., `crm`, `calendar`, `email`) and `{action}` is the specific operation.
Capabilities
CRM & Contacts
Create, retrieve, update, and score contacts. Look up contacts by email, move them between pipeline stages, and manage custom fields.
Calendar & Scheduling
Fetch calendars and schedules, check availability, create events, and send meeting invites programmatically.
Email & Communication
Send emails to contacts, trigger broadcast campaigns and sequences, and retrieve email history.
Forms & Data Collection
Retrieve form fields, submit form responses, and collect data from external applications into Zyntro forms.
Brand & Content
Access brand facts, voice definitions, audience segments, wares, testimonials, and published content.
Billing & Subscriptions
Manage customer subscriptions, process payments, and handle billing lifecycle events via the Edge billing APIs.
Base Request Format
{
"api_key": "YOUR_API_KEY",
"developer_secret": "YOUR_DEVELOPER_SECRET",
"org_id": "YOUR_ORGANIZATION_ID",
"brand_id": "YOUR_BRAND_ID",
"member_id": "YOUR_MEMBER_ID"
}How It All Fits Together
The base identifiers establish context for every API operation:
`api_key` — Authenticates the request. Zyntro validates this against your user account and checks that your account is active. If the key is invalid or the account is inactive, the request is rejected before any data is accessed.
`developer_secret` — A second authentication factor issued during developer onboarding. This secret is tied to a specific developer key with an IP whitelist. Requests from non-whitelisted IPs are rejected. The secret is shown once during onboarding — if lost, the key must be revoked and reissued.
`org_id` — Scopes the request to your organization. All CRM data, pipelines, templates, and settings belong to an organization. Zyntro verifies that the API key's owner has access to this organization.
`brand_id` — Scopes the request further to a specific brand. Since brand context affects how SI processes data, which templates are available, and how communications are personalized, most endpoints require this.
`member_id` — Identifies which team member is performing the action. Required by endpoints that create or modify records (e.g., creating a contact, sending an email). Read-only endpoints like fetching brand facts may not require it.
Not every endpoint requires all five identifiers. Read-only brand endpoints may only need `api_key`, `developer_secret`, and `org_id`. Contact creation endpoints need all five. Each endpoint's documentation specifies exactly which identifiers are required.
Example: Fetching a Contact
curl -X POST https://app.zyntrohq.com/apis/v2/public/crm/fetchContact \
-H "Content-Type: application/json" \
-d '{
"api_key": "UYUJH-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXX",
"developer_secret": "zdk_your_developer_secret",
"org_id": "42cc1aca-3aa5-4339-98d2-480b5b89937b",
"brand_id": "1",
"member_id": "f2470c7f-60b1-4491-b117-8ba0e3e2a53b",
"contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}'Success Response
{
"status": "success",
"data": {
"contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"first_name": "Jane",
"last_name": "Smith",
"email": "[email protected]",
"contact_status": "Active"
}
}Error Response
{
"status": "error",
"data": [
"Invalid API Key"
]
}Common Error Messages
| Error Message | Cause | Fix |
|---|---|---|
| Missing developer_secret | The developer_secret field is missing or empty in the request body | Include your developer secret (zdk_XXX) issued during onboarding |
| Invalid developer_secret | The developer secret does not match any active developer key | Verify your developer secret. If lost, have your client revoke and reissue the key |
| IP address not whitelisted | The request came from an IP not in the developer key's allowed list | Contact your client to add your IP address to the key's whitelist |
| Invalid API Key | The api_key value does not match any active user account | Copy the correct API key from Me > API & Webhooks |
| User is not active | The account associated with the API key has been deactivated | Contact your organization admin to reactivate the account |
| Missing service instance | The api_key field is missing or empty in the request body | Include a valid api_key in your JSON body |
| Missing org ID | The org_id field is missing or empty | Include your organization ID from Me > API & Webhooks |
| Missing brand ID | The brand_id field is missing or empty | Include your brand ID from Me > API & Webhooks |
Pre-Flight Checklist
- Copy your API Key from Me > API & Webhooks
- Copy your Developer Secret from the onboarding confirmation (shown once only)
- Copy your Organization ID
- Copy your Brand ID
- Copy your Member ID
- Set Content-Type: application/json header in your HTTP client
- Use POST method (not GET) for all requests
- Send identifiers as JSON in the request body (not URL parameters)
- Verify your IP address is whitelisted on your developer key
