Connect Crisphive to n8n

By the end of this guide your n8n workflows can find a caller, book and confirm a field job at a chosen time, and start automatically when a job is completed or a customer is created in Crisphive.

n8n is a workflow automation tool: you connect boxes (called nodes) so that something happening in one app does something in another. Crisphive is a field operations platform that schedules your technicians with constraint-based scheduling on a deterministic solver. The Crisphive nodes for n8n are free and open source (n8n-nodes-crisphive on npm, MIT licence).

Three words you will meet below, in plain language: an API key is a long password that lets a program act for your business in Crisphive. A webhook is Crisphive calling a web address when something happens, so n8n hears about it instantly. MCP (Model Context Protocol) is the standard AI assistants use to discover and call tools — it lets an n8n AI Agent use Crisphive by itself.

What you can do

Before you start

• A Crisphive account with Developer access. By default only the business Owner has it. An Owner can grant the Developer module to another group in Settings → Permissions.
• A self-hosted n8n, version 1.x or 2.x, where you are the owner or an admin (only they can install community nodes). The AI Agent option needs an n8n version whose MCP Client Tool offers HTTP Streamable as the Server Transport.
• For the trigger only: your n8n must be reachable from the internet over HTTPS (Crisphive has to call it). On a laptop, use a tunnel and set n8n’s WEBHOOK_URL to the public address — see the trigger section.
• Every job type you will book has a default duration (Crisphive → Settings → Job Types). The built-in “General” type already has one (60 minutes) and is used when you do not choose a type.
• About 15 minutes for the actions, 10 more for the trigger.

Step 1 — Create a Crisphive API key

Start with a test key (it begins with chsk_test_). It works only on your business’s Rehearsal copy — the sandbox, with test data — so nothing you do reaches a real customer or technician. You create a live key at the end (Go live).

Step 2 — Install the Crisphive node in n8n

Step 3 — Add the Crisphive API credential

A credential is where n8n stores your API key, so every Crisphive node can use it without you pasting the key again.

Book and Confirm Job

This is the operation most workflows need. Add a Crisphive node, choose the Crisphive sandbox credential and set Operation to Book and Confirm Job. The Customer field decides which other fields appear.

A successful run returns one item like this:

{
  "job_id": "7b2f0c1e-3a44-4d1b-9a5e-0e6f1c2d3b4a",
  "short_code": "REQ-CA-YCNFQUUV",
  "customer_id": "c4d1a9e2-8f3b-4c6d-a1e2-5f7b9c0d1e2f",
  "customer_url": "https://crisphive.com/…",
  "confirmed": true,
  "scheduled_at": "2026-10-06T14:00:00Z",
  "assigned_technician_id": "1e9d7c5b-3a2f-4e1d-8c7b-6a5f4e3d2c1b"
}

• scheduled_at in the answer is in UTC (Z). 14:00 UTC is 10:00 in Ottawa in October — the same moment you asked for.
• short_code is the human-friendly job reference to send to the customer or a team channel.
• When confirmed is false, the job was saved but no technician can take it at that time. The answer carries a refusal object (for example "error_code": "JOB_REQUEST_NO_TECHNICIAN_AVAILABLE") and the job waits in the coordinator’s queue in the dashboard. Route it to a person — do not run the booking again.

Find Customer by Phone

The match is exact on the stored number. The node returns one item with a customers list (up to 5) and a meta object. Use {{ $json.customers.length }} in an If node: 1 means you found the caller, 0 means a new caller. Each customer carries id, full_name, tier, status, request_count and last_request_at — the list does not repeat the phone and email.

Create Customer

If you add neither a phone nor an email, the node stops with “Add a Phone or an Email under Additional Fields” before calling Crisphive. The output is { "customer_id": "…" }. A customer created this way has no address yet, so book them with New or Returning Caller (which sends the address), not with their ID.

Get Job and List Job Types

• Get Job — one required field, Job ID: the job’s UUID (job_id from Book and Confirm Job, or object.id from the trigger). Returns the full job: short_code, current_status, schedule, assignment, customer (name, phone, email), address, job_type_name, description.
• List Job Types — no fields. Returns your active job types with their IDs and default durations. Copy an id into Book and Confirm Job → Additional Fields → Job Type ID.

Crisphive Trigger — start a workflow on an event

The Crisphive Trigger node is instant: when you activate the workflow, n8n registers a webhook in Crisphive; when you deactivate it, n8n removes it. Crisphive then calls n8n within seconds of each event.

