Skip to content
US Short Code Campaign Re...
/Getting started/
Register a campaign
Last updated

Getting started with registering a campaign

To register a brand, follow these steps:

  1. Create and submit campaign
  2. Upload an attachment
  3. Request client certification

Authentication

All API endpoints described below require authentication. You can authenticate your requests using one of the following two methods for the Authorization header:

Bearer Token:

    Authorization: Bearer <YourJwtToken>

Basic Authentication:

    Authorization: Basic <YourBase64EncodedCredentials>

CreateAndSubmit Campaign

This endpoint allows for the creation and submission of a new campaign in a single API call. All fields are mandatory except for notes, complianceEmails, carrierIds, termsAndConditions.text and privacyPolicy.text, which are optional fields. When scRequested=false, then shortcode is mandatory, otherwise, brandId is mandatory. When carrierIds are not present, all available carrierIds are automatically included.

The following curl command demonstrates how to create and submit a new campaign:

Request

curl -X POST "https://campaigns-api.numbers-registration.prod.sinch.com/v1/projects/<projectId>/campaigns:submit"
  -H "Authorization: Bearer <JWT Token>"
  -H "Content-Type: application/json"
  -d '{
    "name": "Test Campaign",
    "trafficCharge": "STANDARD",
    "scRequested": true,
    "description": "New campaign",
    "contactEmails": ["contact@sinch.com"],
    "complianceEmails": ["compliance@sinch.com"],
    "brandId": "01k7h5y64mh4fwcmxxa48h9m75",
    "isMigrated": false,
    "callbackUrl": "https://webhook.site/d73ba377-90c3-4029-9a99-fe5a7d485b49",
    "notes": ["Initial note"],
    "carrierIds": ["1", "2", "4"],
    "customerCare": {
      "optOutKeywords": "OPT Out Keywords",
      "optOutMtText": "Opt Out Mt text",
      "helpMtText": "Help My Text",
      "email": "eded@sinch.com",
      "website": "https://website.com",
      "phoneNumber": "+346555555555"
    },
    "contentDefinitions": [
    {
      "messageType": "SMS",
      "contentType": "INFORMATIONAL_ALERTS",
      "subscription": "ONE_TIME",
      "messageFlow": {
        "callToAction": "Call 1",
        "optIn": "Opt In",
        "sampleAlert": "Sample Alert"
      }
    },
    {
      "messageType": "MMS_VIDEO",
      "contentType": "ENTERTAINMENT_ALERTS",
      "subscription": "SUBSCRIPTION",
      "messageFlow": {
        "callToAction": "Call 2",
        "optIn": "Opt In 2",
        "sampleAlert": "Sample Alert2"
      }
    }],
    "termsAndConditions": {
      "text": "My terms text",
      "url": "https://www.mycompany.com/myterms"
    },
    "privacyPolicy": {
      "text": "My Privacy Policy",
      "url": "https://www.mycompany.com/policy"
    },
    "attachments": ["663"]
  }'

Response

