GeotechOS
Reference

API reference

Every path of the GeotechOS integration API, with its fields, types, limits and answers. Made from the OpenAPI document.

This page lists every path, the fields each one takes, and what it answers. It is made from the OpenAPI document, which the API checks requests against.

Every path starts with https://au.geotechos.com/api/integration/v1, or the address that Settings › API keys shows for your workspace. Send the headers from Authenticate on every request.

Note: Do not edit this page. Run scripts/docs-reference/api_reference.py after the API changes.

Who am I

Which integration a key belongs to, and what it can do.

GET /whoami

Check a key.

Which integration the key belongs to, the workspace, the account it acts as, and what it can do now.

Answers:

  • 200: The key and what it may do.
  • 401: No key, or an unknown key.

Clients

The companies you work for.

POST /clients

Create a Client.

Send an Idempotency-Key so a retried request cannot create a second record.

  • Idempotency-Key (header): optional
Field Type Required Notes
legal_name string yes up to 255 characters
trading_name string up to 255 characters
display_name string up to 255 characters
business_number string up to 30 characters
tax_id string up to 100 characters
industry string up to 255 characters
email email up to 255 characters
phone string up to 100 characters
website URL up to 255 characters
status active | lead | prospect | inactive
source string up to 100 characters
notes string up to 10000 characters
is_active boolean

Answers:

  • 201: The Client as stored.
  • 409: Conflicts with a record already here.
  • 422: Validation failed, or the key was reused for a different request.

GET /clients/{identifier}

Read a Client.

  • identifier (path): uuid:, ext:.

Answers:

  • 200: The Client as stored.
  • 404: Nothing here matches that identifier.

PUT /clients/{identifier}

Upsert a Client by your own id.

Creates on first call, updates after. The identifier must be ext:<your id>; anything else is refused so that "file my record" cannot be confused with "replace this one". If no mapping exists yet but an obvious match is already here, it is adopted and the response carries adopted: true.

  • identifier (path): ext:.
Field Type Required Notes
legal_name string yes up to 255 characters
trading_name string up to 255 characters
display_name string up to 255 characters
business_number string up to 30 characters
tax_id string up to 100 characters
industry string up to 255 characters
email email up to 255 characters
phone string up to 100 characters
website URL up to 255 characters
status active | lead | prospect | inactive
source string up to 100 characters
notes string up to 10000 characters
is_active boolean

Answers:

  • 200: The Client as stored, after updating or adopting.
  • 201: The Client as stored, newly created.
  • 409: That record is already mapped to a different id of yours.
  • 422: Validation failed, or the identifier was not ext:.

PATCH /clients/{identifier}

Update a Client.

Only the fields you send are changed.

  • identifier (path): uuid:, ext:.
Field Type Required Notes
legal_name string up to 255 characters
trading_name string up to 255 characters
display_name string up to 255 characters
business_number string up to 30 characters
tax_id string up to 100 characters
industry string up to 255 characters
email email up to 255 characters
phone string up to 100 characters
website URL up to 255 characters
status active | lead | prospect | inactive
source string up to 100 characters
notes string up to 10000 characters
is_active boolean

Answers:

  • 200: The Client as stored.
  • 404: Nothing here matches that identifier.
  • 422: Validation failed.

Client contacts

The people at those companies.

POST /client-contacts

Create a Client Contact.

Send an Idempotency-Key so a retried request cannot create a second record.

  • Idempotency-Key (header): optional
Field Type Required Notes
first_name string yes up to 100 characters
last_name string up to 100 characters
display_name string up to 255 characters
email email up to 255 characters
secondary_email email up to 255 characters
phone string up to 100 characters
alternate_phone string up to 100 characters
status active | lead | prospect | inactive
source string up to 100 characters
notes string up to 10000 characters
is_active boolean

Answers:

  • 201: The Client Contact as stored.
  • 409: Conflicts with a record already here.
  • 422: Validation failed, or the key was reused for a different request.

GET /client-contacts/{identifier}

Read a Client Contact.

  • identifier (path): uuid:, ext:.

