Commit import

The request

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

POST /api/v1/commands/commit-import

The key needs the Jobs area at do. An answered call costs 1 credit; a refusal costs nothing. See credits.

It runs the app's own command commit-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.

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"}`
`system`	text, in the JSON body	No	The system the file came from, a key from Import sources. The answers are remembered for it.	`workiz`

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.

Your API key company_id (required, id) plan (required, text) status_map (optional, object) type_map (optional, object) worker_map (optional, object) decisions (optional, object) system (optional, text)

Your key stays in this page and is never sent anywhere. Copy the line below and run it yourself.

What comes back

accepted and position, then per row what landed: imported (line, ticket, new job number, gaps), skipped (already here) and refused (with the reasons), counts, gaps, finance and payments (their own imported, skipped, refused and counts), and figures. The answer is 201 when anything landed.

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.
`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.

Safe to send twice

Every job is stored under its reference from the old system, or a stand-in made from the row's own facts. A row already imported is skipped, so a second commit of the same files lands nothing new. The staged file lives for an hour; after that Commit answers that the upload expired and you stage it again.

Run Rehearse first

Rehearse an import runs the same code and keeps nothing.

What the app does that this leaves out

The app can also close the imported balances in the same step. That option is not offered here; use Close a balance afterwards.

Mapping is remembered

With system, the status, job-type and column answers are saved for the next import from that system, as in the app.

Errors that apply

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

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: 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: 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: 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: 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: 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: 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.
Rehearse import: 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.
The same records in the app: the Jobs panel.
How the API fits together: the model, API keys, errors and the MCP server.

Answer cURL Python JavaScript Your AI

{
  "accepted": true,
  "position": 88611,
  "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 -X POST "https://api.headhoncho.app/api/v1/commands/commit-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"
  },
  "system": "workiz"
}'

import requests
import uuid

response = requests.post(
    "https://api.headhoncho.app/api/v1/commands/commit-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",
        },
        "system": "workiz",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.headhoncho.app/api/v1/commands/commit-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"
    },
    "system": "workiz"
  }),
});
const data = await response.json();
console.log(data);

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