Skip to main content
PATCH
Update Project

Authorizations

X-API-Key
string
header
required

Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy. A key carries up to three permissions: public:read for GET requests, public:write for POST, PATCH, and PUT requests, and public:delete for DELETE requests. public:delete is only available together with public:write.

Headers

Idempotency-Key
string

Optional idempotency key: a unique string of 16-200 printable ASCII characters (a UUID is recommended). Retrying the write with the same key within 24 hours returns the stored response of the first call with an X-Idempotent-Replayed: true response header instead of executing it again. Reusing a key with a different request body returns 422 (IDEMPOTENCY_MISMATCH); a duplicate sent while the first call is still running returns 409 with a Retry-After header. Keys are scoped per endpoint and organization.

Required string length: 16 - 200

Path Parameters

id
string
required

Resource ID

Body

application/json
name
string
message_text
string

Message text. Supports merge tags ({first_name|there}, contact custom fields) and {tracking_url}, {tracking_url_2} and {tracking_url_3} (the project's first, second and third tracked link) when link tracking is enabled on the project. Limited to 10 SMS parts (1,530 GSM-7 or 670 Unicode characters, counted with merge tags removed), or 1,500 characters when the project is MMS (protocol, or the stored protocol when omitted) or media_ids is set; longer text is rejected with 400 and a message naming the limit.

Maximum string length: 1600
protocol
enum<string>
Available options:
sms,
mms
channel
enum<string>

Change the messaging channel. Sending any of channel, brand_id, campaign_id, or toll_free_verification_id requires the full setup for the effective channel plus phone_number_ids (see the endpoint description). Switching to toll-free or short-code clears the brand and campaign.

Available options:
10dlc,
toll-free,
short-code
brand_id
string<uuid>

Required with campaign_id when the effective channel is 10dlc; omit otherwise. Must belong to the project's organization.

campaign_id
string<uuid>

Required with brand_id when the effective channel is 10dlc; omit otherwise. Must belong to brand_id. The brand follows the campaign.

toll_free_verification_id
string<uuid>

Required when the effective channel is toll-free; omit otherwise. Every number in phone_number_ids must be linked to this registration.

phone_number_ids
string[]

Replace the project's sending phone numbers (1-49). New conversations rotate across them; existing conversations keep their already-assigned sticky number.

Required array length: 1 - 49 elements
phone_number_id
string
deprecated

Deprecated. Use phone_number_ids. A single id is treated as a one-element phone_number_ids.

contact_list_ids
string[]

Replaces the project's lists. [] is accepted only when the project keeps at least one tag_ids entry as its source.

suppression_list_ids
string[]
media_ids
string[]

Up to 3 tracked links per message, in tag order: the first answers {tracking_url}, the second {tracking_url_2}, the third {tracking_url_3}. Each tag becomes that recipient's own short link to that link's destination, and repeating a tag repeats the same short link. A tag with no link behind it is rejected when link_tracking_enabled is true. Send 1 to 3 entries on create; on update the list you send replaces the existing one. link_tracking_enabled and link_tracking_domain_id apply to every link (one short-link domain per project). Cannot be sent together with link_tracking_destination_url, link_tracking_param_field or link_tracking_fallback_url, which stay available as aliases for the first link.

Maximum array length: 3

Alias for the first entry of link_tracking_links (its destination_url). Where the tracking link redirects. A {field} placeholder in it must be one of the link's param_fields; otherwise the request is rejected with a 400 (INVALID_LINK_PLACEHOLDER). May also be exactly https://{<field>} to send each recipient to the URL in that contact field; then link_tracking_fallback_url is required. {phone} is not allowed as a whole URL. Cannot be sent together with link_tracking_links.

Alias for the first entry of link_tracking_links (its first param_fields entry): phone, a contact field name, or null for none. Appended to the redirect as a query pair, or embedded in place of a matching {field} placeholder in the destination URL. Cannot be sent together with link_tracking_links.

Maximum string length: 64

Alias for the first entry of link_tracking_links (its fallback_url). Used when a whole-URL destination's contact field is empty or not a valid URL. Required when the destination is a whole-URL placeholder (e.g. https://{custom_url}); rejected with a 400 (INVALID_LINK_PLACEHOLDER) otherwise. Cannot be sent together with link_tracking_links.

Whether the 'STOP=END' opt-out footer is appended to every outbound message.

tag_ids
string<uuid>[]

Send to every contact carrying ANY of these tags, in union with contact_list_ids. Each must be a tag of the project's organization. A tagged contact is only sent to through a list row the project's sender can use (see GET /tags). A tag cannot also be in suppression_tag_ids.

Maximum array length: 50
require_tag_ids
string<uuid>[]

Narrow the audience to contacts carrying ALL of these tags ("only contacts tagged"). A tag cannot also be in suppression_tag_ids.

Maximum array length: 50
suppression_tag_ids
string<uuid>[]

Skip contacts carrying ANY of these tags for this send only. This is separate from opt-outs, which always apply.

Maximum array length: 50
follow_ups
object | null

Replaces the follow-ups; null removes them. Locked once the project has started: a changed value returns 409, an unchanged one is accepted.

scheduled_timezone
enum<string>

The project's time zone for its next-day trigger start and its follow-ups' time of day. Required in the same write as a next_day trigger or a follow-up that waits days. Can be changed after the project starts.

Available options:
America/New_York,
America/Chicago,
America/Denver,
America/Los_Angeles,
America/Anchorage,
Pacific/Honolulu
sequence_send_time
string

The local time of day, HH:MM, for a next_day trigger and follow-ups that wait days. Can be changed after the project starts: people already waiting keep their place.

Pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$

Response

Project updated. Returns the full project object (same shape as GET /projects/{id}).

success
boolean
required
data
object
required