Answers:

  • 200: The Client Contact as stored.
  • 404: Nothing here matches that identifier.

PUT /client-contacts/{identifier}

Upsert a Client Contact by your own id.

Creates on first call, updates after. The identifier must be ext:<your id>; anything else is refused so that "file my record" cannot be confused with "replace this one". If no mapping exists yet but an obvious match is already here, it is adopted and the response carries adopted: true.

  • identifier (path): ext:.
Field Type Required Notes
first_name string yes up to 100 characters
last_name string up to 100 characters
display_name string up to 255 characters
email email up to 255 characters
secondary_email email up to 255 characters
phone string up to 100 characters
alternate_phone string up to 100 characters
status active | lead | prospect | inactive
source string up to 100 characters
notes string up to 10000 characters
is_active boolean

Answers:

  • 200: The Client Contact as stored, after updating or adopting.
  • 201: The Client Contact as stored, newly created.
  • 409: That record is already mapped to a different id of yours.
  • 422: Validation failed, or the identifier was not ext:.

PATCH /client-contacts/{identifier}

Update a Client Contact.

Only the fields you send are changed.

  • identifier (path): uuid:, ext:.
Field Type Required Notes
first_name string up to 100 characters
last_name string up to 100 characters
display_name string up to 255 characters
email email up to 255 characters
secondary_email email up to 255 characters
phone string up to 100 characters
alternate_phone string up to 100 characters
status active | lead | prospect | inactive
source string up to 100 characters
notes string up to 10000 characters
is_active boolean

Answers:

  • 200: The Client Contact as stored.
  • 404: Nothing here matches that identifier.
  • 422: Validation failed.

Projects

Sites and contracts, with their client and contacts.

POST /projects

Create a Project.

Send an Idempotency-Key so a retried request cannot create a second record.

  • Idempotency-Key (header): optional
Field Type Required Notes
name string yes up to 255 characters
description string up to 20000 characters
soil_description string up to 20000 characters
contact_name string up to 50 characters
contact_email email up to 50 characters
contact_phone string up to 100 characters
address string up to 100 characters
address_line_2 string up to 100 characters
city string up to 50 characters
state string up to 50 characters
zip_code string up to 20 characters
country string up to 100 characters
latitude number -90 to 90
longitude number -180 to 180
status string up to 50 characters
is_active boolean
is_completed boolean
is_archived boolean
start_date time (ISO 8601 with offset)
due_date time (ISO 8601 with offset)
client reference: ext, uuid or number
number string Only for a key that keeps your project numbers (whoami: assigns_project_numbers), and then required on a new project. Kept exactly as given; it cannot be changed afterwards.; up to 40 characters
contacts list of reference: ext, uuid or number Client contacts on this project. Each is linked, or its link updated; a contact left out stays linked.; up to 50 items
contacts.ext string
contacts.uuid uuid
contacts.role string up to 100 characters
contacts.report_recipient boolean Sent the project's reports.
contacts.primary boolean

Answers:

  • 201: The Project as stored.
  • 409: Conflicts with a record already here.
  • 422: Validation failed, or the key was reused for a different request.

GET /projects/{identifier}

Read a Project.

  • identifier (path): uuid:, ext:, or number:.

Answers:

  • 200: The Project as stored.
  • 404: Nothing here matches that identifier.

PUT /projects/{identifier}

Upsert a Project by your own id.

Creates on first call, updates after. The identifier must be ext:<your id>; anything else is refused so that "file my record" cannot be confused with "replace this one". If no mapping exists yet but an obvious match is already here, it is adopted and the response carries adopted: true.

  • identifier (path): ext:.
