# Create job

Create job is a command in the HeadHoncho API. Open a job or a lead in one company: the customer, the address, and optionally the job type, the time window and the technician.

Page: https://headhoncho.app/docs/api/create_job | Part of the HeadHoncho API docs: https://headhoncho.app/docs/api | Machine-readable: https://headhoncho.app/docs/api/openapi.json

## The request

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

`POST /api/v1/commands/create-job`

The key or app needs the **Jobs** area at **do**. It counts as a write call: 60 a minute for each key or connected app. See [rate limits](https://headhoncho.app/docs/api/errors#rate-limits).

It runs the app's own command `create-job`. 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 | From Who am I. | `cmp_14f5` |
| `client_name` | text, in the JSON body | Yes | The customer, as they gave it. | `R. Azoulay` |
| `client_phone` | text, in the JSON body | Yes | Any format; stored as E.164. | `+12175550142` |
| `address` | object, in the JSON body | Yes | line1, city, state and postal_code. line2 is optional. | `{"line1": "2590 Main St", "city": "Bloomington", "state": "IL", "postal_code": "61701"}` |
| `job_type_id` | id, in the JSON body | No | From Who am I. | `jt_02` |
| `scheduled_start` | datetime, in the JSON body | No | ISO 8601, with scheduled_end. | `2026-10-16T09:00:00-05:00` |
| `scheduled_end` | datetime, in the JSON body | No | ISO 8601. The end of the window. | `2026-10-16T11:00:00-05:00` |
| `quoted_price` | money, in the JSON body | No | The price quoted, a number. | `1450` |
| `worker_id` | id, in the JSON body | No | Assigns the technician now. | `wrk_3b90` |
| `notes` | text, in the JSON body | No | Anything the crew should know. | `Two flights of stairs` |
| `intent` | text, in the JSON body | No | create (default) opens a job; draft opens a lead; dispatch opens it and sends the ticket to the technician. One of `create`, `draft`, `dispatch`. | `create` |

## What comes back

accepted, job_id, number, and position: the event position, usable as after= on the next read so you see your own write. A missing fact the app would hold on Draft is refused here with 422 naming the field.

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.

## 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. |
| [`expired_token`](https://headhoncho.app/docs/api/errors#expired_token) | 401 | That token has expired. Refresh it, or connect the app again. |
| [`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. |
| [`read_only`](https://headhoncho.app/docs/api/errors#read_only) | 403 | This credential may read this area but not change it. |
| [`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. |
| [`rate_limited`](https://headhoncho.app/docs/api/errors#rate_limited) | 429 | Too many calls this minute. Wait and try again. |

## Related

- [Update job](https://headhoncho.app/docs/api/update_job): Change a job's facts: the customer, the address, the schedule, the price, the job type or the notes. Only the fields you send change.
- [Change job status](https://headhoncho.app/docs/api/change_job_status): Move a job to another status by its name, slug or id. The move lands in the job's history with who asked for it.
- [Assign worker](https://headhoncho.app/docs/api/assign_worker): Put a technician or subcontractor on a job. If Job follow-up is on, the automation acts on it at once, as it would from the app.
- [Unassign worker](https://headhoncho.app/docs/api/unassign_worker): Take a technician or subcontractor off a job. The ticket's cancellation reaches them the way it does from the app.
- [Add job note](https://headhoncho.app/docs/api/add_job_note): Add a note to a job. It appends to the job's log and never overwrites.
- 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,
  "job_id": "job_1203",
  "number": 1203,
  "position": 88411,
  "status": {
    "id": "st_02",
    "name": "Scheduled",
    "slug": "scheduled"
  }
}
```

### cURL

```bash
curl -X POST "https://api.headhoncho.app/api/v1/commands/create-job" \
  -H "Authorization: Bearer hh_live_..." \
  -H "Idempotency-Key: 6f1d2c9e-1b7a-4c1e-9a52-0d3f8e4b7a10" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": "cmp_14f5",
  "client_name": "R. Azoulay",
  "client_phone": "+12175550142",
  "address": {
    "line1": "2590 Main St",
    "city": "Bloomington",
    "state": "IL",
    "postal_code": "61701"
  },
  "job_type_id": "jt_02",
  "scheduled_start": "2026-10-16T09:00:00-05:00",
  "scheduled_end": "2026-10-16T11:00:00-05:00",
  "quoted_price": 1450,
  "worker_id": "wrk_3b90",
  "notes": "Two flights of stairs",
  "intent": "create"
}'
```

### Python

```python
import requests
import uuid

response = requests.post(
    "https://api.headhoncho.app/api/v1/commands/create-job",
    headers={
        "Authorization": "Bearer hh_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "company_id": "cmp_14f5",
        "client_name": "R. Azoulay",
        "client_phone": "+12175550142",
        "address": {
            "line1": "2590 Main St",
            "city": "Bloomington",
            "state": "IL",
            "postal_code": "61701",
        },
        "job_type_id": "jt_02",
        "scheduled_start": "2026-10-16T09:00:00-05:00",
        "scheduled_end": "2026-10-16T11:00:00-05:00",
        "quoted_price": 1450,
        "worker_id": "wrk_3b90",
        "notes": "Two flights of stairs",
        "intent": "create",
    },
)
response.raise_for_status()
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.headhoncho.app/api/v1/commands/create-job", {
  method: "POST",
  headers: {
    Authorization: "Bearer hh_live_...",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "company_id": "cmp_14f5",
    "client_name": "R. Azoulay",
    "client_phone": "+12175550142",
    "address": {
      "line1": "2590 Main St",
      "city": "Bloomington",
      "state": "IL",
      "postal_code": "61701"
    },
    "job_type_id": "jt_02",
    "scheduled_start": "2026-10-16T09:00:00-05:00",
    "scheduled_end": "2026-10-16T11:00:00-05:00",
    "quoted_price": 1450,
    "worker_id": "wrk_3b90",
    "notes": "Two flights of stairs",
    "intent": "create"
  }),
});
const data = await response.json();
console.log(data);
```

### Your AI

```text
Tool: create_job
Arguments: company_id (id, required), client_name (text, required), client_phone (text, required), address (object, required), job_type_id (id, optional), scheduled_start (datetime, optional), scheduled_end (datetime, optional), quoted_price (money, optional), worker_id (id, optional), notes (text, optional), intent (text, optional)
Access: do on Jobs
Hints: readOnly=false, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, create job with company_id cmp_14f5 and client_name R. Azoulay and client_phone +12175550142 and address {"line1": "2590 Main St", "city": "Bloomington", "state": "IL", "postal_code": "61701"} and job_type_id jt_02."
```