GuardDog API Reference

Overview

The GuardDog API is an organization-scoped REST API. It lets you read and replace a branch's escalation contacts and read, assign, or clear the driver for a unit. Requests and responses use JSON.

Organization scoped

An API key can access only the organization that created it.

Production endpoint

https://app.guarddog.live/api/v1

Authentication

Create a key from API keys in GuardDog. Send it as a bearer token in the Authorization header on every request. Keys begin with gd_live_ and are shown only once when created.

HTTP header

Authorization: Bearer gd_live_your_api_key

Treat API keys like passwords. Keep them out of client-side code and source control, store them in a secrets manager, and rotate or revoke them from GuardDog settings when needed.

Quickstart

1
Create and store a key
Create a key in your organization settings and save the secret immediately.
2
Set your environment values
Use a branch ID from your GuardDog organization.
3
Make your first request
Retrieve the branch's active contacts in escalation order.

Terminal

export GUARDDOG_API_KEY="gd_live_your_api_key"
export BRANCH_ID="your_branch_id"

curl "https://app.guarddog.live/api/v1/branches/$BRANCH_ID/call-tree" \
  -H "Authorization: Bearer $GUARDDOG_API_KEY"

GET/branches/{branchId}/call-tree

Get a branch call tree

Returns active, branch-scoped contacts sorted by ascending priority. Corporate contacts are not included.

Path parameters

Field	Type	Required	Description
branchId	string	Yes	The ID of a branch in the authenticated organization.

Request

cURL

curl "https://app.guarddog.live/api/v1/branches/$BRANCH_ID/call-tree" \
  -H "Authorization: Bearer $GUARDDOG_API_KEY"

200 response

JSON

{
  "branch_id": "5f6a1c1d-2d27-4a9f-912a-85815cc976ce",
  "contacts": [
    {
      "id": "9b3c90ab-2d2c-4a1e-bf82-d8ac06f6a5d3",
      "branch_id": "5f6a1c1d-2d27-4a9f-912a-85815cc976ce",
      "organization_id": "org_2y...",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone_number": "+15551234567",
      "email": "jane@example.com",
      "job_title": "Branch Manager",
      "priority": 0,
      "is_corporate": false,
      "archived": false,
      "created_at": "2026-05-26T18:00:00.000Z",
      "updated_at": "2026-05-26T18:00:00.000Z"
    }
  ]
}

PUT/branches/{branchId}/call-tree

Replace a branch call tree

Replaces the branch's entire call tree with the contacts provided. Existing branch contacts are archived so historical call records stay intact. Corporate contacts are never changed by this endpoint.

To manage contacts manually instead, open Branches in GuardDog.

This is a full replacement operation. Sending an empty contacts array clears the branch call tree.

Request body

Field	Type	Required	Description
contacts	array	Yes	Up to 50 contacts.
first_name	string	Yes	Contact first name.
last_name	string	Yes	Contact last name.
phone_number	string	Yes	US phone number in any common format; stored as E.164.
email	string	No	A valid email address when provided.
job_title	string	No	The contact’s job title.
priority	integer	Yes	Zero or greater. Lower values are contacted first.

Request

cURL

curl -X PUT "https://app.guarddog.live/api/v1/branches/$BRANCH_ID/call-tree" \
  -H "Authorization: Bearer $GUARDDOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "contacts": [
      {
        "first_name": "Jane",
        "last_name": "Doe",
        "phone_number": "+15551234567",
        "email": "jane@example.com",
        "job_title": "Branch Manager",
        "priority": 0
      }
    ]
  }'

200 response

Returns the same shape as the GET operation with the newly created contacts.

JSON

{
  "branch_id": "5f6a1c1d-2d27-4a9f-912a-85815cc976ce",
  "contacts": [
    {
      "id": "9b3c90ab-2d2c-4a1e-bf82-d8ac06f6a5d3",
      "branch_id": "5f6a1c1d-2d27-4a9f-912a-85815cc976ce",
      "organization_id": "org_2y...",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone_number": "+15551234567",
      "email": "jane@example.com",
      "job_title": "Branch Manager",
      "priority": 0,
      "is_corporate": false,
      "archived": false,
      "created_at": "2026-05-26T18:00:00.000Z",
      "updated_at": "2026-05-26T18:00:00.000Z"
    }
  ]
}

