US 10DLC registration

US carriers block SMS from numbers that are not registered. A local 10-digit number (10DLC) needs a registered brand (who is sending) and campaign (what they send and how people opted in). A toll-free number goes through toll-free verification instead. Pozy files both through one endpoint, POST /v1/sms/registrations, reviews the filing before it reaches the carriers, and tracks it to approval.

A US number receives texts from the moment SMS is on. It can send only once its registration is approved. Numbers in other countries skip all of this.

#Choose the registration type

#What it costs

Registration adds a one-time brand fee and a monthly campaign fee to your invoice. Adding more numbers to an approved registration is free.

#Before you start

1. Buy or port an SMS-capable US number.
2. Enable SMS on it with POST /v1/phone-numbers/{id}/sms. The response tells you whether the number needsRegistration and whether a reusable approval already covers it. See Send SMS.

#Register a company (standard 10DLC)

curl -X POST https://api.pozy.ai/v1/sms/registrations \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "registrationType": "standard_10dlc",
    "phoneNumbers": ["+14155550142"],
    "brand": {
      "entityType": "PRIVATE_PROFIT",
      "displayName": "Acme",
      "companyName": "Acme Inc.",
      "ein": "12-3456789",
      "phone": "+14155550199",
      "email": "ops@acme.example.com",
      "website": "https://acme.example.com",
      "vertical": "RETAIL",
      "street": "500 Howard St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    },
    "campaign": {
      "usecase": "CUSTOMER_CARE",
      "description": "Order updates and replies to support questions for Acme customers.",
      "messageFlow": "Customers tick an unchecked SMS consent box at checkout on https://acme.example.com/checkout.",
      "sample1": "Acme: order #1234 has shipped and arrives Thursday. Reply STOP to opt out.",
      "sample2": "Acme: a support agent answered your question. Reply HELP for help.",
      "optinKeywords": "START",
      "optoutKeywords": "STOP",
      "helpKeywords": "HELP"
    }
  }'

const res = await fetch("https://api.pozy.ai/v1/sms/registrations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    registrationType: "standard_10dlc",
    phoneNumbers: ["+14155550142"],
    brand: {
      entityType: "PRIVATE_PROFIT",
      displayName: "Acme",
      companyName: "Acme Inc.",
      ein: "12-3456789",
      phone: "+14155550199",
      website: "https://acme.example.com",
      vertical: "RETAIL",
      street: "500 Howard St",
      city: "San Francisco",
      state: "CA",
      postalCode: "94105",
      country: "US",
    },
    campaign: {
      usecase: "CUSTOMER_CARE",
      description: "Order updates and replies to support questions for Acme customers.",
      messageFlow: "Customers tick an unchecked SMS consent box at checkout on https://acme.example.com/checkout.",
      sample1: "Acme: order #1234 has shipped and arrives Thursday. Reply STOP to opt out.",
      sample2: "Acme: a support agent answered your question. Reply HELP for help.",
      optinKeywords: "START",
      optoutKeywords: "STOP",
      helpKeywords: "HELP",
    },
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.registrationId, data.status); // "pending"

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/sms/registrations",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "registrationType": "standard_10dlc",
        "phoneNumbers": ["+14155550142"],
        "brand": {
            "entityType": "PRIVATE_PROFIT", "displayName": "Acme", "companyName": "Acme Inc.",
            "ein": "12-3456789", "phone": "+14155550199", "website": "https://acme.example.com",
            "vertical": "RETAIL", "street": "500 Howard St", "city": "San Francisco",
            "state": "CA", "postalCode": "94105", "country": "US",
        },
        "campaign": {
            "usecase": "CUSTOMER_CARE",
            "description": "Order updates and replies to support questions for Acme customers.",
            "messageFlow": "Customers tick an unchecked SMS consent box at checkout on https://acme.example.com/checkout.",
            "sample1": "Acme: order #1234 has shipped and arrives Thursday. Reply STOP to opt out.",
            "sample2": "Acme: a support agent answered your question. Reply HELP for help.",
            "optinKeywords": "START", "optoutKeywords": "STOP", "helpKeywords": "HELP",
        },
    },
    timeout=60,
)
print(resp.json())

#Write a filing that passes

Carriers reject thin filings. These fields decide most outcomes:

