Stage import

The request

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

POST /api/v1/commands/stage-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 stage-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
`filename`	text, in the JSON body	Yes	The file's name, with its extension.	`jobs.csv`
`content_base64`	text, in the JSON body	Yes	The file's bytes, base64 encoded. Up to 25 MB once decoded.	`UmVmLENsaWVudCxQaG9uZQ...`
`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`
`half`	text, in the JSON body	No	jobs (default) or money. One of `jobs`, `money`.	`jobs`
`shape`	text, in the JSON body	No	For the money half: auto (default), money (one row per job) or payments (one row per payment). One of `auto`, `money`, `payments`.	`auto`

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 filename (required, text) content_base64 (required, text) system (optional, text) half (optional, text) shape (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, position, staging_id (use it in plan), name, identified (the system it looks like, or null), columns_seen, rows_seen, and for a file we map: columns (name, samples, field, confidence, reason), mapping, date_order, missing_required, questions and counts. A Uleadz export is recognized outright and answers native true with its row count.

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.
`staging_id`	id (text)	The id of the staging.
`name`	text	The name, as the app shows it.
`identified`	text	The identified.
`columns_seen`	whole number	The columns seen.
`rows_seen`	whole number	The rows seen.
`native`	true or false	The native.
`half`	text	One of `jobs`, `money`.
`shape`	text	One of `auto`, `money`, `payments`.
`label`	text	The name the app shows for it.
`columns`	list of objects	The columns.
`columns[].index`	whole number	The index.
`columns[].name`	text	The name, as the app shows it.
`columns[].samples`	list of text	The samples.
`columns[].filled`	whole number	The filled.
`columns[].total`	whole number	The total, in the company's currency.
`columns[].field`	text	The field.
`columns[].field_label`	text	The field label.
`columns[].tier`	text	The tier.
`columns[].confidence`	text	The confidence.
`columns[].reason`	text	The reason given.
`mapping`	object	The mapping.
`mapping.ref`	list	The ref.
`date_order`	object	The date order.
`missing_required`	list	The missing required.
`questions`	list	The questions.
`counts`	object	The counts.
`counts.matched`	whole number	The matched.
`counts.guessed`	whole number	The guessed.
`counts.unmatched`	whole number	The unmatched.

A staged file is not a job

The file is held for an hour and is gone after that. Nothing is written to the books until Commit an import. The position in the answer is the latest event, since staging adds none.

Over MCP

The file travels inside the call, so keep it small. The REST door takes the same JSON body.

Personal details

The sample values printed beside each column are customer data. When the credential hides personal details they are left out.

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.
`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.
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.
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.
How the API fits together: the model, API keys, errors and the MCP server.

Answer cURL Python JavaScript Your AI

{
  "accepted": true,
  "position": 88611,
  "staging_id": "k3Zp9aQ1",
  "name": "jobs.csv",
  "identified": "workiz",
  "columns_seen": 9,
  "rows_seen": 120,
  "native": false,
  "half": "jobs",
  "shape": "jobs",
  "label": "Jobs file",
  "columns": [
    {
      "index": 0,
      "name": "Job ID",
      "samples": [
        "W-1001",
        "W-1002"
      ],
      "filled": 120,
      "total": 120,
      "field": "ref",
      "field_label": "Ref",
      "tier": "required",
      "confidence": "name",
      "reason": ""
    }
  ],
  "mapping": {
    "ref": [
      0
    ]
  },
  "date_order": {},
  "missing_required": [],
  "questions": [],
  "counts": {
    "matched": 8,
    "guessed": 1,
    "unmatched": 0
  }
}

curl -X POST "https://api.headhoncho.app/api/v1/commands/stage-import" \
  -H "Authorization: Bearer hh_live_..." \
  -H "Idempotency-Key: 6f1d2c9e-1b7a-4c1e-9a52-0d3f8e4b7a10" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "jobs.csv",
  "content_base64": "UmVmLENsaWVudCxQaG9uZQ...",
  "system": "workiz",
  "half": "jobs",
  "shape": "auto"
}'

import requests
import uuid

response = requests.post(
    "https://api.headhoncho.app/api/v1/commands/stage-import",
    headers={
        "Authorization": "Bearer hh_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "filename": "jobs.csv",
        "content_base64": "UmVmLENsaWVudCxQaG9uZQ...",
        "system": "workiz",
        "half": "jobs",
        "shape": "auto",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.headhoncho.app/api/v1/commands/stage-import", {
  method: "POST",
  headers: {
    Authorization: "Bearer hh_live_...",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "filename": "jobs.csv",
    "content_base64": "UmVmLENsaWVudCxQaG9uZQ...",
    "system": "workiz",
    "half": "jobs",
    "shape": "auto"
  }),
});
const data = await response.json();
console.log(data);

Tool: stage_import
Arguments: filename (text, required), content_base64 (text, required), system (text, optional), half (text, optional), shape (text, optional)
Access: do on Jobs
Hints: readOnly=false, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, stage import with filename jobs.csv and content_base64 UmVmLENsaWVudCxQaG9uZQ... and system workiz."