Un’API influencer per i tuoi dati di gifting.

A cosa serve l’API

È pensata per chi si occupa delle operations o per lo sviluppatore che vuole i dati di Pozto altrove: una base Airtable, un data warehouse, una dashboard, uno strumento interno. Oppure al contrario: aggiungere creator dal sistema che spedisce i tuoi omaggi, così nessuno deve inserirli due volte.

Lavora sul tuo roster, i creator a cui hai spedito prodotti. Non è un database di influencer in cui cercare. Se è questo che ti serve da un’API influencer, Pozto non fa per te.

Chiavi, URL di base e limiti

• URL di base: https://pozto.co/api/v1
• Chiavi: le crea il proprietario del team in Impostazioni → API, con il piano Brand. Una chiave inizia con pz_ e viene mostrata una sola volta: Pozto ne conserva solo un’impronta, quindi copiala subito. Dai a ogni chiave un nome che dica a cosa serve, e revocala quando vuoi. Le Impostazioni mostrano quando ogni chiave è stata usata l’ultima volta.
• Come inviarla: Authorization: Bearer pz_… in ogni richiesta.
• Ambito: una chiave legge e aggiunge dati in tutti i brand del tuo team.
• Limite di frequenza: 120 richieste al minuto per chiave.
• Pagine: GET /creators e GET /posts restituiscono 100 elementi alla volta, o fino a 500 con &limit=. Quando ce ne sono altri, la risposta ha un next_cursor: rimandalo come &cursor= per la pagina successiva. Nell’ultima pagina è null.
• Formato: JSON in entrata e in uscita. Gli id sono stringhe, e le date sono in ISO 8601.

Endpoint

Cosa contengono un creator e un post

Un creator arriva con nome, email, account (e se ogni handle è stato trovato), codici sconto, stato e ogni omaggio: il prodotto e il resto del pacco, la campagna, le date di spedizione e consegna, la scadenza in giorni, il numero di tracking, il compenso, i post richiesti e quelli pubblicati finora.

Un post è un video, con ogni piattaforma su cui è uscito: link, didascalia, data di pubblicazione e se ti ha taggato. Poi l’omaggio e il prodotto per cui conta, e come Pozto lo ha deciso. Poi il controllo video: se il tuo prodotto è stato trovato, ogni momento in cui è sullo schermo in secondi, ogni volta che è stato nominato con la citazione, e un breve riassunto. E la dichiarazione: chiara, debole o assente, con il motivo.

Aggiungere creator e post

POST /creators accetta brand_id e handles: @nomi, link ai profili o link in stile Linktree, fino a sei. Accetta anche platform, name, email, codes, product (un id o un nome; un nome nuovo aggiunge il prodotto), shipped_at, delivered_at, due_days (21 se lo ometti) e tracking. Un creator già in lista, riconosciuto da uno qualsiasi dei suoi account o dalla sua email, riceve l’omaggio invece di un duplicato. Risponde 201 per un nuovo creator e 200 per uno esistente, con l’id del creator e l’id dell’omaggio.

POST /posts accetta brand_id e url, e facoltativamente creator_id e product_id. Il post viene archiviato sotto chi possiede l’account, aggiunto alla tua lista se è nuovo, e messo in coda per il controllo video. Risponde indicando se era nuovo, l’handle, la piattaforma e se conta come post su di te.

# Creator in ritardo, in un brand
curl "https://pozto.co/api/v1/creators?brand_id=BRAND_ID&status=late" \
  -H "Authorization: Bearer pz_…"

# Aggiungi un creator e l’omaggio che gli hai inviato
curl -X POST https://pozto.co/api/v1/creators \
  -H "Authorization: Bearer pz_…" \
  -H "Content-Type: application/json" \
  -d '{"brand_id":"BRAND_ID","handles":["@maya.glows"],"product":"Glow Serum","shipped_at":"2026-10-14"}'

# Post dal 1° ottobre, dal più recente
curl "https://pozto.co/api/v1/posts?brand_id=BRAND_ID&since=2026-10-01" \
  -H "Authorization: Bearer pz_…"

# La pagina successiva: il next_cursor della risposta precedente
curl "https://pozto.co/api/v1/posts?brand_id=BRAND_ID&since=2026-10-01&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer pz_…"

Errori

Un errore torna come JSON con una frase semplice, come {"error": "…"}, e uno stato 4xx:

• 400: il corpo non è JSON, oppure un campo non è valido, come una data di consegna nel futuro.
• 401: nessuna chiave, oppure una chiave errata o revocata.
• 403: il tuo team non ha il piano Brand.
• 404: nessun brand con quel brand_id nel tuo team.
• 409: il brand è bloccato, perché il tuo piano ha meno brand di quelli che usa il tuo team.
• 429: più di 120 richieste in un minuto.

Cosa non fa l’API

• Niente ricerca influencer. Legge e aggiunge alla tua lista. La ricerca di creator è Trova creator, nell’app.
• Niente visualizzazioni, like o EMV nelle risposte. Sono nell’app da Starter, e nel report settimanale. Vedi i report influencer.
• Niente webhook. Per recuperare i nuovi post, chiama GET /posts con since.
• Niente modifiche o eliminazioni. L’API legge e aggiunge. Modifiche e rimozioni si fanno nell’app.
• Niente chiavi personali. Le chiavi appartengono al team, e solo il proprietario le crea.

Il contenuto dei post è lo stesso dell’app: Pozto trova i post guardando il video, fotogrammi, audio e didascalia, quindi arrivano anche i post senza tag. Il monitoraggio influencer spiega come vengono trovati i post.

Prezzi

L’API è inclusa nel piano Brand: $999 al mese, o $799 al mese con pagamento annuale, con 10 brand, 1.000 creator attivi, utenti illimitati e single sign-on. Tutto il resto di Pozto parte da piani inferiori, e il piano gratuito copre i tuoi primi 10 creator. Vedi i piani.