API
The case management system of a firm, a bank or a servicer opens matters and batches, sends documents and receives the outcomes without going through the interface. Every operation, with its parameters, its responses and an example ready to copy.
- One key per system: the firm’s administrator creates it in Organizzazione → API (Organization → API) and it acts on behalf of a member of the firm.
- Matters are queued and followed with a GET or with the key’s signed webhook.
- At most 120 requests per minute per key; on request, access with a client certificate only (mTLS) for dedicated deployments.
The reference below is generated from the OpenAPI specification and is written in Italian, like the API’s field names.
Le pratiche di Trailgun dai sistemi dello studio. Ogni richiesta porta Authorization: Bearer tg_live_…, una chiave creata dall'amministratore dello studio (Organizzazione → API) che agisce per conto di un membro dello studio: vede i suoi clienti e crea a nome suo. Le pratiche vanno in coda e si seguono con GET o col webhook della chiave. A una pratica o a un lotto già creati si mandano altri documenti con POST …/documents (con l'intake acceso per lo studio). Al massimo 120 richieste al minuto per chiave: ogni risposta porta X-RateLimit-Limit e X-RateLimit-Remaining.
Base URL https://app.trailgun.ai/api/v1 · Download the OpenAPI specification
Pratiche
Una pratica è una chiamata: il cliente, il tipo di atto, i fatti e lo zip dei documenti. Va in coda e si segue con GET o col webhook.
GET /pratiche
Le pratiche
Parameters
clienteId query | string Solo le pratiche di questo cliente. |
|---|---|
lottoId query | string Solo le pratiche di questo lotto. |
stato query | in_coda | in_corso | completata | fallita |
limite query | integer Quante pratiche, le più recenti per prime. |
archived query | true | all Senza: le pratiche non archiviate, come gli elenchi dell'app (con lottoId: tutte le pratiche del lotto). true: solo le archiviate. all: tutte. |
Responses
- 200 { pratiche: Pratica[] }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"pratiche": [
{
"id": "job_8f2kq1x9",
"numero": 42,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"lottoId": null,
"titolo": "Alfa S.r.l. — fattura 128/2026",
"stato": "in_coda",
"fase": null,
"documenti": {
"totali": 0,
"lavorati": 0
},
"errore": null,
"origine": "api",
"creataIl": "2026-11-08T09:30:00.000Z",
"completataIl": null,
"archived": false,
"link": "https://app.trailgun.ai/jobs/job_8f2kq1x9"
}
]
}
curl https://app.trailgun.ai/api/v1/pratiche \
-H "Authorization: Bearer tg_live_…"
POST /pratiche
Apre una pratica (va in coda)
Multipart: il cliente, il tipo di atto, i fatti e lo zip dei documenti. La pratica va in coda (stato: in_coda) e si segue con GET /pratiche/{id} o col webhook della chiave (pratica.completata, pratica.fallita). L'utente della chiave deve poter creare pratiche: un operatore o un utente in sola lettura ricevono 403.
Body multipart/form-data
clienteId required | string |
|---|---|
tipo | decreto_ingiuntivo | assessment | escussione_garanzia | insinuazione_passivo | remediation_datatape | affitto_ramo_azienda | analisi_faldone Default decreto_ingiuntivo. |
fatti | string Le note per gli agenti (obbligatorie, tranne per l'assessment e l'analisi del faldone). |
titolo | string |
templateId | string Il questionario, per l'assessment; il template del centro, per l'affitto di ramo d'azienda (facoltativo: senza, si riconosce dal nome del centro in fatti e titolo). |
practiceTemplateId | string Solo per analisi_faldone: il template di pratica (libreria Trailgun, dello studio, o personale di chi possiede la chiave). Dà materia, funzioni e opzioni documentali, i template atto e il workflow proposti sulla pratica. Si congela sulla pratica. |
leaseDeed | auto | preliminary | final Affitto di ramo d'azienda: il documento da redigere. Default auto (dalla proposta economica: rinnovo → definitivo, nuovo → preliminare). |
followedPeople | string Analisi del faldone: chi assiste l'avvocato, una persona per riga coi soprannomi dopo il punto e virgola («Mario Rossi; il biondo»), o il JSON [{ "name": "…", "aliases": ["…"] }]. Le domande potranno leggere solo le pagine che le nominano. |
qaLevel | string |
giurisprudenza | true | false |
raccoltaDati | true | false |
comunicazioni | spenta | semiautomatica | automatica |
archiviAnnidati | true | false Apre anche gli zip dentro lo zip (fino a tre livelli). Default true. |
archivio required | file I documenti, in uno .zip (fino a 4 GB). |
Responses
- 202 { pratica: Pratica }
- 400 Richiesta non valida: tipo, fatti, livello di controllo o archivio (.zip nel campo «archivio»)
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio, è disattivato, o il suo ruolo (operatore, sola lettura) non consente di creare pratiche
- 404 Cliente o template non trovato
- 413 Archivio troppo grande
- 429 Oltre 120 richieste al minuto, troppe pratiche in coda per lo studio o troppe pratiche aperte da questa chiave nelle ultime 24 ore
- 500 Errore interno.
Response example
{
"pratica": {
"id": "job_8f2kq1x9",
"numero": 42,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"lottoId": null,
"titolo": "Alfa S.r.l. — fattura 128/2026",
"stato": "in_coda",
"fase": null,
"documenti": {
"totali": 0,
"lavorati": 0
},
"errore": null,
"origine": "api",
"creataIl": "2026-11-08T09:30:00.000Z",
"completataIl": null,
"archived": false,
"link": "https://app.trailgun.ai/jobs/job_8f2kq1x9"
}
}
curl -X POST https://app.trailgun.ai/api/v1/pratiche \
-H "Authorization: Bearer tg_live_…" \
-F clienteId=<clienteId> \
-F tipo=<tipo> \
-F fatti=<fatti> \
-F archivio=@pratica.zip
GET /pratiche/{id}
Una pratica
Parameters
id required path | string L'id della pratica. |
|---|
Responses
- 200 { pratica: Pratica }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Pratica non trovata, o non visibile alla chiave
- 429 Oltre 120 richieste al minuto per questa chiave.
Response example
{
"pratica": {
"id": "job_8f2kq1x9",
"numero": 42,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"lottoId": null,
"titolo": "Alfa S.r.l. — fattura 128/2026",
"stato": "completata",
"fase": null,
"documenti": {
"totali": 14,
"lavorati": 14
},
"errore": null,
"origine": "api",
"creataIl": "2026-11-08T09:30:00.000Z",
"completataIl": "2026-11-08T10:12:00.000Z",
"archived": false,
"link": "https://app.trailgun.ai/jobs/job_8f2kq1x9"
}
}
curl https://app.trailgun.ai/api/v1/pratiche/<id> \
-H "Authorization: Bearer tg_live_…"
GET /pratiche/{id}/documento
Il documento prodotto (markdown)
Il testo dell'atto, quando la pratica è completata.
Parameters
id required path | string L'id della pratica. |
|---|
Responses
- 200 Il documento, in markdown
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Pratica non trovata
- 409 Il documento non è ancora pronto
- 429 Oltre 120 richieste al minuto per questa chiave.
Response example
# Ricorso per decreto ingiuntivo
…
curl https://app.trailgun.ai/api/v1/pratiche/<id>/documento \
-H "Authorization: Bearer tg_live_…" \
-o documento.md
GET /pratiche/{id}/faldone
Il faldone (zip): atto, allegati, deposito, dati
Parameters
id required path | string L'id della pratica. |
|---|
Responses
- 200 Il faldone, come allegato (
Content-Disposition: attachment) - 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Pratica non trovata
- 409 La pratica è ancora in lavorazione
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
curl https://app.trailgun.ai/api/v1/pratiche/<id>/faldone \
-H "Authorization: Bearer tg_live_…" \
-o faldone.zip
Lotti
Molte pratiche da un solo archivio: si crea il lotto, si carica lo zip (uno zip o una cartella per pratica), si avvia.
POST /lotti
Crea un lotto (bozza): un cliente, un tipo, le stesse opzioni per tutte le pratiche
Poi si carica l'archivio (PUT /lotti/{id}/archivio) e si avvia (POST /lotti/{id}/avvia). Alla fine arriva il webhook lotto.concluso.
Body application/json
clienteId required | string |
|---|---|
tipo | decreto_ingiuntivo | assessment | escussione_garanzia | insinuazione_passivo | remediation_datatape | affitto_ramo_azienda | analisi_faldone Default decreto_ingiuntivo. |
titolo | string |
fatti | string Le note comuni a tutte le pratiche. |
templateId | string |
practiceTemplateId | string Solo per analisi_faldone: il template di pratica (libreria Trailgun, dello studio, o personale di chi possiede la chiave). Dà materia, funzioni e opzioni documentali, i template atto e il workflow proposti sulla pratica. Si congela sulla pratica. |
matterId | string La pratica dello studio (fascicolo) a cui legare le pratiche del lotto. |
opzioni | Opzioni Assenti = le impostazioni dello studio e dell’utente della chiave. |
Body example
{
"clienteId": "cli_4hd8s2",
"tipo": "decreto_ingiuntivo",
"titolo": "Fatture insolute — ottobre 2026",
"fatti": "Fatture scadute e non pagate; nessuna contestazione."
}
Responses
- 201 { lotto: Lotto }
- 400 Richiesta non valida
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Cliente o template non trovato
- 409 Troppi lotti in bozza per questo utente
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"lotto": {
"id": "lot_3m9x2a",
"numero": 7,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"titolo": "Fatture insolute — ottobre 2026",
"stato": "bozza",
"creatoIl": "2026-11-08T09:30:00.000Z",
"avviatoIl": null,
"conclusoIl": null,
"archived": false,
"link": "https://app.trailgun.ai/batches/lot_3m9x2a"
}
}
curl -X POST https://app.trailgun.ai/api/v1/lotti \
-H "Authorization: Bearer tg_live_…" \
-H "Content-Type: application/json" \
-d '{"clienteId":"cli_4hd8s2","tipo":"decreto_ingiuntivo","titolo":"Fatture insolute — ottobre 2026","fatti":"Fatture scadute e non pagate; nessuna contestazione."}'
GET /lotti/{id}
Il lotto, i suoi numeri e le sue pratiche
Parameters
id required path | string L'id del lotto. |
|---|
Responses
- 200 { lotto: Lotto & { conteggi, minutiRimanenti }, anteprima, pratiche: Pratica[] }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Lotto non trovato, o non visibile alla chiave
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"lotto": {
"id": "lot_3m9x2a",
"numero": 7,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"titolo": "Fatture insolute — ottobre 2026",
"stato": "in_corso",
"creatoIl": "2026-11-08T09:30:00.000Z",
"avviatoIl": "2026-11-08T09:40:00.000Z",
"conclusoIl": null,
"archived": false,
"link": "https://app.trailgun.ai/batches/lot_3m9x2a",
"conteggi": {
"in_coda": 3,
"in_corso": 2,
"completato": 5,
"fallito": 0,
"totale": 10
},
"minutiRimanenti": 24
},
"anteprima": null,
"pratiche": [
{
"id": "job_8f2kq1x9",
"numero": 42,
"tipo": "decreto_ingiuntivo",
"clienteId": "cli_4hd8s2",
"lottoId": "lot_3m9x2a",
"titolo": "Alfa S.r.l. — fattura 128/2026",
"stato": "in_coda",
"fase": null,
"documenti": {
"totali": 0,
"lavorati": 0
},
"errore": null,
"origine": "lotto",
"creataIl": "2026-11-08T09:30:00.000Z",
"completataIl": null,
"archived": false,
"link": "https://app.trailgun.ai/jobs/job_8f2kq1x9"
}
]
}
curl https://app.trailgun.ai/api/v1/lotti/<id> \
-H "Authorization: Bearer tg_live_…"
PUT /lotti/{id}/archivio
Carica l'archivio del lotto: uno zip con uno zip (o una cartella) per pratica
Il corpo è lo zip, grezzo. Facoltativi: lotto.csv alla radice (archivio;titolo;fatti) e fatti.txt dentro ogni pratica. La risposta contiene l’anteprima: le pratiche trovate e quelle scartate, col motivo.
Parameters
id required path | string L'id del lotto. |
|---|---|
nome query | string Il nome del file, per riconoscerlo. Default lotto.zip. |
Body application/zip
Responses
- 200 { lotto: Lotto, anteprima }
- 400 Corpo assente o archivio non utilizzabile
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Lotto non trovato
- 409 Il lotto è già avviato: non si cambia più il suo archivio
- 413 Troppo grande
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
- 507 Spazio su disco insufficiente in questo momento: riprovare più tardi
curl -X PUT https://app.trailgun.ai/api/v1/lotti/<id>/archivio \
-H "Authorization: Bearer tg_live_…" \
-H "Content-Type: application/zip" \
--data-binary @lotto.zip
POST /lotti/{id}/avvia
Avvia il lotto: le pratiche vanno in coda
Parameters
id required path | string L'id del lotto. |
|---|
Body application/json
escludi | integer[] Le voci dell'anteprima (n) da non avviare. |
|---|---|
archiviAnnidati | boolean Cambia la scelta del lotto sugli zip dentro lo zip prima di avviare. |
Body example
{
"escludi": [
3
]
}
Responses
- 200 { lotto: Lotto }
- 400 Nessuna pratica da avviare
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Lotto non trovato
- 409 Già avviato o senza archivio
- 413 Una pratica oltre il limite
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
curl -X POST https://app.trailgun.ai/api/v1/lotti/<id>/avvia \
-H "Authorization: Bearer tg_live_…" \
-H "Content-Type: application/json" \
-d '{"escludi":[3]}'
Documenti e intake
Altri documenti a una pratica o a un lotto già creati, e l'esito di ogni invio. Serve l'intake acceso per lo studio.
POST /pratiche/{id}/documents
Manda documenti a una pratica già creata
I documenti entrano nella pratica dall'intake (lo stesso dell'indirizzo email della pratica, creato al primo invio). Una pratica conclusa li riceve subito; una in lavorazione li tiene in attesa (waiting) e li prende appena finisce. Serve l'intake acceso per lo studio.
Parameters
id required path | string L'id della pratica. |
|---|---|
Idempotency-Key header | string La stessa chiave due volte (con la stessa chiave API) dà un arrivo solo: la seconda risposta (200, header Idempotent-Replayed: true) è il primo arrivo. |
Body multipart/form-data
files | file[] I documenti: uno o più file nel campo files (anche files[]). Al massimo 20, 25 MB ciascuno. |
|---|---|
text | string Un testo che accompagna i documenti (da solo, senza file, diventa esso stesso un documento). |
Responses
- 200 Stessa Idempotency-Key: lo stesso arrivo di prima. Eccezione: un arrivo finito in errore senza documenti salvati (es. un riavvio) libera la chiave, e la ripetizione è un invio nuovo (202).
- 202 Ricevuto (
status: received): l'esito arriva col webhookintake.*o con GET /intakes/{id}/arrivals/{arrivalId} - 400 Nessun file né testo, più di 20 file,
refnon valido o Idempotency-Key oltre 200 caratteri - 401 Chiave assente, non valida o revocata.
- 403 L'intake non è attivo per lo studio (lo accende il backoffice di Trailgun) o è disattivato (
{ error }); oppure, dal controllo della chiave, l'utente non è più nello studio o il suo ruolo non lo consente ({ errore }) - 404 Pratica non trovato/a, o non visibile alla chiave
- 409 Idempotency-Key già usata per un altro invio
- 413 Un file oltre il limite per file (25 MB)
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"arrival": {
"id": "arr_7d1q8z",
"channel": "api",
"from": null,
"subject": null,
"ref": null,
"status": "received",
"reason": null,
"jobId": null,
"documents": [
{
"name": "estratto-conto.pdf",
"bytes": 182344
}
],
"createdAt": "2026-11-08T09:31:00.000Z",
"deliveredAt": null
},
"intake": {
"id": "int_5k2p9w",
"address": "intake-a8f3k2@mail.trailgun.ai",
"target": "job",
"jobId": "job_8f2kq1x9",
"batchId": null,
"clientId": "cli_4hd8s2",
"name": null,
"enabled": true,
"senders": [],
"createdAt": "2026-11-08T09:31:00.000Z",
"updatedAt": "2026-11-08T09:31:00.000Z"
}
}
curl -X POST https://app.trailgun.ai/api/v1/pratiche/<id>/documents \
-H "Authorization: Bearer tg_live_…" \
-H "Idempotency-Key: <idempotency-key>" \
-F files=@documento.pdf
POST /lotti/{id}/documents
Manda documenti a un lotto già creato
Con ref vanno alla pratica del lotto con quel riferimento; senza, il lotto decide (una pratica nuova del lotto).
Parameters
id required path | string L'id del lotto. |
|---|---|
Idempotency-Key header | string La stessa chiave due volte (con la stessa chiave API) dà un arrivo solo: la seconda risposta (200, header Idempotent-Replayed: true) è il primo arrivo. |
Body multipart/form-data
files | file[] I documenti: uno o più file nel campo files (anche files[]). Al massimo 20, 25 MB ciascuno. |
|---|---|
text | string Un testo che accompagna i documenti (da solo, senza file, diventa esso stesso un documento). |
ref | string Il riferimento di una pratica già esistente del lotto, cioè il suo numero (42 o trail42 per TRAIL-42; li elenca jobs in GET /intakes): i documenti vanno a quella pratica invece di aprirne una nuova. |
Responses
- 200 Stessa Idempotency-Key: lo stesso arrivo di prima. Eccezione: un arrivo finito in errore senza documenti salvati (es. un riavvio) libera la chiave, e la ripetizione è un invio nuovo (202).
- 202 Ricevuto (
status: received): l'esito arriva col webhookintake.*o con GET /intakes/{id}/arrivals/{arrivalId} - 400 Nessun file né testo, più di 20 file,
refnon valido o Idempotency-Key oltre 200 caratteri - 401 Chiave assente, non valida o revocata.
- 403 L'intake non è attivo per lo studio (lo accende il backoffice di Trailgun) o è disattivato (
{ error }); oppure, dal controllo della chiave, l'utente non è più nello studio o il suo ruolo non lo consente ({ errore }) - 404 Lotto non trovato/a, o non visibile alla chiave
- 409 Idempotency-Key già usata per un altro invio
- 413 Un file oltre il limite per file (25 MB)
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"arrival": {
"id": "arr_7d1q8z",
"channel": "api",
"from": null,
"subject": null,
"ref": null,
"status": "received",
"reason": null,
"jobId": null,
"documents": [
{
"name": "estratto-conto.pdf",
"bytes": 182344
}
],
"createdAt": "2026-11-08T09:31:00.000Z",
"deliveredAt": null
},
"intake": {
"id": "int_5k2p9w",
"address": "intake-a8f3k2@mail.trailgun.ai",
"target": "job",
"jobId": "job_8f2kq1x9",
"batchId": null,
"clientId": "cli_4hd8s2",
"name": null,
"enabled": true,
"senders": [],
"createdAt": "2026-11-08T09:31:00.000Z",
"updatedAt": "2026-11-08T09:31:00.000Z"
}
}
curl -X POST https://app.trailgun.ai/api/v1/lotti/<id>/documents \
-H "Authorization: Bearer tg_live_…" \
-H "Idempotency-Key: <idempotency-key>" \
-F files=@documento.pdf
GET /intakes
Gli intake di un cliente, di una pratica o di un lotto
Uno dei tre parametri è obbligatorio. Per i lotti, jobs elenca le pratiche del lotto col loro ref.
Parameters
clientId query | string |
|---|---|
jobId query | string |
batchId query | string |
Responses
- 200 { intakes: Intake[], enabled }
- 400 Manca clientId, jobId o batchId
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Cliente, pratica o lotto non trovato
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"intakes": [
{
"id": "int_5k2p9w",
"address": "intake-a8f3k2@mail.trailgun.ai",
"target": "job",
"jobId": "job_8f2kq1x9",
"batchId": null,
"clientId": "cli_4hd8s2",
"name": null,
"enabled": true,
"senders": [],
"createdAt": "2026-11-08T09:31:00.000Z",
"updatedAt": "2026-11-08T09:31:00.000Z"
}
],
"enabled": true
}
curl https://app.trailgun.ai/api/v1/intakes \
-H "Authorization: Bearer tg_live_…"
GET /intakes/{id}
Un intake e i suoi arrivi più recenti
Parameters
id required path | string L'id dell'intake. |
|---|---|
limit query | integer Quanti arrivi, i più recenti per primi. |
Responses
- 200 { intake, arrivals }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Non trovato
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"intake": {
"id": "int_5k2p9w",
"address": "intake-a8f3k2@mail.trailgun.ai",
"target": "job",
"jobId": "job_8f2kq1x9",
"batchId": null,
"clientId": "cli_4hd8s2",
"name": null,
"enabled": true,
"senders": [],
"createdAt": "2026-11-08T09:31:00.000Z",
"updatedAt": "2026-11-08T09:31:00.000Z"
},
"arrivals": [
{
"id": "arr_7d1q8z",
"channel": "api",
"from": null,
"subject": null,
"ref": null,
"status": "received",
"reason": null,
"jobId": null,
"documents": [
{
"name": "estratto-conto.pdf",
"bytes": 182344
}
],
"createdAt": "2026-11-08T09:31:00.000Z",
"deliveredAt": null
}
]
}
curl https://app.trailgun.ai/api/v1/intakes/<id> \
-H "Authorization: Bearer tg_live_…"
GET /intakes/{id}/arrivals/{arrivalId}
Lo stato di un arrivo (per chi non usa i webhook)
Parameters
id required path | string L'id dell'intake. |
|---|---|
arrivalId required path | string L'id dell'arrivo. |
Responses
- 200 { arrival }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 404 Non trovato
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"arrival": {
"id": "arr_7d1q8z",
"channel": "api",
"from": null,
"subject": null,
"ref": null,
"status": "delivered",
"reason": null,
"jobId": "job_8f2kq1x9",
"documents": [
{
"name": "estratto-conto.pdf",
"bytes": 182344
}
],
"createdAt": "2026-11-08T09:31:00.000Z",
"deliveredAt": "2026-11-08T09:32:10.000Z"
}
}
curl https://app.trailgun.ai/api/v1/intakes/<id>/arrivals/<arrivalId> \
-H "Authorization: Bearer tg_live_…"
Clienti e tipi
I clienti visibili all'utente della chiave e i tipi di atto che si possono aprire.
GET /tipi
I tipi di atto e cosa chiedono
Per ogni tipo: il nome, quando si usa, se i fatti sono obbligatori, se serve un questionario e quali opzioni accetta.
Responses
- 200 { tipi: TipoAtto[] }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 429 Oltre 120 richieste al minuto per questa chiave.
Response example
{
"tipi": [
{
"tipo": "decreto_ingiuntivo",
"nome": "Decreto ingiuntivo",
"quando": "Recupero di un credito con prova scritta verso un debitore in bonis: ricorso per decreto ingiuntivo.",
"fatti": "obbligatori",
"template": false,
"opzioni": {
"qa": true,
"raccoltaDati": true,
"giurisprudenza": true
}
}
]
}
curl https://app.trailgun.ai/api/v1/tipi \
-H "Authorization: Bearer tg_live_…"
GET /clienti
I clienti visibili all'utente della chiave
Parameters
q query | string Ricerca per nome o partita IVA. |
|---|
Responses
- 200 { clienti: Cliente[] }
- 401 Chiave assente, non valida o revocata.
- 403 L'utente della chiave non è più nello studio o è disattivato, oppure il suo ruolo non consente l'operazione (sola lettura; un operatore non crea pratiche né lotti).
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"clienti": [
{
"id": "cli_4hd8s2",
"numero": 12,
"nome": "Servicer Beta S.p.A.",
"partitaIva": "01234567890",
"citta": "Milano"
}
]
}
curl https://app.trailgun.ai/api/v1/clienti \
-H "Authorization: Bearer tg_live_…"
Audit
Chi ha fatto che cosa nello studio, col valore prima e dopo, per il SIEM dello studio. Solo con la chiave di un amministratore.
GET /audit
Il registro di audit dello studio (per il SIEM)
Gli eventi dello studio della chiave, dal più recente, a pagine con cursore: passa next come after per la pagina dopo. Solo con la chiave di un amministratore dello studio (403 altrimenti).
Parameters
from query | string Dal (millisecondi o data ISO). |
|---|---|
to query | string Al (millisecondi o data ISO). |
action query | auth.session.start | client.create | client.update | client.delete | client.visibility.update | client.members.update | matter.create | act.create | act.delete | act.archive | act.restore | act.redraft | act.text.update | act.playbook.update | act.actors.update | act.document.sign | external.request.open | external.request.download | external.request.move | external.request.comment | external.request.resend | external.account.register | external.account.login | external.account.delete | external.account.whatsapp.verify | external.account.whatsapp.remove | act.spending_limit.update | act.space.update | document.add | document.restore | user.invite | user.disable | user.enable | user.resend_invite | user.role.update | user.admin.update | user.permissions.update | org.update | settings.studio.update | settings.user.update | settings.platform.update | prompt.platform.update | prompt.studio_addition.update | api_key.create | api_key.update | api_key.revoke | platform.org.create | platform.org.update | platform.feature.update | platform.limits.update | platform.users.add | platform.site.update | platform.compliance_document.update | platform.audit.purge | outlook.connection.updated | outlook.connection.enabled | outlook.connection.disabled | outlook.connection.deleted | outlook.connection.secret_rotated | platform.outlook.enabled | platform.outlook.disabled | governance.owner_changed | document.injection_suspected | export.download | audit.export | data_export.requested | data_export.completed | data_export.failed | data_export.downloaded | data_export.deleted | data_export.expired | sso.connection.create | sso.connection.update | sso.connection.delete | sso.domain.add | sso.domain.remove | sso.sso_only.update | sso.jit_user_created | sso.jit_refused | sso.first_login | sso.login_refused | scim.enabled_changed | scim.token_created | scim.token_revoked | scim.default_role_changed | scim.group_role_changed | scim.user_created | scim.user_updated | scim.user_disabled | scim.user_enabled | scim.user_deleted | scim.group_created | scim.group_updated | scim.group_deleted | scim.group_members_changed | scim.role_changed | scim.role_change_blocked | scim.request_refused | regulatory_topic.create | regulatory_topic.update | regulatory_topic.delete | platform.regulatory_source.update | actor.create | actor.update | actor.archive | actor.restore | actor.person.erase | voice_note.create | voice_note.view | voice_note.audio_access | voice_note.update | voice_note.link | voice_note.delete | dictation.transcribe | space.create | space.rename | space.members.update | space.delete | transfer.settings.update | transfer.quota.update | transfer.sender.block | transfer.sender.unblock | transfer.revoke | transfer.abuse.update |
entity query | client | matter | act | document | user | org | settings | api_key | prompt | session | export | site | compliance_document | audit | data_export | sso | outlook_connection | agent | scim | regulatory_topic | regulatory_source | actor | space | external_request | external_account | voice_note | dictation | transfer | transfer_sender | transfer_abuse_report |
entityId query | string |
actor query | string L'id, l'email o il nome della chiave di chi ha agito. |
limit query | integer |
after query | string Il cursore next della pagina prima. |
Responses
- 200 { events: AuditEvent[], next }
- 400 Filtro o cursore non valido
- 401 Chiave assente, non valida o revocata.
- 403 La chiave non è di un amministratore dello studio, o l'utente della chiave non è più nello studio
- 429 Oltre 120 richieste al minuto per questa chiave.
- 500 Errore interno.
Response example
{
"events": [
{
"id": "aud_7Qp2x9",
"occurredAt": "2026-11-08T10:15:00.000Z",
"actor": {
"kind": "user",
"id": "usr_3kd9",
"label": "avvocato@studio.it"
},
"action": "client.visibility.update",
"entity": "client",
"entityId": "cli_4hd8s2",
"clientId": "cli_4hd8s2",
"before": {
"visibility": "org"
},
"after": {
"visibility": "privato"
},
"meta": null,
"ip": "203.0.113.5",
"userAgent": "Mozilla/5.0",
"hidden": false
}
],
"next": null
}
curl https://app.trailgun.ai/api/v1/audit \
-H "Authorization: Bearer tg_live_…"
Webhook
Se la chiave ha un webhook, Trailgun manda un POST firmato alla fine di ciò che la chiave ha creato e a ogni esito dell'intake.
Events
pratica.completatauna pratica creata dalla chiave (fuori da un lotto) è completatapratica.fallitauna pratica creata dalla chiave (fuori da un lotto) non è riuscitalotto.conclusoun lotto creato dalla chiave è finito (le sue pratiche non mandano un evento ciascuna)intake.consegnatoi documenti sono entrati nella praticaintake.in_attesala pratica è in lavorazione: i documenti entrano appena finisceintake.da_verificareuna mail da un mittente sconosciuto: l'avvocato approva o rifiuta in appintake.rifiutatoi documenti non sono stati accettati (motivo inarrival.reason)intake.errorela consegna non è riuscita (motivo inarrival.reason)
Signature and retries
Se la chiave ha un webhook, Trailgun manda un POST JSON { tipo, creatoIl, dati } con tipo = pratica.completata | pratica.fallita (pratiche fuori da un lotto) | lotto.concluso | intake.consegnato | intake.in_attesa | intake.da_verificare | intake.rifiutato | intake.errore. Gli eventi intake.* (dati: { arrival, intake, pratica? }) vanno alla chiave che ha creato la pratica o il lotto e a quella che ha mandato i documenti. Header Trailgun-Signature: t=<secondi>,v1=<hex>: HMAC-SHA256, col segreto del webhook, di <t>.<corpo>. Tre tentativi.