SUsurgeapi
Campaigns

Update a campaign

Changed on

Updates supplied fields on a campaign and submits it for review. Omitted fields retain their stored values. An empty object or empty request body resubmits the existing campaign without changing its registration details. Supplied arrays replace their stored values; an empty includes array clears all inclusion flags. Returns an error if the resulting campaign is incomplete or invalid, or the campaign is not editable.

patch/campaigns/{id}

Request

  • Base URL
    https://api.surge.app
  • URL
    https://api.surge.app/campaigns/{id}
  • Auth
    HTTP bearer

Path parameters

idstring required

The ID of the campaign to update.

Example:cpn_01k0qczvhbet4azgn5xm2ccfst

Request body

consent_flowstring

A string explaining the method through which end users will opt in to receive messages from the brand. Typically this should include URLs for opt-in forms or screenshots that might be helpful in explaining the flow to someone unfamiliar with the organization's purpose.

descriptionstring

An explanation of the organization's purpose and how it will be using text messaging to accomplish that purpose.

includesstring[]

A list of properties that this campaign should include. These properties can be any of the following values:

  • links - whether the campaign might send links in messages
  • phone_numbers - whether the campaign might send phone numbers in messages
  • age_gated - whether the campaign contains age gated content (controlled substances or adult content)
  • direct_lending - whether the campaign contains content related to direct lending or other loan arrangements
link_samplestring uri nullable

A sample link that might be sent by this campaign. This is required when includes contains links. Provide the same URL or domain that the campaign will use in production. If links from other domains are sent through this campaign, they are much more likely to be filtered by the carriers.

message_samplesstring[]

An array of 2-5 strings with examples of the messages that will be sent from this campaign. Typically the first sample should be a compliance message like You are now opted in to messages from {brand name}. Frequency varies. Msg&data rates apply. Reply STOP to opt out. These samples don't necessarily need to be the only templates that will be used for the campaign, but they should reflect the purpose of the messages that will be sent. Any variable content can be reflected by wrapping it in square brackets like [customer name].

privacy_policy_urlstring uri

The URL of the privacy policy for the brand in question. This may be a shared privacy policy if it's the policy that is displayed to end users when they opt in to messaging.

terms_and_conditions_urlstring uri

The URL of the terms and conditions presented to end users when they opt in to messaging. These terms and conditions may be shared among all of a platform's customers if they're the terms that are presented to end users when they opt in to messaging.

use_casesstring[]

A list containing 1-5 types of messages that will be sent with this campaign.

The following use cases are typically available to all brands:

  • account_notification - For sending reminders, alerts, and general account-related notifications like booking confirmations or appointment reminders.
  • customer_care - For account support, troubleshooting, and general customer service communication.
  • delivery_notification - For notifying customers about the status of product or service deliveries.
  • fraud_alert - For warning customers about suspicious or potentially fraudulent activity.
  • higher_education - For messaging related to colleges, universities, and school districts outside of K–12.
  • marketing - For promotional or advertising messages intended to market products or services.
  • polling_voting - For conducting surveys, polls, or voting-related messaging.
  • public_service_announcement - For raising awareness about social issues or important public information.
  • security_alert - For alerts related to potential security breaches or compromised systems requiring user action.
  • two_factor_authentication - For sending one-time passwords or verification codes for login or password reset.

For access to special use cases not shown here, reach out to support@surge.app.

volume'high' | 'low'

This will be one of the following:

  • low - The campaign will be allowed to send up to 2000 SMS segments to T-Mobile customers each day. In this case your project will be charged for the setup fee for a low volume number upon receipt of the API request.
  • high - The campaign will be allowed to send up to 200k SMS segments to T-Mobile customers each day, depending on the trust score assigned by The Campaign Registry. Your project will be charged for the setup fee for a high volume number upon receipt of the API request, and phone numbers will be charged as high volume numbers going forward.

Example request

{}

Response

Updated campaign

account_idstring required

The ID of the account that owns this campaign

consent_flowstring required

A string explaining the method through which end users will opt in to receive messages from the brand. Typically this should include URLs for opt-in forms or screenshots that might be helpful in explaining the flow to someone unfamiliar with the organization's purpose.

descriptionstring required

An explanation of the organization's purpose and how it will be using text messaging to accomplish that purpose.

idstring required

The campaign ID

includesstring[] required

