Get started

Your first integration with cURL

Send a client, a project and a job to GeotechOS in three cURL requests, then send them again to see that nothing is made twice.

This page sends a client, a project and a job, in that order, with cURL. For the same steps in Python, see Python examples. Each request uses the id your own system gives the record. Run the requests twice: the second time, GeotechOS updates the records and makes nothing new.

Before you start

Get an API key.
Set two environment variables in your terminal:

export GEOTECHOS_URL="https://au.geotechos.com/api/integration/v1"
export GEOTECHOS_API_KEY="<your API key>"

1. Send the client

curl -s -X PUT "$GEOTECHOS_URL/clients/ext:C-19" \
  -H "Authorization: Bearer $GEOTECHOS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"legal_name": "Example Developments Pty Ltd", "email": "[email protected]"}'

ext:C-19 is the id of the client in your system. GeotechOS answers 201 Created the first time and 200 OK after that.

If GeotechOS already has a client with this legal name, it attaches your id to that client instead of making a second one. The answer then has "adopted": true.

2. Send the project

A project names its client with the same id.

curl -s -X PUT "$GEOTECHOS_URL/projects/ext:P-500" \
  -H "Authorization: Bearer $GEOTECHOS_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Estate Stage 2",
    "address": "14 Sample Road",
    "city": "Parramatta",
    "state": "NSW",
    "client": {"ext": "C-19"}
  }'

GeotechOS gives the project its number, for example G-0042, and sends it back in data.number. People quote this number on the phone and on reports.

3. Send the job

A job names its project. It has a schedule and, if you want, a crew.

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"},
    "scheduled_start_at": "2026-11-03T07:00:00+11:00",
    "scheduled_end_at": "2026-11-03T12:00:00+11:00",
    "assignee_emails": ["[email protected]"]
  }'

The job gets a number from its project (G-0042-001) and a docket, the same as a job made in GeotechOS. Send each time with its offset from UTC. GeotechOS stores the moment it names.

Each email in assignee_emails must belong to an active account in your workspace. An unknown address is refused, so that a job does not arrive with nobody on it.

4. Read the job back

curl -s "$GEOTECHOS_URL/jobs/ext:J-88421" \
  -H "Authorization: Bearer $GEOTECHOS_API_KEY" \
  -H "Accept: application/json"

{
  "data": {
    "resource": "jobs",
    "uuid": "01a2b3c4-…",
    "number": "G-0042-001",
    "title": "Compaction testing, lot 3",
    "job_type": "field_work",
    "scheduled_start_at": "2026-11-02T20:00:00+00:00",
    "scheduled_end_at": "2026-11-03T01:00:00+00:00",
    "cancelled_at": null,
    "project": { "uuid": "01a2b3c5-…", "number": "G-0042" },
    "docket": { "number": "G-0042-001", "visit_date": null, "is_locked": false, "items": [] },
    "assignee_emails": ["[email protected]"]
  },
  "external_references": [ { "provider": "website", "external_id": "J-88421" } ]
}

Times come back in UTC.

5. Run it again

Send the three PUT requests again. Each answers 200 OK, and GeotechOS has one client, one project and one job. Build your integration on this: when a record changes in your system, send it again with PUT.