---
title: Add Delivery Status


---


## Add Delivery Status


**Required scope:** `public-api:write`

This endpoint allows an external system to send updates about a delivery build to Livingdocs.

Delivery builds are initiated by users within the Livingdocs editor and can be configured to notify an external system. Through this endpoint, external systems can report back to Livingdocs regarding the status of a triggered task or request further clarification by providing user choices. For more information on how to set up and use delivery builds, please refer to our [guide](/guides/editor/publish-control/delivery/llms.txt).

**History**

| Version | Change |
| ------- | ------ |

| release-2024-07 | Added support for `userChoices` to allow interactive delivery builds. |
| release-2022-09 | Initial support. |

**Curl Example**

```bash
ACCESS_TOKEN=ey1234
curl -k -X POST "https://server.livingdocs.io/api/2026-05/documents/{documentId}/addDeliveryStatus" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @- << EOF
  {
    "reportId": "2SG2MAA9RwPn",
    "publicationId": 524,
    "deliveryHandle": "web",
    "status": "success",
    "message": "Message with <strong>html</strong>"
  }
  EOF
```


**Endpoint**

```http
POST /api/2026-05/documents/{documentId}/addDeliveryStatus
```


**Parameters**

| Name | Type | Required | Notes |
| ---- | ---- | :------: | ----- |

| documentId | integer | x |  |
| reportId | string |  | If provided, this will update the matching delivery build; otherwise, it will create a new one. |
| publicationId | integer | x | Required for delivery builds of type `publication` |
| deliveryHandle | string | x |  |
| status | string | x | One of: `success`, `failed`, `aborted` (Added in: [`release-2024-07`](/operations/releases/release-2024-07/)), `in-progress` |
| message | string |  | String or sanitized HTML (supports `<em>`, `<strong>`, `<a>` and `<br>` tags) |
| userChoices | Array<{label: string, value: string}>
 |  | An array of options given to the user to choose from. This parameter is only allowed when `status` is set to `in-progress`. (Added in: [`release-2024-07`](/operations/releases/release-2024-07/)) |

**Response**

_200 OK_ — `/api/2026-05/documents/222/addDeliveryStatus`

```json
{
  "reportId": "0TAW2ORdNjuM"
}
```