POST /v1/content/:containerId/notify-device

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.

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.

Example request

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

const result = await layers.publishing.notifyDevice({
  containerId: "cnt_8f1d6c3e-4b2a-4a18-9e4f-c2d7a1b0e999",
  phoneNumber: "+15551234567",
});

result = layers.publishing.notify_device(
    container_id="cnt_8f1d6c3e-4b2a-4a18-9e4f-c2d7a1b0e999",
    phone_number="+15551234567",
)

Response

{
  "containerId": "cnt_8f1d6c3e-4b2a-4a18-9e4f-c2d7a1b0e999",
  "deliveryStatus": "sent",
  "phoneNumberLast4": "4567",
  "providerChatId": "linq_chat_5f3a...",
  "mediaCount": 2
}

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

See also

• POST /v1/content/:containerId/publish — publish-now via the connected platform (TikTok / Instagram OAuth)
• POST /v1/content/:containerId/schedule — schedule a future direct publish or platform-native draft (mode: "draft")