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.
Important: All Zyntro public APIs use the POST method with a JSON request body. There are no GET-based public endpoints. Always set the Content-Type: application/json header.
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"
}Info: You can find all four identifiers in the Zyntro dashboard under Me > API & Webhooks. Each value has a copy button next to it for easy access.
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"
]
}Tip: Always check the status field first. A value of "success" means your request was processed correctly and the data field contains the result. A value of "error" means one or more validation checks failed, and data contains an array of error messages describing what went wrong.
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
Warning: Your API key and developer secret grant access to your client's organization data. Treat them like passwords — do not commit them to public repositories, share them in client-side code, or include them in URLs. Store credentials in a secrets management system and rotate them regularly. If you suspect your credentials have been compromised, notify your client and Zyntro ([email protected]) immediately.