• The key needs the trigger scopes. Subscribing and removing the webhook needs developer_manage_api_keys, and listing the events needs developer_view. A restricted key without them is refused when you activate the workflow (API_KEY_SCOPE_INSUFFICIENT); it can still run the Crisphive actions. Creating such a key in the dashboard needs Developer access, which by default only the Owner has.
• Public HTTPS address. Crisphive must be able to reach n8n. On a server, set WEBHOOK_URL to your public n8n address (for example https://n8n.yourcompany.com/) and, behind a reverse proxy, N8N_PROXY_HOPS=1. On a laptop, run a tunnel and set WEBHOOK_URL to the tunnel address — and open n8n on that address, not on localhost.
• Permissions decide the events. customer.* needs customers_view, job_request.* needs job_view, technician.* needs team_view. An event the key cannot read is refused with WEBHOOK_EVENT_NOT_PERMITTED, naming the missing permission.
• Up to 25 active webhooks per environment per business. Every active trigger uses one; deactivating frees it.

Each event becomes one item:

{
  "event_id": "evt_…",
  "type": "job_request.completed",
  "object": {
    "id": "7b2f0c1e-3a44-4d1b-9a5e-0e6f1c2d3b4a",
    "short_code": "REQ-CA-YCNFQUUV",
    "current_status": { "key": "completed", "display_name": "Completed" },
    "customer": { "name": "Alex Martin", "phone": "+16135550177", "email": "alex.martin@example.com" },
    "address": { "line": "145 Laurier Avenue West", "…": "…" },
    "schedule": { "scheduled_at": "2026-10-06T14:00:00Z", "…": "…" }
  }
}

• Security. Every delivery carries a Crisphive-Signature header (HMAC-SHA256 of the exact request body with the subscription’s secret). The node checks it, refuses anything unsigned or older than 5 minutes with 401, and never starts the workflow for a forged call. Crisphive’s first message, a ping, is answered and ignored.
• Lifetime. The node asks for the maximum secret lifetime, 365 days. After that Crisphive disables the webhook and emails the Owner; deactivate and reactivate the workflow to subscribe again. Put the date in your calendar.
• A subscription stops by itself when the API key that created it is revoked. If you replace the key, deactivate and reactivate every workflow that has a Crisphive Trigger.

Use Crisphive from an n8n AI Agent

There are two ways. Choose option A if you installed the community node. Choose option B if you are on n8n Cloud or want the agent to pick from the Crisphive MCP tools itself.

Option A — the Crisphive node as a tool.

Option B — the MCP Client Tool (no installation).

System prompt for a booking agent (replace the bracketed parts):

You book service visits for [Business name], a [trade] company in [city].
Times are in [Business timezone, e.g. America/Toronto].

1. Ask for the customer's phone number and look them up with "Find Customer
   by Phone" (E.164, e.g. +16135550177). If one customer comes back, greet
   them by name. Never guess between several matches.
2. Always ask for and confirm the service address for THIS visit (street,
   city, postal code), and spell the customer's name back before booking.
3. Ask what the problem is; it becomes the job description.
4. Agree a start time. Send it as the business's local time with no offset,
   e.g. 2026-10-06T10:00:00.
5. Book once with "Book and Confirm Job", Customer = New or Returning Caller,
   with the name, phone (or email) and the address. Do not retry.
6. Only if confirmed is true, read back the date, time and short_code. If it
   is false, say the office will call back to confirm a time.

Rules: never quote a price. Only turn on SMS Consent if the customer
explicitly agrees to text messages.

Ready-to-copy workflows

Three workflows business owners ask for most. The values below use n8n expressions ({{ … }}); type them in the field’s Expression mode.

1. Website form → confirmed job. n8n Form Trigger (or your form tool’s webhook) → Crisphive Book and Confirm Job → If confirmed is true → email the customer; otherwise → post to your team channel.

Crisphive node — Operation: Book and Confirm Job
Customer:                     New or Returning Caller
Full Name:                    {{ $json["Full name"] }}
Address Line:                 {{ $json["Street address"] }}
Start (Business Local Time):  {{ $json["Preferred date"] }}T09:00:00
Additional Fields:
  Phone (E.164):              {{ $json["Phone"] }}
  Email:                      {{ $json["Email"] }}
  City:                       {{ $json["City"] }}
  Postal Code:                {{ $json["Postal code"] }}
  Country:                    CA
  Description:                {{ $json["What do you need?"] }}

If node — condition:  {{ $json.confirmed }}  is true
  true  → "Booked: {{ $json.short_code }}"
  false → "Needs a time: {{ $json.short_code }} ({{ $json.refusal.error_code }})"

2. Job completed → review request. Crisphive Trigger (Job Completed, Fetch Full Job on) → Send Email / Gmail.

To:       {{ $json.object.customer.email }}
Subject:  Thanks for choosing us — job {{ $json.object.short_code }}
Body:     Hi {{ $json.object.customer.name }}, your visit is complete.
          Would you leave us a quick review? [your review link]

3. New customer → spreadsheet or CRM. Crisphive Trigger (Customer Created) → Google Sheets “Append row” with {{ $json.object.full_name }}, {{ $json.object.phone }}, {{ $json.object.email }} and {{ $json.event_id }} (keep the event ID: Crisphive delivers at least once, so a repeat delivery has the same ID and can be skipped).

Retries never book twice

Every write the node makes carries an Idempotency-Key — a label that tells Crisphive “this is the same request as before”. The node builds it from the n8n execution ID and the item number. So:

• If a Crisphive step fails on a network blip and n8n retries it inside the same execution (the node’s Retry On Fail setting), Crisphive replays the first answer instead of booking a second job.
• Each item in one execution gets its own key, so ten form rows book ten jobs.
• A new execution — a new trigger event, or running the workflow again by hand — is a new booking. That is why you must not re-run a booking whose answer was confirmed: false: the job already exists in the queue.
• Writes are Book and Confirm Job and Create Customer. Reads (Find Customer, Get Job, List Job Types) are always safe to repeat.

Test it

Use these fictional details. The 555-01xx range and example.com are reserved for fiction, and Crisphive never texts or emails them.

Troubleshooting

Go live

Related guides and reference

• Automation platforms overview — what every automation integration shares
• Zapier — book jobs from any Zap; instant job and customer triggers
• Make — the same booking and triggers in Make scenarios
• Pipedream — HTTP and Node.js steps against the API
• MCP server reference — every tool, the tool profiles and client setup
• Webhooks reference — events, signatures and retries
• Book and confirm a job — the API call behind every booking step