Form — Server-to-server

Create and manage practices directly from your backend, authenticating with the api_token (Bearer). Base URL: https://app.dokicasa.it.

Main endpoints

Method	Path	What it does
GET	/api/v3/catalog-forms	All available forms (services, contracts, bundles) with slug and form_url — public
GET	/api/list-form/canone-concordato-{city}	List the steps of the flow for a city
GET	/api/v3/form/{slug}	Schema (fields) of a form
POST	/api/v3/form/{slug}	Submit the form → creates a practice
PUT	/api/v3/form/{bundleUserServiceId}	Update an already submitted form
GET	/api/v3/user/{id}/services	List practices (filterable by external_id)
GET	/api/v3/practices/{practice}	Detail + status of a practice
GET	/api/v3/practices/{practice}/tasks	Tasks linked to the practice

0. Discover the available forms

A single public call returns every form, sorted by name:

curl https://app.dokicasa.it/api/v3/catalog-forms -H "Accept: application/json"

Each entry has kind (service / contract / bundle), name, slug and form_url. Bundles include steps (one form per step):

[
  { "kind": "service", "name": "Cadastral visura", "slug": "visura-catastale",
    "form_url": "/api/v3/form/visura-catastale", "steps": [] },
  { "kind": "bundle", "name": "Canone Concordato", "slug": "canone-concordato",
    "form_url": null, "steps": [
      { "step": 1, "name": "Contract", "type": "Contract",
        "slug": "contratto-locazione", "form_url": "/api/v3/form/contratto-locazione" }
    ] }
]

The interactive list (with copy-slug) is also in JavaScript SDK → Available forms.

1. Create a practice

PHP / Laravel

$res = Http::withToken(env('DOKICASA_TOKEN'))
    ->acceptJson()
    ->post('https://app.dokicasa.it/api/v3/form/locazione-ad-uso-abitativo-4-4', [
        'form' => [ /* ...field answers... */ ],
        'metadata' => [
            'external_id' => 'order_8842', // YOUR id, to look it up later
        ],
    ])
    ->json();

// $res['id'], $res['external_id']

Node.js

const res = await fetch(
  'https://app.dokicasa.it/api/v3/form/locazione-ad-uso-abitativo-4-4',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.DOKICASA_TOKEN}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({
      form: { /* ...answers... */ },
      metadata: { external_id: 'order_8842' },
    }),
  }
).then((r) => r.json())

cURL

curl -X POST \
  https://app.dokicasa.it/api/v3/form/locazione-ad-uso-abitativo-4-4 \
  -H "Authorization: Bearer $DOKICASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"form":{},"metadata":{"external_id":"order_8842"}}'

WARNING

POST /api/v3/form/{slug} may charge credit from the partner wallet. Check the balance before automating bulk creations.

2. Look up your practices

$practices = Http::withToken(env('DOKICASA_TOKEN'))
    ->acceptJson()
    ->get('https://app.dokicasa.it/api/v3/user/me/services', [
        'filter[external_id]' => 'order_8842',
    ])
    ->json();

3. Practice status and tasks

$id = 84213; // practice id or public uuid

$practice = Http::withToken(env('DOKICASA_TOKEN'))->acceptJson()
    ->get("https://app.dokicasa.it/api/v3/practices/{$id}")->json();
// $practice['status'] → e.g. WAITING / DOING / ...

$tasks = Http::withToken(env('DOKICASA_TOKEN'))->acceptJson()
    ->get("https://app.dokicasa.it/api/v3/practices/{$id}/tasks")->json();
// $tasks['tasks'] → Activity (type=TASK) with status TO_DO / DOING / DONE

TIP

With the uuid instead of the numeric id, GET /practices/{practice} and .../tasks are public (no Bearer): handy for a read-only link. With the numeric id you need Bearer and ownership of the practice.

OpenAPI reference

The full spec (parameters, schemas, responses) is below, generated from the same spec also published at api.dokicasa.it/api-doc/.