---
title: "Link an SMS to a workflow"
method: POST
path: "/v1/design_studio/sms/{id}/link"
tags: ["SMS link and publish"]
---

# Link an SMS to a workflow

`POST /v1/design_studio/sms/{id}/link`

## Request

- Base URL: `https://api.customer.io`
- URL: `https://api.customer.io/v1/design_studio/sms/{id}/link`
- Auth: none declared

Link an existing SMS to a workflow—a transactional message, a one-time send, an automation action, or an API-triggered broadcast—to send it to your audience.

If your workflow is already live, people start receiving this SMS as soon as you link it. If you make changes to the message after linking it, you need to [publish the SMS](/integrations/api/design-studio/tag/sms-link-and-publish/publishSms/) to send the latest content to your audience.

You can only link an SMS to one workflow at a time. If you try to link an SMS to a workflow or action that's already linked to a *different* message, the request fails with a `409` unless you pass `"force": true`. The `force` parameter replaces (and unlinks) the other message.

## Path parameters

- `id` string, uuid, required

## Request body

- LinkRequest
  - `target` LinkTarget, required: The workflow to link the content to.
    - `type` 'transactional_message' | 'newsletter' | 'campaign_action', required: The kind of workflow to link. Provide the matching ID field for the type you choose. Use `campaign_action` for an automation or API-triggered broadcast.
    - `transactional_message_id` integer: The ID of the transactional message to link your content to. Required when `type` is `transactional_message`.
    - `newsletter_id` integer: The ID of the one-time send to link your content to. Required when `type` is `newsletter`.
    - `action_id` integer: The ID of the action in the automation or API-triggered broadcast to link your content to. Required when `type` is `campaign_action`.
  - `force` boolean: Replace an existing link if the workflow or action is already linked to *different* Design Studio content.

## Response `200`

SMS linked

- LinkResponse
  - `node_id` string, uuid: The UUID of the linked message.
  - `template_id` integer: The ID of the workflow template the content is now linked to.
  - `target` LinkTargetResponse: The workflow linked to the message. The response returns `campaign_action` for an automation or an API-triggered broadcast.
    - `type` 'transactional_message' | 'newsletter' | 'campaign_action', required: The type of workflow linked.
    - `transactional_message_id` integer: The ID of the transactional message linked.
    - `newsletter_id` integer: The ID of the one-time send linked.
    - `action_id` integer: The ID of the action in the automation or API-triggered broadcast that was linked.

## Other responses

- `400`: The request is invalid due to malformed parameters, missing required fields, or constraint violations.
- `401`: Authentication failed due to a missing or invalid API key.
- `404`: The requested resource was not found.
- `409`: The destination is already linked to a different message. Pass `"force": true` to replace that link.
- `422`: The liquid in the SMS's content or recipient isn't valid, so Customer.io doesn't link it. Each error's `source.pointer` names the field that failed, as `/data/attributes/content` or `/data/attributes/recipient`. Fix the SMS, then link it again.

## Changes

- **2026-10-08** `6378ded43e43`: 2 info
  - api tag `SMS link and publish` added
  - api tag `Design Studio SMS` removed
- **2026-10-06** `b0a0db5fbc21`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/changes/v1/design_studio/sms/:id/link/post.md)

---

[API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) - [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/revisions/ac0b282053fe?raw)