Collega Scanlead ai tuoi strumenti.

Leggi e crea lead da Make, Zapier, dal tuo CRM, ERP o da uno script.

Inizia in 3 passaggi

Crea una chiave in Impostazioni → API.

Invia la tua prima richiesta curl con Bearer.

Aggiungi un webhook per ricevere i nuovi lead.

Collega CRMlead

01In CRMlead → Impostazioni → Integrazioni → Collega Scanlead → Consenti.
02OAuth 2.0 con PKCE non condivide segreti (piani Pro e Pro+).

Con il piano Free, esporta un CSV e importalo in CRMlead.

Per le future applicazioni: usa GET /oauth/authorize e POST /oauth/token con OAuth 2.0 authorization code + PKCE S256.

OAuth per le applicazioni

Registra un client pubblico con URL di reindirizzamento esatti e autorizzazioni consentite. Nessun segreto client. Genera un code_verifier casuale (43–128 caratteri), quindi code_challenge = BASE64URL(SHA256(code_verifier)), senza padding. Il codice scade dopo 2 minuti ed è monouso.

GET /oauth/authorize?response_type=code&client_id=crmlead&redirect_uri=<registered_uri>&scope=read&state=<random_state>&code_challenge=<S256_challenge>&code_challenge_method=S256

Scambia il codice con una richiesta POST application/x-www-form-urlencoded. La risposta contiene access_token (una chiave API v1), token_type=Bearer, scope=read e workspace { id, name }. Conserva il token in modo sicuro; puoi revocarlo in Impostazioni → API. /oauth/token non supporta CORS.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id=crmlead&code=<code>&redirect_uri=<registered_uri>&code_verifier=<original_verifier>

Per Zapier, Make o i tuoi script, crea invece una chiave da incollare manualmente in Scanlead → Impostazioni → API.

Endpoint

Gli elenchi di eventi restituiscono { data: [...] }. Per creare un lead è obbligatorio solo email; tutti gli altri campi sono facoltativi. PATCH accetta qualsiasi sottoinsieme, incluso event_id.

Il campo status è accettato in fase di creazione e aggiornamento. Valori consentiti: hot, warm o cold.

GET/me

curl https://scanlead.io/api/v1/me \
  -H "Authorization: Bearer slk_live_YOUR_KEY"

GET/events

curl https://scanlead.io/api/v1/events \
  -H "Authorization: Bearer slk_live_YOUR_KEY"

GET/events/{id}

curl https://scanlead.io/api/v1/events/{id} \
  -H "Authorization: Bearer slk_live_YOUR_KEY"

GET/leads?limit=50

curl https://scanlead.io/api/v1/leads?limit=50 \
  -H "Authorization: Bearer slk_live_YOUR_KEY"

GET/leads/{id}

curl https://scanlead.io/api/v1/leads/{id} \
  -H "Authorization: Bearer slk_live_YOUR_KEY"

POST/leads

curl https://scanlead.io/api/v1/leads \
  -H "Authorization: Bearer slk_live_YOUR_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","company":"Analytical Engines","tags":["vip"],"status":"hot"}'

PATCH/leads/{id}

curl https://scanlead.io/api/v1/leads/{id} \
  -H "Authorization: Bearer slk_live_YOUR_KEY" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"notes":"Follow up next week","status":"warm"}'

Autenticazione e firme

Usa Authorization: Bearer slk_live_…. Le chiavi hanno autorizzazioni read o read_write. I webhook includono Scanlead-Signature: t=timestamp,v1=hex, calcolata come HMAC-SHA256(secret, timestamp.body).

Verifica una firma webhook: Node.js

const crypto = require('node:crypto');
const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
if (expected !== signature) throw new Error('invalid signature');

Python

import hmac, hashlib
expected = hmac.new(secret.encode(), f'{t}.{body}'.encode(), hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, signature)

Limiti

60 richieste al minuto per chiave. Gli elenchi accettano da 1 a 100 lead e usano un cursore opaco.

Codici di errore

401 invalid_api_key: chiave mancante, sconosciuta o revocata
403 insufficient_scope: una chiave read è stata usata per scrivere
404 not_found: la risorsa appartiene a un altro spazio
429 rate_limited: riprova dopo l’intervallo Retry-After
400 unknown_fields: i nomi dei campi non supportati sono restituiti in error.fields. Esempio: { error: { code: "unknown_fields", fields: ["full_name"] } }.
402 plan_required: è richiesto un abbonamento Pro o Pro+

Visualizza lo schema OpenAPI 3.1 →