Field Type Required Notes
name string yes up to 255 characters
description string up to 20000 characters
soil_description string up to 20000 characters
contact_name string up to 50 characters
contact_email email up to 50 characters
contact_phone string up to 100 characters
address string up to 100 characters
address_line_2 string up to 100 characters
city string up to 50 characters
state string up to 50 characters
zip_code string up to 20 characters
country string up to 100 characters
latitude number -90 to 90
longitude number -180 to 180
status string up to 50 characters
is_active boolean
is_completed boolean
is_archived boolean
start_date time (ISO 8601 with offset)
due_date time (ISO 8601 with offset)
client reference: ext, uuid or number
number string Only for a key that keeps your project numbers (whoami: assigns_project_numbers), and then required on a new project. Kept exactly as given; it cannot be changed afterwards.; up to 40 characters
contacts list of reference: ext, uuid or number Client contacts on this project. Each is linked, or its link updated; a contact left out stays linked.; up to 50 items
contacts.ext string
contacts.uuid uuid
contacts.role string up to 100 characters
contacts.report_recipient boolean Sent the project's reports.
contacts.primary boolean

Answers:

  • 200: The Project as stored, after updating or adopting.
  • 201: The Project as stored, newly created.
  • 409: That record is already mapped to a different id of yours.
  • 422: Validation failed, or the identifier was not ext:.

PATCH /projects/{identifier}

Update a Project.

Only the fields you send are changed.

  • identifier (path): uuid:, ext:, or number:.
Field Type Required Notes
name string up to 255 characters
description string up to 20000 characters
soil_description string up to 20000 characters
contact_name string up to 50 characters
contact_email email up to 50 characters
contact_phone string up to 100 characters
address string up to 100 characters
address_line_2 string up to 100 characters
city string up to 50 characters
state string up to 50 characters
zip_code string up to 20 characters
country string up to 100 characters
latitude number -90 to 90
longitude number -180 to 180
status string up to 50 characters
is_active boolean
is_completed boolean
is_archived boolean
start_date time (ISO 8601 with offset)
due_date time (ISO 8601 with offset)
client reference: ext, uuid or number
number string Only for a key that keeps your project numbers (whoami: assigns_project_numbers), and then required on a new project. Kept exactly as given; it cannot be changed afterwards.; up to 40 characters
contacts list of reference: ext, uuid or number Client contacts on this project. Each is linked, or its link updated; a contact left out stays linked.; up to 50 items
contacts.ext string
contacts.uuid uuid
contacts.role string up to 100 characters
contacts.report_recipient boolean Sent the project's reports.
contacts.primary boolean

Answers:

  • 200: The Project as stored.
  • 404: Nothing here matches that identifier.
  • 422: Validation failed.

Jobs

Visits and tasks on a project, with their schedule, crew and docket.

POST /jobs

Create a Job.

Send an Idempotency-Key so a retried request cannot create a second record.

  • Idempotency-Key (header): optional
Field Type Required Notes
title string yes up to 255 characters
job_type field_work | meeting | office | laboratory | other
is_billable boolean
scope_of_work string up to 20000 characters
scheduled_start_at time (ISO 8601 with offset)
scheduled_end_at time (ISO 8601 with offset)
started_at time (ISO 8601 with offset)
completed_at time (ISO 8601 with offset)
cancelled_at time (ISO 8601 with offset)
cancellation_reason string up to 2000 characters
contact_name string up to 50 characters
contact_email email up to 50 characters
contact_phone string up to 50 characters
internal_notes string up to 20000 characters
docket object The job's docket. Items replace the lines sent before; lines added in GeotechOS stay. A locked docket is refused (409).
docket.external_number string up to 60 characters
docket.visit_date day (YYYY-MM-DD)
docket.started_at time (ISO 8601 with offset)
docket.ended_at time (ISO 8601 with offset)
docket.field_notes string up to 10000 characters
docket.travel_hours number 0 to 100
docket.is_completed boolean
docket.items[] list Each with: name, description, quantity, unit, code
project reference: ext, uuid or number yes
assignee_emails list of email Matched to active accounts in this workspace. An address that matches nobody is refused, never ignored.

Answers:

  • 201: The Job as stored.
  • 409: Conflicts with a record already here.
  • 422: Validation failed, or the key was reused for a different request.

GET /jobs/{identifier}

Read a Job.

  • identifier (path): uuid:, ext:, or number:.

Answers:

  • 200: The Job as stored.
  • 404: Nothing here matches that identifier.

