Riferimento API REST

L'API REST pubblica di The-Y CRM è pensata per le integrazioni server-to-server: leggere o creare contatti, conversazioni, trattative, attività e note, rispondere nelle conversazioni e ricevere eventi via webhook. Le richieste si autenticano con una chiave API. In breve: 11 ambiti di autorizzazione (scope), 11 eventi webhook firmati con HMAC-SHA256. In cloud con Free: 60 richieste al minuto e 1.000 al giorno; Cloud Pro e Paid: 300 al minuto, nessun limite giornaliero; self-hosted: nessun limite per account.

URL di base (in cloud): https://crm.the-y.at/api/ext/v1 · self-host: https://<your-domain>/api/ext/v1 · disponibile su tutti i piani, Free compreso · Aggiornato al 12 nov 2026 (versione 1.1.65)

Nessun numero WhatsApp ancora collegato? API WhatsApp senza app Meta: collegare il numero, creare una chiave, aggiungere un webhook →

Autenticazione

Ogni richiesta ha bisogno della tua chiave API nell'header, come Bearer token oppure come X-API-Key:

Authorization: Bearer <YOUR_API_KEY>
# or
X-API-Key: <YOUR_API_KEY>

Crea una chiave: nell'app in Settings → Integrations (in “Advanced” → Connections) → “API keys” → nuova chiave. La chiave inizia con tyk_ e viene mostrata una sola volta: conservala al sicuro (The-Y salva solo un hash). La chiave è legata al tuo tenant.

Autorizzazioni (scope), scadenza e rinnovo: ogni chiave ha i suoi scope, che scegli quando la crei: contacts:read, contacts:write, conversations:read, conversations:write, deals:read, deals:write, tasks:write, notes:write, users:read, webhooks:manage e, dalla 1.1.67, per i negozi online, orders:write (quale route richiede quale scope lo trovi nella panoramica). Volendo le dai una data di scadenza (al massimo 5 anni). “Renew” crea una nuova chiave; quella vecchia resta valida per il tempo che scegli (scade subito, dopo 24 ore, 7 o 30 giorni). Le chiavi più vecchie senza autorizzazioni definite (prima della 1.1.60) possono ancora solo leggere e scrivere contatti: per le nuove aree imposta le autorizzazioni nelle impostazioni o crea una nuova chiave.

Tratta la chiave come una password: usala solo lato server, mai nel browser/frontend. Revoca le chiavi compromesse in Integrations.

Panoramica: tutte le route (dalla 1.1.62)

Tutte le route si trovano sotto https://crm.the-y.at/api/ext/v1 (self-hosted: il tuo indirizzo + /api/ext/v1). Ogni route richiede uno scope della chiave.

OpzioneAmbitoCosa
GET /me– (qualsiasi chiave valida)nome, scope e limiti della chiave stessa (ad es. per un test di connessione)
GET /contacts, GET /contacts/{id}contacts:readcercare / leggere contatti
POST /contacts, PATCH /contacts/{id}contacts:writecreare / aggiornare un contatto
POST /contacts/upsertcontacts:writecreare o aggiornare in base all'email (senza duplicati)
GET /custom-fields?entity=contact|company|dealcontacts:read (trattative: deals:read)campi personalizzati (chiave, tipo, opzioni)
GET /conversations, GET /conversations/{id}conversations:readconversazioni e messaggi
POST /conversations/{id}/messagesconversations:writerispondere in una conversazione
PATCH /conversations/{id}conversations:writestato, assegnatario
GET /pipelines, GET /deals/{id}deals:readpipeline con fasi, una trattativa
POST /deals, PATCH /deals/{id}deals:writecreare una trattativa, cambiarne la fase
POST /taskstasks:writecreare un'attività
POST /notesnotes:writenota su un contatto, un'azienda, una trattativa o una conversazione
GET /usersusers:readmembri attivi del team (per gli assegnatari)
GET/POST /webhooks, GET/DELETE /webhooks/{id}webhooks:manageregistrare e rimuovere webhook
POST /ordersorders:writeinviare un ordine da un negozio online (dalla 1.1.67; lo fa per te il plugin “The-Y CRM for WooCommerce”: guida)

