Reference · POST /v1/sites

Create site

Add a new site under a customer you have access to. business_name and address are required; everything else is optional. Requires the sites:write scope on your key. Useful when you onboard a new location and want to reference it in a job request immediately. (You can also create a site inline as part of POST /v1/jobs via the new_site field.)

Request

curl -X POST -H "Authorization: Bearer fi_pk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Depot — Brand Drive",
    "address": "Unit 3/24 Brand Dr, Pimpama QLD 4209",
    "first_name": "Jane",
    "last_name": "Patel",
    "mobile_number": "+61400000000",
    "email": "site@acme.example",
    "notes": "Roller door access on east side.",
    "external_id": "client-site-001"
  }' \
  https://<host>/v1/sites

Response

{ "id": "3065756" }

Fields

customer

string

Usually omit this — the gateway automatically sets the site’s owner to your account’s customer. Only relevant if your key has multiple customers in scope, in which case pass one of them (fetch valid IDs from /v1/customers).

business_namerequired

string

Display name for the site — what staff and field techs see. Brand + location works well for disambiguation. Example: `"Hungry Jacks — Swanston Street"`. ≤ 200 chars.

addressrequired

string

Postal/street address as a free-form string. Example: `"Unit 3/24 Brand Dr, Pimpama QLD 4209"`. ≤ 500 chars.

first_name

string

Primary contact at the site (e.g. site manager). ≤ 100 chars.

last_name

string

≤ 100 chars.

mobile_number

string

Contact phone in E.164 form is safest, but free-form is accepted. Example: `"+61400000000"`. ≤ 50 chars.

email

string

Contact email. ≤ 200 chars.

notes

string

Free-form notes about the site — access instructions, parking, gate codes. Visible to field techs. ≤ 2000 chars.

url

string

Optional URL — e.g. a link to the customer’s portal entry for this site. ≤ 500 chars.

external_id

string

Your own reference for the site — typically a record ID in your system. ≤ 36 chars.

Errors

400 invalid-body400 customer-not-in-scope401 unauthorized422 invalid-request429 rate-limited502 schema-drift

The new site appears in /v1/sites immediately and can be referenced as `site=` on POST /v1/jobs.