PUT /jobs/{identifier}

Upsert a Job by your own id.

Creates on first call, updates after. The identifier must be ext:<your id>; anything else is refused so that "file my record" cannot be confused with "replace this one". If no mapping exists yet but an obvious match is already here, it is adopted and the response carries adopted: true.

  • identifier (path): ext:.
Field Type Required Notes
title string yes up to 255 characters
job_type field_work | meeting | office | laboratory | other
is_billable boolean
scope_of_work string up to 20000 characters
scheduled_start_at time (ISO 8601 with offset)
scheduled_end_at time (ISO 8601 with offset)
started_at time (ISO 8601 with offset)
completed_at time (ISO 8601 with offset)
cancelled_at time (ISO 8601 with offset)
cancellation_reason string up to 2000 characters
contact_name string up to 50 characters
contact_email email up to 50 characters
contact_phone string up to 50 characters
internal_notes string up to 20000 characters
docket object The job's docket. Items replace the lines sent before; lines added in GeotechOS stay. A locked docket is refused (409).
docket.external_number string up to 60 characters
docket.visit_date day (YYYY-MM-DD)
docket.started_at time (ISO 8601 with offset)
docket.ended_at time (ISO 8601 with offset)
docket.field_notes string up to 10000 characters
docket.travel_hours number 0 to 100
docket.is_completed boolean
docket.items[] list Each with: name, description, quantity, unit, code
project reference: ext, uuid or number yes
assignee_emails list of email Matched to active accounts in this workspace. An address that matches nobody is refused, never ignored.

Answers:

  • 200: The Job as stored, after updating or adopting.
  • 201: The Job as stored, newly created.
  • 409: That record is already mapped to a different id of yours.
  • 422: Validation failed, or the identifier was not ext:.

PATCH /jobs/{identifier}

Update a Job.

Only the fields you send are changed.

  • identifier (path): uuid:, ext:, or number:.
Field Type Required Notes
title string up to 255 characters
job_type field_work | meeting | office | laboratory | other
is_billable boolean
scope_of_work string up to 20000 characters
scheduled_start_at time (ISO 8601 with offset)
scheduled_end_at time (ISO 8601 with offset)
started_at time (ISO 8601 with offset)
completed_at time (ISO 8601 with offset)
cancelled_at time (ISO 8601 with offset)
cancellation_reason string up to 2000 characters
contact_name string up to 50 characters
contact_email email up to 50 characters
contact_phone string up to 50 characters
internal_notes string up to 20000 characters
docket object The job's docket. Items replace the lines sent before; lines added in GeotechOS stay. A locked docket is refused (409).
docket.external_number string up to 60 characters
docket.visit_date day (YYYY-MM-DD)
docket.started_at time (ISO 8601 with offset)
docket.ended_at time (ISO 8601 with offset)
docket.field_notes string up to 10000 characters
docket.travel_hours number 0 to 100
docket.is_completed boolean
docket.items[] list Each with: name, description, quantity, unit, code
project reference: ext, uuid or number
assignee_emails list of email Matched to active accounts in this workspace. An address that matches nobody is refused, never ignored.

Answers:

  • 200: The Job as stored.
  • 404: Nothing here matches that identifier.
  • 422: Validation failed.

Staff accounts

Your staff, so jobs keep their crew.

PUT /users/{identifier}

Create or update a staff account by your own id.

Only for a key the office has given a role (whoami: adds_staff_accounts); otherwise 403. A new account gets that role, never full access, and no email: the person signs in with Aeflow by this address. An address with an account in another workspace is a 409.

  • identifier (path): ext:
Field Type Required Notes
email email yes One account per address across GeotechOS: an account already in this workspace is linked and left as the office set it.; up to 255 characters
first_name string yes up to 100 characters
last_name string up to 100 characters
phone string up to 50 characters
position string up to 100 characters
is_active boolean

Answers:

  • 200: Updated, or linked to an account already here.
  • 201: Created.
  • 403: This key does not add staff accounts.
  • 409: The address has an account in another workspace.
  • 422: Validation failed.