Convenzioni

StatoSignificato
200 / 201OK / creato (eventualmente con warnings, vedi sopra)
400invalid_json: il body non è un oggetto JSON valido (o è vuoto) · invalid_field: un campo ha il tipo sbagliato (vedi field; sono ammessi testo, un numero o null) · contact_empty: creazione di un contatto senza nome, cognome, email e telefono · altri codici delle nuove route: vedi codici di errore
401unauthorized: chiave mancante, sconosciuta, revocata o scaduta
403insufficient_scope: alla chiave manca l'autorizzazione (vedi required) · tenant_suspended: account sospeso · feature_locked: le integrazioni sono disattivate per questo account · cloud_readonly: l'account al momento è in sola lettura (ad es. dopo la fine di Cloud Pro con dati oltre i limiti di Free): creazione e aggiornamento bloccati, la lettura funziona · terms_required: nuove condizioni d'uso non ancora accettate: aggiornamento bloccato, creazione e lettura funzionano
404not_found: l'elemento non esiste, è stato eliminato oppure l'ID non è un ID valido (ad es. /contacts/abc)
409una risposta in una conversazione non viene inviata (ad es. window_closed, vedi conversazioni) · webhook_limit: ci sono già 100 webhook
429limite superato (rate_limited oppure, sul piano Free, daily_limit_reached, con Retry-After; vedi limiti)
500errore del server

Codici di errore delle nuove route (dalla 1.1.62): 400: invalid_events, unsafe_url, invalid_status, invalid_assignee, text_required, template_not_supported, template_not_found, invalid_reference, title_required, target_required, email_required, invalid_entity (sempre con message, quasi sempre con field) · 403: limit_reached (limite mensile sul piano Free) · 409: vedi risposta, webhook_limit · 429: rate_limited, daily_limit_reached.

Limiti e piani (dalla 1.1.62)

Oltre al limite per indirizzo IP (300 richieste al minuto), ogni account ha:

FreeCloud Pro, Paid, Founderself-hosted
al minuto60300nessuno (configurabile: API_LIMIT_PER_MINUTE)
al giorno (UTC)1,000nessunanessuno (configurabile: API_LIMIT_PER_DAY)

Ogni risposta a una richiesta autenticata porta gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi Unix) per il minuto in corso; sul piano Free anche X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day e X-RateLimit-Reset-Day per il giorno (UTC). Così vedi quante richieste ti restano. In self-hosted senza un limite configurato non c'è limite e quindi nessuno di questi header. Non vengono inviati prima dell'autenticazione (chiave mancante o sbagliata).

Oltre un limite l'API risponde 429 e in più Retry-After (in secondi): { "error": { "code": "rate_limited", "message": "…", "limit": 60, "window": "minute", "retry_after": 12, "reset_at": "…" } }, oppure per il limite giornaliero { "error": { "code": "daily_limit_reached", "message": "…", "upgrade": { "href": "…" } } }. I webhook che il CRM ti invia non contano. Consiglio: con 429 aspetta i secondi indicati in Retry-After prima di riprovare.

Contatti

Gli ID dei contatti sono UUID (ad es. 3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90). In creazione e aggiornamento l'API capisce questi campi:

CampoTipoSignificato
first_nametestonome
last_nametestocognome
emailtestoun indirizzo email
phonetestoun numero di telefono
customoggettocampi personalizzati come { "key": value }. Vengono riprese solo le chiavi dei campi personalizzati che esistono per i contatti nel CRM (Settings → Custom fields, chiavi tramite GET /custom-fields). Le chiavi sconosciute non vengono salvate e sono elencate nella risposta sotto warnings

