Skip to content
Trailgun
ITEN Log in

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 querystring Solo le pratiche di questo cliente.
lottoId querystring Solo le pratiche di questo lotto.
stato queryin_coda | in_corso | completata | fallita
limite queryinteger Quante pratiche, le più recenti per prime.
archived querytrue | 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 requiredstring
tipodecreto_ingiuntivo | assessment | escussione_garanzia | insinuazione_passivo | remediation_datatape | affitto_ramo_azienda | analisi_faldone Default decreto_ingiuntivo.
fattistring Le note per gli agenti (obbligatorie, tranne per l'assessment e l'analisi del faldone).
titolostring
templateIdstring 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).
practiceTemplateIdstring 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.
leaseDeedauto | preliminary | final Affitto di ramo d'azienda: il documento da redigere. Default auto (dalla proposta economica: rinnovo → definitivo, nuovo → preliminare).
followedPeoplestring 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.
qaLevelstring
giurisprudenzatrue | false
raccoltaDatitrue | false
comunicazionispenta | semiautomatica | automatica
archiviAnnidatitrue | false Apre anche gli zip dentro lo zip (fino a tre livelli). Default true.
archivio requiredfile 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 pathstring 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 pathstring 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 pathstring 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 requiredstring
tipodecreto_ingiuntivo | assessment | escussione_garanzia | insinuazione_passivo | remediation_datatape | affitto_ramo_azienda | analisi_faldone Default decreto_ingiuntivo.
titolostring
fattistring Le note comuni a tutte le pratiche.
templateIdstring
practiceTemplateIdstring 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.
matterIdstring La pratica dello studio (fascicolo) a cui legare le pratiche del lotto.
opzioniOpzioni 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 pathstring 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 pathstring L'id del lotto.
nome querystring 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 pathstring L'id del lotto.

Body application/json

escludiinteger[] Le voci dell'anteprima (n) da non avviare.
archiviAnnidatiboolean 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 pathstring L'id della pratica.
Idempotency-Key headerstring 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

filesfile[] I documenti: uno o più file nel campo files (anche files[]). Al massimo 20, 25 MB ciascuno.
textstring 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 webhook intake.* o con GET /intakes/{id}/arrivals/{arrivalId}
  • 400 Nessun file né testo, più di 20 file, ref non 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 pathstring L'id del lotto.
Idempotency-Key headerstring 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

filesfile[] I documenti: uno o più file nel campo files (anche files[]). Al massimo 20, 25 MB ciascuno.
textstring Un testo che accompagna i documenti (da solo, senza file, diventa esso stesso un documento).
refstring 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 webhook intake.* o con GET /intakes/{id}/arrivals/{arrivalId}
  • 400 Nessun file né testo, più di 20 file, ref non 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 querystring
jobId querystring
batchId querystring

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 pathstring L'id dell'intake.
limit queryinteger 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 pathstring L'id dell'intake.
arrivalId required pathstring 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 querystring 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 querystring Dal (millisecondi o data ISO).
to querystring Al (millisecondi o data ISO).
action queryauth.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 queryclient | 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 querystring
actor querystring L'id, l'email o il nome della chiave di chi ha agito.
limit queryinteger
after querystring 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.completata una pratica creata dalla chiave (fuori da un lotto) è completata
  • pratica.fallita una pratica creata dalla chiave (fuori da un lotto) non è riuscita
  • lotto.concluso un lotto creato dalla chiave è finito (le sue pratiche non mandano un evento ciascuna)
  • intake.consegnato i documenti sono entrati nella pratica
  • intake.in_attesa la pratica è in lavorazione: i documenti entrano appena finisce
  • intake.da_verificare una mail da un mittente sconosciuto: l'avvocato approva o rifiuta in app
  • intake.rifiutato i documenti non sono stati accettati (motivo in arrival.reason)
  • intake.errore la consegna non è riuscita (motivo in arrival.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.