# POST /v1/content/:containerId/notify-device (/docs/api/reference/publishing/notify-device)



<Endpoint method="POST" path="/v1/content/:containerId/notify-device" auth="Bearer" scope="publish:write" phase="1" />

Mirror of the Layers UI's "Text me this post" / Elle SMS device handoff. Sends three messages over iMessage / SMS to a target phone:

1. The container's media (images / video).
2. The caption (copy-paste-ready).
3. Friendly posting instructions generated by Elle (the Layers AI agent).

Use this when a creator needs the assets on their phone so they can publish manually inside the native TikTok / Instagram app — typical when the creator hasn't connected their account via OAuth or wants final visual review before posting.

<Callout type="info">
  This is a **content delivery** path, not a scheduling path. There is no `scheduled_posts` row and no future `scheduledFor` field. Messages are dispatched immediately. To push a draft into the platform-native inbox (TikTok inbox / Instagram SMS draft) at a future time, use [`mode: "draft"`](/docs/api/reference/publishing/schedule-content) on `/schedule` instead.
</Callout>

## Phone-number resolution [#phone-number-resolution]

Partner API keys are organization-scoped — there is no end-user session. The destination phone is resolved in this order:

1. **Explicit `phoneNumber` in the body.** E.164 format only (`+15551234567`). Required for sending to a managed creator's device.
2. **Fallback to the API key owner.** If `phoneNumber` is omitted, Layers reads the `phone_number` of the user who minted the API key. The user must have a verified phone (`phone_verified = true`); if not, you'll get `OWNER_PHONE_UNVERIFIED`.
3. **`PHONE_REQUIRED`** — if neither resolves.

The fallback exists for the common case where a partner is sending content to themselves to QA. For production creator-handoff flows, always pass `phoneNumber` explicitly.

<Parameters
  title="Path"
  rows="[
  { name: 'containerId', type: 'string', required: true, description: 'Completed content container id (cnt_<UUID>).' },
]"
/>

<Parameters
  title="Headers"
  rows="[
  { name: 'Idempotency-Key', type: 'string (UUID)', description: 'Same key + same body replays the cached response. Recommended — accidental retries spam the destination phone.' },
]"
/>

<Parameters
  title="Body"
  rows="[
  { name: 'phoneNumber', type: 'string (E.164)', description: 'Destination phone number, e.g. `+15551234567`. Optional — falls back to API key owner. 422 VALIDATION if malformed.' },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl https://api.layers.com/v1/content/cnt_8f1d6c3e-4b2a-4a18-9e4f-c2d7a1b0e999/notify-device \
      -H "Authorization: Bearer lp_..." \
      -H "Idempotency-Key: 4f2a1b8c-7d3e-4c5a-9b6f-1e2d3c4b5a67" \
      -H "Content-Type: application/json" \
      -d '{ "phoneNumber": "+15551234567" }'
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const result = await layers.publishing.notifyDevice({
      containerId: "cnt_8f1d6c3e-4b2a-4a18-9e4f-c2d7a1b0e999",
      phoneNumber: "+15551234567",
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python
    result = layers.publishing.notify_device(
        container_id="cnt_8f1d6c3e-4b2a-4a18-9e4f-c2d7a1b0e999",
        phone_number="+15551234567",
    )
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="200" description="Sent">
  ```json
  {
    "containerId": "cnt_8f1d6c3e-4b2a-4a18-9e4f-c2d7a1b0e999",
    "deliveryStatus": "sent",
    "phoneNumberLast4": "4567",
    "providerChatId": "linq_chat_5f3a...",
    "mediaCount": 2
  }
  ```
</Response>

`phoneNumberLast4` is the last 4 digits of the destination phone in E.164 trailing form — included so partner UIs can render "sent to \*\*\*\*4567" without round-tripping the full number.

`providerChatId` is the Linq chat id for the conversation. It's stable across resends to the same phone, so subsequent calls land in the same iMessage thread.

## Errors [#errors]

| Status | Code                                                            | When                                                                                               |
| ------ | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 401    | `UNAUTHENTICATED`                                               | Missing or invalid key.                                                                            |
| 403    | `FORBIDDEN_SCOPE`                                               | Key lacks `publish:write`.                                                                         |
| 404    | `NOT_FOUND`                                                     | Container not in your organization.                                                                |
| 409    | `CONFLICT` (`details.reason: "CONTENT_NOT_READY"`)              | Container `status` ≠ `completed`. Wait for generation to finish.                                   |
| 422    | `VALIDATION` (E.164 regex)                                      | `phoneNumber` malformed.                                                                           |
| 422    | `VALIDATION` (`details.reason: "PHONE_REQUIRED"`)               | No `phoneNumber` and no resolvable API key owner.                                                  |
| 422    | `VALIDATION` (`details.reason: "OWNER_PHONE_UNVERIFIED"`)       | Fallback owner has unverified phone.                                                               |
| 422    | `VALIDATION` (`details.reason: "NO_MEDIA"`)                     | Container has zero media URLs.                                                                     |
| 502    | `PLATFORM_ERROR` (`details.reason: "PROVIDER_REJECTED"`)        | The SMS provider rejected one or more parts. `details.providerError` carries the upstream message. |
| 503    | `PLATFORM_ERROR` (`details.reason: "SMS_PROVIDER_UNAVAILABLE"`) | The SMS provider is not configured for this Layers deployment. Retry later.                        |

## See also [#see-also]

* [`POST /v1/content/:containerId/publish`](/docs/api/reference/publishing/publish-content) — publish-now via the connected platform (TikTok / Instagram OAuth)
* [`POST /v1/content/:containerId/schedule`](/docs/api/reference/publishing/schedule-content) — schedule a future direct publish or platform-native draft (`mode: "draft"`)