Customer visit links

How a customer confirms or counters a repair visit from the link in their email, and the three endpoints behind that page.

When a provider proposes visit times for an on-site repair, the customer receives an email from SureBright with a link. The page behind it shows the proposed arrival windows and lets the customer pick one or ask for different times. Read this page if you build the customer-facing page yourself, or want to know what the customer sees and why a link stops working.

What the customer sees#

The page shows SureBright as the sender, the product, the proposed arrival windows in the job's time zone, and the technician's first name where there is one. It never shows the provider's business or store, a price, or anything about the claim's decision.

The customer can:

  • Confirm one of the windows. The visit is booked, the provider is told, and the link is spent.

  • Counter with a note saying what times would work. The proposal is withdrawn, the provider is told to propose again, and the link is spent.

A link that has been used, has expired, or whose proposal was withdrawn, superseded or already answered shows This link is no longer active; SureBright will contact you.

The token#

The link carries a single-use token minted when the email is sent. It expires with the proposal it belongs to, which is when the last proposed window can no longer be held. Sending the customer a newer proposal kills the links sent before it.

The token is the only credential. It is sent on every request in the X-Customer-Link-Token header, never in the URL path or query, so it does not land in access logs or a Referer. Every response carries Referrer-Policy: no-referrer and Cache-Control: no-store.

Endpoints#

Three routes, on the SureBright API host, with the token header on each.

Method and pathWhat it does
GET /customer/visit-proposalsThe proposal: product, windows, technician first name, and when the link stops working
POST /customer/visit-proposals/confirmBook one window
POST /customer/visit-proposals/counterDecline the windows and say what would work

Read the proposal#

bash
curl "$SUREBRIGHT_API/customer/visit-proposals" \
  -H "X-Customer-Link-Token: $TOKEN"
fromstring
Always SureBright.
productNamestring
The product being repaired.
technicianFirstNamestring | null
The technician's first name, or null when the page should say "your technician".
slotsarray
The windows still bookable. Each carries slotHoldId, startsAt and endsAt in the job's time zone. A single window can drop out before the link expires.
expiresAtstring
When the link stops working.

Confirm a window#

bash
curl -X POST "$SUREBRIGHT_API/customer/visit-proposals/confirm" \
  -H "X-Customer-Link-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slotHoldId":"..."}'
stringrequired
One of the slotHoldId values from the proposal. Any other value is 400 SLOT_NOT_IN_PROPOSAL.

Counter#

bash
curl -X POST "$SUREBRIGHT_API/customer/visit-proposals/counter" \
  -H "X-Customer-Link-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note":"Mornings do not work for me","preferredTimes":"weekday evenings"}'
stringrequired
What the customer wants the provider to know. Up to 500 characters.
string
Free text, up to 500 characters.

Both bodies are strict: an unknown field is refused rather than ignored, and the token is never accepted in a body.

Idempotency#

The two POSTs are idempotent. A retry of a confirm or counter that already succeeded, while the link is still live, returns the first answer rather than acting twice. The idempotency scope is the token, so one customer's retry can never replay another's. A dead link answers 404 or 410 even to a retry of a request that once succeeded.

Responses the page should handle#

StatusCodeMeaning
400VALIDATION_FAILED, SLOT_NOT_IN_PROPOSALThe body is wrong; field errors are in details
404LINK_NOT_FOUNDNot a token this service issued. Show the inactive message
410LINK_INACTIVEUsed, expired, withdrawn or superseded. Show the inactive message
409IDEMPOTENCY_IN_PROGRESSThe first attempt is still running; retry shortly
429Too many requests on this link
503The schedule is busy; the message is written for the customer. Retry

Anything else the service could say about the job is deliberately answered as 410 LINK_INACTIVE with no details, so the page has one inactive state and nothing about another job, a provider or a member can leak through it.

The mail-in variant of this link (GET /customer/mail-in, a label and ship-by page) uses the same token header and the same inactive answers. It is read-only.