Ogni campo accetta testo, un numero (salvato come testo, ad es. un numero di telefono da un foglio di calcolo) o null (vuoto). Un oggetto, una lista o true/false restituiscono 400 invalid_field. Gli altri campi (ad es. name, company, emails) vengono ignorati. Al momento non si può impostare un'azienda tramite l'API.

GET/contacts

Elenca i contatti, dal più recente (paginato, vedi Convenzioni). ?q= cerca in nome e cognome, email, telefono, nome dell'azienda e nome utente WhatsApp. Più parole: ciascuna deve corrispondere (ad es. nome e cognome in qualsiasi ordine). I numeri di telefono corrispondono in qualsiasi formato. Funziona anche ?search=.

# Request
curl "https://crm.the-y.at/api/ext/v1/contacts?limit=20&offset=0" \
  -H "Authorization: Bearer $API_KEY"

# Response 200
{
  "data": [
    {
      "id": "3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90",
      "first_name": "Maria",
      "last_name": "Muster",
      "emails": [{ "type": "work", "value": "maria@example.com" }],
      "phones": [{ "type": "mobile", "value": "+4366012345678" }],
      "company": "ACME",
      "created_at": "2026-11-09T10:15:00.000Z",
      "wa": null
    }
  ],
  "limit": 20,
  "offset": 0,
  "count": 1,
  "hasMore": false
}

company è il nome dell'azienda collegata (o null), wa l'ID WhatsApp { "bsuid", "username" } (o null). I campi personalizzati sono inclusi solo quando leggi un singolo contatto.

POST/contacts

Crea un contatto. Campi: vedi la tabella sopra.

curl -X POST "https://crm.the-y.at/api/ext/v1/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Muster", "email": "maria@example.com", "phone": "+4366012345678" }'

# Response 201 Created
{
  "id": "3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90",
  "contact": {
    "id": "3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90",
    "first_name": "Maria",
    "last_name": "Muster",
    "emails": [{ "type": "work", "value": "maria@example.com" }],
    "phones": [{ "type": "mobile", "value": "+4366012345678" }],
    "company": null,
    …
  }
}

contact ha gli stessi campi della lettura di un singolo contatto, solo senza custom. Invia insieme i campi personalizzati, ad es. "custom": { "customer_no": "K-1001" } (solo se nel CRM esiste il campo “customer_no”).

Obbligatorio (dalla 1.1.62): almeno uno tra first_name, last_name, email o phone con un contenuto. Altrimenti ricevi 400 contact_empty e non viene creato nessun contatto, così come con un JSON non valido (400 invalid_json). POST /contacts non riconosce gli indirizzi email doppi: ogni chiamata crea un nuovo contatto. Per evitare duplicati usa POST /contacts/upsert.
# Response 400 (empty body, or unknown fields only such as "name")
{ "error": "contact_empty", "message": "A contact needs at least one of these fields: first_name, last_name, email or phone." }

# Response 201 with a warning (the custom field "colour" doesn't exist in the CRM – the contact is created anyway)
{
  "id": "3f6c1e2a-…",
  "contact": { … },
  "warnings": [
    { "code": "unknown_custom_fields", "fields": ["colour"], "message": "…" }
  ]
}

GET/contacts/{id}

Legge un singolo contatto. La risposta è il contatto stesso (senza wrapper data), con i campi personalizzati in custom.

curl "https://crm.the-y.at/api/ext/v1/contacts/3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90" \
  -H "Authorization: Bearer $API_KEY"

# Response 200
{
  "id": "3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90",
  "first_name": "Maria",
  "last_name": "Muster",
  "emails": [{ "type": "work", "value": "maria@example.com" }],
  "phones": [{ "type": "mobile", "value": "+4366012345678" }],
  "company_id": null,
  "company": null,
  "owner_user_id": null,
  "owner_name": null,
  "birthday": null,
  "consent_state": {},
  "consent_meta": {},
  "created_at": "2026-11-09T10:15:00.000Z",
  "wa": null,
  "custom": { "customer_no": "K-1001" }
}

