Import SMS marketing opt-ins via API

Overview

If you have already collected SMS marketing consent from your customers outside of ServiceTitan, you can import those opt-ins into ServiceTitan using the Marketing API instead of asking those customers to opt in a second time.

This is useful when you have obtained consent through:

• A third-party platform — for example, an SMS marketing tool, customer engagement platform, or loyalty program you used before moving to Marketing Pro, or one you run alongside it.

• Your own web forms — for example, a lead form, quote request form, or newsletter signup on your website that includes SMS marketing consent language.

Imported opt-ins let you start sending marketing text messages to consenting customers right away, without interrupting them with a new opt-in request.

Things to know

Before you import opt-ins, read this section carefully. Importing consent records carries compliance obligations that stay with your business.

You are responsible for maintaining proof of consent

ServiceTitan does not store or validate the underlying proof of consent for imported opt-ins. When you import an opt-in, you are asserting to ServiceTitan that you have already obtained valid SMS marketing consent from that customer.

You must independently retain records that document each customer's consent, including:

• The date and time consent was given

• The exact consent language the customer agreed to

• The source of the consent (for example, the specific web form, platform, or campaign)

• The phone number the consent applies to

If a customer later contests their consent, or if you receive a carrier or regulatory inquiry, you will need to produce this proof yourself. ServiceTitan cannot provide it on your behalf.

Consult your own legal counsel to confirm that the consent you collected meets the requirements that apply to your business, including TCPA and applicable state regulations, and that your record retention practices are adequate.

Imported opt-ins are flagged

Opt-ins created through the API are marked with an imported flag. This distinguishes them from opt-ins collected organically through Marketing Pro's double opt-in flows, where ServiceTitan has a record of the customer's confirming reply.

The flag lets ServiceTitan tell the two consent sources apart when reviewing opt-in records or investigating a complaint.

Import opt-ins using the API

Opt-ins are imported through the Import Opt-In endpoint in the Marketing v2 API.

Endpoint reference: Sms_ImportOptIn — Marketing v2 API

The developer portal reference is the authoritative source for the request format, required fields, response codes, and rate limits. Use it alongside the steps below.

Import the opt-ins

1. Have your developer or integration partner authenticate against the ServiceTitan API. For more, see the authentication guide on the developer portal.

2. Call the Import Opt-In endpoint with the phone numbers and consent details from your records in your API Platform (i.e Postman). See the endpoint reference for the exact request body and field requirements.

3. Review the response for each request to confirm which opt-ins were accepted and which were rejected, and resolve any errors before retrying.

4. Verify the results in ServiceTitan. Go to Settings > Marketing Pro > Phone Numbers and confirm the imported numbers show a status of Opted In. 

Tip: Import a small test batch first and verify it in the Phone Numbers screen before importing your full list.

Keep imports in sync going forward

If you are collecting consent on an ongoing basis — for example, through a web form that stays live — set up your integration to import each new opt-in as it is collected, rather than importing in large periodic batches. This keeps your ServiceTitan audiences accurate and reduces the chance of texting someone whose consent status has changed.

Just as importantly, make sure opt-outs flow in the other direction. If a customer opts out in ServiceTitan, honor that in your third-party platform as well, and stop texting them from any system.

Verify imported opt-in status

After importing, you can confirm a customer's status the same way you would for any other opt-in.

From the customer record:

1. Search for and open the customer record.

2. In the side menu, click Edit next to Contact Methods.

3. Confirm the Marketing SMS Opt-In status for the mobile number is Opted In. 

From Marketing Pro settings:

1. Go to the top toolbar and click Settings.

2. In the side panel, go to Marketing Pro > Phone Numbers.

3. Search for the phone number, or filter the list by opt-in status.

For an explanation of each status, see the Understand opt-in statuses section in Generate opt-in requests for marketing text messages.