Work with records

Address and write records

Name a GeotechOS record by your own id, its uuid or its number, and create or update it with PUT, POST, PATCH and GET.

This page tells you how to name a record in a request, and which method to use to make, change and read it.

Name a record

A record has three names. Use the one you have.

Name	Example	Use it when
`ext:`	`ext:J-88421`	It is the id in your own system. Use this for everything you send
`uuid:`	`uuid:01a2b3c4-…`	You have the uuid from an earlier answer
`number:`	`number:G-0042`	You have the project or job number that people quote

Your id may contain a slash. ext:2026/41 is one id.

Ids belong to your integration's provider slug. Your client C-19 and another system's client C-19 are different records. A project P-1 and a client P-1 from your system are also different.

Choose a method

Method	Path	What it does
`PUT`	`/{resource}/ext:{your id}`	Makes the record, or updates it if it is there. Use this for a sync
`POST`	`/{resource}`	Makes a new record. Send an `Idempotency-Key` header
`PATCH`	`/{resource}/{name}`	Changes only the fields you send
`GET`	`/{resource}/{name}`	Reads one record

PUT: make or update by your id

PUT is safe to send again. If a request times out, send it again: GeotechOS updates the record that the first request made.

curl -s -X PUT "$GEOTECHOS_URL/client-contacts/ext:K-7" \
  -H "Authorization: Bearer $GEOTECHOS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Sam", "last_name": "Site", "email": "[email protected]"}'

POST: make a record with no id of your own

Send a unique Idempotency-Key. If you send the same request again with the same key, GeotechOS sends back the first answer and makes nothing new.

curl -s -X POST "$GEOTECHOS_URL/clients" \
  -H "Authorization: Bearer $GEOTECHOS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b7e-4d0a-4c8e-9a5b-1d2e3f4a5b6c" \
  -d '{"legal_name": "Walk-in Client Pty Ltd"}'

The same key with a different body is refused with 422.

PATCH: change some fields

curl -s -X PATCH "$GEOTECHOS_URL/jobs/number:G-0042-001" \
  -H "Authorization: Bearer $GEOTECHOS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_start_at": "2026-11-04T07:00:00+11:00"}'

Send references, not ids

A record that points to another record uses a reference with one of ext, uuid or number:

{ "project": { "ext": "P-500" } }

The other record must be there first. GeotechOS does not make it for you. Send the client before the project, and the project before the job.

What comes back

{
  "data": { "resource": "projects", "uuid": "…", "number": "G-0042", "name": "…" },
  "external_references": [ { "provider": "website", "external_id": "P-500" } ],
  "adopted": true
}

data is the record. It has no database ids.
external_references lists every id this record has, in every system that sent it.
adopted shows only when your request attached to a record that was already in GeotechOS.

Fields

Send only the fields you know. A field you leave out keeps its value. A field you send as null is cleared.

Times are ISO 8601 with an offset, for example 2026-11-03T07:00:00+11:00. GeotechOS stores the moment and answers in UTC. Days, such as a project's start_date, are 2026-11-03.

The API reference lists every field, its type and its limits.