> ## 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.

# notifyId

> A user-defined identifier that ties outbound messages, webhooks, DLRs, and inbound replies together.

`notifyId` is a string you define and attach to each recipient when sending an SMS. Phonovation echoes it back in every outbound event for that recipient — webhooks and DLRs — so you can match each callback to the right record in your own system without relying on phone numbers.

## Where it appears

| System            | Field                      | Notes                                                                                             |
| ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
| **Outbound send** | `recipientInfo[].notifyId` | You set it here — per recipient                                                                   |
| **Webhook**       | `NotifyId`                 | Echoed back per recipient                                                                         |
| **DLR**           | `SMS-NotifyId`             | Echoed back per recipient                                                                         |
| **Inbound relay** | `SMS-NotifyId`             | Populated when the gateway links the reply to an outbound with a `notifyId` set — otherwise empty |

## Rules

* **User-defined** — you choose the value. Use whatever makes sense for your system: a database ID, an order number, a UUID.
* **Per recipient** — set independently on each entry in `recipientInfo`, so different recipients in the same campaign can carry different identifiers.
* **Optional** — if omitted, webhook and DLR callbacks will carry an empty `NotifyId`/`SMS-NotifyId`. You can still receive callbacks; you just won't be able to match them automatically.
* **String only** — any string up to a reasonable length. There is no enforced format.

## Setting a notifyId

```json title="Campaign payload with notifyId" icon="fingerprint" highlight={5-6} wrap theme={"dark"}
{
  "text": "Your appointment is confirmed for tomorrow at 10am.",
  "from": "Clinic",
  "recipientInfo": [
    { "msisdn": "353861234567", "notifyId": "appt-8821" },
    { "msisdn": "353871234567", "notifyId": "appt-8822" }
  ]
}
```

Each of those recipients will carry their own `notifyId` through every subsequent callback.

## Use cases

### Order and transaction tracking

Attach an order ID so every delivery callback maps directly to a record in your database — no phone number lookups needed.

```json title="Order tracking notifyId" icon="cart-shopping" highlight={1} wrap theme={"dark"}
{ "msisdn": "353861234567", "notifyId": "order-10045" }
```

When the DLR arrives with `SMS-NotifyId=order-10045`, you update that order row to `sms_delivered = true`.

### Multi-step user journeys

Use the same identifier across the full send → deliver → reply flow to keep a user's journey stitched together in your logs.

```json title="Journey step notifyId" icon="route" highlight={1} wrap theme={"dark"}
{ "msisdn": "353871234567", "notifyId": "user-7712-step-2" }
```

### Audit trails and support

Store the `notifyId` alongside the send record. If a customer contacts support claiming they never received a message, you can pull the DLR and webhook logs for that ID immediately.

### Batch reconciliation

After a large campaign send, use `notifyId` values to reconcile delivery status back to your CRM or data warehouse — matching each row by ID rather than by phone number.

***

## Full flow example — appointment reminder

This example traces a single message from send through to a reply, showing where `notifyId` appears at each step.

```mermaid title="notifyId correlation flow" theme={"dark"}
sequenceDiagram
  participant App as Your app
  participant API as Phonovation SMS API
  participant Gateway as Phonovation gateway
  participant Endpoint as Your endpoint
  participant DB as Your database
  participant Recipient as Recipient

  App->>API: Send SMS with notifyId
  App->>DB: Store notifyId with business record
  API->>Gateway: Queue message
  Gateway->>Endpoint: Webhook includes NotifyId
  Gateway->>Endpoint: DLR includes SMS-NotifyId
  Recipient->>Gateway: Reply to message
  Gateway->>Endpoint: Inbound relay includes SMS-NotifyId when linked
  Endpoint->>DB: Update the matching record
```

**Scenario:** A clinic sends an appointment reminder. The patient can reply `CONFIRM` or `CANCEL`.

### 1. Send the message

```json title="Appointment reminder request" icon="calendar-check" highlight={7} wrap theme={"dark"}
POST /api/v2/Campaign

{
  "text": "Hi Sarah, your appointment is tomorrow at 10am. Reply CONFIRM or CANCEL.",
  "from": "Clinic",
  "recipientInfo": [
    { "msisdn": "353861234567", "notifyId": "appt-8821" }
  ]
}
```

### 2. Webhook fires — message accepted

Phonovation immediately sends a webhook to your endpoint:

