Home service API

Visits at the customer’s address — who goes, when they arrive, signature and photos.

Module code field_service · 5 actions · 1 data models · 7 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: field_service (everything), field_service:read (read only) or field_service:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

field_service.advance

Update the visit — On the way, arrived, work started — in that order.

Needs field_service:write · changes data

• Canonical address: POST /api/v1/actions/field_service.advance

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: field_service.en_route, field_service.arrived, field_service.started

What it writes: field_visit (update) — Moves the status and stamps the time

curl -X POST https://app.getera.io/api/v1/field_visits/FIELD_VISIT_ID/actions/advance \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"en_route"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.en_route",
    "field_service.arrived",
    "field_service.started"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.advance("FIELD_VISIT_ID", {
  to: "en_route"
})

era field_visits advance FIELD_VISIT_ID \
  --to "en_route"

{
  "name": "era__field_service__advance",
  "arguments": {
    "visitId": "FIELD_VISIT_ID",
    "to": "en_route"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold field_service:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 visit_not_found, visit_closed, wrong_order · 429 slow down

field_service.cancel_visit

Call off the visit — Takes a visit off the route. The booking itself is not cancelled.

Needs field_service:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/field_service.cancel_visit

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: field_service.visit_cancelled

What it writes: field_visit (update) — Moves it to cancelled

curl -X POST https://app.getera.io/api/v1/field_visits/FIELD_VISIT_ID/actions/cancel_visit \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"note":"Why"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.visit_cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.cancelVisit("FIELD_VISIT_ID", {
  note: "Why"
})

era field_visits cancel_visit FIELD_VISIT_ID \
  --note "Why"

{
  "name": "era__field_service__cancel_visit",
  "arguments": {
    "visitId": "FIELD_VISIT_ID",
    "note": "Why"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold field_service:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 visit_not_found, visit_closed · 429 slow down

field_service.complete

Finish the visit — Closes the visit with notes, the customer’s signature and photos.

Needs field_service:write · changes data

• Canonical address: POST /api/v1/actions/field_service.complete

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: field_service.completed

What it writes: field_visit (update) — Completes it with its proof of work

curl -X POST https://app.getera.io/api/v1/field_visits/FIELD_VISIT_ID/actions/complete \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"notes":"What was done"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.completed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.complete("FIELD_VISIT_ID", {
  notes: "What was done"
})

era field_visits complete FIELD_VISIT_ID \
  --notes "What was done"

{
  "name": "era__field_service__complete",
  "arguments": {
    "visitId": "FIELD_VISIT_ID",
    "notes": "What was done"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold field_service:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 visit_not_found, visit_closed, not_started, signature_required, file_not_found · 429 slow down

field_service.dispatch

Dispatch a visit — Puts a home-service booking on somebody’s route, at an address inside the service area.

Needs field_service:write · reaches outside (sends, publishes or charges)

• Canonical address: POST /api/v1/actions/field_service.dispatch

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: field_service.dispatched

What it writes: field_visit (insert) — Opens the visit

curl -X POST https://app.getera.io/api/v1/field_visits/actions/dispatch \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"appointmentId":"APPOINTMENT_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.dispatched"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.dispatch({
  appointmentId: "APPOINTMENT_ID"
})

era field_visits dispatch \
  --appointment-id "APPOINTMENT_ID"

{
  "name": "era__field_service__dispatch",
  "arguments": {
    "appointmentId": "APPOINTMENT_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold field_service:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 appointment_not_found, appointment_closed, already_dispatched, address_not_found, not_home_visit, outside_service_area, provider_cannot_perform · 429 slow down

field_service.reassign

Send somebody else — Gives an open visit to another member who delivers the service.

Needs field_service:write · changes data

• Canonical address: POST /api/v1/actions/field_service.reassign

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: field_service.reassigned

What it writes: field_visit (update) — Changes who goes

curl -X POST https://app.getera.io/api/v1/field_visits/FIELD_VISIT_ID/actions/reassign \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"memberUserId":"MEMBER_USER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "field_service.reassigned"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.fieldVisits.reassign("FIELD_VISIT_ID", {
  memberUserId: "MEMBER_USER_ID"
})

era field_visits reassign FIELD_VISIT_ID \
  --member-user-id "MEMBER_USER_ID"

{
  "name": "era__field_service__reassign",
  "arguments": {
    "visitId": "FIELD_VISIT_ID",
    "memberUserId": "MEMBER_USER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold field_service:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 visit_not_found, visit_closed, provider_cannot_perform · 429 slow down

Data models

FieldVisit

Table field_visit · Resource field_visits

• GET /api/v1/field_visits
• GET /api/v1/field_visits/{id}

Primary key: id

Unique: appointment_id

Checks:

• CHECK ((length(btrim(address)) > 0))
• CHECK (((status = 'cancelled'::text) = (cancelled_at IS NOT NULL)))
• CHECK (((status = 'completed'::text) = (completed_at IS NOT NULL)))

Events

Workflows and webhooks react to these events.