{
  "campaignId": "8834",
  "name": "Test Campaign",
  "description": "New campaign",
  "trafficCharge": "STANDARD",
  "status": "PENDING_REVIEW",
  "scRequested": true,
  "brandId": "01k7h5y64mh4fwcmxxa48h9m75",
  "customerCare": {
    "optOutKeywords": "OPT Out Keywords",
    "optOutMtText": "Opt Out Mt text",
    "helpMtText": "Help My Text",
    "email": "eded@sinch.com",
    "website": "https://website.com",
    "phoneNumber": "+346555555555"
  },
  "contentDefinitions": [
    {
      "contentType": "INFORMATIONAL_ALERTS",
      "messageType": "SMS",
      "subscription": "ONE_TIME",
      "messageFlow": {
        "callToAction": "Call 1",
        "optIn": "Opt In",
        "sampleAlert": "Sample Alert"
      }
    },
    {
      "contentType": "ENTERTAINMENT_ALERTS",
      "messageType": "MMS_VIDEO",
      "subscription": "SUBSCRIPTION",
      "messageFlow": {
        "callToAction": "Call 2",
        "optIn": "Opt In 2",
        "sampleAlert": "Sample Alert2"
      }
    }
  ],
  "termsAndConditions": {
    "text": "My terms text",
    "url": "https://www.mycompany.com/myterms"
  },
  "privacyPolicy": {
    "text": "My Privacy Policy",
    "url": "https://www.mycompany.com/policy"
  },
  "complianceEmails": [
    "compliance1@sinch.com",
    "compliance2@sinch.com"
  ],
  "contactEmails": [
    "myemail@sinch.com",
    "borja.pilarte@sinch.com"
  ],
  "callbackUrl": "https://webhook.site/d73ba377-90c3-4029-9a99-fe5a7d485b49",
  "isMigrated": false,
  "carrierOrders": [
    {
      "carrierOrderId": "71052",
      "carrierId": "1",
      "carrierName": "AT&T Mobility",
      "status": "PENDING",
      "notes": [],
      "logs": [],
      "createdAt": "2025-11-19T10:12:12Z",
      "updatedAt": "2025-11-19T10:12:12Z"
    },
    {
      "carrierOrderId": "71053",
      "carrierId": "2",
      "carrierName": "Verizon Wireless",
      "status": "PENDING",
      "notes": [],
      "logs": [],
      "createdAt": "2025-11-19T10:12:13Z",
      "updatedAt": "2025-11-19T10:12:13Z"
    },
    {
      "carrierOrderId": "71054",
      "carrierId": "4",
      "carrierName": "T-Mobile & MetroPCS",
      "status": "PENDING",
      "notes": [],
      "logs": [],
      "createdAt": "2025-11-19T10:12:13Z",
      "updatedAt": "2025-11-19T10:12:13Z"
    }
  ],
  "campaignAttachments": [
    {
      "attachmentId": "663",
      "name": "myAttachment.pdf",
      "description": "proof of ownership"
    }
  ],
  "logs": [
    {
      "previousStatus": "DRAFT",
      "currentStatus": "PENDING_REVIEW",
      "createdAt": "2025-11-19T10:12:13Z"
    }
  ],
  "notes": [
    {
      "author": "CUSTOMER",
      "text": "Initial note",
      "createdAt": "2025-11-19T10:12:13Z"
    }
  ],
  "createdAt": "2025-11-19T10:12:12Z",
  "updatedAt": "2025-11-19T10:12:13Z"
}

Upload an attachment

An attachment can be uploaded for project:

Request

curl -X POST --location 'https://campaigns.numbers-registration.staging.sinch.com/v1/projects/<projectId>/attachments'
  -H "Authorization: Bearer <JWT Token>" 
  --form 'file=@"<file_location>"'

Request Client Certification

Once the Carrier Order is in Provisioned by Sinch state, the Request Client Certification may be called:

Request

curl -X POST "https://campaigns.numbers-registration.staging.sinch.com/v1/projects/<projectId>/campaigns/<campaignId>/carriers/<carrierOrderId>/request-certification
  -H "Authorization: Bearer <JWT Token>"
  -H "Content-Type: application/json"

Response

{
    "carrierOrderId": "69635",
    "carrierId": "1",
    "carrierName": "AT&T Mobility",
    "status": "CLIENT_CERTIFICATION_REQUESTED",
    "notes": [],
    "logs": [
        {
            "previousStatus": "PENDING",
            "currentStatus": "SUBMITTED",
            "createdAt": "2025-10-20T09:15:11Z"
        },
        {
            "previousStatus": "SUBMITTED",
            "currentStatus": "APPROVED",
            "createdAt": "2025-10-20T09:15:28Z"
        },
        {
            "previousStatus": "APPROVED",
            "currentStatus": "PROVISIONED_BY_CARRIER",
            "createdAt": "2025-10-20T09:15:45Z"
        },
        {
            "previousStatus": "PROVISIONED_BY_CARRIER",
            "currentStatus": "PROVISIONED_BY_SINCH",
            "createdAt": "2025-10-20T09:59:02Z"
        },
        {
            "previousStatus": "PROVISIONED_BY_SINCH",
            "currentStatus": "CLIENT_CERTIFICATION_REQUESTED",
            "createdAt": "2025-10-20T10:04:13Z"
        }
    ],
    "createdAt": "2025-10-15T15:20:05Z",
    "updatedAt": "2025-10-20T10:04:13Z"
}

Update Campaign

This endpoint allows you to modify the details of an existing campaign. To use it, you must specify which campaign to update by including campaignId in the API endpoint's URL.

Request