```json title="Appointment webhook payload" icon="link" highlight={5} wrap theme={"dark"}
{
  "Status": "MESSAGE_SUCCESS",
  "FinishedAt": "2026-04-09T09:01:12.000Z",
  "Message": "Your message has been queued.",
  "NotifyId": "appt-8821"
}
```

Your system marks appointment `8821` as `sms_queued`.

### 3. DLR fires — message delivered to handset

Minutes later, once the network confirms delivery:

```text title="Appointment DLR payload" icon="receipt" highlight={2} wrap theme={"dark"}
SMS-Type=Notification
SMS-NotifyId=appt-8821
SMS-Success=True
SMS-To=353861234567
SMS-From=Clinic
SMS-TotalToSend=1
SMS-TotalSent=1
SMS-TotalFailed=0
SMS-TimeStamp=2026-04-09 09:01:45
```

Your system marks appointment `8821` as `sms_delivered`.

### 4. Patient replies — inbound relay fires

Sarah texts back `CONFIRM`. Your inbound relay receives:

```text title="Appointment inbound payload" icon="inbox" highlight={2,3} wrap theme={"dark"}
SMS-Type=Text
SMS-Content=CONFIRM
SMS-Keyphrase=CONFIRM
SMS-From=353861234567
SMS-To=Clinic
SMS-TimeStamp=2026-04-09 09:03:11
```

The inbound payload includes `SMS-NotifyId`. When the gateway can link the reply to the original outbound message, this will be populated with `appt-8821` — no phone number lookup needed. If it's empty, fall back to looking up `SMS-From` (`353861234567`) in your system to find the associated record.

### Full state after each step

| Step | Event         | notifyId visible                                       | Appointment 8821 status |
| ---- | ------------- | ------------------------------------------------------ | ----------------------- |
| 1    | Send API call | You set `appt-8821`                                    | `sms_pending`           |
| 2    | Webhook       | `NotifyId: appt-8821`                                  | `sms_queued`            |
| 3    | DLR           | `SMS-NotifyId: appt-8821`                              | `sms_delivered`         |
| 4    | Inbound reply | `SMS-NotifyId: appt-8821` (or use `SMS-From` fallback) | `confirmed`             |

***

## Full flow example — e-commerce order notification

**Scenario:** An online shop notifies a customer their order has shipped. If the customer replies, the shop wants to know which order they're referring to.

### 1. Send the message

```json title="Order notification request" icon="truck" highlight={5} wrap theme={"dark"}
{
  "text": "Your order #10045 has shipped! Track it at: example.com/track/10045",
  "from": "ShopName",
  "recipientInfo": [
    { "msisdn": "353871234567", "notifyId": "order-10045" }
  ]
}
```

### 2. Webhook — accepted

```json title="Order webhook payload" icon="link" highlight={5} wrap theme={"dark"}
{
  "Status": "MESSAGE_SUCCESS",
  "FinishedAt": "2026-04-09T11:14:00.000Z",
  "Message": "Your message has been queued.",
  "NotifyId": "order-10045"
}
```

### 3. DLR — delivered

```text title="Order DLR payload" icon="receipt" highlight={1} wrap theme={"dark"}
SMS-NotifyId=order-10045
SMS-Success=True
SMS-To=353871234567
SMS-TimeStamp=2026-04-09 11:14:22
```

Update `orders` table: `sms_delivered_at = 2026-04-09 11:14:22` where `id = 10045`.

### 4. Customer replies

```text title="Order inbound payload" icon="inbox" highlight={5} wrap theme={"dark"}
SMS-Type=AuthCode
SMS-Content=Where is my order?
SMS-Keyphrase=*
SMS-From=353871234567
SMS-To=ShopName
SMS-NotifyId=order-10045
```

`SMS-NotifyId` is populated directly — route straight to your support queue with the order context pre-filled. No phone number lookup needed.

***

## Tips

* Keep `notifyId` values **unique per send** where possible. Reusing the same ID across multiple sends makes it harder to distinguish callbacks.
* For inbound replies, check `SMS-NotifyId` first. If it's populated, you have a direct link to the original send. If it's empty, fall back to looking up `SMS-From` in your records — so it's worth **storing `notifyId` alongside the phone number** at send time as a safety net.
* `notifyId` has no meaning to the Phonovation network — it is purely for your use. The gateway stores and echoes it; nothing else.