owner_user_id/owner_name = il responsabile, consent_state/consent_meta = consenso per canale con prova. ID sconosciuto o non valido (ad es. abc): 404 { "error": "not_found" }.

PATCH/contacts/{id}

Aggiorna in parte un contatto: cambiano solo i campi che invii, tutto il resto resta com'è:

curl -X PATCH "https://crm.the-y.at/api/ext/v1/contacts/3f6c1e2a-8b4d-4c1e-9a7f-2d5b6c7e8f90" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+4366099999999" }'

# Response 200: { "id": "…", "contact": { … } } (same as when creating, possibly with warnings)

POST/contacts/upsert

Crea o aggiorna in base all'indirizzo email (dalla 1.1.62): { "email": "maria@example.com", "first_name": "Maria", "custom": { … } } → nuovo: 201 { "created": true, … }, esistente: 200 { "created": false, … } (cambiano solo i campi che invii). Se più contatti hanno quell'indirizzo, viene aggiornato il più vecchio e warnings contiene multiple_matches. Senza email: 400 email_required.

GET/custom-fields

GET /custom-fields?entity=contact (anche company, deal) → { "entity", "data": [{ "key", "label", "type", "options", "required" }] }. key è la chiave in custom.

Conversazioni (dalla 1.1.62)

GET /conversations?status=open&channel=whatsapp&since=2026-11-01T00:00:00Z&limit=50&offset=0: ordinate per attività più recente. Filtri facoltativi: status (open, snoozed, closed), channel (email, whatsapp, sms, webchat, messenger, instagram, call, …), since (ultimo messaggio in quel momento o dopo), contact_id. Risposta { "data": [ … ], "limit", "offset", "count", "hasMore" }.

Una conversazione: { "id", "number", "channel", "status", "priority", "subject", "contact_id", "customer": { "name", "address" }, "assignee": { "id", "name" } | null, "created_at", "last_message_at", "first_response_at", "resolved_at", "snooze_until", … }. GET /conversations/{id}?messages=200 aggiunge messages (gli ultimi, dal più vecchio): { "id", "direction": "in" | "out", "internal", "text", "author_name", "created_at", "delivery", "attachments": [{ "id", "filename", "content_type", "size" }] }. in = dal cliente, internal: true = nota interna (mai inviata al cliente).

Rispondere: POST /conversations/{id}/messages con { "text": "…" }, sullo stesso canale e account dell'inbox (email con firma, oggetto “Re:” e citazione; WhatsApp; SMS; Messenger; Instagram; web chat). Su WhatsApp, fuori dalla finestra di 24 ore, funziona solo un modello approvato: { "template": { "name": "appointment_reminder", "language": "en", "params": ["Maria"] } }. Risposta 201 { "id", "conversation_id", "delivery", "message" }; delivery come nell'inbox (sent, simulated senza un canale configurato, failed con delivery_info). Il messaggio mostra come autore “API: <key name>” e conta come una risposta dall'inbox (limite mensile sul piano Free, prima risposta). Link su WhatsApp (dalla 1.1.69.1): se il testo contiene un link (http:// o https://), il destinatario vede un'anteprima con immagine e titolo – come nell'app WhatsApp (la pagina deve avere i tag Open Graph). Con "previewUrl": false il link parte senza anteprima, ad es. { "text": "Your appointment: https://…", "previewUrl": false }. Vale solo per WhatsApp; gli altri canali ignorano il campo.

