openapi: 3.0.3 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/toc 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/EditCampaignRequest' 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: Registration 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: shortCodes description: Filter campaigns based on the short code assigned. schema: type: string - 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', 'status', 'createDate', 'updateDate' 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 a system in a previous list request.' schema: type: string responses: '200': description: Campaigns retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListCampaignResponse' '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/{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}/carrier/{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/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 '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}/campaigns/{campaignId}/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. operationId: uploadCampaignAttachment 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: 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 /v1/projects/{projectId}/campaigns/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: - callback-configuration 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: - callback-configuration 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. CampaignId, CarrierOrderId and NoteId indicate the note. CARRIER_ORDER_STATUS_UPDATE: The event is related to a carrier order status update. CampaignId, CarrierOrderId and CarrierOrder indicate the note. CAMPAIGN_NOTE: A new carrier order note has been added. CampaignId and NoteId indicate the note. CAMPAIGN_STATUS_UPDATE: The event is related to a campaign status update. 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 shortCodes: description: The list of short codes 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-01T12:00:00Z 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: id: description: Carrier ID example: '123' type: string name: description: Carrier name example: 'AT&T' type: string 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 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 EditCampaignRequest: description: Create/Update a new US Short Code Campaign Draft request. required: - name - trafficCharge - scRequested 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' shortCodes: $ref: '#/components/schemas/ShortCodes' carrierIds: description: Carrier IDs. Carrier IDs and names must be retrieved from /carriers endpoint. items: description: Carrier ID example: '123' type: string type: array 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. items: $ref: '#/components/schemas/ContentDefinitionRequest' type: array termsAndConditions: $ref: '#/components/schemas/TermsAndConditions' privacyPolicy: $ref: '#/components/schemas/PrivacyPolicy' isMigrated: $ref: '#/components/schemas/IsMigrated' callbackUrl: $ref: '#/components/schemas/CallbackUrl' notes: description: Add some comments to the campaign. This field is optional. type: array items: type: string example: 'This is a note' BasicCampaign: description: List of campaigns returns a subset of data from campaign object properties: id: description: Campaign ID example: '20000' type: string name: description: Campaign name example: 'My Campaign' type: string shortCodes: $ref: '#/components/schemas/ShortCodes' 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 Campaign: description: Campaign content properties: id: description: Campaign ID example: '20000' type: string name: description: Campaign name example: 'My Campaign' type: string description: description: Campaign description example: 'My Campaign Description' type: string trafficCharge: $ref: '#/components/schemas/TrafficCharge' status: $ref: '#/components/schemas/CampaignStatus' scRequested: $ref: '#/components/schemas/ScRequested' brandId: $ref: '#/components/schemas/BrandId' shortCodes: $ref: '#/components/schemas/ShortCodes' 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. items: $ref: '#/components/schemas/ContentDefinition' type: array 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' campaignLogs: 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' 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 CallbackUrl: description: Callback URL that will be used to notify about campaign order updates. There are four different events that will be sent - CAMPAIGN_STATUS_UPDATED - CARRIER_ORDER_STATUS_UPDATED - CAMPAIGN_NOTE_ADDED - CARRIER_ORDER_NOTE_ADDED See callback documentation in submit endpoint section. type: string format: uri 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 ShortCodes: 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 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 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 ComplianceEmails: description: Compliance emails that will be used to contact compliance team. Mandatory at submission time. type: array items: type: string format: email 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 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 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 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: contentDefinitionId: description: Content definition ID. Leave empty when creating a new content definition. If the ID is provided by the customer, the existing Content Definition will be updated. If the Content Definition does not exist, an error will be returned. example: '12345' type: string messageType: $ref: '#/components/schemas/MessageTypeEnum' contentType: $ref: '#/components/schemas/ContentTypeEnum' subscriptionType: 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 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: contentDefinitionId: description: Content definition ID. example: '12345' type: string 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 subscriptionType: description: Content definition subscription type. example: 'ONE_TIME' type: string messageFlow: $ref: '#/components/schemas/MessageFlow' type: object 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 ContentTypeEnum: description: Content type that will be used in the content definition. enum: - CHAT - COUPONS - ENTERTAINMENT_ALERTS - INFORMATIONAL_ALERTS - SWEEPSTAKES - TRIVIA - TWO_FACTOR_AUTHENTICATION - VOTING_POLLING x-enumDescriptions: CHAT: Chat COUPONS: Coupons ENTERTAINMENT_ALERTS: Entertainment alerts INFORMATIONAL_ALERTS: Informational alerts SWEEPSTAKES: Sweepstakes TRIVIA: Trivia TWO_FACTOR_AUTHENTICATION: Two factor authentication VOTING_POLLING: Voting polling example: 'CHAT' format: enum type: string 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 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 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 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 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 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 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 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 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 RestError: properties: error: $ref: '#/components/schemas/InternalRestError' type: object InternalRestError: properties: code: format: int32 type: integer details: items: $ref: '#/components/schemas/ErrorDetails' type: array message: type: string status: type: string 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' 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.' 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 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. 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. servers: - description: Production server url: https://usshortcode.api.sinch.com tags: - description: Create and manage US Short Code Campaigns. name: campaigns x-displayName: Campaigns - description: 'You can set up callback URLs to receive event notifications when your campaign status is updated or when a new note is addeed to your campaign or any of the carrier orders. When delivering events the order is not guaranteed (for example, a failed event scheduled for retry will not block other events that were queued). The client''s callback handler must implement the state machine that can decide what to do with unexpected events, for example, "old" events or invalid state transitions. In these cases the handler could use the API to GET the latest state for the resource. The callback handler is expected to "ingest" the event and respond with 200 OK. The domain-specific business logic and processes should be executed outside of the callback request, as internal asynchronous jobs. An HMAC encrypted secret is used for hashing the payload and sending the hashed String via the X-Sinch-Signature header - that you can use to validate that an incoming request is secure. Hmac secret value can be checked with GET endpoint, and it can be updated with PUT endpoint' name: callback-configuration x-displayName: Callback configuration x-explorer-enabled: false x-samples-languages: - curl - java - csharp - node - php