openapi: 3.2.0 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/toc servers: - description: Production server url: https://usshortcode.registrations.api.sinch.com tags: - description: Create and manage US Short Code Campaigns name: Campaigns x-displayName: Campaigns 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 components: schemas: FieldViolation: type: object properties: field: type: string description: The field that contains the error example: carrierIds description: type: string example: Carrier Id 123 does not exist. description: A field violation error that contains the field name, reason and value that caused the error. BasicCampaign: description: List of campaigns returns a subset of data from campaign object properties: campaignId: description: Campaign ID example: '20000' type: string name: description: Campaign name example: My Campaign type: string shortcode: $ref: '#/components/schemas/Shortcode' status: $ref: '#/components/schemas/CampaignStatus' createdAt: description: Campaign creation date example: '2023-01-01T00:00:00Z' type: string format: date-time updatedAt: description: Campaign update date example: '2023-01-01T00:00:00Z' type: string format: date-time type: object mmsMoUrl: description: Location where MO messages will be delivered. A specific URL for Mobile Originated at the shortcode level. This parameter is optional and allows for overriding the account-level MO URL. If a value is provided, all MO notifications for this shortcode will be sent to the specified URL. If it is not provided, notifications will continue to be sent to the default URL configured at the account level. example: https://mycompany/mo/url type: string IsMigrated: description: Indicates the campaign is migrated from another provided or another customer Sinch account. It is required to submit the campaign details in dashboard when it’s a migration. example: true type: boolean ComplianceEmails: description: Compliance emails that will be used to contact compliance team. Mandatory at submission time. type: array items: type: string format: email NotFoundDetails: type: object properties: type: type: string description: For not found details. enum: - ResourceInfo x-enumDescriptions: ResourceInfo: Value indicate it is related to a NotFound error example: ResourceInfo resourceType: type: string description: The type of the resource that was not found. Campaign, Project, Carrier, CarrierOrder, Brand, etc. example: Campaign resourceName: type: string description: Corresponds to the unique identifier of the resource that was not found. example: '1234567890' description: type: string description: A human-readable description of the error. example: The campaign with the specified ID was not found. CallbackUrl: description: Callback URL that will be used to notify about campaign order updates. There are four different events that will be sent - CARRIER_ORDER_NOTE - CARRIER_ORDER_STATUS_UPDATE - CAMPAIGN_NOTE - CAMPAIGN_STATUS_UPDATE See callback documentation in submit endpoint section. type: string format: uri InternalRestError: properties: code: format: int32 type: integer details: items: $ref: '#/components/schemas/ErrorDetails' type: array message: type: string status: type: string type: object CampaignAttachment: description: Attachment linked to this campaign request. properties: attachmentId: description: Attachment ID example: '12345' type: string name: description: Attachment name example: migration.pdf type: string description: description: Attachment description example: Migration campaign SC letter type: string TermsAndConditions: description: Provide the URL to your company’s Terms and Conditions, which explain the rules and guidelines for using your services. If you do not have a URL, please provide the full text of your Terms and Conditions. Mandatory at submission time. properties: text: description: Terms and conditions text. example: By subscribing to this service, you agree to receive messages from MyCompany. Text STOP to opt-out. type: string url: description: Terms and conditions URL example: https://www.mycompany.com/terms type: string format: uri type: object ContentTypeEnum: description: Content type that will be used in the content definition. oneOf: - const: CHAT description: Chat - const: COUPONS description: Coupons deprecated: true - const: ENTERTAINMENT_ALERTS description: Entertainment alerts deprecated: true - const: INFORMATIONAL_ALERTS description: Informational alerts deprecated: true - const: SWEEPSTAKES description: Sweepstakes - const: TRIVIA description: Trivia deprecated: true - const: TWO_FACTOR_AUTHENTICATION description: Two factor authentication - const: VOTING_POLLING description: Voting polling - const: ACCOUNT_NOTIFICATION description: Account Notification - const: CHARITABLE_DONATION description: Charity - const: CUSTOMER_CARE description: Customer Care - const: DELIVERY_NOTIFICATION description: Delivery Notifications - const: EMERGENCY description: Emergency - const: FINANCIAL description: Financial - const: FRAUD_ALERT description: Fraud Alert Messaging - const: HEALTHCARE description: Healthcare - const: HIGH_EDUCATION description: High Education - const: INTERNAL_TESTING description: Internal Testing/Demo - const: K12_EDUCATION description: K-12 Education - const: MARKETING description: Marketing - const: POLITICAL description: Political (Election Campaigns) - const: PUBLIC_SERVICE_ANNOUNCEMENT description: Public Service Announcement - const: SECURITY_ALERT description: Security Alert - const: SHOPPING_CART_REMINDER description: Shopping Cart Reminder example: CHAT type: string 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' CampaignRequestBase: description: Common properties for create\/edit US Short Code Campaign requests. type: object required: - name - trafficCharge - scRequested - customerCare - contentDefinitions properties: name: description: Campaign name. Max length is 100 characters. example: My Campaign type: string description: description: Campaign description. example: My Campaign Description type: string trafficCharge: $ref: '#/components/schemas/TrafficCharge' contactEmails: $ref: '#/components/schemas/ContactEmails' complianceEmails: $ref: '#/components/schemas/ComplianceEmails' scRequested: $ref: '#/components/schemas/ScRequested' brandId: $ref: '#/components/schemas/BrandId' shortcode: $ref: '#/components/schemas/Shortcode' carrierIds: description: Carrier IDs. Carrier IDs and names must be retrieved from /carriers endpoint. type: array items: description: Carrier ID example: '123' type: string customerCare: $ref: '#/components/schemas/CustomerCare' contentDefinitions: description: You can configure specific flows to fit your needs. You can check the documentation for more information about flows. Each campaign must contain at least one content definition at submission time. type: array minItems: 1 items: $ref: '#/components/schemas/ContentDefinitionRequest' termsAndConditions: $ref: '#/components/schemas/TermsAndConditions' privacyPolicy: $ref: '#/components/schemas/PrivacyPolicy' isMigrated: $ref: '#/components/schemas/IsMigrated' callbackUrl: $ref: '#/components/schemas/CallbackUrl' attachments: description: Attachment IDs. Attachments must be created using /attachments endpoint, and then link here to the campaign. Attachments are set at project level. If needed, they can be reused by more than one campaign within the same project. type: array items: description: Attachment ID example: '123' type: string smsApp: $ref: '#/components/schemas/smsApp' mmsApp: $ref: '#/components/schemas/mmsApp' mmsMoUrl: $ref: '#/components/schemas/mmsMoUrl' mmsDrUrl: $ref: '#/components/schemas/mmsDrUrl' 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' Shortcode: description: Short codes configured for the campaign. Short code must be provided when sc_requested is false. There are two options (1) if customers have their own short code (sc_requested=true), we would ask that they provide the short code number in this field and also attach a copy of their latest short code receipt upon submitting the campaign. (2) If customers have elected that Sinch lease the code (sc_requested=false), this field should be blank, and Sinch will fill it once short code has been procured. example: '23242' type: string CarrierOrder: description: Carrier order linked to country specific carriers that must be configured for this campaign. properties: carrierOrderId: description: Carrier order ID example: '12345' type: string carrierId: description: Carrier ID. Carrier IDs and names must be retrieved from /carriers endpoint. example: '123' type: string carrierName: description: Carrier name. Carrier IDs and names must be retrieved from /carriers endpoint. example: AT&T Mobility type: string status: $ref: '#/components/schemas/CarrierOrderStatus' notes: description: Notes regarding carrier configuration. type: array items: $ref: '#/components/schemas/Note' logs: description: All transitions applied to this carrier order type: array items: $ref: '#/components/schemas/CarrierOrderLog' createdAt: description: Carrier order creation date example: '2023-01-01T00:00:00Z' type: string format: date-time updatedAt: description: Carrier order update date example: '2023-01-01T00:00:00Z' type: string format: date-time type: object CreateNoteRequest: description: Create a new note for a US Short Code Campaign or Carrier Order. properties: text: description: Note text. Max length is 1000 characters. example: This is a note type: string type: object smsApp: description: The SMS routing profile app example: My_SMS_App type: string CustomerCare: description: Customer care info that end customers will see. Mandatory at submission time. properties: optOutKeywords: description: These are keywords end users can use to unsubscribe from the short program. Acceptable Opt-out keywords are STOP, END, CANCEL, UNSUBSCRIBE, QUIT, REVOKE, OPTOUT, OPT-OUT. Max length is 100 characters. example: END, STOP, QUIT, CANCEL type: string optOutMtText: description: The outgoing message that the brand needs to send to acknowledge the opt out and informing subscribers that they will no longer receive further messages. This responsibility generally falls on the brand/client (exceptions on 2FA/OTP campaigns as they are not recurring programs) example: You have ended this service. You will no longer receive messages. Call 1234567890 for support. type: string helpMtText: description: The help message is a message sent in response to when end users are requesting help by testing the keyword HELP. This message should include a phone number, email address or URL leading to the support contact page. example: This service provides banking alerts. Text STOP to cancel. Call 1234567890 for support. type: string email: description: Customer care email that will be used to contact customer care. example: support@mycompany.com type: string format: email website: description: Customer care website that will be used to contact customer care. example: https://www.mycompany.com type: string format: uri phoneNumber: description: Customer care phone number that will be used to contact customer care. example: '+14155552671' type: string format: phone type: object 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 EditCampaignRequest: allOf: - $ref: '#/components/schemas/CampaignRequestBase' - type: object description: Update a US Short Code Campaign request. BrandId: description: Brand ID created in the Brands API, US_SHORT_CODE_REGISTRY type. This field is required when sc_requested is true. Brand must be provided to the US Short Code Registry to be approved. Brand must exist and not be rejected at submission time (incomplete or pending brands are allowed) Brands approval must be completed in order to complete the campaign registration. example: '43342642354352344' type: string InvalidRequestDetails: type: object description: this body is expected when invalid argument, failed precondition or already exists error occurs. properties: type: type: string description: For invalid arguments details, this value is always BadRequest. example: BadRequest enum: - BadRequest x-enumDescriptions: BadRequest: Value indicate it is related to a InvalidRequest error fieldViolations: items: $ref: '#/components/schemas/FieldViolation' type: array 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' PrivacyPolicy: description: Provide the URL to your company’s Privacy Policy, which outlines how you collect, use, and protect customers' personal information. If you do not have a URL, please enter the full text of your Privacy Policy. Mandatory at submission time. properties: text: description: Privacy policy text. example: We respect your privacy and will not share your personal information with third parties. type: string url: description: Privacy policy URL example: https://www.mycompany.com/privacy type: string format: uri type: object Carrier: description: Carrier object properties: carrier_id: description: Carrier ID example: '123' type: string name: description: Carrier name example: AT&T type: string type: object Campaign: description: Campaign content allOf: - $ref: '#/components/schemas/BasicCampaign' - type: object properties: description: description: Campaign description example: My Campaign Description type: string trafficCharge: $ref: '#/components/schemas/TrafficCharge' scRequested: $ref: '#/components/schemas/ScRequested' brandId: $ref: '#/components/schemas/BrandId' customerCare: $ref: '#/components/schemas/CustomerCare' contentDefinitions: description: You can configure specific flows to fit your needs. You can check the documentation for more information about flows. Each campaign must contain at least one content definition at submission time. type: array items: $ref: '#/components/schemas/ContentDefinition' termsAndConditions: $ref: '#/components/schemas/TermsAndConditions' privacyPolicy: $ref: '#/components/schemas/PrivacyPolicy' complianceEmails: $ref: '#/components/schemas/ComplianceEmails' contactEmails: $ref: '#/components/schemas/ContactEmails' callbackUrl: $ref: '#/components/schemas/CallbackUrl' isMigrated: $ref: '#/components/schemas/IsMigrated' carrierOrders: description: List of carrier orders. type: array items: $ref: '#/components/schemas/CarrierOrder' campaignAttachments: description: Attachments linked to this campaign request. type: array items: $ref: '#/components/schemas/CampaignAttachment' logs: description: All transitions applied to this campaign type: array items: $ref: '#/components/schemas/CampaignLog' notes: description: Notes used to contact customer and agents regarding this campaign. type: array items: $ref: '#/components/schemas/Note' smsApp: $ref: '#/components/schemas/smsApp' mmsApp: $ref: '#/components/schemas/mmsApp' mmsMoUrl: $ref: '#/components/schemas/mmsMoUrl' mmsDrUrl: $ref: '#/components/schemas/mmsDrUrl' ContentDefinitionRequest: description: This is where the client would provide important information about their short code campaign(s) – what the call to action is (how is the short code advertised and how consent is collected), whether it’s a one-time or subscription/recurring campaign, and example messages (example messages of what the brand will be sending once live) properties: messageType: $ref: '#/components/schemas/MessageTypeEnum' contentType: $ref: '#/components/schemas/ContentTypeEnum' subscription: description: Content definition subscription type. enum: - ONE_TIME - SUBSCRIPTION x-enumDescriptions: ONE_TIME: One time payment SUBSCRIPTION: Subscription payment example: ONE_TIME format: enum type: string messageFlow: $ref: '#/components/schemas/MessageFlow' type: object ListCampaignResponse: description: List of campaigns object properties: campaigns: description: List of campaigns items: $ref: '#/components/schemas/BasicCampaign' type: array nextPageToken: description: Token to request the next page of results. type: string totalSize: description: Total count of campaigns matching provided search criteria format: int32 type: integer type: object 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' CarrierOrderStatus: description: Carrier order status enum: - PENDING - SUBMITTED - APPROVED - REJECTED - PROVISIONED_BY_CARRIER - PROVISIONED_BY_SINCH - CLIENT_CERTIFICATION_REQUESTED - CARRIER_CERTIFICATION_REQUESTED - CERTIFIED - DEPROVISIONED - CERTIFICATION_FAILURE - CANCELLED x-enumDescriptions: PENDING: Campaign has not been submitted yet to the carrier. SUBMITTED: Campaign has been submitted to the carrier. APPROVED: Campaign has been approved by carrier. REJECTED: Campaign has not been approved by carrier. PROVISIONED_BY_CARRIER: Short Code has been approved and configured on Sinch’s bind by this carrier. PROVISIONED_BY_SINCH: Short Code has been set up on client’s account. CLIENT_CERTIFICATION_REQUESTED: Campaign is ready to be tested by Sinch Team (to test opt-in and auto-responses such as HELP and STOP) CARRIER_CERTIFICATION_REQUESTED: Campaign has passed Sinch testing and is pending certification/testing with the Carrier(not all carriers require this) where they will test opt-in and auto-responses for HELP and STOP. CERTIFIED: Campaign has passed certification on this carrier and it is now LIVE! Ready for live traffic DEPROVISIONED: Used when cancelling the connectivity part with this carrier. CERTIFICATION_FAILURE: Testing failed. It can be due to keyword and auto-responses not set up as described in the campaign or the call to action is not live or not compliant. CANCELLED: When the overall SC Campaign is not longer active with all carriers and the SC lease is cancelled. example: PENDING format: enum type: string CampaignLog: description: A transition applied to a campaign properties: previousStatus: $ref: '#/components/schemas/CampaignStatus' currentStatus: $ref: '#/components/schemas/CampaignStatus' createdAt: description: Log creation date example: '2023-01-01T00:00:00Z' type: string format: date-time type: object ErrorDetails: type: object oneOf: - $ref: '#/components/schemas/NotFoundDetails' - $ref: '#/components/schemas/InvalidRequestDetails' discriminator: propertyName: type mapping: ResourceInfo: '#/components/schemas/NotFoundDetails' BadRequest: '#/components/schemas/InvalidRequestDetails' TrafficCharge: description: Campaign traffic charge type. enum: - STANDARD - FREE_TO_END_USER x-enumDescriptions: STANDARD: Standard rates apply to send and receive for end users. Sinch customers will be charged for MT/MO messages. FREE_TO_END_USER: Sinch customers will be charged at a higher MT/MO rate while end users will not be charged. example: STANDARD format: enum type: string MessageTypeEnum: description: Message type that will be used in the content definition. enum: - SMS - MMS_VIDEO - MMS_AUDIO - MMS_IMAGE x-enumDescriptions: SMS: SMS MMS_VIDEO: MMS Video MMS_AUDIO: MMS Audio MMS_IMAGE: MMS Image example: SMS format: enum type: string ContentDefinition: description: This is where the client would provide important information about their short code campaign(s) – what the call to action is (how is the short code advertised and how consent is collected), whether it’s a one-time or subscription/recurring campaign, and example messages (example messages of what the brand will be sending once live) properties: messageType: description: Message type that will be used in the content definition. example: SMS format: enum type: string contentType: description: Content type that will be used in the content definition. example: CHAT type: string subscription: description: Content definition subscription type. example: ONE_TIME type: string messageFlow: $ref: '#/components/schemas/MessageFlow' type: object RestError: properties: error: $ref: '#/components/schemas/InternalRestError' type: object ContactEmails: description: Contact emails that will be used to contact about campaign order status. If you plan to set a callback url, please ignore this field type: array items: type: string format: email MessageFlow: description: Message flow that will be used in the content definition. Contains the call to action, opt in and sample alert. properties: callToAction: description: Call to action that will be used in the content definition. example: Text JOIN to 12345 and receive a link to start setting up your MyCompany account. type: string optIn: description: Opt-in message that will be used in the content definition. example: You are subscribed to MyCompany texting alerts. Text HELP for help, STOP to opt-out. type: string sampleAlert: description: Sample alert that will be used in the content definition. example: Are you enrolled for your compliance regulations? Text me at this number for help. STOP to opt out. type: string type: object CreateCampaignRequest: allOf: - $ref: '#/components/schemas/CampaignRequestBase' - type: object description: Create a new US Short Code Campaign Draft request. properties: notes: description: Add some comments to the campaign. This field is optional. type: array items: type: string example: This is a note CampaignStatus: description: Campaign status enum: - DRAFT - PENDING_REVIEW - REVIEWING - READY_CARRIER_SUBMISSION - CARRIER_SUBMITTED - COMPLETED - CANCELLED - DEPROVISIONED - AWAITING_CLIENT_UPDATE x-enumDescriptions: DRAFT: A working draft campaign, not submitted for review PENDING_REVIEW: Submitted campaign, waiting for review REVIEWING: An agent is actively reviewing the campaign READY_CARRIER_SUBMISSION: Agent has completed review and is ready to submit to carriers CARRIER_SUBMITTED: Campaign information has been submitted to carriers (at this point follow carrier order status updates) COMPLETED: Campaign has been approved by all carriers and is ready for use CANCELLED: Campaign has been cancelled DEPROVISIONED: An approved campaign that has been deprovisioned and is no longer in use AWAITING_CLIENT_UPDATE: Some information must be edited or added to the campaign to continue the review process example: DRAFT format: enum type: string mmsDrUrl: description: Location where DR messages will be delivered. A specific URL for Delivery Receipt at the shortcode level. This parameter is optional and allows for overriding the account-level DR URL. If a value is provided, all DR notifications for this shortcode will be sent to the specified URL. If it is not provided, notifications will continue to be sent to the default URL configured at the account level. example: https://mycompany/dr/url type: string Note: description: Notes used to contact customer and agents. properties: author: description: Author. It can be either a customer or an agent. enum: - CUSTOMER - AGENT x-enumDescriptions: CUSTOMER: Customer AGENT: Agent example: CUSTOMER format: enum type: string text: description: Note text example: This is a note type: string createdAt: description: Note creation date example: '2023-01-01T00:00:00Z' type: string format: date-time type: object CarrierOrderLog: description: A transition applied to a carrier order properties: previousStatus: $ref: '#/components/schemas/CarrierOrderStatus' currentStatus: $ref: '#/components/schemas/CarrierOrderStatus' createdAt: description: Log creation date example: '2023-01-01T00:00:00Z' type: string format: date-time 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 ScRequested: description: Customer needs Sinch to lease a short code for them. When sc_requested is true, customers need to provide an existing brand ID, not rejected. example: true type: boolean mmsApp: description: The MMS routing profile app example: My_MMS_App type: string securitySchemes: OAuth2: description: The username and password are your Key ID and Key Secret from the Access keys section in the Sinch Customer Dashboard. Exchange these for a bearer token (access token). flows: clientCredentials: scopes: read: read write: write tokenUrl: https://auth.sinch.com/oauth2/token type: oauth2 hmacAuth: type: http scheme: hmac description: Used for hashing callbacks. Please refer to the callback-configuration endpoints for more information. 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/ x-explorer-enabled: false x-samples-languages: - curl - java - csharp - node - php