# Rehearse import

Rehearse import is a command in the HeadHoncho API. Run the whole import for real inside one step that is then thrown away, and say what it would have landed and refused. Nothing is kept.

Page: https://headhoncho.app/docs/api/rehearse_import | Part of the HeadHoncho API docs: https://headhoncho.app/docs/api | Machine-readable: https://headhoncho.app/docs/api/openapi.json | Everything in one file: https://headhoncho.app/docs/api/llms-full.txt

## The request

Reference for **Rehearse import**, HeadHoncho API v1. It is a command, sent to the base address `https://api.headhoncho.app`.

`POST /api/v1/commands/rehearse-import`

The key needs the **Jobs** area at **read**. An answered call costs 1 credit; a refusal costs nothing. See [credits](https://headhoncho.app/docs/api/errors#credits).

It runs the app's own command `rehearse-import`. Send an `Idempotency-Key` header with every call: the same key with the same body returns the first answer and runs nothing twice. See [the model](https://headhoncho.app/docs/api/model#idempotency).

## Parameters

| Name | Kind | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `company_id` | id, in the JSON body | Yes | The company the jobs land in. From Who am I. | `cmp_14f5` |
| `plan` | text, in the JSON body | Yes | The staged files as a JSON list. Each item: staging_id (from Stage an import file), half (jobs, money or payments), mapping (field to column numbers) and date_order. | `[{"staging_id": "k3Zp...", "half": "jobs", "mapping": {"ref": [0], "client_name": [1]}}]` |
| `status_map` | object, in the JSON body | No | The file's status word to a target, from Map statuses. | `{"Done": "st_06"}` |
| `type_map` | object, in the JSON body | No | The file's job-type word to a target, from Map job types. | `{"Local Move": "jt_02"}` |
| `worker_map` | object, in the JSON body | No | The file's technician name to one of our worker ids, or null to leave that technician's jobs unassigned. | `{"Dana R.": "wrk_3b90"}` |
| `decisions` | object, in the JSON body | No | Your answers where the two files disagree, from Preview an import's decisions: the decision key to the side chosen, jobs (the jobs file's value) or money (the money file's). | `{"W-1001:status": "money"}` |

## Try it with your key

Paste your key and change the values. The box builds the call as a cURL line and a fetch line, ready to copy. It never sends anything itself.

Paste your key on the web page and it fills a cURL line and a fetch line with your key and the example values. The page never sends the key anywhere. The same lines with a placeholder key are under Examples below.

## What comes back

accepted and position, rehearsal true, then the same report Commit an import gives: imported, skipped and refused per row, counts, gaps, finance and payments counts, and figures, the totals the files themselves state.

It never deletes anything. It changes only what the command names, and it writes the change to the job's history with who asked for it.

## Every field in the answer

Types are read from the example answer. Money is a plain number in the company's currency. A time carries its offset from UTC (`Z` is UTC). Ids are opaque text. A field with no line of its own here has its name spelled out; the common fields mean the same on every page.

| Field | Type | Meaning |
| --- | --- | --- |
| `accepted` | true or false | True when the command ran. A command that cannot run is an error instead. |
| `position` | whole number | Where the change landed in the event log. Pass it as `after` on a read to see your own write. |
| `rehearsal` | true or false | The rehearsal. |
| `imported` | list of objects | The imported. |
| `imported[].line` | whole number | The line. |
| `imported[].ticket` | text | The job number the ticket shows. |
| `imported[].number` | whole number | The number people say out loud, such as the job number. |
| `imported[].gaps` | list | The gaps. |
| `skipped` | list | The skipped. |
| `refused` | list of objects | The refused. |
| `refused[].line` | whole number | The line. |
| `refused[].ticket` | text | The job number the ticket shows. |
| `refused[].reasons` | list of text | The reasons. |
| `counts` | object | The counts. |
| `counts.imported` | whole number | The imported. |
| `counts.skipped` | whole number | The skipped. |
| `counts.refused` | whole number | The refused. |
| `counts.incomplete` | whole number | The incomplete. |
| `examples` | whole number | The examples. |
| `finance` | object | The finance. |
| `finance.imported` | list | The imported. |
| `finance.skipped` | list | The skipped. |
| `finance.refused` | list | The refused. |
| `finance.counts` | object | The counts. |
| `finance.counts.imported` | whole number | The imported. |
| `finance.counts.skipped` | whole number | The skipped. |
| `finance.counts.refused` | whole number | The refused. |
| `payments` | object | The payments. |
| `payments.imported` | list | The imported. |
| `payments.skipped` | list | The skipped. |
| `payments.refused` | list | The refused. |
| `payments.counts` | object | The counts. |
| `payments.counts.imported` | whole number | The imported. |
| `payments.counts.skipped` | whole number | The skipped. |
| `payments.counts.refused` | whole number | The refused. |
| `payments.counts.amount` | money (decimal as text) | The amount. In the company's currency. |
| `figures` | object | The figures. |
| `figures.money` | value or null | The money. |
| `figures.payments` | value or null | The payments. |
| `figures.span` | value or null | The span. |

## Why it exists

A preview adds up the rows. A rehearsal runs the real commands, so a row that only fails inside a command shows up here and not after the import.

## What it leaves out

The app also reads the Finance panel back after a rehearsal. The public API does not: the Finance panel is the app's own screen. Compare figures with Job money after a real import instead.

## Safe to repeat

Nothing is kept, so run it as often as you like. Needs read access to Jobs, as in the app.

## Errors that apply

| Code | Status | What it means |
| --- | --- | --- |
| [`missing_key`](https://headhoncho.app/docs/api/errors#missing_key) | 401 | Send your key as Authorization: Bearer hh_live_... |
| [`unknown_key`](https://headhoncho.app/docs/api/errors#unknown_key) | 401 | That key is not one we issued, or it was revoked. |
| [`no_access`](https://headhoncho.app/docs/api/errors#no_access) | 403 | This credential does not reach that. Ask the person who made it for access. |
| [`not_found`](https://headhoncho.app/docs/api/errors#not_found) | 404 | No such record in the companies this credential reaches. |
| [`out_of_scope`](https://headhoncho.app/docs/api/errors#out_of_scope) | 404 | No such company in the companies this credential reaches. |
| [`invalid`](https://headhoncho.app/docs/api/errors#invalid) | 422 | Some fields were refused. See fields. |
| [`missing_idempotency_key`](https://headhoncho.app/docs/api/errors#missing_idempotency_key) | 400 | Send an Idempotency-Key header on every command. |
| [`idempotency_mismatch`](https://headhoncho.app/docs/api/errors#idempotency_mismatch) | 409 | This Idempotency-Key was used with a different body. |
| [`idempotency_in_progress`](https://headhoncho.app/docs/api/errors#idempotency_in_progress) | 409 | A command with this Idempotency-Key is still running. Wait a moment and send it again. |
| [`no_credits`](https://headhoncho.app/docs/api/errors#no_credits) | 402 | Out of credits. Top up on Settings › Credits, or turn on auto top-up. |

## Related

- [List import systems](https://headhoncho.app/docs/api/list_import_systems): The systems a book can be imported from, and for each the steps to get its file out, what the file cannot carry, and which one this workspace used last.
- [Get import fields](https://headhoncho.app/docs/api/get_import_fields): Every field an import reads, for the jobs file and the money file: its label, its tier and what leaving it blank costs.
- [Get import template](https://headhoncho.app/docs/api/get_import_template): A CSV to fill in, with every column the import reads and three example rows, for the jobs file, the money file or a payments list.
- [Stage import](https://headhoncho.app/docs/api/stage_import): Send one export file (CSV or Excel) and get back what each column looks like and the mapping we propose. Nothing is imported yet.
- [List import statuses](https://headhoncho.app/docs/api/list_import_statuses): The status words the staged files use, how many rows carry each, and which of our statuses each should land on. Nothing is written.
- [List import job types](https://headhoncho.app/docs/api/list_import_job_types): The job-type words the staged files use, how many rows carry each, and which of our job types each should land on. Nothing is written.
- [Preview import](https://headhoncho.app/docs/api/preview_import): Read the staged files against this workspace and say what an import would do, row by row: what lands, what is already here, what is refused and why.
- [Commit import](https://headhoncho.app/docs/api/commit_import): Import every clean row of the staged files: the jobs, then the money on them. Rows already here are skipped, so sending it twice adds nothing.
- The same records in the app: [the Jobs panel](https://headhoncho.app/docs/jobs).
- How the API fits together: [the model](https://headhoncho.app/docs/api/model), [API keys](https://headhoncho.app/docs/api/keys), [errors](https://headhoncho.app/docs/api/errors) and [the MCP server](https://headhoncho.app/docs/api/mcp).

## Examples

### Answer

```json
{
  "accepted": true,
  "position": 88611,
  "rehearsal": true,
  "imported": [
    {
      "line": 2,
      "ticket": "W-1001",
      "number": 1301,
      "gaps": []
    }
  ],
  "skipped": [],
  "refused": [
    {
      "line": 9,
      "ticket": "W-1008",
      "reasons": [
        "Status \"Archived\" is retired."
      ]
    }
  ],
  "counts": {
    "imported": 118,
    "skipped": 0,
    "refused": 2,
    "incomplete": 5
  },
  "examples": 0,
  "finance": {
    "imported": [],
    "skipped": [],
    "refused": [],
    "counts": {
      "imported": 0,
      "skipped": 0,
      "refused": 0
    }
  },
  "payments": {
    "imported": [],
    "skipped": [],
    "refused": [],
    "counts": {
      "imported": 0,
      "skipped": 0,
      "refused": 0,
      "amount": "0.00"
    }
  },
  "figures": {
    "money": null,
    "payments": null,
    "span": null
  }
}
```

### cURL

```bash
curl -X POST "https://api.headhoncho.app/api/v1/commands/rehearse-import" \
  -H "Authorization: Bearer hh_live_..." \
  -H "Idempotency-Key: 6f1d2c9e-1b7a-4c1e-9a52-0d3f8e4b7a10" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": "cmp_14f5",
  "plan": "[{\"staging_id\": \"k3Zp...\", \"half\": \"jobs\", \"mapping\": {\"ref\": [0], \"client_name\": [1]}}]",
  "status_map": {
    "Done": "st_06"
  },
  "type_map": {
    "Local Move": "jt_02"
  },
  "worker_map": {
    "Dana R.": "wrk_3b90"
  },
  "decisions": {
    "W-1001:status": "money"
  }
}'
```

### Python

```python
import requests
import uuid

response = requests.post(
    "https://api.headhoncho.app/api/v1/commands/rehearse-import",
    headers={
        "Authorization": "Bearer hh_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "company_id": "cmp_14f5",
        "plan": "[{\"staging_id\": \"k3Zp...\", \"half\": \"jobs\", \"mapping\": {\"ref\": [0], \"client_name\": [1]}}]",
        "status_map": {
            "Done": "st_06",
        },
        "type_map": {
            "Local Move": "jt_02",
        },
        "worker_map": {
            "Dana R.": "wrk_3b90",
        },
        "decisions": {
            "W-1001:status": "money",
        },
    },
)
response.raise_for_status()
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.headhoncho.app/api/v1/commands/rehearse-import", {
  method: "POST",
  headers: {
    Authorization: "Bearer hh_live_...",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "company_id": "cmp_14f5",
    "plan": "[{\"staging_id\": \"k3Zp...\", \"half\": \"jobs\", \"mapping\": {\"ref\": [0], \"client_name\": [1]}}]",
    "status_map": {
      "Done": "st_06"
    },
    "type_map": {
      "Local Move": "jt_02"
    },
    "worker_map": {
      "Dana R.": "wrk_3b90"
    },
    "decisions": {
      "W-1001:status": "money"
    }
  }),
});
const data = await response.json();
console.log(data);
```

### Your AI

```text
Tool: rehearse_import
Arguments: company_id (id, required), plan (text, required), status_map (object, optional), type_map (object, optional), worker_map (object, optional), decisions (object, optional)
Access: read on Jobs
Hints: readOnly=false, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, rehearse import with company_id cmp_14f5 and plan [{"staging_id": "k3Zp...", "half": "jobs", "mapping": {"ref": [0], "client_name": [1]}}]."
```