> ## Documentation Index > Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt > Use this file to discover all available pages before exploring further. # Update Project > Update a project while in `draft`, `awaiting_test`, or `ready`. `organization_id` / `brand_id` / `campaign_id` / `channel` / `toll_free_verification_id` / `type` are immutable after creation; including them in the body returns a 400. All other fields are partial: send only the keys you want to change. The payload shape follows the project's `type`. For surveys, `questions` is a full replacement: sending it swaps the entire question set (same rules as create). Editing content on a `ready` project moves it back to `awaiting_test` (re-test required). ## OpenAPI ````yaml /api-reference/openapi.json patch /projects/{id} openapi: 3.1.0 info: title: Political Comms API summary: >- Direct-to-carrier political texting API for campaigns, PACs, advocacy organizations, fundraisers, and elected officials. description: >- Public REST API for the Political Comms platform. Surfaces include Projects (compose, test, schedule, send), Conversations (read inbound threads and reply inside them), Contact Lists (S3 import and analysis), Media Files, Organizations and hierarchy, Brands, Campaigns, Tracking Domains, Phone Numbers, Analytics, and Billing. Authentication is an API key passed in the `X-API-Key` header. Keys are generated from the dashboard at Admin → API and are prefixed `pc_live_`. All POST and PATCH endpoints that mutate state are designed to be safe to retry, with optional `Idempotency-Key` headers for stronger guarantees. Rate limit is 600 requests per minute per key (bursts up to 600, refilling at 10 per second, the same for every scope; the `X-RateLimit-Limit` header reports your key's exact limit, and `Retry-After` on a 429 is the seconds until your next request is allowed). Webhooks emit `message.sent`, `message.delivered`, `message.failed`, `message.replied`, and `link.clicked` events. Payloads are HMAC-signed; validate the signature before trusting any payload. A Model Context Protocol (MCP) server is available at https://docs.politicalcomms.com/mcp for AI agents that need to search the documentation programmatically. The developer hub at https://politicalcomms.com/developers/ has quickstart examples in cURL, raw HTTP, and Python. version: 1.4.1 termsOfService: https://politicalcomms.com/terms/ contact: name: Political Comms Support email: support@politicalcomms.com url: https://docs.politicalcomms.com license: name: Proprietary url: https://politicalcomms.com/terms/ x-logo: url: https://politicalcomms.com/images/brand/pcomms-logo-left-of-text.png altText: Political Comms backgroundColor: '#ffffff' href: https://politicalcomms.com/ x-mcp: url: https://docs.politicalcomms.com/mcp discovery_url: https://docs.politicalcomms.com/.well-known/mcp transport: http auth: none tools: - search_political_comms - query_docs_filesystem_political_comms - submit_feedback servers: - url: https://api.politicalcomms.com/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Projects description: Create, edit, test, schedule, and inspect projects. - name: Conversations description: >- Read inbound threads and reply inside them from the same number. Conversations are created by project sends; the API never starts one. - name: Phone Numbers description: List phone numbers across 10DLC campaigns and toll-free verifications. - name: Toll-Free Verifications description: >- List toll-free verifications (carrier registrations) across your organization hierarchy. - name: Brands description: List brands across your organization hierarchy. - name: 10DLC Campaigns description: >- List 10DLC campaigns (carrier registrations) across your organization hierarchy. - name: Email Campaigns description: >- Create, schedule, and report on email campaigns. Pause, resume, and test sends are deliverability decisions a human makes while watching a send, and live in the dashboard. - name: Email Templates description: Create and read saved email templates. - name: Email Senders description: >- Read the sender identities (From addresses) on your verified domains. Identities carry the physical mailing address and paid-for-by disclaimer, so they are created and edited in the dashboard. - name: Email Suppressions description: >- Read, add, and lift suppressions in bulk. This is the primitive for keeping your own opt-out record in sync with ours. - name: Contact Lists description: List, import, and analyze contact lists. - name: Email Lists description: >- Create email lists, read their contacts, and bulk-upsert or import addresses. To stop mailing someone use Email Suppressions, which survives a re-import. - name: Media Files description: List, import, and fetch media files. - name: Sending Domains description: >- Read the sending domains in your organization and the DNS records to publish. Domains are added in the dashboard: DNS is published by hand, so creation is not part of the API. - name: Tracking Domains description: >- List active link-tracking domains. Use the returned ids as `link_tracking_domain_id` on project create/update. - name: Organizations description: List descendant organizations and hierarchy. - name: Billing description: Usage and billing data across your organization. - name: Analytics description: Message statistics and delivery performance. paths: /projects/{id}: patch: tags: - Projects summary: Update Project description: >- Update a project while in `draft`, `awaiting_test`, or `ready`. `organization_id` / `brand_id` / `campaign_id` / `channel` / `toll_free_verification_id` / `type` are immutable after creation; including them in the body returns a 400. All other fields are partial: send only the keys you want to change. The payload shape follows the project's `type`. For surveys, `questions` is a full replacement: sending it swaps the entire question set (same rules as create). Editing content on a `ready` project moves it back to `awaiting_test` (re-test required). operationId: updateProject parameters: - $ref: '#/components/parameters/IdPath' - $ref: '#/components/parameters/IdempotencyKeyHeader' requestBody: required: true content: application/json: schema: oneOf: - type: object properties: name: type: string message_text: type: string protocol: type: string enum: - sms - mms phone_number_ids: type: array items: type: string minItems: 1 maxItems: 49 description: >- Replace the project's sending phone numbers (1-49). New conversations rotate across them; existing conversations keep their already-assigned sticky number. phone_number_id: type: string deprecated: true description: >- Deprecated. Use phone_number_ids. A single id is treated as a one-element phone_number_ids. contact_list_ids: type: array items: type: string minItems: 1 suppression_list_ids: type: array items: type: string media_ids: type: array items: type: string link_tracking_enabled: type: boolean link_tracking_destination_url: type: - string - 'null' format: uri description: >- Where tracking links redirect. May embed the selected link parameter via a {field} placeholder named after it (see POST /projects); a placeholder that does not match the effective link_tracking_param_field is rejected with a 400 (INVALID_LINK_PLACEHOLDER). May also be exactly 'https://{}' 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. link_tracking_domain_id: type: - string - 'null' link_tracking_param_field: type: - string - 'null' maxLength: 64 description: >- Contact field carried on tracking-link redirects ('phone', a custom-field name, or null for none). Appended as a query pair, or embedded in place of a matching {field} placeholder in the destination URL. link_tracking_fallback_url: type: - string - 'null' format: uri description: >- Redirect used when a recipient's link_tracking_param_field value is empty or not a valid URL. Required when link_tracking_destination_url is a whole-URL placeholder (e.g. 'https://{custom_url}'); rejected with a 400 (INVALID_LINK_PLACEHOLDER) otherwise. opt_out_footer_enabled: type: boolean description: >- Whether the 'STOP=END' opt-out footer is appended to every outbound message. title: Broadcast project update - title: Survey project update type: object properties: name: type: string phone_number_ids: type: array items: type: string minItems: 1 maxItems: 49 phone_number_id: type: string deprecated: true contact_list_ids: type: array items: type: string minItems: 1 suppression_list_ids: type: array items: type: string questions: type: array minItems: 2 maxItems: 32 description: >- Full replacement of the question set (same rules as create). Omit to leave questions unchanged. items: type: object required: - sequence - question_type - question_text properties: sequence: type: integer minimum: 1 maximum: 32 description: >- Position in the flow. Sequences must be exactly 1..N with no gaps; sequence 1 must be the intro. question_type: type: string enum: - intro - multiple_choice - open_ended - outro description: >- intro: the opening message (must be sequence 1). multiple_choice: 2-9 numbered response_options. open_ended: free-text answer, no response_options. outro: closing message, expects no reply. question_text: type: string minLength: 1 maxLength: 1600 description: >- Message text. Supports merge tags (`{first_name|there}`, contact custom fields) and `{tracking_url}` when link tracking is enabled on the project. message_type: type: string enum: - sms - mms default: sms description: >- Per-question delivery type. MMS questions require media_ids. media_ids: type: array items: type: string maxItems: 10 description: >- Media file IDs attached to this question (see Media Files). Required (at least one) when message_type=mms; not allowed when message_type=sms. response_options: type: array minItems: 2 maxItems: 9 description: >- Numbered answer options. Required for multiple_choice; not allowed for open_ended. items: type: object required: - value - label properties: value: type: integer minimum: 1 maximum: 9 description: >- The digit a recipient texts to pick this option. label: type: string maxLength: 200 description: >- Descriptive label used for matching and reporting. next_sequence: type: integer minimum: 1 maximum: 32 description: >- Branch target when this option is picked. Must point to a later question (forward-only, no loops). Omit for linear progression to sequence + 1. no_match_sequence: type: integer minimum: 1 maximum: 32 description: >- Branch target when a reply matches none of the response_options. Only valid on questions with response_options; forward-only. Omit to fall through to sequence + 1. is_required: type: boolean default: true link_tracking_enabled: type: boolean link_tracking_destination_url: type: - string - 'null' format: uri description: >- May also be exactly 'https://{}' 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. link_tracking_domain_id: type: - string - 'null' link_tracking_param_field: type: - string - 'null' maxLength: 64 link_tracking_fallback_url: type: - string - 'null' format: uri description: >- Redirect used when a recipient's link_tracking_param_field value is empty or not a valid URL. Required when link_tracking_destination_url is a whole-URL placeholder; rejected with a 400 (INVALID_LINK_PLACEHOLDER) otherwise. ai_survey_analysis_enabled: type: boolean example: name: Spring Outreach (revised) message_text: 'Hi {first_name}, early voting starts Monday. Learn more: {link}' media_ids: [] responses: '200': description: >- Project updated. Returns the full project object (same shape as GET /projects/{id}). content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: project_id: type: string organization_id: type: string channel: type: string enum: - 10dlc - toll-free brand_id: type: - string - 'null' description: null for toll-free projects. campaign_id: type: - string - 'null' description: null for toll-free broadcast projects. toll_free_verification_id: type: - string - 'null' description: null for 10DLC projects. phone_number_ids: type: array items: type: string name: type: string status: type: string type: type: string enum: - broadcast - survey protocol: type: string enum: - sms - mms message_text: type: - string - 'null' description: null for survey projects. contact_list_ids: type: array items: type: string suppression_list_ids: type: array items: type: string media_ids: type: array items: type: string description: >- Always an empty array in the current API version; attached media is exposed via media_urls. media_urls: type: array items: type: string link_tracking_enabled: type: boolean link_tracking_destination_url: type: - string - 'null' description: >- May be exactly 'https://{}' (a whole-URL placeholder). In that mode link_tracking_fallback_url is also set, and each recipient's tracking link resolved to the URL in that recipient's contact field (or the fallback) at link-creation time. link_tracking_domain_id: type: - string - 'null' link_tracking_param_field: type: - string - 'null' link_tracking_fallback_url: type: - string - 'null' description: >- Redirect used when a recipient's link_tracking_param_field value was empty or not a valid URL. Set only when link_tracking_destination_url is a whole-URL placeholder. opt_out_footer_enabled: type: boolean description: >- Whether the 'STOP=END' opt-out footer is appended to outbound messages (always true for surveys' stored flag, but surveys never send the footer). ai_survey_analysis_enabled: type: boolean total_recipients: type: integer estimated_cost_cents: type: integer scheduled_at: type: - string - 'null' scheduled_timezone: type: - string - 'null' pause_reason: type: - string - 'null' description: >- Why a `paused` project stopped; null when not paused. Known values: `brand_daily_cap` (T-Mobile daily cap reached; schedule it for the next day's sending hours with `POST /projects/{id}/schedule` and a morning `scheduled_at`, or resume now with `daily_cap_bypass: true`), `quiet_hours` (paused when the project's sending window closes: 10 PM in the time zone of most recipients, or 10 PM Pacific when no zone holds a majority; restart manually once the window opens), `carrier_block_rate`, `unregistered_campaign`, `provider_error`, `insufficient_funds_auto_recharge_failed`, `insufficient_funds_ancestor`, `shared_phone_revoked`, `phone_released`, `organization_deleted`, and `manual` or a short free-text reason (up to 100 characters) set by a user who paused it. Other values may appear. Every automatic pause needs a manual restart via `POST /projects/{id}/schedule`. auto_paused: type: boolean description: >- true when the platform paused the project itself (for example at the daily cap). Start it again with `POST /projects/{id}/schedule`. daily_cap_bypass: type: boolean description: >- Whether the project runs through the T-Mobile daily cap. Set by the last schedule or resume call. created_via_api: type: boolean created_at: type: string format: date-time updated_at: type: string format: date-time questions: type: array items: type: object properties: id: type: string sequence: type: integer question_type: type: string enum: - intro - multiple_choice - open_ended - outro question_text: type: string message_type: type: string enum: - sms - mms media_urls: type: array items: type: string response_options: type: - array - 'null' items: type: object properties: value: type: integer label: type: string next_sequence: type: - integer - 'null' additionalProperties: true no_match_sequence: type: - integer - 'null' is_required: type: boolean additionalProperties: true description: Survey projects only; absent on broadcast projects. additionalProperties: true required: - success - data additionalProperties: true example: success: true data: project_id: 8a3f5c7e-2d91-4b64-ae08-6f1c9d3e7b52 organization_id: 0d9f6a2e-1b34-4c8e-9f21-3e7a8b5c4d10 channel: 10dlc brand_id: 7c1de5f0-9a42-4b6d-8e33-2f5a9c7b1e64 campaign_id: 4b8fa3c1-6d25-4e9a-bf47-8c2e5d9a3f71 toll_free_verification_id: null phone_number_ids: - b2e8d4f6-1a37-4c95-8e62-5d9f3b7a1c48 name: July GOTV Blast status: ready type: broadcast protocol: sms message_text: Hi {{first_name}}, election day is coming up! contact_list_ids: - 3f7a9c1e-8b24-4d6f-a2e5-9c7b3f1a8d42 suppression_list_ids: [] media_ids: [] media_urls: [] link_tracking_enabled: true link_tracking_destination_url: https://smithcampaign.com/vote link_tracking_domain_id: 6e2c9a4f-8b51-4d73-a9e6-1f4b8c5d2a90 link_tracking_param_field: phone link_tracking_fallback_url: null opt_out_footer_enabled: true ai_survey_analysis_enabled: false total_recipients: 11800 estimated_cost_cents: 35400 scheduled_at: null scheduled_timezone: null created_via_api: true created_at: '2025-07-01T14:00:00.000Z' updated_at: '2025-07-02T09:15:00.000Z' pause_reason: null auto_paused: false daily_cap_bypass: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- Project is not in an editable state (only draft, awaiting_test, and ready projects can be updated; error code INVALID_STATE_TRANSITION), or a contact list on the project is still being analyzed (error code LIST_ANALYSIS_IN_PROGRESS; nothing is changed, retry as-is once `analysis.status` is `complete`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: IdPath: name: id in: path required: true description: Resource ID schema: type: string IdempotencyKeyHeader: name: Idempotency-Key in: header required: false schema: type: string minLength: 16 maxLength: 200 description: >- 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. responses: BadRequest: description: >- Invalid request (validation failure, malformed parameters, or a request the resource state does not allow). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Validation failed code: VALIDATION_ERROR correlationId: 030bf857-922f-4b82-8fca-c5b0769c1590 details: - field: organization_id message: Invalid UUID code: invalid_format Unauthorized: description: Missing, malformed, revoked, or expired API key. content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' example: error: API key required message: Please provide an API key in the X-API-Key header Forbidden: description: >- The API key lacks the required permission scope, or the requested resource belongs to an organization outside the key's hierarchy. content: application/json: schema: oneOf: - $ref: '#/components/schemas/AuthErrorResponse' - $ref: '#/components/schemas/ErrorResponse' examples: missingScope: summary: Key lacks the required permission scope value: error: Insufficient permissions message: >- This API key does not have the required permissions: public:read orgAccessDenied: summary: Resource outside the key's organization hierarchy value: error: >- Access denied: You do not have permission to access this organization's data code: ORG_ACCESS_DENIED correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e NotFound: description: Resource not found or not visible to this API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Project not found code: PROJECT_NOT_FOUND correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e RateLimited: description: Rate limit exceeded. Check the Retry-After header. headers: Retry-After: description: Seconds until the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' example: success: false error: Rate limit exceeded message: Maximum 600 requests per 60 seconds code: RATE_LIMIT_EXCEEDED statusCode: 429 retryAfter: 3 InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: An unexpected error occurred. Please try again later. code: INTERNAL_ERROR correlationId: de038205-7c9c-4d4a-99bc-d7275a52f07e schemas: ErrorResponse: type: object properties: error: type: string description: Human-readable error message. code: type: string description: >- Machine-readable error code, e.g. VALIDATION_ERROR, ORG_ACCESS_DENIED, PROJECT_NOT_FOUND. correlationId: type: string description: Request correlation ID; include it in support requests. details: type: - array - object description: >- Present on some errors. For VALIDATION_ERROR, an array of { field, message, code } with one entry per rejected field (field is the dotted path); an object for other codes (e.g. insufficient-balance shortfall). required: - error - code additionalProperties: true description: >- Standard error body produced by the API error handler for 4xx/5xx responses. AuthErrorResponse: type: object properties: error: type: string description: Short error summary. message: type: string description: Human-readable detail. required: - error - message additionalProperties: true description: >- Error body returned by the API-key authentication layer (401 and permission 403s). RateLimitErrorResponse: type: object properties: success: type: boolean enum: - false error: type: string message: type: string code: type: string enum: - RATE_LIMIT_EXCEEDED statusCode: type: integer enum: - 429 retryAfter: type: integer description: >- Seconds until the rate-limit window resets. Also sent as the Retry-After header. required: - success - error - code - statusCode - retryAfter additionalProperties: true securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- Authenticate every request by passing your API key in the X-API-Key header. Keys are scoped to your organization hierarchy. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.