Register a campaign | Surge

To crack down on spam and other undesirable messaging, carriers must know the legal entity responsible for each text message sent from software to a device on their network. Each phone number that will be sending messages from an application to a person must be associated with a “campaign” that explains who will be sending messages, why, and how the end user will opt in to and out of receiving them.

This guide covers registering a campaign through the API for an account.

Create an account

Skip this step if you already have an account for this campaign.

Many fields on the account are optional at this step but will be required to register a campaign. Certain fields will also affect requirements for other fields; organization.type, for example, drastically affects which fields are required. We therefore recommend including all the fields you believe you need in the intial create to reduce iterations on providing missing fields.

See “Create an account”.

Here’s an example where most of the fields required for local messaging are provided.

1 curl -X POST https://api.surge.app/accounts \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "name": "DT Precision Auto",
6   "organization": {
7     "address": {
8       "name": "DT Precision Auto",
9       "line1": "2640 Huron St",
10       "locality": "Los Angeles",
11       "postal_code": "90065",
12       "region": "CA",
13       "country": "US"
14     },
15     "contact": {
16       "first_name": "Dominic",
17       "last_name": "Toretto",
18       "email": "dom@dtprecisionauto.com",
19       "phone_number": "+13235556439"
20     },
21     "industry": "automotive",
22     "type": "llc",
23     "website": "https://dtprecisionauto.com"
24   }
25 }'

Check account capabilities (optional)

This step allows you to check for missing or invalid fields on the account that must be provided or fixed before it is ready to register a campaign.

See “Check account status”.

This example checks the local messaging capability of the account created in the previous example.

1 curl -G https://api.surge.app/accounts/acct_01jpqjvfg9enpt7pyxd60pcmxj/status?capabilities=local_messaging \
2      -H "Authorization: Bearer <token>"

Update account (optional)

If the capability request did not return a ready status, you’ll need to update the account to fix missing or broken fields. As mentioned in the “Create an account” step, fixing fields can uncover additional fields that need changed, so you may need to repeat this step and the previous until the account is ready for local messaging.

See “Update an account”.

This example provides the missing fields from the example in the previous step.

1 curl -X PATCH https://api.surge.app/accounts/acct_01jpqjvfg9enpt7pyxd60pcmxj \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "organization": {
6     "contact": {
7       "title": "other",
8       "title_other": "Owner"
9     },
10     "country": "US",
11     "identifier": "123456789",
12     "identifier_type": "ein",
13     "regions_of_operation": ["usa_and_canada"],
14     "registered_name": "DT Precision Auto LLC",
15   }
16 }'

Create a campaign

Once the account is ready for local messaging you can create a campaign documenting its intended messaging use case.

See “Create a campaign”.

1 curl -X POST https://api.surge.app/accounts/acct_01jpqjvfg9enpt7pyxd60pcmxj/campaigns \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "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.",
6   "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.",
7   "message_samples": [
8     "You are now opted in to receive repair notifications from DT Precision Auto. Frequency varies. Msg&data rates apply. Reply STOP to opt out.",
9     "You’re lucky that hundred shot of NOS didn’t blow the welds on the intake!",
10     "Your car is ready to go. See your invoice here: https://l.fastauto.shop/s034ij"
11   ],
12   "privacy_policy_url": "https://fastauto.shop/sms-privacy",
13   "use_cases": [
14     "account_notification",
15     "customer_care",
16     "marketing"
17   ],
18   "volume": "high",
19   "includes": [
20     "links",
21     "phone_numbers"
22   ],
23   "link_sample": "https://l.fastauto.shop/s034ij",
24   "terms_and_conditions_url": "https://fastauto.shop/terms-and-conditions"
25 }'

Purchase a phone number

While you await campaign approval, you can purchase a phone number for the account, and it will be ready to send text messages when the campaign is approved.

See “Create a phone number”.

1 curl -X POST https://api.surge.app/accounts/acct_01jpqjvfg9enpt7pyxd60pcmxj/phone_numbers \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "type": "local",
6   "area_code": "323"
7 }'