Sinch US ShortCode Campaigns API
Register and manage US short code campaigns.
Register and manage US short code campaigns.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/sinch:sinch-us-shortcode-campaigns-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
externalDocs:
description: All endpoints available under this API require Bearer token authentication. Please check oauth api documentation if you need more details.
url: https://developers.sinch.com/docs/numbers/api-reference/authentication/oauth/
info:
description: 'This API describes the set of endpoints available to create US Short Code Campaign requests.
The list of endpoints allows to create, update and delete a campaign and also get the current state.
Additional endpoints are available to get specific content or add notes to communicate to backoffice teams.'
title: Sinch US ShortCode Campaigns API
version: 0.0.1
contact:
name: Support
url: https://www.sinch.com
email: Support@sinch.com
license:
name: MIT
url: https://www.sinch.com/legal
webhooks:
EventsCallback:
post:
tags:
- Campaigns Callbacks
summary: Event notification
description: A notification of an event sent to your configured callback URL.
operationId: EventsCallback
security:
- hmacAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackEventBody'
responses:
default:
description: 200 OK
paths:
/v1/projects/{projectId}/campaigns:
post:
description: Create a new US Short Code Campaign Draft. Draft requirements are based on the requirement fields, but extra validations are applied at submission time.
operationId: createCampaign
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignRequest'
responses:
'200':
description: Campaign created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'BAD_REQUEST: Campaign validation error'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Create US SC Campaign Draft
tags:
- campaigns
get:
description: List campaigns based on filters provided
operationId: listCampaigns
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: query
description: Campaign status. If not provided, all campaigns are returned.
name: status
schema:
type: string
- in: query
name: shortcode
description: Filter campaigns based on the short code assigned.
schema:
type: string
- in: query
name: date
description: Filter campaigns based on the date, ISO 8601 format. Applies to both createdAt and updatedAt fields.
schema:
type: string
example: '2025-01-01'
- in: query
name: orderBy
description: 'Ordering of the results: field name with an optional order separated by a comma. Fields that support ordering are ''campaignId'', ''name'', ''shortcode'', ''status'', ''createdAt'', ''updatedAt'' with possible ordering ''desc'' or ''asc'''
schema:
type: string
example: campaignId,asc
- in: query
name: pageSize
description: Size of the page to be returned.
schema:
format: int32
type: integer
example: 100
- in: query
name: pageToken
description: Page token to request subsequent pages when using pagination. This should be the value generated by the system in a previous list request.
schema:
type: string
responses:
'200':
description: Campaigns retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ListCampaignResponse'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'UNAUTHORIZED: User Unauthorized.'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- read
summary: List US SC Campaigns
tags:
- campaigns
/v1/projects/{projectId}/campaigns:submit:
post:
description: Create and submit a new US Short Code Campaign in a single step. Both draft and submission requirements will be validated together.
operationId: createAndSubmitCampaign
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignRequest'
responses:
'200':
description: Campaign created and submitted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'BAD_REQUEST: Campaign validation error'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Create and Submit US SC Campaign
tags:
- campaigns
/v1/projects/{projectId}/campaigns/{campaignId}:
put:
description: Update a US Short Code Campaign. The campaign must be in DRAFT or AWAITING_CLIENT_UPDATE status to be updated. If the campaign is in any other status, an error will be returned.
operationId: updateCampaign
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: path
description: Campaign ID
name: campaignId
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EditCampaignRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'BAD_REQUEST: Campaign in illegal state'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Update US SC Campaign
tags:
- campaigns
get:
description: Get a US Short Code Campaign by campaign ID.
operationId: getCampaign
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: path
description: Campaign ID
name: campaignId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
description: OK
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- read
summary: Get US SC Campaign
tags:
- campaigns
/v1/projects/{projectId}/campaigns/{campaignId}:submit:
post:
description: Submit a US Short Code Campaign for review. The campaign must be in DRAFT or AWAITING_CLIENT_UPDATE status to be submitted. If the campaign is in any other status, an error will be returned. The submission of a campaign applies some extra validations that are not applied when creating or updating a campaign. This document contains all these validations per field.
operationId: submitCampaign
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: path
description: Campaign ID
name: campaignId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: A BAD_REQUEST error can be triggered by the internal campaign validations or by the submission of a campaign in an illegal state. Proper error will be raise.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Submit US SC Campaign
tags:
- campaigns
callbacks:
Campaign Update:
'{$request.body#/callbackUrl}':
post:
description: Callback URL to be called when a campaign is updated. The callback URL must be configured in the campaign creation request. The callback URL must be a valid URL and must be reachable from Sinch. System notifies about any campaign status update, carrier order status update or any note added to the campaign or carrier order.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackEventBody'
responses:
'200':
description: OK
4XX:
description: Customer has refused callback event for any reason.
summary: Event notification
security:
- hmacAuth: []
/v1/projects/{projectId}/campaigns/{campaignId}:cancel:
post:
description: Cancel a US Short Code Campaign. The campaign is not deleted, but moved to cancelled status. The campaign must be in DRAFT, PENDING_REVIEW or AWAITING_CLIENT_UPDATE status to be cancelled. If the campaign is in any other status, an error will be returned.
operationId: cancelCampaign
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: path
description: Campaign ID
name: campaignId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'BAD_REQUEST: Campaign in illegal state'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Cancel US SC Campaign
tags:
- campaigns
/v1/projects/{projectId}/campaigns/{campaignId}/notes:
post:
description: Add a note to a US Short Code Campaign. The note is added to the campaign and can be used to communicate with backoffice teams. The note is not mandatory and can be added at any time.
operationId: addCampaignNote
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: path
description: Campaign ID
name: campaignId
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNoteRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Note'
description: OK
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Add US SC Campaign Note
tags:
- campaigns
/v1/projects/{projectId}/campaigns/{campaignId}/carriers/{carrierOrderId}/notes:
post:
description: Add a note to a US Short Code Campaign - Carrier Order. The note is added to the carrier order and can be used to communicate with backoffice teams. The note is not mandatory and can be added at any time.
operationId: addCarrierOrderNote
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: path
description: Campaign ID
name: campaignId
required: true
schema:
type: string
- in: path
description: Carrier Order ID
name: carrierOrderId
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNoteRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Note'
description: OK
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID/Carrier Order ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Add US SC Campaign - Carrier Order Note
tags:
- campaigns
/v1/projects/{projectId}/campaigns/{campaignId}/carriers/{carrierOrderId}/request-certification:
post:
description: Request client certification for a US Short Code Campaign - Carrier Order. The carrier order must be in PROVISIONED_BY_SINCH status to request the client certification. If the carrier order is in any other status, an error will be returned.
operationId: requestCarrierOrderCertification
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: path
description: Campaign ID
name: campaignId
required: true
schema:
type: string
- in: path
description: Carrier Order ID
name: carrierOrderId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierOrder'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'BAD_REQUEST: Invalid Carrier Order state'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID/Carrier Order ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Request Client Certificate for US SC Campaign - Carrier Order
tags:
- campaigns
/v1/projects/{projectId}/carriers:
get:
description: Get a list of carriers available for a campaign. When creating a new campaign, add the carrier ids in the carriers field, therefore Sinch will configure the campaign with those carriers selected.
operationId: getCarriers
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CarrierList'
description: OK
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'UNAUTHORIZED: User Unauthorized.'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- read
summary: Get Carriers List
tags:
- campaigns
/v1/projects/{projectId}/attachments:
post:
description: Upload a file to a US Short Code Campaign. Attachments are needed when bringing a SC or migrating a campaign, but they can also be required by backoffice team. If you are filing campaigns for US Short codes and you have already procured your Short code from CSCA, please make sure that you attach your Short code receipt (proof of identity). If MMS is a message type for this campaign, please submit a .jpg or .png example.
operationId: uploadAttachment
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
example: file.txt
description: File content body
description:
type: string
example: This is a file
description: File description
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignAttachment'
description: OK
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Upload US SC Campaign Attachment
tags:
- campaigns
/v1/projects/{projectId}/campaigns/{campaignId}/attachments/{attachmentId}:
get:
description: Download a file from a US Short Code Campaign.
operationId: downloadCampaignAttachment
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: path
description: Campaign ID
name: campaignId
required: true
schema:
type: string
- in: path
description: Attachment ID
name: attachmentId
required: true
schema:
type: string
responses:
'200':
content:
application/octet-stream:
schema:
format: binary
type: string
description: Request Successful with binary file returned in octet stream
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID/Attachment ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- read
summary: Download US SC Campaign Attachment
tags:
- campaigns
delete:
description: Delete a file from a US Short Code Campaign.
operationId: deleteCampaignAttachment
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
- in: path
description: Campaign ID
name: campaignId
required: true
schema:
type: string
- in: path
description: Attachment ID
name: attachmentId
required: true
schema:
type: string
responses:
'204':
description: Resource successfully deleted. No content is returned.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: Campaign ID/Attachment ID not found'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- read
summary: Delete US SC Campaign Attachment
tags:
- campaigns
/v1/projects/{projectId}/callback-configuration:
get:
description: The endpoint receives as path param project id. If the project exists, the details of the callback configuration are returned.
operationId: getCallbackConfiguration
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackConfigurationResponse'
description: OK
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: The project id introduced does not exist.'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- read
summary: Get a callback configuration by project id.
tags:
- Campaigns Callbacks
put:
description: The endpoint updates the callback configuration with specified project ID
operationId: updateCallbackConfiguration
parameters:
- in: path
description: Customer's project id
name: projectId
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackConfigurationUpdateBody'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CallbackConfigurationResponse'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'BAD_REQUEST: Project validation error'
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'NOT_FOUND: The project id introduced does not exist.'
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestError'
description: 'INTERNAL: Internal server error. Typically, a server bug.'
security:
- OAuth2:
- write
summary: Update a callback configuration
tags:
- Campaigns Callbacks
components:
schemas:
CallbackEventBody:
description: Callback event body.
properties:
eventId:
description: The ID of the event.
example: ee34ccbf-919d-462f-8587-dec95a1b11ee
type: string
eventType:
description: The type of the event. Possible values are CARRIER_ORDER_NOTE, CARRIER_ORDER_STATUS_UPDATE, CAMPAIGN_NOTE, CAMPAIGN_STATUS_UPDATE.
enum:
- CARRIER_ORDER_NOTE
- CARRIER_ORDER_STATUS_UPDATE
- CAMPAIGN_NOTE
- CAMPAIGN_STATUS_UPDATE
x-enumDescriptions:
CARRIER_ORDER_NOTE: A new carrier order note has been added. Fields in data are campaignId, carrierId and note (author, text, createdAt).
CARRIER_ORDER_STATUS_UPDATE: The event is related to a carrier order status update. Fields in data are campaignId, carrierOrderId and newStatus (CarrierOrderStatus).
CAMPAIGN_NOTE: A new campaign note has been added. Fields in data are campaignId and note (author, text, createdAt).
CAMPAIGN_STATUS_UPDATE: The event is related to a campaign status update. Fields in data are campaignId and newStatus (CampaignStatus).
example: CAMPAIGN_STATUS_UPDATE
type: string
projectId:
description: The ID of the project to which the event belongs.
example: aad4ccbf-919d-462f-8587-dec95a1b11b0
type: string
resourceId:
description: Corresponds to the campaign id in case of CAMPAIGN_NOTE and CAMPAIGN_STATUS_UPDATE events. Corresponds to the carrier order id in case of CARRIER_ORDER_NOTE and CARRIER_ORDER_STATUS_UPDATE events.
example: '123123'
type: string
resourceType:
description: The type of the resource. Possible values are CAMPAIGN and CARRIER_ORDER.
enum:
- CAMPAIGN
- CARRIER_ORDER
x-enumDescriptions:
CAMPAIGN: The event is related to a campaign.
CARRIER_ORDER: The event is related to a carrier order.
example: CAMPAIGN
type: string
shortcode:
description: The short code related to the event.
type: string
data:
oneOf:
- $ref: '#/components/schemas/CampaignStatusUpdateBody'
- $ref: '#/components/schemas/CampaignNoteBody'
- $ref: '#/components/schemas/CarrierOrderStatusUpdateBody'
- $ref: '#/components/schemas/CarrierOrderNoteBody'
discriminator:
propertyName: eventType
createTime:
description: The date and time when the event was created.
example: '2023-10-01 12:00:00+00:00'
type: string
format: date-time
type: object
CampaignStatusUpdateBody:
description: Body object linked to callback body when event type is CAMPAIGN_STATUS_UPDATE.
type: object
properties:
campaignId:
description: The ID of the campaign to which the event belongs.
example: '20000'
type: string
newStatus:
$ref: '#/components/schemas/CampaignStatus'
CampaignNoteBody:
description: Body object linked to callback body when event type is CAMPAIGN_NOTE.
type: object
properties:
campaignId:
description: The ID of the campaign to which the event belongs.
example: '20000'
type: string
note:
$ref: '#/components/schemas/Note'
CarrierOrderStatusUpdateBody:
description: Body object linked to callback body when event type is CARRIER_ORDER_STATUS_UPDATE.
type: object
properties:
campaignId:
description: The ID of the campaign to which the event belongs.
example: '20000'
type: string
carrierOrderId:
description: The ID of the carrier order to which the event belongs.
example: '20010'
type: string
newStatus:
$ref: '#/components/schemas/CarrierOrderStatus'
CarrierOrderNoteBody:
description: Body object linked to callback body when event type is CARRIER_ORDER_NOTE.
type: object
properties:
campaignId:
description: The ID of the campaign to which the event belongs.
example: '20000'
type: string
carrierOrderId:
description: The ID of the carrier order to which the event belongs.
example: '20010'
type: string
note:
$ref: '#/components/schemas/Note'
CallbackConfigurationResponse:
properties:
hmacSecret:
description: The HMAC secret used for hashing the callback body using the HMAC-SHA1 algorithm - and for creating the X-Sinch-Signature header.
example: d1c7ccbf-919d-462f-8587-dec95a1b11ee
type: string
projectId:
type: string
type: object
CallbackConfigurationUpdateBody:
properties:
hmacSecret:
description: The HMAC secret to be updated for the specified project
example: d1c7ccbf-919d-462f-8587-dec95a1b11ee
type: string
type: object
CarrierList:
description: List of carriers available for a campaign
properties:
carriers:
description: List of carriers
items:
$ref: '#/components/schemas/Carrier'
type: array
type: object
Carrier:
description: Carrier object
properties:
carrier_id:
description: Carrier ID
example: '123'
typ
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://artifacts.apis.io/sinch/openapi/sinch-us-shortcode-campaigns-api-openapi.yml