Valgono le stesse regole di una risposta dall'inbox: una risposta normale (testo o modello di servizio) viene inviata anche se il contatto si è opposto a quel canale o si è disiscritto dalle email; come nell'inbox, decidi tu (o il tuo workflow). Un modello di marketing (categoria “Marketing”) viene inviato solo con consenso esplicito. La risposta non viene inviata (409) in caso di: window_closed (finestra di 24 ore chiusa e testo libero su WhatsApp, Messenger o Instagram; su WhatsApp in quel caso funziona un modello), no_optin o consent_off (solo modello di marketing: nessun consenso esplicito o opposizione al canale), wa_thread_owned_by_other (la conversazione WhatsApp è gestita da un altro sistema di risposta), no_mailbox, recipient_suppressed, channel_not_supported. 403 limit_reached = raggiunto il limite mensile sul piano Free.

Stato / assegnatario: PATCH /conversations/{id} con { "status": "closed" }, { "status": "snoozed", "snooze_until": "…" } o { "assignee_user_id": "<ID from GET /users>" | null }. Lo storico della conversazione mostra “API (<name>) closed the conversation”.

Trattative (dalla 1.1.62)

GET /pipelines → pipeline con fasi (id, name, sort_order, probability, is_won, is_lost). GET /deals/{id} legge una trattativa. POST /deals con { "title": "Website relaunch", "value": 4800, "currency": "EUR", "stage_id": "…", "contact_id": "…", "custom": { … } } (senza fase: prima fase della pipeline predefinita). PATCH /deals/{id} con { "stage_id": "…" }: la pipeline segue la fase, vinta / persa dipendono dalla fase. ID di un altro account → 400 invalid_reference con field.

Attività, note, team (dalla 1.1.62)

Ti servono altre risorse (ad es. aziende)? Scrivici a office@the-y.at; per gli eventi in tempo reale ci sono i webhook qui sotto.

Webhook in uscita (eventi)

Invece di interrogare di continuo l'API (polling), fatti inviare gli eventi al tuo URL. In Settings → Integrations → “Send data (webhook)” imposti un URL di destinazione e gli eventi. Il CRM crea il secret per la firma.

Registrare tramite l'API (dalla 1.1.62): POST /webhooks con { "url": "https://…", "events": ["message.received", "deal.won"], "name": "My system" }; "events": ["*"] = tutti. Risposta 201 { "id", "secret": "whsec_…", "webhook" }. Il secret compare solo in questa risposta, mai più (né l'elenco né la lettura singola lo mostrano). DELETE /webhooks/{id} rimuove il webhook. Al massimo 100 webhook per account.

EventoQuandodata
contact.createdcontatto creato: a mano, tramite l'API, da WhatsApp, email, SMS, chiamate, web chat, prenotazioni, appuntamenti; le importazioni CSV solo con la casella “Run automations, … campaigns and webhooks …” spuntatacontatto + source (whatsapp, email, import, api, …)
contact.updatedmodificato nel modulo, nell'inbox o tramite l'APIcontatto + changed
message.receivedun cliente scrivemessaggio: text, conversation_id, channel, contact_id, from { name, address }, first
conversation.createdun cliente o il team avvia una conversazioneconversazione + started_by (customer / team)
conversation.closed / conversation.assignedchiusa / nuovo assegnatarioconversazione (+ previous_status / previous_assignee_id)
deal.created, deal.stage_changed, deal.won, deal.losttrattativetrattativa (+ from_stage, to_stage ai cambi di fase)
task.createdattività creataattività
Protezione dei dati (da leggere): con message.received, conversation.* e contact.*, testi dei messaggi, nomi, numeri di telefono e indirizzi email dei tuoi clienti vanno all'indirizzo che inserisci (ad esempio il tuo strumento di automazione). Il CRM invia solo ciò a cui ti iscrivi, e solo a destinazioni inserite da un admin. Verifica che il sistema di destinazione possa trattare questi dati (accordo sul trattamento dei dati, sede dei server) e iscriviti solo agli eventi che ti servono. Lo stesso vale per le chiavi API con conversations:read e users:read (indirizzi email del tuo team). Invia i webhook solo tramite https://.

Verificare la firma del webhook (dalla 1.1.60)