curl -X PUT "https://campaigns.numbers-registration.staging.sinch.com/v1/projects/<projectId>/campaigns/<campaignId>"
  -H "Authorization: Bearer <JWT Token>"
  -H "Content-Type: application/json"
  -d '{
  "name": "A new Campaign Created DEMO III",
  "trafficCharge": "STANDARD",
  "scRequested": true,
  "shortcode": "",
  "brandId": "01k6n04h28hn8m29a77ee3bj4p",
  "description": "My Description",
  "contactEmails": ["myemail@sinch.com", "myemail2@sinch.com"],
  "complianceEmails": ["compliance1@sinch.com", "compliance2@sinch.com"],
  "carrierIds": ["1", "2", "4"],
  "customerCare": {
    "optOutKeywords": "OPT Out Keywords",
    "optOutMtText": "Opt Out Mt text",
    "helpMtText": "Help My Text",
    "email": "eded@sinch.com",
    "website": "https://website.com",
    "phoneNumber": "+346555555555"
  },
  "contentDefinitions": [
    {
      "messageType": "SMS",
      "contentType": "INFORMATIONAL_ALERTS",
      "subscription": "ONE_TIME",
      "messageFlow": {
        "callToAction": "Call 1",
        "optIn": "Opt In",
        "sampleAlert": "Sample Alert"
      }
    },
    {
      "messageType": "MMS_VIDEO",
      "contentType": "ENTERTAINMENT_ALERTS",
      "subscription": "SUBSCRIPTION",
      "messageFlow": {
        "callToAction": "Call 2",
        "optIn": "Opt In 2",
        "sampleAlert": "Sample Alert2"
      }
    }
  ],
  "termsAndConditions": {
    "text": "My terms text",
    "url": "https://www.mycompany.com/myterms"
  },
  "privacyPolicy": {
    "text": "My Privacy Policy",
    "url": "https://www.mycompany.com/policy"
  },
  "isMigrated": false,
  "callbackUrl": "https://webhook.site/dab8449d-aea8-4a8b-b98b-01ad3406b38d",
  "attachments": ["663"]
}'

Response

{
  "campaignId": "8834",
  "name": "A new Campaign Created DEMO III",
  "description": "My Description",
  "trafficCharge": "STANDARD",
  "status": "AWAITING_CLIENT_UPDATE",
  "scRequested": true,
  "brandId": "01k6n04h28hn8m29a77ee3bj4p",
  "shortcode": "",
  "customerCare": {
    "optOutKeywords": "OPT Out Keywords",
    "optOutMtText": "Opt Out Mt text",
    "helpMtText": "Help My Text",
    "email": "eded@sinch.com",
    "website": "https://website.com",
    "phoneNumber": "+346555555555"
  },
  "contentDefinitions": [
    {
      "contentType": "INFORMATIONAL_ALERTS",
      "messageType": "SMS",
      "subscription": "ONE_TIME",
      "messageFlow": {
        "callToAction": "Call 1",
        "optIn": "Opt In",
        "sampleAlert": "Sample Alert"
      }
    },
    {
      "contentType": "ENTERTAINMENT_ALERTS",
      "messageType": "MMS_VIDEO",
      "subscription": "SUBSCRIPTION",
      "messageFlow": {
        "callToAction": "Call 2",
        "optIn": "Opt In 2",
        "sampleAlert": "Sample Alert2"
      }
    }
  ],
  "termsAndConditions": {
    "text": "My terms text",
    "url": "https://www.mycompany.com/myterms"
  },
  "privacyPolicy": {
    "text": "My Privacy Policy",
    "url": "https://www.mycompany.com/policy"
  },
  "complianceEmails": [
    "compliance1@sinch.com",
    "compliance2@sinch.com"
  ],
  "contactEmails": [
    "myemail@sinch.com",
    "myemail2@sinch.com"
  ],
  "callbackUrl": "https://webhook.site/dab8449d-aea8-4a8b-b98b-01ad3406b38d",
  "isMigrated": false,
  "carrierOrders": [
    {
      "carrierOrderId": "71052",
      "carrierId": "1",
      "carrierName": "AT&T Mobility",
      "status": "PENDING",
      "notes": [],
      "logs": [],
      "createdAt": "2025-11-19T10:12:12Z",
      "updatedAt": "2025-11-19T10:12:12Z"
    },
    {
      "carrierOrderId": "71053",
      "carrierId": "2",
      "carrierName": "Verizon Wireless",
      "status": "PENDING",
      "notes": [],
      "logs": [],
      "createdAt": "2025-11-19T10:12:13Z",
      "updatedAt": "2025-11-19T10:12:13Z"
    },
    {
      "carrierOrderId": "71054",
      "carrierId": "4",
      "carrierName": "T-Mobile & MetroPCS",
      "status": "PENDING",
      "notes": [],
      "logs": [],
      "createdAt": "2025-11-19T10:12:13Z",
      "updatedAt": "2025-11-19T10:12:13Z"
    }
  ],
  "campaignAttachments": [
    {
      "attachmentId": "663",
      "name": "Screenshot 2025-09-30 at 17.25.48.png",
      "description": "proof of ownership"
    }
  ],
  "logs": [
    {
      "previousStatus": "DRAFT",
      "currentStatus": "PENDING_REVIEW",
      "createdAt": "2025-11-19T10:12:13Z"
    },
    {
      "previousStatus": "PENDING_REVIEW",
      "currentStatus": "REVIEWING",
      "createdAt": "2025-11-19T10:21:42Z"
    },
    {
      "previousStatus": "REVIEWING",
      "currentStatus": "AWAITING_CLIENT_UPDATE",
      "createdAt": "2025-11-19T10:21:47Z"
    }
  ],
  "notes": [
    {
      "author": "CUSTOMER",
      "text": "My added note 1",
      "createdAt": "2025-11-19T10:12:13Z"
    },
    {
      "author": "CUSTOMER",
      "text": "My added note 2",
      "createdAt": "2025-11-19T10:12:13Z"
    }
  ],
  "createdAt": "2025-11-19T10:12:12Z",
  "updatedAt": "2025-11-19T10:22:00Z"
}

