{ "swagger": "2.0", "info": { "title": "ShortCodesNumbersClient", "description": "The short codes client uses Azure Communication Services to purchase and manage short codes.", "version": "2021-10-25-preview" }, "paths": { "/shortCodes": { "get": { "tags": [ "ShortCodes" ], "summary": "Gets the list of short codes for the current resource.", "operationId": "ShortCodes_GetShortCodes", "produces": [ "application/json" ], "parameters": [ { "in": "query", "name": "skip", "description": "An optional parameter for how many entries to skip, for pagination purposes.", "type": "integer", "format": "int32", "default": 0 }, { "in": "query", "name": "top", "description": "An optional parameter for how many entries to return, for pagination purposes.", "type": "integer", "format": "int32", "default": 100 }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/ShortCodes" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink", "itemName": "shortCodes" }, "x-ms-examples": { "List short codes": { "$ref": "./examples/GetShortCodesAsync.json" } } } }, "/shortCodes/countries/US/programBriefs/{programBriefId}": { "patch": { "tags": [ "ShortCodes - ProgramBrief" ], "summary": "Creates or updates a US Program Brief.", "operationId": "ShortCodes_UpsertUSProgramBrief", "consumes": [ "application/merge-patch+json" ], "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "programBriefId", "description": "Program Brief Id. Must be a valid GUID", "required": true, "type": "string", "format": "uuid" }, { "$ref": "#/parameters/ApiVersionParameter" }, { "in": "body", "name": "body", "description": "Data to create new a Program Brief or fields to update an existing Program Brief", "schema": { "$ref": "#/definitions/USProgramBrief" } } ], "responses": { "201": { "description": "Success", "schema": { "$ref": "#/definitions/USProgramBrief" } }, "200": { "description": "Success", "schema": { "$ref": "#/definitions/USProgramBrief" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Creates or Updates a US Program Brief": { "$ref": "./examples/UpsertUSProgramBriefAsync.json" } } }, "delete": { "tags": [ "ShortCodes - ProgramBrief" ], "summary": "Deletes a US Program Brief.", "operationId": "ShortCodes_DeleteUSProgramBrief", "parameters": [ { "in": "path", "name": "programBriefId", "description": "Program Brief Id. Must be a valid GUID", "required": true, "type": "string", "format": "uuid" }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "204": { "description": "Success" }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Deletes a US Program Brief": { "$ref": "./examples/DeleteUSProgramBriefAsync.json" } }, "produces": [ "application/json" ] }, "get": { "tags": [ "ShortCodes - ProgramBrief" ], "summary": "Get a US Program Brief by id.", "operationId": "ShortCodes_GetUSProgramBrief", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "programBriefId", "description": "Program Brief Id. Must be a valid GUID", "required": true, "type": "string", "format": "uuid" }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/USProgramBrief" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Query a US Program Brief": { "$ref": "./examples/GetUSProgramBriefAsync.json" } } } }, "/shortCodes/countries/US/programBriefs/{programBriefId}/:submit": { "post": { "tags": [ "ShortCodes - ProgramBrief" ], "summary": "Submits a US Program Brief for review.", "operationId": "ShortCodes_SubmitUSProgramBrief", "produces": [ "application/json" ], "parameters": [ { "in": "path", "name": "programBriefId", "description": "Program Brief Id. Must be a valid GUID", "required": true, "type": "string", "format": "uuid" }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/USProgramBrief" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-examples": { "Submit a US Program Brief": { "$ref": "./examples/SubmitUSProgramBriefAsync.json" } } } }, "/shortCodes/countries/US/programBriefs": { "get": { "tags": [ "ShortCodes - ProgramBrief" ], "summary": "Gets the list of US Program Briefs for the current resource.", "operationId": "ShortCodes_GetUSProgramBriefs", "produces": [ "application/json" ], "parameters": [ { "in": "query", "name": "skip", "description": "An optional parameter for how many entries to skip, for pagination purposes.", "type": "integer", "format": "int32", "default": 0 }, { "in": "query", "name": "top", "description": "An optional parameter for how many entries to return, for pagination purposes.", "type": "integer", "format": "int32", "default": 100 }, { "$ref": "#/parameters/ApiVersionParameter" } ], "responses": { "200": { "description": "Success", "schema": { "$ref": "#/definitions/USProgramBriefs" } }, "default": { "description": "Failure", "schema": { "$ref": "#/definitions/CommunicationErrorResponse" } } }, "x-ms-pageable": { "nextLinkName": "nextLink", "itemName": "programBriefs" }, "x-ms-examples": { "List US Program Briefs": { "$ref": "./examples/GetUSProgramBriefsAsync.json" } } } } }, "definitions": { "ShortCode": { "description": "Represents a number, ShortCode or AlphaId, acquired in a given country.", "type": "object", "properties": { "number": { "description": "The value of the ShortCode or the alpha numeric e.g. '555555', 'CONTOSO', etc.", "type": "string" }, "numberType": { "description": "The type of number e.g. 'ShortCode', 'AlphaId'.", "enum": [ "shortCode", "alphaId" ], "type": "string", "x-ms-enum": { "name": "NumberType", "modelAsString": true } }, "countryCode": { "description": "ISO 3166 2-char code representing the country e.g. 'US'.", "type": "string" }, "programBriefIds": { "description": "Program Brief Name.", "type": "array", "items": { "type": "string" } }, "purchaseDate": { "format": "date-time", "description": "Date in which number was purchased.", "type": "string" } } }, "ShortCodes": { "description": "A wrapper for a list of short code entities.", "type": "object", "properties": { "shortCodes": { "description": "List of short codes.", "type": "array", "items": { "$ref": "#/definitions/ShortCode" } }, "nextLink": { "description": "Represents the URL link to the next page.", "type": "string" } } }, "ReviewNote": { "description": "Holds a note about a Program Brief that has gone thru stages of review process.", "type": "object", "properties": { "message": { "description": "Note related to a Program Brief that may imply changes needed from the client.", "type": "string" }, "date": { "format": "date-time", "description": "Date and time when the note was added to the Program Brief.", "type": "string" } } }, "ShortCodeCost": { "description": "The incurred cost for a single short code.", "required": [ "amount", "billingFrequency", "currencyCode" ], "type": "object", "properties": { "amount": { "format": "double", "description": "The cost amount.", "type": "number" }, "currencyCode": { "description": "The ISO 4217 currency code for the cost amount, e.g. USD.", "type": "string" }, "billingFrequency": { "description": "The frequency with which the cost gets billed.", "enum": [ "monthly", "once" ], "type": "string", "x-ms-enum": { "name": "BillingFrequency", "modelAsString": true } } } }, "ProgramDetails": { "type": "object", "properties": { "isVanity": { "description": "Set to true if the request is for a vanity number.", "type": "boolean" }, "preferredVanityNumbers": { "description": "Priority ordered list of preferred vanity numbers.\r\nVanity numbers should be 5 or 6 digit when number type is ShortCode.\r\ne.g. 555555, 222222.", "type": "array", "items": { "type": "string" } }, "numberType": { "description": "Type for desired numbers e.g. 'shortCode' or 'alphaId'.", "enum": [ "shortCode", "alphaId" ], "type": "string", "x-ms-enum": { "name": "NumberType", "modelAsString": true } }, "isPoliticalCampaign": { "description": "Indicates whether the number will be used for political campaigns or not.", "type": "boolean" }, "name": { "description": "A program name that indicates the purpose of filling the Program Brief and how the number will be used for messaging.\r\ne.g. 'CONTOSO Shipping'", "type": "string" }, "description": { "description": "Describes how and why the number will be used for messaging as part of the program.", "type": "string" }, "url": { "format": "uri", "description": "URL for the program or company.", "type": "string" }, "signUpTypes": { "description": "Indicates how the consumer can sign up to the program e.g. 'website', 'pointOfSale' and/or 'sms'.", "type": "array", "items": { "description": "Indicates how a program will be discoverable by the consumer.", "enum": [ "website", "pointOfSale", "sms", "interactiveVoiceResponse" ], "type": "string", "x-ms-enum": { "name": "ProgramSignUpType", "modelAsString": true } } }, "signUpUrl": { "format": "uri", "description": "URL for \"call to action\" image for the program.", "type": "string" }, "termsOfServiceUrl": { "format": "uri", "description": "URL for program terms of service.", "type": "string" }, "privacyPolicyUrl": { "format": "uri", "description": "URL for privacy policy.", "type": "string" }, "expectedDateOfService": { "format": "date-time", "description": "Date in which SMS messages will start to be sent out.\r\nShould follow ISO 8601 internet format for datetimes.\r\ne.g. 2021-08-17T22:02:51.316Z, 2021-08-17T16:39:57-08:00, etc.", "type": "string" } } }, "ContactInformation": { "description": "Contact Information", "type": "object", "properties": { "name": { "description": "Name of authorized user for purposes of submitting the Program Brief.", "type": "string" }, "phone": { "description": "Contact phone number for the authorized user for the customer. Use E164 format. e.g. +14086111111.", "type": "string" }, "email": { "format": "email", "description": "Contact email address number for the authorized user for the customer.", "type": "string" } } }, "CustomerCareInformation": { "description": "Customer Care Information", "type": "object", "properties": { "tollFreeNumber": { "description": "Customer support phone number for the customer submitting the Program Brief. Use E164 format. e.g. +18005551212", "type": "string" }, "email": { "format": "email", "description": "Customer support email address for the customer submitting the Program Brief.", "type": "string" } } }, "CompanyInformation": { "type": "object", "properties": { "name": { "description": "Legal entity name for customer submitting Program Brief.", "type": "string" }, "url": { "format": "uri", "description": "Company URL for customer submitting Program Brief.", "type": "string" }, "address": { "description": "Company's address for the customer submitting the Program Brief.", "type": "string" }, "contactInformation": { "$ref": "#/definitions/ContactInformation" }, "customerCareInformation": { "$ref": "#/definitions/CustomerCareInformation" } } }, "MessageExample": { "description": "Represents a message example to be sent from or to the end user.", "type": "object", "properties": { "direction": { "description": "Indicates whether the message example is supposed to be sent to or from the end user e.g. toUser", "enum": [ "toUser", "fromUser" ], "type": "string", "x-ms-enum": { "name": "MessageDirection", "modelAsString": true } }, "text": { "description": "Actual example text for the message e.g. 'Want me to notify you when package in the way?'", "type": "string" } } }, "MessageExampleSequence": { "description": "A sequence of example messages to and from the end user.", "type": "object", "properties": { "messages": { "description": "Example messages to be sent to and from the end user.", "type": "array", "items": { "$ref": "#/definitions/MessageExample" } } } }, "UseCase": { "description": "Describes a messaging use case for a given content type by providing example messages.", "type": "object", "properties": { "contentCategory": { "description": "Indicates the messaging content category used in the program e.g. 'ringTones', 'smsChat', 'video', 'loyaltyProgramPointsPrizes', 'gifting', 'inApplicationBilling', 'textToScreen'.", "enum": [ "ringTones", "smsChat", "video", "loyaltyProgramPointsPrizes", "gifting", "inApplicationBilling", "textToScreen", "games", "audioChat", "mmsPictures", "sweepstakesContestAuction", "financialBanking", "premiumWap", "queryService", "wallpaperScreensaver", "voting", "application", "mobileGivingDonations", "coupons", "loyaltyProgram", "noPointsPrizes", "informationalAlerts", "microBilling", "trivia", "entertainmentAlerts", "accountNotification", "ageGatedContent", "conversationalMessaging", "deliveryNotification", "education", "emergencyAlerts", "fraudAlerts", "loanArrangement", "onBehalfOfCarrier", "political", "promotionalMarketing", "publicServiceAnnouncements", "securityAlerts", "socialMedia", "twoFactorAuthentication", "other" ], "type": "string", "x-ms-enum": { "name": "MessageContentCategory", "modelAsString": true } }, "examples": { "description": "Example messages to be sent to and from the end user for the indicated content type.", "type": "array", "items": { "$ref": "#/definitions/MessageExampleSequence" } } } }, "MessageDetails": { "type": "object", "properties": { "supportedProtocols": { "description": "Applicable message protocols used in the program e.g. SMS, MMS.", "type": "array", "items": { "description": "Applicable message protocols to be used in a program.", "enum": [ "sms", "mms" ], "type": "string", "x-ms-enum": { "name": "MessageProtocol", "modelAsString": true } } }, "recurrence": { "description": "Indicates the nature of the messaging associated with the program e.g. 'subscription', 'transaction'.", "enum": [ "subscription", "transaction" ], "type": "string", "x-ms-enum": { "name": "MessageRecurrence", "modelAsString": true } }, "helpMessage": { "description": "Message text for mobile terminated message associated with HELP keyword\r\ne.g 'This is the HELP message test.'.", "type": "string" }, "optOutMessage": { "description": "\"Message text for mobile terminated message associated with STOP keyword\r\ne.g. 'This is the STOP message test.'.", "type": "string" }, "optInMessage": { "description": "OptInMessage.", "type": "string" }, "optInReply": { "description": "Keyword used to confirm double Opt-In method e.g. 'JOIN'.", "type": "string" }, "confirmationMessage": { "description": "ConfirmationMessage.", "type": "string" }, "directionality": { "description": "Describes directionality e.g. oneWay or twoWay", "enum": [ "oneWay", "twoWay" ], "type": "string", "x-ms-enum": { "name": "MessageDirectionality", "modelAsString": true } }, "useCases": { "description": "Provides message exchange examples from and to end user for each supported message content type.", "type": "array", "items": { "$ref": "#/definitions/UseCase" } } } }, "TrafficDetails": { "type": "object", "properties": { "totalMonthlyVolume": { "format": "int32", "description": "Estimated total messages per month.", "maximum": 2147483647, "minimum": 0, "type": "integer" }, "monthlyAverageMessagesFromUser": { "format": "int32", "description": "Estimated number of Mobile-Originated messages likely to be received from a user per month.", "maximum": 2147483647, "minimum": 0, "type": "integer" }, "monthlyAverageMessagesToUser": { "format": "int32", "description": "Estimated number of Mobile-Terminated messages likely to be sent per user per month.", "maximum": 2147483647, "minimum": 0, "type": "integer" }, "isSpiky": { "description": "Indicates if the nature of the messaging traffic will be bursty.", "type": "boolean" }, "spikeDetails": { "description": "If isSpiky=true, then explain additional details about the traffic pattern\r\ne.g. 'Higher traffic expected during holiday season and Black Friday.'.", "type": "string" }, "estimatedRampUpTimeInDays": { "format": "int32", "description": "Numbers of days in which is expected to start sending messages from the short code.", "maximum": 2147483647, "minimum": 0, "type": "integer" } } }, "USProgramBrief": { "description": "Represents a US Program Brief for acquiring a short code in the United States.\r\nA Program Brief provides vital information to the carriers about a messaging program or campaign that would be associated with a short code or alpha sender number.\r\nA Program Brief also provides specifics about the use case, the purpose and the consumer experience receiving the message.", "required": [ "id" ], "type": "object", "properties": { "id": { "format": "uuid", "description": "Program Brief Id.", "type": "string" }, "status": { "description": "Program Brief status e.g. 'submitted', 'approved', etc", "enum": [ "submitted", "approved", "submitNewVanityNumbers", "updateProgramBrief", "draft", "denied" ], "type": "string", "x-ms-enum": { "name": "ProgramBriefStatus", "modelAsString": true } }, "number": { "description": "Number provisioned for the Program Brief e.g. 555555, 'CONTOSO'", "type": "string" }, "reviewNotes": { "description": "Notes added to the Program Brief after being reviewed to help customer understand\r\nreview results and necessary follow up actions.", "type": "array", "items": { "$ref": "#/definitions/ReviewNote" } }, "costs": { "description": "Represents the costs tied to the number.", "type": "array", "items": { "$ref": "#/definitions/ShortCodeCost" } }, "submissionDate": { "format": "date-time", "description": "Date and time when the Program Brief was submitted.", "type": "string" }, "statusUpdatedDate": { "format": "date-time", "description": "Last date and time when the Program Brief status was updated.", "type": "string" }, "programDetails": { "description": "ProgramDetails.", "$ref": "#/definitions/ProgramDetails" }, "companyInformation": { "description": "CompanyInformation.", "$ref": "#/definitions/CompanyInformation" }, "messageDetails": { "description": "MessageDetails.", "$ref": "#/definitions/MessageDetails" }, "trafficDetails": { "description": "TrafficDetails.", "$ref": "#/definitions/TrafficDetails" } } }, "USProgramBriefs": { "description": "A wrapper for a list of USProgramBrief entities.", "type": "object", "properties": { "programBriefs": { "description": "List of Program Briefs.", "type": "array", "items": { "$ref": "#/definitions/USProgramBrief" } }, "nextLink": { "description": "Represents the URL link to the next page.", "type": "string" } } }, "CommunicationErrorResponse": { "description": "The Communication Services error.", "type": "object", "required": [ "error" ], "properties": { "error": { "description": "The Communication Services error.", "$ref": "#/definitions/CommunicationError" } } }, "CommunicationError": { "description": "The Communication Services error.", "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "The error code." }, "message": { "type": "string", "description": "The error message." }, "target": { "type": "string", "readOnly": true, "description": "The error target." }, "details": { "type": "array", "items": { "$ref": "#/definitions/CommunicationError" }, "readOnly": true, "description": "Further details about specific errors that led to this error." }, "innererror": { "x-ms-client-name": "innerError", "readOnly": true, "$ref": "#/definitions/CommunicationError", "description": "The inner error if any." } } }, "CommunicationCloudEnvironmentModel": { "description": "The cloud that the identifier belongs to.", "type": "string", "enum": [ "public", "dod", "gcch" ], "x-ms-enum": { "name": "CommunicationCloudEnvironmentModel", "modelAsString": true } }, "CommunicationIdentifierModel": { "description": "Identifies a participant in Azure Communication services. A participant is, for example, a phone number or an Azure communication user. This model must be interpreted as a union: Apart from rawId, at most one further property may be set.", "type": "object", "properties": { "rawId": { "type": "string", "description": "Raw Id of the identifier. Optional in requests, required in responses." }, "communicationUser": { "$ref": "#/definitions/CommunicationUserIdentifierModel", "description": "The communication user." }, "phoneNumber": { "$ref": "#/definitions/PhoneNumberIdentifierModel", "description": "The phone number." }, "microsoftTeamsUser": { "$ref": "#/definitions/MicrosoftTeamsUserIdentifierModel", "description": "The Microsoft Teams user." } } }, "CommunicationUserIdentifierModel": { "description": "A user that got created with an Azure Communication Services resource.", "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The Id of the communication user." } } }, "PhoneNumberIdentifierModel": { "description": "A phone number.", "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "The phone number in E.164 format." } } }, "MicrosoftTeamsUserIdentifierModel": { "description": "A Microsoft Teams user.", "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "string", "description": "The Id of the Microsoft Teams user. If not anonymous, this is the AAD object Id of the user." }, "isAnonymous": { "type": "boolean", "description": "True if the Microsoft Teams user is anonymous. By default false if missing." }, "cloud": { "$ref": "#/definitions/CommunicationCloudEnvironmentModel", "description": "The cloud that the Microsoft Teams user belongs to. By default 'public' if missing." } } } }, "parameters": { "ApiVersionParameter": { "in": "query", "name": "api-version", "description": "Version of API to invoke", "required": true, "type": "string" }, "Endpoint": { "in": "path", "name": "endpoint", "description": "The communication resource, for example https://resourcename.communication.azure.com", "required": true, "type": "string", "x-ms-skip-url-encoding": true, "x-ms-parameter-location": "client" } }, "securityDefinitions": { "azure_auth": { "type": "oauth2", "flow": "implicit", "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", "scopes": { "user_impersonation": "impersonate your user account" }, "description": "Azure Active Directory OAuth2 Flow" } }, "x-ms-parameterized-host": { "hostTemplate": "{endpoint}", "useSchemePrefix": false, "parameters": [ { "$ref": "#/parameters/Endpoint" } ] } }