Ogni consegna è firmata, così il tuo sistema può verificare che i dati arrivino davvero da The-Y CRM e non siano stati modificati lungo il percorso.

Secret: viene mostrato una volta quando crei il webhook (whsec_…). Poi viene salvato solo cifrato e non è più visibile da nessuna parte. L'hai perso? “Renew secret”: quello vecchio smette subito di funzionare.

HeaderContenuto
X-TheY-Timestampora della consegna in secondi dal 1970 (Unix time)
X-TheY-Signaturev1=<hex> – HMAC-SHA256 (metodo HMAC) con il secret su <X-TheY-Timestamp>.<body> (timestamp, un punto, il body invariato)
X-TheY-Evente.g. contact.created
X-TheY-Event-IdID dell'evento (evt_…, dalla 1.1.62). È lo stesso a ogni nuovo tentativo e per tutti i webhook dello stesso evento; si trova anche nel body firmato come id. Usalo per riconoscere le consegne doppie
X-TheY-DeliveryID di questa consegna a questo webhook (resta lo stesso nei nuovi tentativi)
X-KSCRM-Signature, X-KSCRM-Eventvecchio: HMAC-SHA256 solo sul body, senza timestamp. Viene ancora inviato perché i ricevitori esistenti non smettano di funzionare
Passa al nuovo: il vecchio header X-KSCRM-Signature verrà rimosso con la versione 1.2.0. Fino ad allora verifica X-TheY-Signature come mostrato qui sotto.

Come verificare: calcola tu la firma e confrontala in tempo costante, e rifiuta le consegne il cui timestamp si discosta di più di 5 minuti dal tuo orologio (protegge dal riutilizzo di consegne intercettate). Importante: firma il body grezzo, così come lo ricevi, senza prima interpretarlo come JSON e serializzarlo di nuovo.

# Node.js (Express)
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.THEY_WEBHOOK_SECRET; // whsec_…
const app = express();
const alreadyProcessed = new Set(); // in real life rather a table/Redis entry that expires after e.g. 24 h

app.post("/the-y/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const ts = Number(req.get("X-TheY-Timestamp"));
  const sig = (req.get("X-TheY-Signature") || "").split(",").map((s) => s.trim()).find((s) => s.startsWith("v1="))?.slice(3) || "";
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return res.status(400).send("too old");
  const want = crypto.createHmac("sha256", SECRET).update(`${ts}.${req.body.toString("utf8")}`).digest("hex");
  const a = Buffer.from(sig, "utf8"), b = Buffer.from(want, "utf8");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).send("bad signature");
  const event = JSON.parse(req.body.toString("utf8"));
  if (alreadyProcessed.has(event.id)) return res.sendStatus(204); // retry – process only once
  alreadyProcessed.add(event.id);
  // … process event.event, event.data
  res.sendStatus(204);
});
# PHP
<?php
$secret = getenv('THEY_WEBHOOK_SECRET'); // whsec_…
$body   = file_get_contents('php://input');
$ts     = (int)($_SERVER['HTTP_X_THEY_TIMESTAMP'] ?? 0);
$sigHdr = $_SERVER['HTTP_X_THEY_SIGNATURE'] ?? '';
$sig    = '';
foreach (explode(',', $sigHdr) as $part) { $part = trim($part); if (str_starts_with($part, 'v1=')) $sig = substr($part, 3); }
if (abs(time() - $ts) > 300) { http_response_code(400); exit('too old'); }
$want = hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($want, $sig)) { http_response_code(401); exit('bad signature'); }
$event = json_decode($body, true);
// … process $event['event'], $event['data']
http_response_code(204);

Webhook in entrata

I sistemi esterni possono creare/aggiornare dati in The-Y tramite un URL con token: POST /api/hooks/<token> (token creato in Integrations). Per ogni webhook scegli il livello di accesso: upsert (solo creare/aggiornare, le eliminazioni vengono ignorate: contro il lock-in) o full (eliminazione compresa).

Prossimi passi