GET/units/{unitId}/driver

Get a unit driver

Returns the driver assigned to a unit. The driver value is null when no driver is assigned. When that unit has an incident, the assigned driver receives a $1.99 phone call in parallel with the call tree. Drivers are not sent the call-tree text message.

Path parameters

Field	Type	Required	Description
unitId	string	Yes	The ID of a unit in the authenticated organization.

Request

cURL

curl "https://app.guarddog.live/api/v1/units/$UNIT_ID/driver" \
  -H "Authorization: Bearer $GUARDDOG_API_KEY"

200 response

JSON

{
  "unit_id": "7c1d8584-8cb3-4b30-92af-283126f589b2",
  "driver": {
    "id": "a2b947c4-844d-4ca7-9cf7-cbd367098d83",
    "branch_id": "5f6a1c1d-2d27-4a9f-912a-85815cc976ce",
    "organization_id": "org_2y...",
    "first_name": "Sam",
    "last_name": "Rivera",
    "phone_number": "+15559876543",
    "archived": false,
    "created_at": "2026-06-24T18:00:00.000Z",
    "updated_at": "2026-06-24T18:00:00.000Z"
  }
}

PUT/units/{unitId}/driver

Set or clear a unit driver

Assigns a driver to the unit or clears the assignment. When assigning, GuardDog reuses an active driver in the same branch with the same phone number; otherwise it creates one. Phone numbers are normalized to E.164.

Driver fields

Field	Type	Required	Description
driver	object \| null	Yes	Driver details to assign, or null to clear the unit.
first_name	string	Yes	Driver first name.
last_name	string	Yes	Driver last name.
phone_number	string	Yes	US phone number in any common format; stored as E.164.

Assign a driver

cURL

curl -X PUT "https://app.guarddog.live/api/v1/units/$UNIT_ID/driver" \
  -H "Authorization: Bearer $GUARDDOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "driver": {
      "first_name": "Sam",
      "last_name": "Rivera",
      "phone_number": "(555) 987-6543"
    }
  }'

Clear a driver

cURL

curl -X PUT "https://app.guarddog.live/api/v1/units/$UNIT_ID/driver" \
  -H "Authorization: Bearer $GUARDDOG_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "driver": null }'

200 response

JSON

{
  "unit_id": "7c1d8584-8cb3-4b30-92af-283126f589b2",
  "driver": {
    "id": "a2b947c4-844d-4ca7-9cf7-cbd367098d83",
    "branch_id": "5f6a1c1d-2d27-4a9f-912a-85815cc976ce",
    "organization_id": "org_2y...",
    "first_name": "Sam",
    "last_name": "Rivera",
    "phone_number": "+15559876543",
    "archived": false,
    "created_at": "2026-06-24T18:00:00.000Z",
    "updated_at": "2026-06-24T18:00:00.000Z"
  }
}

Errors

Errors use a JSON object with an error message. Validation responses also include details describing the invalid fields.

Status	Meaning
400	The JSON request body could not be parsed.
401	The API key is missing, invalid, or revoked.
404	The branch or unit was not found in your organization.
422	The body failed validation. Inspect `details` for field-level issues.

422 response

{
  "error": "Invalid body",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "contacts": ["Too big: expected array to have <=50 items"]
    }
  }
}

Need help?

Contact support@guarddog.live and include the endpoint, HTTP status, and approximate request time. Never send your API key.

GuardDog API reference

Overview

Authentication

Quickstart

Create and store a key

Set your environment values

Make your first request

Get a branch call tree

Path parameters

Request

200 response

Replace a branch call tree

Request body

Request

200 response

Get a unit driver

Path parameters

Request

200 response

Set or clear a unit driver

Driver fields

Assign a driver

Clear a driver

200 response

Errors

Need help?