---
title: "Customer visit links"
description: "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 path | What it does |
|---|---|
| `GET /customer/visit-proposals` | The proposal: product, windows, technician first name, and when the link stops working |
| `POST /customer/visit-proposals/confirm` | Book one window |
| `POST /customer/visit-proposals/counter` | Decline the windows and say what would work |

### Read the proposal

```bash
curl "$SUREBRIGHT_API/customer/visit-proposals" \
  -H "X-Customer-Link-Token: $TOKEN"
```

<ResponseField name="from" type="string">Always `SureBright`.</ResponseField>
<ResponseField name="productName" type="string">The product being repaired.</ResponseField>
<ResponseField name="technicianFirstName" type="string | null">The technician's first name, or null when the page should say "your technician".</ResponseField>
<ResponseField name="slots" type="array">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.</ResponseField>
<ResponseField name="expiresAt" type="string">When the link stops working.</ResponseField>

### 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":"..."}'
```

<ParamField body="slotHoldId" type="string" required>One of the `slotHoldId` values from the proposal. Any other value is `400 SLOT_NOT_IN_PROPOSAL`.</ParamField>

### 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"}'
```

<ParamField body="note" type="string" required>What the customer wants the provider to know. Up to 500 characters.</ParamField>
<ParamField body="preferredTimes" type="string">Free text, up to 500 characters.</ParamField>

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

| Status | Code | Meaning |
|---|---|---|
| `400` | `VALIDATION_FAILED`, `SLOT_NOT_IN_PROPOSAL` | The body is wrong; field errors are in `details` |
| `404` | `LINK_NOT_FOUND` | Not a token this service issued. Show the inactive message |
| `410` | `LINK_INACTIVE` | Used, expired, withdrawn or superseded. Show the inactive message |
| `409` | `IDEMPOTENCY_IN_PROGRESS` | The first attempt is still running; retry shortly |
| `429` | | Too many requests on this link |
| `503` | | The 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.

<Note>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.</Note>
