> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phonovation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Reference

> Match each delivery receipt to the customer, order, appointment, or record in your system.

`ClientReference` is an optional value that you attach to each recipient. Phonovation stores it unchanged and returns it in that recipient's delivery receipt (DLR) webhook.

```mermaid title="Client Reference correlation" theme={"dark"}
%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Outfit", "fontSize": "16px", "primaryColor": "#fff1ef", "primaryTextColor": "#0f1926", "primaryBorderColor": "#d23a25", "lineColor": "#4b69a0", "actorBkg": "#eaf0fa", "actorBorder": "#4b69a0", "actorTextColor": "#0f1926", "signalColor": "#4b69a0", "signalTextColor": "#0f1926"}}}%%
sequenceDiagram
  participant App as Your application
  participant API as Phonovation API
  participant Store as Your database
  participant Hook as Your webhook

  App->>Store: Save appointment-88421
  App->>API: Send SMS with ClientReference
  API-->>App: 202 + campaign ID
  API->>Hook: DLR with appointment-88421
  Hook->>Store: Find matching appointment
  Store-->>Hook: Update delivery status
```

## Add it to a recipient

Property names are case-sensitive. Use `ClientReference` exactly as shown.

```json title="Recipient with Client Reference" theme={"dark"}
{
  "msisdn": "353871234567",
  "ClientReference": "appointment-88421"
}
```

## Rules

| Rule                 | Behavior                                                         |
| -------------------- | ---------------------------------------------------------------- |
| Required             | No                                                               |
| Type                 | String or `null`                                                 |
| Maximum length       | 30 characters                                                    |
| Uniqueness           | Not required by Phonovation                                      |
| Storage              | Preserved unchanged                                              |
| If omitted           | Stored and returned as `null`                                    |
| Duplicate recipients | The first normalized recipient and its Client Reference are kept |

Use a value that is meaningful inside your system, such as an appointment, order, or notification ID. Avoid phone numbers, message text, names, or other personal data.

## Match the webhook

A delivery webhook returns the same property:

```json title="Delivered DLR" theme={"dark"}
{
  "To": "353871234567",
  "From": "CompanyName",
  "Status": "DELIVERED",
  "ClientReference": "appointment-88421"
}
```

Use the value to locate your record, then update it with the delivery status. Make the update idempotent because webhook delivery can be duplicated and event order is not guaranteed.

<Note>
  Campaign summaries contain aggregate totals only. Use `ClientReference` on the DLR webhook when you need recipient-level correlation.
</Note>

<Card title="Webhooks" icon="webhook" href="/phonovation-api/webhooks">
  Verify signed DLRs and process Client References safely.
</Card>