Callback event reception

If a callback URL was specified in the CreateAndSubmit or Update Request endpoint, then callback events will be received once the campaign state changes.

Receive callback for Status Campaign update

When a campaign is first submitted, it receives a PENDING_REVIEW status. Once it is picked up for the review process, its status will be updated to REVIEWING. This REVIEWING status confirms that the campaign is now in process of internal review by our team. Once the review is complete and the status changes again (e.g., to COMPLETED or CANCELLED), a callback notification will be sent to the callback_url you provided. Please, read carefully the callback configuration API documentation to see how to authenticate this event.

{
  "eventId": "01k7m7aj4z127xs47rby8csbe6",
  "resourceId": "8567",
  "projectId": "27eb83b8-6030-491b-a3f5-2fc4b92a3aee",
  "resourceType": "CAMPAIGN",
  "eventType": "CAMPAIGN_STATUS_UPDATE",
  "createTime": "2025-10-15T15:20:24Z",
  "campaignStatus": {
    "campaignId": "8567",
    "newStatus": "REVIEWING"
  }
}

Receive callback for Status Carrier Order Update

A similar message is sent to update the carrier order status. When a campaign is first submitted, it receives a SUBMITTED status. A callback notification is sent to the provided callback_url.

{
  "eventId": "01k82z9pw57pscp4eber3d5vmg",
  "resourceId": "69962",
  "projectId": "27eb83b8-6030-491b-a3f5-2fc4b92a3aee",
  "resourceType": "CARRIER_ORDER",
  "eventType": "CARRIER_ORDER_STATUS_UPDATE",
  "createTime": "2025-10-21T08:48:44Z",
  "carrierOrderStatus": {
    "campaignId": "8633",
    "carrierOrderId": "69962",
    "newStatus": "APPROVED"
  }
}

Receive callback for Create Campaign Note

You will receive a callback notification at your provided callback_url when a reviewer adds a note to a submitted campaign. Please, read carefully the callback configuration API documentation to see how to authenticate this event.

{
  "eventId": "01k815m2n680rknjwgsf1nt000",
  "resourceId": "8624",
  "projectId": "27eb83b8-6030-491b-a3f5-2fc4b92a3aee",
  "resourceType": "CAMPAIGN",
  "eventType": "CAMPAIGN_NOTE",
  "createTime": "2025-10-20T16:00:46Z",
  "campaignNote": {
    "campaignId": "8624",
    "note": {
      "author": "AGENT",
      "text": "Test Note Public",
      "createdAt": "2025-10-20T16:00:46Z"
    }
  }
}

Receive callback for Create Carrier Order Note

A similar message is sent when a Note is created for Carrier Order. You will receive a callback notification at your provided callback_url when a reviewer adds a note to a submitted carrier order. Please, read carefully the callback configuration API documentation to see how to authenticate this event.

{
  "eventId": "01k831skbapcvh4mf9ffrp071h",
  "resourceId": "69962",
  "projectId": "27eb83b8-6030-491b-a3f5-2fc4b92a3aee",
  "resourceType": "CARRIER_ORDER",
  "eventType": "CARRIER_ORDER_NOTE",
  "createTime": "2025-10-21T09:32:22Z",
  "carrierOrderNote": {
    "campaignId": "8633",
    "carrierOrderId": "69962",
    "note": {
      "author": "AGENT",
      "text": "Test Carrier Order note",
      "createdAt": "2025-10-21T09:32:22Z"
    }
  }
}
We'd love to hear from you!
Rate this content:

Getting started

Overview