optinMessage, optoutMessage and helpMessage are optional: Pozy writes compliant auto-replies when you leave them out. subUsecases, embeddedLink, embeddedPhone, ageGated, privacyPolicyLink and termsAndConditionsLink describe the campaign in more detail.

#Check before you submit

POST /v1/sms/registrations/preflight takes the same body, runs the same checks plus a compliance review, and creates nothing. It returns a verdict (pass, warn, fail or unreviewed) and a list of advisories, each with a severity of block or warn.

#Register a sole proprietor

Use registrationType: "sole_prop_10dlc" and brand.entityType: "SOLE_PROPRIETOR", with a mobilePhone on the brand. The response has awaitingOtp: true, and a code is texted to that mobile.

curl -X POST https://api.pozy.ai/v1/sms/registrations/67a7b8c9d0e1f2a3b4c5d6e7/verify-otp \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "otpPin": "482913" }'

If the code expired or never arrived, POST /v1/sms/registrations/{id}/resend-otp sends a new one (at most once a minute).

#Verify a toll-free number

Toll-free numbers are verified separately, so the body takes a tollFree object instead of brand and campaign. Every field in it is required except businessAddr2.

{
  "registrationType": "toll_free",
  "phoneNumbers": ["+18445550100"],
  "tollFree": {
    "businessName": "Acme Inc.",
    "corporateWebsite": "https://acme.example.com",
    "phoneNumbers": ["+18445550100"],
    "useCase": "Customer care",
    "useCaseSummary": "Order updates and support replies for Acme customers.",
    "productionMessageContent": "Acme: order #1234 has shipped. Reply STOP to opt out.",
    "optInWorkflow": "Customers tick the SMS updates box at checkout on https://acme.example.com/checkout.",
    "optInWorkflowImageUrls": ["https://pozy.ai/media/opt-in-proof/acme-checkout.png"],
    "messageVolume": "10,000",
    "additionalInformation": "Transactional messages only.",
    "businessAddr1": "500 Howard St",
    "businessCity": "San Francisco",
    "businessState": "CA",
    "businessZip": "94105",
    "businessContactFirstName": "Dana",
    "businessContactLastName": "Reyes",
    "businessContactEmail": "dana@acme.example.com",
    "businessContactPhone": "+14155550199",
    "businessRegistrationNumber": "12-3456789",
    "businessRegistrationType": "EIN",
    "businessRegistrationCountry": "US"
  }
}

optInWorkflowImageUrls needs at least one screenshot of the opt-in form (upload it with POST /v1/sms/opt-in-proof). messageVolume is a monthly tier: 10, 100, 1,000, 10,000, 100,000, 250,000, 500,000, 750,000, 1,000,000, 5,000,000 or 10,000,000+. Toll-free verification has no code step and cannot be appealed.

#Reuse an approval on more numbers

Once one registration is approved, add more numbers to it instead of registering again. There is no new brand fee and no extra campaign.

curl -X POST https://api.pozy.ai/v1/phone-numbers/6650d2e1b3c4d5e6f7081924/sms/reuse-registration \
  -H "Authorization: Bearer $POZY_API_KEY"

{ "registrationId": "67a7b8c9d0e1f2a3b4c5d6e7", "status": "approved" }

Enable SMS on the number first. Its response shows the reusable registration.

#Let your customer fill it in

When your customer holds the legal business details, POST /v1/sms/registrations/share with a numberId returns a single-use link (valid 7 days). Your customer completes the form without a Pozy login, and the registration is created under your workspace.

#Track the registration

GET /v1/sms/registrations/{id} returns the current state. Branch on status, not on the raw carrier fields (brandStatus, campaignStatus).

#Answer a change request

POST /v1/sms/registrations/{id}/respond takes answers, one per point (pointId plus text, url or files), and an optional note. The registration goes back to requested.

#Appeal a rejected campaign

POST /v1/sms/registrations/{id}/appeal takes an appealReason (up to 2,000 characters) that answers declineReason directly, plus any corrected messageFlow, sample1 or sample2. The content on file comes back as campaignContent on a rejected registration. A rejection at brand level cannot be appealed: correct the brand and file again.

#Stop a registration

DELETE /v1/sms/registrations/{id} deactivates a brand or campaign registration. Its numbers can no longer send.

#Webhook events

Both carry registration.id and registration.profileId, not an account id.

#Errors

#Endpoints