canonical: https://jentic.com/apis/contlo.com/contlo

# Contlo API

Jentic publishes the only available OpenAPI specification for Contlo API, keeping it validated and agent-ready. The Contlo marketing API ingests customer profile updates and behavioural events for AI-driven marketing campaigns, and exposes integration endpoints used by the Contlo Zapier connector to read subscribers and customers. Authentication uses an X-API-KEY header issued from the Contlo workspace.

## For AI agents

Identify customer profiles and track behavioural events into Contlo for AI-driven marketing, plus read subscribers and customers via the Zapier-integration endpoints.

## Scope

Does not handle email or SMS sending, campaign authoring, or ad management - use for customer identify, event tracking, and subscriber/customer reads only.

## Capabilities

- Identify a customer profile by sending traits to `/v1/identify`
- Track a behavioural event for a customer with `/v1/track`
- Authenticate the Zapier integration on behalf of a workspace via `/api/integrations/zapier`
- Read the list of subscribers exposed to the Zapier integration
- Read the list of customers exposed to the Zapier integration

## Use cases

### Behavioural Event Capture

Direct-to-consumer brands use POST `/v1/track` to capture behavioural events such as product views, add-to-cart, and purchases, which Contlo then uses to power AI-segmented marketing campaigns. Events carry a user identifier and an event payload, so downstream Contlo flows can react in near real time. Integration takes hours rather than days because the track endpoint accepts simple JSON.

Example prompt: POST `/v1/track` with user_id, event='order_placed', and properties including order_id and total_amount, then verify the event arrives in Contlo's event stream

### Customer Profile Sync

POST `/v1/identify` pushes a known customer's traits - name, email, location, lifecycle stage - into Contlo so that segments and AI-personalised campaigns target the right person. Identify calls upsert profiles, so syncing from a CRM or e-commerce backend is idempotent. Combined with track, identify gives Contlo a unified view of who the user is and what they did.

Example prompt: POST `/v1/identify` with user_id, email, traits including first_name and lifecycle_stage='active' for each row in a daily customer export

### Zapier-Backed Data Export

When a Contlo customer needs to export subscribers or customers without writing a backend integration, GET `/api/integrations/zapier/subscribers` and GET `/api/integrations/zapier/customers` expose the data the Zapier connector consumes. These endpoints can also be called directly from a custom integration that wants to mirror the Zapier behaviour. The `/api/integrations/zapier` POST authenticates the workspace for the integration session.

Example prompt: POST `/api/integrations/zapier` to authenticate, then GET `/api/integrations/zapier/subscribers` paginated, and write each subscriber to a CSV

### AI Agent Marketing Event Capture via Jentic

An AI agent embedded in an e-commerce backend calls Contlo's identify and track endpoints whenever a relevant business event occurs - order placed, abandonment, lifecycle-stage change. Through Jentic the X-API-KEY is held in your Jentic One instance so the agent never sees the raw key, and the agent reads the operation schema before sending the event. This avoids hard-coding the Contlo URL and key into agent prompts.

Example prompt: Search Jentic for 'track a contlo event', execute with user_id, event='cart_abandoned', and properties including cart_value=149.00 and currency='INR'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/identify` | Identify or upsert a customer profile with traits |
| POST | `/v1/track` | Track a behavioural event for a known user |
| POST | `/api/integrations/zapier` | Authenticate the Zapier integration session |
| GET | `/api/integrations/zapier/subscribers` | List subscribers visible to the Zapier integration |
| GET | `/api/integrations/zapier/customers` | List customers visible to the Zapier integration |

## Key resources

- **Subscribers** — Marketing subscribers in the Contlo workspace exposed via the Zapier integration
- **Customers** — Customer profiles exposed via the Zapier integration
- **Events** — Behavioural events keyed to a user_id, ingested through the track endpoint
- **Profiles** — Identify upserts that maintain Contlo's view of a known user with traits

## Why Jentic

- **Setup:** Wiring the Contlo API by hand means passing your X-API-KEY header and coordinating the identify, track, and subscriber read operations yourself. Through Jentic you install once, import the Contlo API from the API Directory, store the api_key once, and your agent calls it.
- **Permission scoping:** The Contlo API takes its customer and event targets in the request body rather than the URL path, so you limit the agent to the operations it needs, such as identifying a customer or tracking an event, and it can call nothing outside that set. Reads like listing subscribers or customers stay unavailable unless you include them in the allowed set.
- **Credential handling:** Your Contlo X-API-KEY is stored once, encrypted, by your own Jentic One instance and injected into the header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'track a customer event' or 'identify a customer', and Jentic returns the matching Contlo operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Klaviyo API** — Klaviyo provides a deeper marketing automation suite with built-in flows, segments, and SMS in one API.
- **Mailchimp Marketing API** — Mailchimp covers email, automations, and audience management at scale.
- **SendGrid Email Activity API** — SendGrid handles transactional email delivery while Contlo runs the marketing campaigns.

## FAQ

### Why is there no official OpenAPI spec for Contlo API?

Contlo's documentation lives across help articles and a Zapier connector reference rather than a hosted OpenAPI 3 file. Jentic generates and maintains this spec so that AI agents and developers can call Contlo API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Contlo API use?

Each request must include an X-API-KEY header issued from the Contlo workspace. Through Jentic the API key is stored in your Jentic One instance and applied at call time, so the agent never holds the raw value.

### Can I track customer events with the Contlo API?

Yes. POST `/v1/track` with a user_id, event name, and properties payload records a behavioural event tied to that user. Combine with POST `/v1/identify` to make sure the user profile and traits are up to date before the event is recorded.

### What are the rate limits for the Contlo API?

Contlo applies per-workspace rate limits sized to the customer's plan; current quotas and usage are visible in the Contlo dashboard. Through Jentic, retries with exponential backoff are handled at the SDK level so transient throttling does not surface to agent code.

### How do I send an identify call with the Contlo API through Jentic?

Run `jentic.search('identify a contlo customer')`, load the operation, and execute with user_id, email, and any extra traits. Jentic resolves this to POST `/v1/identify` and upserts the profile in Contlo.

### Does the Contlo API support exporting subscribers?

Yes. GET `/api/integrations/zapier/subscribers` returns the subscribers visible to the Zapier integration session, which can be paginated to export the full list. POST `/api/integrations/zapier` authenticates the integration session before the subscriber list call.

### Can I limit what my agent is allowed to do with the Contlo API?

Yes. Because you run Jentic One yourself, your own rules decide which Contlo operations and credentials the agent may use, so you can allow only what it needs, such as identifying a customer via POST `/v1/identify` or tracking an event via POST `/v1/track.` Since Contlo takes its customer and event targets in the request body rather than the URL path, the agent can call nothing outside the operations you permit. Reads like GET `/api/integrations/zapier/subscribers` and GET `/api/integrations/zapier/customers` stay unavailable unless you add them to the allowed set.