A list of properties that this campaign should include. These properties can be any of the following values:

  • links - whether the campaign might send links in messages
  • phone_numbers - whether the campaign might send phone numbers in messages
  • age_gated - whether the campaign contains age gated content (controlled substances or adult content)
  • direct_lending - whether the campaign contains content related to direct lending or other loan arrangements
link_samplestring uri

A sample link that might be sent by this campaign. This is required when includes contains links. Provide the same URL or domain that the campaign will use in production. If links from other domains are sent through this campaign, they are much more likely to be filtered by the carriers.

message_samplesstring[] required

An array of 2-5 strings with examples of the messages that will be sent from this campaign. Typically the first sample should be a compliance message like You are now opted in to messages from {brand name}. Frequency varies. Msg&data rates apply. Reply STOP to opt out. These samples don't necessarily need to be the only templates that will be used for the campaign, but they should reflect the purpose of the messages that will be sent. Any variable content can be reflected by wrapping it in square brackets like [customer name].

privacy_policy_urlstring uri required

The URL of the privacy policy for the brand in question. This may be a shared privacy policy if it's the policy that is displayed to end users when they opt in to messaging.

status'active' | 'canceled' | 'rejected' | 'created' | 'deactivated' | 'in_review' required

The current status of the campaign.

terms_and_conditions_urlstring uri

The URL of the terms and conditions presented to end users when they opt in to messaging. These terms and conditions may be shared among all of a platform's customers if they're the terms that are presented to end users when they opt in to messaging.

use_casesstring[] required

A list containing 1-5 types of messages that will be sent with this campaign.

The following use cases are typically available to all brands:

  • account_notification - For sending reminders, alerts, and general account-related notifications like booking confirmations or appointment reminders.
  • customer_care - For account support, troubleshooting, and general customer service communication.
  • delivery_notification - For notifying customers about the status of product or service deliveries.
  • fraud_alert - For warning customers about suspicious or potentially fraudulent activity.
  • higher_education - For messaging related to colleges, universities, and school districts outside of K–12.
  • marketing - For promotional or advertising messages intended to market products or services.
  • polling_voting - For conducting surveys, polls, or voting-related messaging.
  • public_service_announcement - For raising awareness about social issues or important public information.
  • security_alert - For alerts related to potential security breaches or compromised systems requiring user action.
  • two_factor_authentication - For sending one-time passwords or verification codes for login or password reset.

For access to special use cases not shown here, reach out to support@surge.app.

volume'high' | 'low' required

This will be one of the following:

  • low - The campaign will be allowed to send up to 2000 SMS segments to T-Mobile customers each day. In this case your project will be charged for the setup fee for a low volume number upon receipt of the API request.
  • high - The campaign will be allowed to send up to 200k SMS segments to T-Mobile customers each day, depending on the trust score assigned by The Campaign Registry. Your project will be charged for the setup fee for a high volume number upon receipt of the API request, and phone numbers will be charged as high volume numbers going forward.

Example response

{
  "account_id": "acct_01j9a43avnfqzbjfch6pygv1td",
  "consent_flow": "When customers bring in their car for service, they will fill out this web form for intake: https://fastauto.shop/bp108c In it they can choose to opt in to text message notifications. If they choose to opt in, we will send them notifications to let them know if our mechanics find issues and once the car is ready to go, as well as links to invoices and to leave us feedback.",
  "description": "This phone number will send auto maintenance notifications to end users that have opted in. It will also be used for responding to customer inquiries and sending some marketing offers.",
  "id": "cpn_01k0qczvhbet4azgn5xm2ccfst",
  "includes": [
    "links",
    "phone_numbers"
  ],
  "link_sample": "https://l.fastauto.shop/s034ij",
  "message_samples": [
    "You are now opted in to receive repair notifications from DT Precision Auto. Frequency varies. Msg&data rates apply. Reply STOP to opt out.",
    "You're lucky that hundred shot of NOS didn't blow the welds on the intake!",
    "Your car is ready to go. See your invoice here: https://l.fastauto.shop/s034ij"
  ],
  "privacy_policy_url": "https://fastauto.shop/sms-privacy",
  "status": "pending",
  "terms_and_conditions_url": "https://fastauto.shop/terms-and-conditions",
  "use_cases": [
    "account_notification",
    "customer_care",
    "marketing"
  ],
  "volume": "high"
}

Changes

  • 912b2a3101fcRevision changes
    • breaking

      removed from the request body oneOf list

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      request body became optional

    • info

      added the required property to the response with the status

  • 93f3909cbde3Revision changes
    • warning

      added the new rejected enum value to the response property for the response status