Work with records

Jobs and dockets

Schedule a job on a project, give it a crew, and send its docket with the visit times and the work done. Cancel instead of delete.

A job is a visit or a task on a project. It has a schedule, a crew and a docket: the record of the visit and the work done.

Send a job

curl -s -X PUT "$GEOTECHOS_URL/jobs/ext:J-88421" \
  -H "Authorization: Bearer $GEOTECHOS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Compaction testing, lot 3",
    "project": {"ext": "P-500"},
    "job_type": "field_work",
    "scope_of_work": "Nuclear density tests on the subgrade, lot 3.",
    "scheduled_start_at": "2026-11-03T07:00:00+11:00",
    "scheduled_end_at": "2026-11-03T12:00:00+11:00",
    "contact_name": "Sam Site",
    "contact_phone": "0400 000 000",
    "assignee_emails": ["[email protected]"]
  }'

Field	Notes
`title`	Required
`project`	Required on a new job. A reference to the project
`job_type`	`field_work`, `laboratory`, `office`, `meeting` or `other`
`scope_of_work`, `internal_notes`	Free text
`scheduled_start_at`, `scheduled_end_at`	When the job is booked. The end cannot be before the start
`started_at`, `completed_at`	When the work started and finished
`cancelled_at`, `cancellation_reason`	When and why the job was cancelled
`contact_name`, `contact_email`, `contact_phone`	The person to meet on site
`is_billable`	`false` for work you do not charge for
`assignee_emails`	The crew. See below
`docket`	The visit and the work done. See below

A new job gets its number from the project (G-0042-001) and a docket, the same as a job made in GeotechOS.

The job's status

GeotechOS works out the status from the times. You do not send a status.

You send	The job shows as
Only `scheduled_start_at`	Scheduled
`started_at`	In progress
`completed_at`	Completed
`cancelled_at`	Cancelled

To take a job back from cancelled, send "cancelled_at": null.

The crew

assignee_emails is the list of people on the job. Each email must belong to an active account in your workspace. An email that matches nobody is refused with 422, so that a job does not arrive with nobody on it.

The list replaces the crew each time you send it. Send [] to take everyone off. Leave the field out to keep the crew as it is.

To make the accounts from your system, see Staff accounts.

The docket

docket writes the visit and its lines on the job's docket.

{
  "docket": {
    "external_number": "D-5521",
    "visit_date": "2026-11-03",
    "started_at": "2026-11-03T07:10:00+11:00",
    "ended_at": "2026-11-03T11:40:00+11:00",
    "field_notes": "Six tests on lot 3. All passed.",
    "travel_hours": 1.5,
    "is_completed": true,
    "items": [
      {"name": "Nuclear density test", "quantity": 6, "unit": "test", "code": "ND-01"},
      {"name": "Travel", "quantity": 1.5, "unit": "h"}
    ]
  }
}

items replaces the lines that you sent before. Lines that the office added in GeotechOS stay.
A code that matches a service in the workspace's catalogue links the line to it. GeotechOS sets the prices.
A docket that is locked in GeotechOS, because it was signed or invoiced, is refused with 409.

Cancel a job

There is no delete. When a job is cancelled or deleted in your system, send:

curl -s -X PATCH "$GEOTECHOS_URL/jobs/ext:J-88421" \
  -H "Authorization: Bearer $GEOTECHOS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"cancelled_at": "2026-11-02T16:30:00+11:00", "cancellation_reason": "Client postponed the pour."}'