Use cases

Every example assumes a key with the listed scope and a Pro or Enterprise plan (see Plans and limits). Replace aa_YOUR_FULL_KEY with your real key.

1. Sync leads into your own CRM

Your agency already uses a CRM (HubSpot, Zoho…) besides Aymar Agents. Instead of us pushing to your CRM, your integration pulls new leads every hour with dateFrom:

curl "https://api.aymaragents.com/public/v1/leads?dateFrom=2026-09-01T00:00:00Z" \
  -H "X-API-Key: aa_YOUR_FULL_KEY"

import requests

resp = requests.get(
    "https://api.aymaragents.com/public/v1/leads",
    params={"dateFrom": "2026-09-01T00:00:00Z"},
    headers={"X-API-Key": "aa_YOUR_FULL_KEY"},
)
for lead in resp.json()["data"]:
    sync_to_my_crm(lead)

Scope: tenant:leads.read.

2. Capture leads from your own website

You have a landing page outside Aymar Agents’s embeddable widget and don’t want to add the chat widget to it — send the form straight to the API:

await fetch("https://api.aymaragents.com/public/v1/leads", {
  method: "POST",
  headers: {
    "X-API-Key": "aa_YOUR_FULL_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customerPhone: "+34600111222",
    stageId: "...",
    notes: "Form on the services landing page",
  }),
});

Scope: tenant:leads.manage (or tenant:contacts.manage if you send the form to /contacts instead).

3. Keep an external calendar unified

You already use Calendly or Google Calendar as another team’s source of truth — check Aymar Agents’s open slots before offering a time, and create the appointment here so it’s reflected in both places:

curl "https://api.aymaragents.com/public/v1/availability?from=2026-09-10&to=2026-09-14" \
  -H "X-API-Key: aa_YOUR_FULL_KEY"

slot = pick_a_slot(available_slots)
requests.post(
    "https://api.aymaragents.com/public/v1/appointments",
    json={"userId": slot["userId"], "startsAt": slot["startsAt"], "customerId": customer_id},
    headers={"X-API-Key": "aa_YOUR_FULL_KEY"},
)

Scopes: tenant:appointments.read (availability) + tenant:appointments.manage (creating).

4. Sync tickets with your helpdesk

Your own Zendesk or Freshdesk (different from one of our own Zendesk integrations) mirrors each ticket’s status in both directions:

const res = await fetch("https://api.aymaragents.com/public/v1/tickets?status=open", {
  headers: { "X-API-Key": "aa_YOUR_FULL_KEY" },
});
const { data: openTickets } = await res.json();

curl -X PATCH "https://api.aymaragents.com/public/v1/tickets/TICKET_ID" \
  -H "X-API-Key: aa_YOUR_FULL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'

Scopes: tenant:tickets.read (reading) + tenant:tickets.manage (creating/updating/commenting).

5. Low-code automation (Zapier and similar)

Trigger a Zap when a new lead comes in (by polling GET /leads periodically, until a webhook exists) and use “send a WhatsApp message from a spreadsheet” as an action:

curl -X POST "https://api.aymaragents.com/public/v1/conversations/CONVERSATION_ID/messages" \
  -H "X-API-Key: aa_YOUR_FULL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your appointment is confirmed for tomorrow at 10:00"}'

Scope: tenant:conversations.manage. Remember: if the contact is on WhatsApp and their 24h window is closed, this call responds 409 WHATSAPP_SESSION_WINDOW_CLOSED without attempting the send — use POST /conversations/start with an approved template to open a new conversation instead. And either way, the message you send does not show up instantly in the Platform inbox — see the note in Getting started with the API.