diff --git a/site/specs/global.yml b/site/specs/global.yml index 0821c84e3..fa3bdbbdd 100644 --- a/site/specs/global.yml +++ b/site/specs/global.yml @@ -1232,6 +1232,16 @@ paths: description: >- Indicating if you want the numbers returned in your results to consecutive only, or not. (true/false) + - name: digits + in: query + description: >- + You can search a specific phone number in the Bandwidth inventory + with a specific pattern e.g. 123. + schema: + type: string + minLength: 2 + maxLength: 10 + example: 123 responses: '200': description: successful operation diff --git a/site/specs/messaging.yml b/site/specs/messaging.yml index ca0b8a90f..3cefe0379 100644 --- a/site/specs/messaging.yml +++ b/site/specs/messaging.yml @@ -1794,6 +1794,11 @@ components: example: custom tag priority: $ref: '#/components/schemas/priorityEnum' + expiration: + type: string + format: date-time + description: The expiration date-time set by the user. + example: '2021-02-01T11:29:18-05:00' messageRequest: title: MessageRequest type: object @@ -1852,10 +1857,12 @@ components: $ref: '#/components/schemas/priorityEnum' expiration: type: string + format: date-time description: >- A string with the date/time value that the message will automatically expire by. This must be a valid RFC-3339 value, e.g., - 2021-03-14T01:59:26Z or 2021-03-13T20:59:26-05:00. + 2021-03-14T01:59:26Z or 2021-03-13T20:59:26-05:00. Must be a + date-time in the future. example: '2021-02-01T11:29:18-05:00' inboundMessageCallback: description: Inbound Message Callback diff --git a/site/specs/numbers.yml b/site/specs/numbers.yml index 51c34f227..d779ba759 100644 --- a/site/specs/numbers.yml +++ b/site/specs/numbers.yml @@ -1,4 +1,642 @@ components: + examples: + Brand400Error: + value: |- + + + + 12055 + 'LONG_CODE' feature is not enabled on account 900000 + + + Brand404Error: + value: |- + + + + 12067 + Brand ID 'CVBURY' does not found. + + + BrandMissingFieldError: + value: |- + + + + 1003 + CompanyName is required + + + BrandResponse: + value: |- + + + + + PUBLIC_PROFIT + 111111111 + DUNS + MEDIUM_ACCOUNT + Raleigh + Bandwidth + US + Bandwidth + 123456789 + user@mail.com + +19195551234 + 27616 + NC + 123 street + NASDAQ + BAND + TECHNOLOGY + www.my.website.com + false + + + 1 + + BrandRevet400Error: + value: |- + + + + 12210 + The Brand 'BEAQBHG' with identity status 'VETTED_VERIFIED' not allowed to revet + + + BrandRevetResponse: + value: |- + + + + BJDHM3 + CMHSJ9 + NON_PROFIT + 111111111 + DUNS + MEDIUM_ACCOUNT + Raleigh + Bandwidth + US + Bandwidth + 111111111 + 111111111 + Test1@bandwidth.com + +18009999999 + 27606 + NC + 1200 Test Road + NASDAQ + BAND + COMMUNICATION + https://www.bandwidth.com + true + + + BrandVetting400Error: + value: |- + + + + 12055 + 'LONG_CODE' feature is not enabled on account 900000 + + + BrandVettingImportRequest: + value: |- + + + AEGIS + b62ed6ba-20f7-4031-a5fa-68e96cd6c036 + + BrandVettingImportResponse: + value: |- + + + + BJDHM3 + CMHSJ9 + PUBLIC_PROFIT + 111111111 + + + BrandVettingPost400Error: + value: |- + + + + 12055 + 'LONG_CODE' feature is not enabled on account 900000 + + + BrandVettingPostResponse: + value: |- + + + + BJDHM3 + CMHSJ9 + ACTIVE + 111111111 + + + BrandVettingRequest: + value: |- + + + AEGIS + STANDARD + + BrandVettingResponse: + value: |- + + + + 69823255-96b3-412f-9120-3e77f94c6be5 + PENDING + + + BulkTnVendorAssignmentPayload: + value: |- + + + + + 9195551111 + 49 + + + 9195552222 + 49 + + + 9195553333 + 69 + + + + BulkTnVendorAssignmentTaskErrorResponse: + value: |- + + + + 18000 + The vendor id is invalid. + + + BulkTnVendorAssignmentTaskResponseForGet: + value: |- + + + + 2022-09-08 06:45:13.0 + 2022-09-08 06:46:21.0 + PARTIAL + 8e4c0d41-3477-427c-bf2e-e06382d80f62 + 3 + 2 + 1 + + + XXXX + Telephone Number not found + + 9195553333 + 69 + + + + + + 9195551111 + 49 + + + 9195552222 + 49 + + + + + BulkTnVendorAssignmentTaskResponseForPost: + value: |- + + + + PROCESSING + 8e4c0d41-3477-427c-bf2e-e06382d80f62 + + + 9195551111 + 49 + + + 9195552222 + 49 + + + 9195553333 + 69 + + + + + Campaign403Error: + value: |- + + + + 12055 + CampaignManagement feature is not enabled on account 9999999 + + + CampaignImport400CampaignTooLongError: + value: |- + + + + 1011 + CampaignId is too long. Max length 12 characters. + + + CampaignImport400Error: + value: |- + + + + 12055 + 10DLCImportCampaign feature is not enabled on account + + + CampaignImportRequest: + value: |- + + + CJEUMDK + + CampaignImportResponse: + value: |- + + + + CA114BN + Test 1 + Campaign-E + 2021-03-18T12:50:45Z + ACCEPTED + ACTIVE + + + ATT + 10017 + APPROVED + + + TMO + 10035 + APPROVED + + + + + CampaignNotFound404Error: + value: |- + + + + 12189 + Campaign with id 'C8QH5FC' not found + + + CampaignResponse: + value: |- + + + + CW12PSQ + BDPD3I1 + REAL_ESTATE + ACCOUNT_NOTIFICATION + Campaign description + false + false + false + false + false + true + true + true + Sample message + Type /help for help + false + PENDING + + + ATT + true + false + true + 1 + true + true + true + true + true + 0.0035 + E + 30 + + + + + CampaignSetting400Error: + value: |- + + + + 1003 + Phone is required + + + CampaignSetting404Error: + value: |- + + + + 12178 + 10DLC settings not found for account '9999999' + + + CampaignSetting409Error: + value: |- + + + + 12177 + Account '9999999' already has existing 10DLC settings + + + CampaignUpdateRequest: + value: |- + + + Sample message + + CampaignsListResponse: + value: |- + + + + + CH1GMWI + ACTIVE + 2021-05-25T19:06:23 + true + 2021-05-25T00:00 + B9AVERT + 2FA + + test + RPTAYWZ + false + false + false + false + false + true + false + true + test + false + DECLINED + Some Decline reason from secondary DCA + This is a sample Message Flow of my campaign. + HELP + This is a sample Help Message of my campaign. + START,YES + This is a sample Opt-In Message of my campaign. + STOP,NO + This is a sample Opt-Out Message of my campaign. + + + ATT + 10017 + APPROVED + + + TMO + 10035 + APPROVED + + + true + + + CU3UTYW + EXPIRED + 2021-06-03T11:50:16 + false + 2021-06-03T00:00 + B9AVERT + ENERGY + 2FA + + test + RPTAYWZ + false + false + false + false + false + true + false + true + test + test 15 + false + ACCEPTED + This is a sample Message Flow of my campaign. + HELP + This is a sample Help Message of my campaign. + START, YES + This is a sample Opt-In Message of my campaign. + STOP, NO + This is a sample Opt-Out Message of my campaign. + + + ATT + 10017 + APPROVED + + + TMO + 10035 + APPROVED + + + true + + + 17 + + CreateCampaign400Error: + value: |- + + + + 12185 + A call to the campaign registry service has failed validation. + + + + 509 + subscriberHelp + Support for standard help command is required by some MNOs + + + + CreateCampaignImportResponse: + value: |- + + + + CA114BN + Test 1 + Campaign-E + 2021-03-18T12:50:45Z + PENDING + ACTIVE + + + ATT + 10017 + APPROVED + + + TMO + 10035 + APPROVED + + + + + CreateCampaignRequest: + value: |- + + + 1 + B9AVERT + 2FA + + + COMMUNICATION + Test Campaign + Test Sample + true + false + true + false + false + false + false + false + false + true + This is a sample Message Flow of my campaign. + HELP + This is a sample Help Message of my campaign. + START,YES + This is a sample Opt-In Message of my campaign. + STOP,NO + This is a sample Opt-Out Message of my campaign. + + CustomerBrandRequest: + value: |- + + + PUBLIC_PROFIT + 111111111 + DUNS + MEDIUM_ACCOUNT + Raleigh + Bandwidth + US + Bandwidth + 123456789 + user@mail.com + +19195551234 + 27616 + NC + 123 street + NASDAQ + BAND + TECHNOLOGY + www.my.website.com + false + + DirectCustomerSetupRequest: + value: |- + + + DirectCustomer + + DirectCustomerSetupResponse: + value: |- + + + + DirectCustomer + + + MyBrandRequest: + value: |- + + + PUBLIC_PROFIT + 111111111 + DUNS + MEDIUM_ACCOUNT + Raleigh + Bandwidth + US + Bandwidth + 123456789 + user@mail.com + +19195551234 + 27616 + NC + 123 street + NASDAQ + BAND + TECHNOLOGY + www.my.website.com + true + + ResellerSetupRequest: + value: |- + + + Reseller + + Test Bandwidth Company + +18009999999 + Test1@bandwidth.com + + + ResellerSetupResponse: + value: |- + + + + Reseller + + Test 1 + +18002837273 + Test1@bandwidth.com + + + parameters: AccountIdPathParam: description: User's account ID @@ -8,6 +646,14 @@ components: required: true schema: type: string + CampaignIdPathParam: + description: User's campaign ID + example: CBA001 + in: path + name: campaignId + required: true + schema: + type: string DomainNamePathParam: description: Domain name example: dashboard @@ -90,6 +736,14 @@ components: - FAILED type: string type: array + TaskIdPathParam: + description: Bulk tn vendor task's ID + example: 093a9f9b-1a78-4e47-b6e2-776a484596f4 + in: path + name: taskId + required: true + schema: + type: string UserIdPathParam: description: User Id example: testUser @@ -98,6 +752,183 @@ components: required: true schema: type: string + shortCodeCountryPathParam: + description: The short code number country. + example: USA + in: path + name: country + required: true + schema: + items: + enum: + - USA + - CAN + type: string + shortCodeHistoryShortCodeSortParam: + description: Sorting parameters for `shortCode` + example: + sort: asc + explode: true + in: query + name: shortCode + properties: + sort: + enum: + - asc + - desc + type: string + required: false + style: deepObject + shortCodeHistoryVersionSortParam: + description: Sorting parameters for `version` + example: + sort: asc + explode: true + in: query + name: version + properties: + sort: + enum: + - asc + - desc + type: string + required: false + style: deepObject + shortCodeLimitQueryParam: + description: The number of entities to return based in the offset. + in: query + name: limit + required: false + schema: + default: 50 + maximum: 250 + type: integer + shortCodeOffsetQueryParam: + description: The offset number of the results to return. + in: query + name: offset + required: false + schema: + default: 0 + type: integer + shortCodePathParam: + description: The short code number used in the request. + example: '123321' + in: path + name: shortCode + required: true + schema: + type: string + requestBodies: {} + responses: + shortCode400: + content: + application/json: + examples: + example: + value: + description: Cannot process request. + type: cannot process request + schema: + $ref: '#/components/schemas/shortCodeError400' + description: Bad request, can not process the request. + shortCode401: + content: + application/json: + examples: + example: + value: + description: Client is providing incorrect or invalid credentials. + type: unauthorized + schema: + $ref: '#/components/schemas/shortCodeError' + description: Client is providing incorrect or invalid credentials. + shortCode403: + content: + application/json: + examples: + example: + value: + description: Client does not have access rights to the content. + type: forbidden + schema: + $ref: '#/components/schemas/shortCodeError' + description: Client is providing incorrect or invalid credentials. + shortCode404: + content: + application/json: + examples: + example: + value: + description: Cannot find requested resource. + type: not found + schema: + $ref: '#/components/schemas/shortCodeError' + description: The short code details not have been found. + shortCode405: + content: + application/json: + examples: + example: + value: + description: Request method 'POST' not supported. + type: method not supported + schema: + $ref: '#/components/schemas/shortCodeError' + description: Request method is not supported. + shortCode409: + content: + application/json: + examples: + example: + value: + description: Short code already exists. + type: conflict + schema: + $ref: '#/components/schemas/shortCodeError' + description: The short code already exists. + shortCode429: + content: + application/json: + examples: + example: + value: + description: Too many requests. + type: too many requests + schema: + $ref: '#/components/schemas/shortCodeError' + description: Too many requests. + shortCode500: + content: + application/json: + examples: + example: + value: + description: The server has encountered an internal error. + type: internal server error + schema: + $ref: '#/components/schemas/shortCodeError' + description: The server has encountered an internal error. + shortCodeGetAllShortCodesByAccountResponse: + content: + application/json: + schema: + $ref: '#/components/schemas/shortCodeApiPage' + description: Successful response with a paginated list of short codes. + shortCodeGetShortCodeByAccountIdCountryAndShortCodeResponse: + content: + application/json: + schema: + $ref: '#/components/schemas/shortCode' + description: The short code details have been successfully retrieved and displayed. + shortCodeGetShortCodeHistoryAccountIdCountryAndShortCodeResponse: + content: + application/json: + schema: + $ref: '#/components/schemas/shortCodeHistoryApiPage' + description: >- + The short code number history details have been successfully retrieved + and displayed. schemas: A2pClass: properties: @@ -1300,7 +2131,6 @@ components: - PUBLIC_PROFIT - NON_PROFIT - GOVERNMENT - - SOLE_PROPRIETOR type: string IsMain: description: >- @@ -1403,6 +2233,14 @@ components: $ref: '#/components/schemas/Brand' type: object type: object + BrandRevetErrorResponse: + properties: + BrandRevetResponse: + properties: + ResponseStatus: + $ref: '#/components/schemas/ResponseStatus' + type: object + type: object BrandVetting: properties: VettingClass: @@ -2192,6 +3030,282 @@ components: maxLength: 50 title: CallerName type: string + CampaignErrorResponse: + properties: + CampaignErrorResponse: + $ref: '#/components/schemas/ResponseStatus' + type: object + CampaignRequest: + properties: + Campaign: + properties: + AffiliateMarketing: + description: >- + Is affiliate marketing being used (or was used in the creation + of the campaign)? Default false + type: boolean + AgeGated: + description: Age gated content in campaign? Default false + type: boolean + AutoRenewal: + description: Campaign subscription auto-renewal status. Default true + type: boolean + BrandId: + description: >- + Alphanumeric identifier of the brand associated with this + campaign + type: string + Description: + description: Summary description of this campaign. + maximum: 4096 + minimum: 40 + type: string + DirectLending: + description: >- + Will the campaign include content related to direct lending or + other loan arrangements? Default false + type: boolean + EmbeddedLink: + description: >- + Does message generated by the campaign include URL link in SMS? + Default false + type: boolean + EmbeddedPhone: + description: >- + Does message generated by the campaign include phone number in + SMS? Default false + type: boolean + HelpKeywords: + description: >- + Help keywords of the campaign. TCR will default the value to + HELP. Multiple keywords are comma separated without space. + maximum: 320 + type: string + HelpMessage: + description: Help message of the campaign. + maximum: 320 + minimum: 20 + type: string + MessageFlow: + description: Message flow description. + maximum: 2048 + minimum: 40 + type: string + NumberPool: + description: Does campaign utilize pool of phone numbers? Default false + type: boolean + OptinKeywords: + description: >- + Opt-In keywords of the campaign. Multiple keywords are comma + separated without space. + maximum: 320 + type: string + OptinMessage: + description: Opt-In message of the campaign. + maximum: 320 + minimum: 20 + type: string + OptoutKeywords: + description: >- + Opt-Out keywords of the campaign. TCR will default the value to + STOP. Multiple keywords are comma separated without space. + maximum: 320 + type: string + OptoutMessage: + description: Opt-Out message of the campaign. + maximum: 320 + minimum: 20 + type: string + ReferenceId: + description: >- + Caller supplied campaign reference ID. If supplied, the value + must be unique across all submitted campaigns. Can be used to + prevent duplicate campaign registrations. + maximum: 50 + type: string + ResellerId: + description: >- + Alphanumeric identifier of the reseller that you want to + associate with this campaign. + type: string + Sample1: + description: >- + Message sample. Some campaign tiers require 1 or more message + samples. + maximum: 1024 + minimum: 20 + type: string + Sample2: + description: >- + Message sample. Some campaign tiers require 2 or more message + samples. Required for some usecases. + maximum: 1024 + minimum: 20 + type: string + Sample3: + description: >- + Message sample. Some campaign tiers require 3 or more message + samples. Required for some usecases. + maximum: 1024 + minimum: 20 + type: string + Sample4: + description: >- + Message sample. Some campaign tiers require 4 or more message + samples. Required for some usecases. + maximum: 1024 + minimum: 20 + type: string + Sample5: + description: >- + Message sample. Some campaign tiers require 5 or more message + samples. Required for some usecases. + maximum: 1024 + minimum: 20 + type: string + SubUsecases: + description: >- + Campaign usecase. Must be of defined valid types. Required for + some usecases. + enum: + - 2FA + - ACCOUNT_NOTIFICATION + - CARRIER_EXEMPT + - CHARITY + - CONVERSATIONAL + - CUSTOMER_CARE + - DELIVERY_NOTIFICATION + - EMERGENCY + - FRAUD_ALERT + - HIGHER_EDUCATION + - K12_EDUCATION + - LOW_VOLUME + - MARKETING + - MIXED + - POLITICAL + - POLLING_VOTING + - PUBLIC_SERVICE_ANNOUNCEMENT + - SECURITY_ALERT + - SOCIAL + - SWEEPSTAKE + - TRIAL + - AGENTS_FRANCHISES + - PROXY + - UCAAS_HIGH + - UCAAS_LOW + - M2M + type: string + SubscriberHelp: + description: >- + Have you implemented a response to the HELP keyword informing + customers of how they can contact the message sender? Default + false + type: boolean + SubscriberOptIn: + description: >- + Does campaign require subscriber to opt-in before SMS is sent to + subscriber? Default false + type: boolean + SubscriberOptOut: + description: >- + Does campaign support subscriber opt-out keyword(s)? Default + false + type: boolean + Usecase: + description: Campaign usecase. Must be of defined valid types + enum: + - 2FA + - ACCOUNT_NOTIFICATION + - CARRIER_EXEMPT + - CHARITY + - CONVERSATIONAL + - CUSTOMER_CARE + - DELIVERY_NOTIFICATION + - EMERGENCY + - FRAUD_ALERT + - HIGHER_EDUCATION + - K12_EDUCATION + - LOW_VOLUME + - MARKETING + - MIXED + - POLITICAL + - POLLING_VOTING + - PUBLIC_SERVICE_ANNOUNCEMENT + - SECURITY_ALERT + - SOCIAL + - SWEEPSTAKE + - TRIAL + - AGENTS_FRANCHISES + - PROXY + - UCAAS_HIGH + - UCAAS_LOW + - M2M + type: string + Vertical: + description: >- + Optional business/industry segment of this campaign (any value + allowed) as TCR has deprecated this field. + enum: + - REAL_ESTATE + - HEALTHCARE + - ENERGY + - ENTERTAINMENT + - RETAIL + - AGRICULTURE + - INSURANCE + - EDUCATION + - HOSPITALITY + - FINANCIAL + - GAMBLING + - CONSTRUCTION + - NGO + - MANUFACTURING + - GOVERNMENT + - TECHNOLOGY + - COMMUNICATION + type: string + required: + - BrandId + - Usecase + - SubUsecases + - Description + - Sample1 + - MessageFlow + - HelpMessage + - OptoutMessage + - AutoRenewal + type: object + type: object + CampaignSettingsRequest: + properties: + CampaignSettings: + properties: + BusinessIdentity: + description: Business Identity of customer + enum: + - Reseller + - Direct Customer + type: string + Reseller: + description: >- + Reseller Properties. This block is not allowed for Direct + Customer. + properties: + CompanyName: + description: Company name of a reseller + type: string + Email: + description: Email ID of a reseller + type: string + Phone: + description: 11 digits phone number of a reseller. Must put '+' in front + pattern: ^[+][1][0-9]{10}$ + type: string + type: object + required: + - BusinessIdentity + type: object + type: object CitySearchAndOrder: allOf: - $ref: '#/components/schemas/orderMetadata' @@ -9240,8 +10354,6 @@ components: items: $ref: '#/components/schemas/Address' type: array - TerminationHosts: - $ref: '#/components/schemas/SipPeerTerminationHosts' TnCount: format: int32 type: integer @@ -11849,6 +12961,525 @@ components: type: object xml: name: Order + shortCode: + description: Short code registration. + properties: + accountId: + description: Account ID. + example: '123123' + type: string + carrierStatuses: + description: >- + List of objects each providing the registration status for an + individual carrier. + example: + - activatedDate: '2021-10-15' + carrierId: att + status: ACTIVE + - carrierId: tmobile + status: PENDING + - carrierId: verizon + status: INACTIVE + items: + $ref: '#/components/schemas/shortCodeCarrierInfo' + type: array + country: + description: The country the short code is registered in. + enum: + - USA + - CAN + example: USA + type: string + createdDateTime: + example: '2022-11-14T18:39:04.505Z' + format: date-time + type: string + customerManagedLease: + description: >- + Flag indicating whether the customer is managing the short code + lease. + example: true + type: boolean + leaseEndsDate: + description: >- + Date the short code lease ends. Customer managed leases may not have + lease start and end dates. Date is inclusive as it relates to + expiration. + example: '2024-01-29' + format: date + type: string + leaseStartsDate: + description: >- + Date the short code lease starts. Customer managed leases may not + have lease start and end dates. Date is inclusive as it relates to + expiration. + example: '2023-01-28' + format: date + type: string + modifiedDateTime: + example: '2022-11-15T18:39:04.505Z' + format: date-time + type: string + orderedDate: + description: Date the short code was registered. + example: '2023-01-30' + format: date + type: string + shortCode: + description: The short code. + example: '12345' + type: string + sipPeerId: + description: SIP Peer ID. + example: '123321' + type: string + siteId: + description: Sub-account ID. + example: '321321' + type: string + status: + description: >- + If at least one carrier status is ACTIVE or PENDING, the status will + be ACTIVE. If all carrier statues are INACTIVE, the status will be + INACTIVE. + enum: + - ACTIVE + - EXPIRED + - SUSPENDED + - INACTIVE + example: ACTIVE + type: string + type: + description: The lease type. + enum: + - RANDOM + - VANITY + example: RANDOM + type: string + version: + description: >- + A internal field that represents the current version of the short + code data. + example: 100 + type: integer + shortCodeApiPage: + description: >- + Pagination object that represents the current page of short code + numbers. + properties: + data: + items: + $ref: '#/components/schemas/shortCode' + type: array + errors: + example: + description: Client is providing incorrect or invalid credentials. + type: unauthorized + items: + $ref: '#/components/schemas/shortCodeError' + type: array + page: + $ref: '#/components/schemas/shortCodePage' + type: object + shortCodeCarrierInfo: + description: The registration status for each carrier. + properties: + activatedDate: + description: >- + The date the short code was activated for this carrier, this date + only will be defined when the status of the carrier becomes ACTIVE. + example: '2023-01-28' + format: date + type: string + carrierId: + description: Carrier identifier (possible values att, tmobile, and verizon). + example: tmobile + type: string + status: + enum: + - ACTIVE + - INACTIVE + - PENDING + example: ACTIVE + type: string + type: object + shortCodeData: + description: Short code details representation. + properties: + accountId: + description: Account ID. + example: '123123' + type: string + carrierStatuses: + description: >- + List of objects each providing the registration status for an + individual carrier. + example: + - activatedDate: '2021-10-15' + carrierId: att + status: ACTIVE + - carrierId: tmobile + status: PENDING + - carrierId: verizon + status: INACTIVE + items: + $ref: '#/components/schemas/shortCodeCarrierInfo' + type: array + country: + description: The country the short code is registered in. + enum: + - USA + - CAN + example: USA + type: string + customerManagedLease: + description: >- + Flag indicating whether the customer is managing the short code + lease. + example: true + type: boolean + leaseEndsDate: + description: >- + Date the short code lease ends. Customer managed leases may not have + lease start and end dates. Date is inclusive as it relates to + expiration. + example: '2024-01-29' + format: date + type: string + leaseStartsDate: + description: >- + Date the short code lease starts. Customer managed leases may not + have lease start and end dates. Date is inclusive as it relates to + expiration. + example: '2023-01-28' + format: date + type: string + orderedDate: + description: Date the short code was registered. + example: '2023-01-30' + format: date + type: string + shortCode: + description: The short code. + example: '12345' + type: string + sipPeerId: + description: SIP Peer ID from Iris. + example: '123321' + type: string + siteId: + description: Sub-account ID. + example: '321321' + type: string + status: + description: >- + If at least one carrier status is ACTIVE or PENDING, the status will + be ACTIVE. If all carrier statues are INACTIVE, the status will be + INACTIVE. + enum: + - ACTIVE + - EXPIRED + - SUSPENDED + - INACTIVE + example: ACTIVE + type: string + type: + description: The lease type. + enum: + - RANDOM + - VANITY + example: RANDOM + type: string + version: + description: >- + A field that represents the version of the short code data, when + updating a short code is necessary to supply the last version value + added by 1. + example: 100 + type: integer + type: object + shortCodeError: + description: A generic error object. + properties: + description: + example: cannot find requested resource + type: string + type: + example: not found + type: string + type: object + shortCodeError400: + description: A specific error object for HTTP Status 400. + example: + description: Cannot process request. + errors: + accountId: + - is required + - can not be empty + shortCode: + - is required + - can not be empty + type: cannot process request + properties: + description: + example: Cannot process request. + type: string + errors: + $ref: '#/components/schemas/stringObjectMap' + type: + example: cannot process request + type: string + type: object + shortCodeHistory: + description: >- + Short code history details representation, each history element + represents an operation or an event that changed the state of the short + code. + properties: + accountId: + description: Account ID. + example: '123123' + type: string + carrierStatuses: + description: >- + List of objects each providing the registration status for each + carrier at the time the event occurred. + example: + - activatedDate: '2021-10-15' + carrierId: att + status: ACTIVE + - carrierId: tmobile + status: PENDING + - carrierId: verizon + status: INACTIVE + items: + $ref: '#/components/schemas/shortCodeCarrierInfo' + type: array + country: + description: The country the short code was registered in. + enum: + - USA + - CAN + example: USA + type: string + createdDateTime: + example: '2022-11-14T18:39:04.505Z' + format: date-time + type: string + customerManagedLease: + description: >- + Flag indicating whether the customer is managing the short code + lease. + example: true + type: boolean + leaseEndsDate: + description: >- + Date the short code lease ends. Customer managed leases may not have + lease start and end dates. Date is inclusive as it relates to + expiration. + example: '2024-01-29' + format: date + type: string + leaseStartsDate: + description: >- + Date the short code lease starts. Customer managed leases may not + have lease start and end dates. Date is inclusive as it relates to + expiration. + example: '2023-01-28' + format: date + type: string + modifiedDateTime: + example: '2022-11-15T18:39:04.505Z' + format: date-time + type: string + operation: + description: Operation executed over the short code. + enum: + - CREATED + - UPDATED + - DELETED + example: UPDATED + type: string + orderedDate: + description: Date the short code was registered. + example: '2023-01-30' + format: date + type: string + shortCode: + description: The short code. + example: '12345' + type: string + sipPeerId: + description: SIP Peer ID. + example: '123321' + type: string + siteId: + description: Sub-account ID. + example: '321321' + type: string + status: + description: >- + If at least one carrier status is ACTIVE or PENDING, the status will + be ACTIVE. If all carrier statues are INACTIVE, the status will be + INACTIVE. + enum: + - ACTIVE + - EXPIRED + - SUSPENDED + - INACTIVE + example: ACTIVE + type: string + type: + description: The lease type. + enum: + - RANDOM + - VANITY + example: RANDOM + type: string + user: + description: The customer user ID that initiated the operation. + example: systemUser + type: string + version: + description: A internal field that represents the version of the short code data. + example: 100 + type: integer + shortCodeHistoryApiPage: + description: >- + Pagination object that represents the current page of short code number + history. + properties: + data: + items: + $ref: '#/components/schemas/shortCodeHistory' + type: array + errors: + example: + description: Client is providing incorrect or invalid credentials. + type: unauthorized + items: + $ref: '#/components/schemas/shortCodeError' + type: array + page: + $ref: '#/components/schemas/shortCodePage' + type: object + shortCodePage: + description: Pagination object that represents the current page. + properties: + pageNumber: + description: The current page used in the request. + example: 1 + type: integer + pageSize: + description: The current page size used in the request. + example: 50 + type: integer + totalElements: + description: The total of objects that could be paginated. + example: 100 + type: integer + totalPages: + description: The total of pages that could be paginated. + example: 100 + type: integer + type: object + shortCodeUpdateData: + description: Short code update details representation. + properties: + carrierStatuses: + description: >- + List of objects each providing the registration status for an + individual carrier. + example: + - activatedDate: '2021-10-15' + carrierId: att + status: ACTIVE + - carrierId: tmobile + status: PENDING + - carrierId: verizon + status: INACTIVE + items: + $ref: '#/components/schemas/shortCodeCarrierInfo' + type: array + customerManagedLease: + description: >- + Flag indicating whether the customer is managing the short code + lease. + example: true + type: boolean + leaseEndsDate: + description: >- + Date the short code lease ends. Customer managed leases may not have + lease start and end dates. Date is inclusive as it relates to + expiration. + example: '2024-01-29' + format: date + type: string + leaseStartsDate: + description: >- + Date the short code lease starts. Customer managed leases may not + have lease start and end dates. Date is inclusive as it relates to + expiration. + example: '2023-01-28' + format: date + type: string + orderedDate: + description: Date the short code was registered. + example: '2023-01-30' + format: date + type: string + sipPeerId: + description: SIP Peer ID from Iris. + example: '123321' + type: string + siteId: + description: Sub-account ID. + example: '321321' + type: string + status: + description: >- + If at least one carrier status is ACTIVE or PENDING, the status will + be ACTIVE. If all carrier statues are INACTIVE, the status will be + INACTIVE. + enum: + - ACTIVE + - EXPIRED + - SUSPENDED + - INACTIVE + example: ACTIVE + type: string + type: + description: The lease type. + enum: + - RANDOM + - VANITY + example: RANDOM + type: string + version: + description: >- + A field that represents the version of the short code data, when + updating a short code is necessary to supply the last version value + added by 1. + example: 100 + type: integer + type: object + stringObjectMap: + additionalProperties: + example: + - is required + - can not be empty + items: + example: is required + type: string + type: array + example: + accountId: + - is required + - can not be empty + shortCode: + - is required + - can not be empty + type: object telephoneNumberDetail: description: Returned when `enableTnDetail=True` properties: @@ -13669,7 +15300,7 @@ paths: modified on the specified date/time, only the latest update for that order is included in the results. Date format can be one of: `yyyy-mm-ddThh:mm:ss.sZ`, `yyyy-mm-ddZ`, `yyyy-mm-ddThh:mm:ssTZD`. - example: '2021-06-21T18:45:00.000Z' + example: '2021-06-21' in: query name: orderDate required: false @@ -13691,7 +15322,7 @@ paths: update for that order is included in the results. Date format can be one of: `yyyy-mm-ddThh:mm:ss.sZ`, `yyyy-mm-ddZ`, `yyyy-mm-ddThh:mm:ssTZD`. - example: '2021-06-21T18:45:00.000Z' + example: '2021-06-21' in: query name: modifiedDateFrom required: false @@ -13715,7 +15346,7 @@ paths: The modifiedDateTo value may be in the future. Date format can be one of: `yyyy-mm-ddThh:mm:ss.sZ`, `yyyy-mm-ddZ`, `yyyy-mm-ddThh:mm:ssTZD`. - example: '2021-06-21T18:45:00.000Z' + example: '2021-06-21' in: query name: modifiedDateTo required: false @@ -14093,6 +15724,39 @@ paths:

+

When uploading documents using the /loas resource, you must specify + the MIME type of the document being upload using the Content-Type HTTP + header.

+ +

Information for non-toll free port-in customers:

+ +

The LOA document must be uploaded using one of the following MIME + types:

+ + +

Information for toll free port-in customers:

If you are porting toll free numbers and either of the following are @@ -14954,10 +16618,138 @@ paths: summary: Update bulk port-in order tags: - Bulk Port-In + /accounts/{accountId}/campaignManagement/10dlc: + get: + description: >- + This GET resource can be used to fetch 10dlc campaign settings + configuration on an account. + operationId: fetchCampaignSettings + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + responses: + '200': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/ResellerSetupResponse' + description: example + description: OK + '404': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignSetting404Error' + description: example + description: Not Found + summary: Fetch Campaign Settings + tags: + - 10DLC + post: + description: >- + This POST resource can be used to create a 10dlc campaign settings + configuration on an account. + operationId: createCampaignSettings + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + requestBody: + content: + application/xml: + examples: + DirectCustomer: + $ref: '#/components/examples/DirectCustomerSetupRequest' + summary: Setting up as Direct Customer + Reseller: + $ref: '#/components/examples/ResellerSetupRequest' + summary: Setting up as Reseller + schema: + $ref: '#/components/schemas/CampaignSettingsRequest' + responses: + '201': + content: + application/xml: + examples: + DirectCustomer: + $ref: '#/components/examples/DirectCustomerSetupResponse' + description: Direct Customer Campaign Settings success response + resellerExample: + $ref: '#/components/examples/ResellerSetupResponse' + description: Create Reseller Campaign Settings success response + description: Created + '400': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignSetting400Error' + description: example + description: Bad Request + '409': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignSetting409Error' + description: example + description: Conflict + summary: Create Campaign Settings + tags: + - 10DLC + put: + description: >- + This PUT resource can be used to update a 10dlc campaign settings + configuration on an account. + operationId: updateCampaignSettings + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + requestBody: + content: + application/xml: + examples: + DirectCustomer: + $ref: '#/components/examples/DirectCustomerSetupRequest' + summary: Updating campaign setting as Direct Customer + Reseller: + $ref: '#/components/examples/ResellerSetupRequest' + summary: Updating campaign setting as Reseller + schema: + $ref: '#/components/schemas/CampaignSettingsRequest' + responses: + '200': + content: + application/xml: + examples: + DirectCustomer: + $ref: '#/components/examples/DirectCustomerSetupResponse' + description: Direct Customer Campaign Settings update success response + resellerExample: + $ref: '#/components/examples/ResellerSetupResponse' + description: Reseller Campaign Settings update success response + description: OK + '400': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignSetting400Error' + description: example + description: Bad Request + '404': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignSetting404Error' + description: example + description: Not Found + summary: Update Campaign Settings + tags: + - 10DLC /accounts/{accountId}/campaignManagement/10dlc/brands: get: description: Retrieve a list of campaign registry brands for the account - operationId: List brands + operationId: listBrands parameters: - $ref: '#/components/parameters/AccountIdPathParam' - in: query @@ -14982,34 +16774,7 @@ paths: application/xml: examples: example: - value: |- - - - - - PUBLIC_PROFIT - 111111111 - DUNS - MEDIUM_ACCOUNT - Raleigh - Bandwidth - US - Bandwidth - 123456789 - user@mail.com - +19195551234 - 27616 - NC - 123 street - NASDAQ - BAND - TECHNOLOGY - www.my.website.com - false - - - 1 - + $ref: '#/components/examples/BrandResponse' schema: $ref: '#/components/schemas/BrandsResponse' description: OK @@ -15018,17 +16783,11 @@ paths: application/xml: examples: example: - value: |- - - - - 12055 - 'LONG_CODE' feature is not enabled on account 900000 - - + $ref: '#/components/examples/Brand400Error' schema: $ref: '#/components/schemas/BrandsErrorResponse' - description: Error Response + description: Bad Request + summary: List Brands tags: - 10DLC post: @@ -15043,7 +16802,7 @@ paths: Please visit [Brand and Reseller Management](/docs/messaging/campaign-management/csp/reseller-brand-api) - operationId: Create brand + operationId: createBrand parameters: - $ref: '#/components/parameters/AccountIdPathParam' requestBody: @@ -15051,55 +16810,11 @@ paths: application/xml: examples: Customer Brand: + $ref: '#/components/examples/CustomerBrandRequest' summary: Customer Brand - value: |- - - - PUBLIC_PROFIT - 111111111 - DUNS - MEDIUM_ACCOUNT - Raleigh - Bandwidth - US - Bandwidth - 123456789 - user@mail.com - +19195551234 - 27616 - NC - 123 street - NASDAQ - BAND - TECHNOLOGY - www.my.website.com - false - My Brand: + $ref: '#/components/examples/MyBrandRequest' summary: My Brand - value: |- - - - PUBLIC_PROFIT - 111111111 - DUNS - MEDIUM_ACCOUNT - Raleigh - Bandwidth - US - Bandwidth - 123456789 - user@mail.com - +19195551234 - 27616 - NC - 123 street - NASDAQ - BAND - TECHNOLOGY - www.my.website.com - true - schema: $ref: '#/components/schemas/BrandRequest' responses: @@ -15108,33 +16823,7 @@ paths: application/xml: examples: example: - value: |- - - - - BJDHM3 - CMHSJ9 - PUBLIC_PROFIT - 111111111 - DUNS - MEDIUM_ACCOUNT - Raleigh - Bandwidth - US - Bandwidth - 123456789 - 111111111 - user@mail.com - +19195551234 - 27616 - NC - 123 street - NASDAQ - BAND - TECHNOLOGY - www.my.website.com - true - + $ref: '#/components/examples/BrandResponse' schema: $ref: '#/components/schemas/BrandResponse' description: CREATED @@ -15143,23 +16832,17 @@ paths: application/xml: examples: example: - value: |- - - - - 1003 - CompanyName is required - - + $ref: '#/components/examples/BrandMissingFieldError' schema: $ref: '#/components/schemas/BrandErrorResponse' - description: Error Response + description: Bad Request + summary: Create brand tags: - 10DLC /accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}: delete: description: Delete campaign registry brand - operationId: Delete Brand + operationId: deleteBrand parameters: - $ref: '#/components/parameters/AccountIdPathParam' - description: Brand id. @@ -15172,13 +16855,13 @@ paths: responses: '204': content: - application/xml: {} - description: Successfully deleted + description: No Content + summary: Delete Brand tags: - 10DLC get: description: Retrieve a campaign registry brand for the Account - operationId: Retrieve Brand + operationId: retrieveBrand parameters: - $ref: '#/components/parameters/AccountIdPathParam' - description: Brand id. @@ -15194,31 +16877,7 @@ paths: application/xml: examples: example: - value: |- - - - - PUBLIC_PROFIT - 111111111 - DUNS - MEDIUM_ACCOUNT - Raleigh - Bandwidth - US - Bandwidth - 123456789 - user@mail.com - +19195551234 - 27616 - NC - 123 street - NASDAQ - BAND - TECHNOLOGY - www.my.website.com - false - - + $ref: '#/components/examples/BrandResponse' schema: $ref: '#/components/schemas/BrandResponse' description: OK @@ -15227,22 +16886,25 @@ paths: application/xml: examples: example: - value: |- - - - - 12055 - 'LONG_CODE' feature is not enabled on account 900000 - - + $ref: '#/components/examples/Brand400Error' + schema: + $ref: '#/components/schemas/BrandErrorResponse' + description: Bad Request + '404': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/Brand404Error' schema: $ref: '#/components/schemas/BrandErrorResponse' - description: Error Response + description: Not Found + summary: Retrieve Brand tags: - 10DLC put: description: Update campaign registry brand on the Account - operationId: Update brand + operationId: updateBrand parameters: - $ref: '#/components/parameters/AccountIdPathParam' - description: Brand id. @@ -15257,55 +16919,11 @@ paths: application/xml: examples: Customer Brand: + $ref: '#/components/examples/CustomerBrandRequest' summary: Customer Brand - value: |- - - - PUBLIC_PROFIT - 111111111 - DUNS - MEDIUM_ACCOUNT - Raleigh - Bandwidth - US - Bandwidth - 123456789 - user@mail.com - +19195551234 - 27616 - NC - 123 street - NASDAQ - BAND - TECHNOLOGY - www.my.website.com - false - My Brand: + $ref: '#/components/examples/MyBrandRequest' summary: My Brand - value: |- - - - PUBLIC_PROFIT - 111111111 - DUNS - MEDIUM_ACCOUNT - Raleigh - Bandwidth - US - Bandwidth - 123456789 - user@mail.com - +19195551234 - 27616 - NC - 123 street - NASDAQ - BAND - TECHNOLOGY - www.my.website.com - true - schema: $ref: '#/components/schemas/BrandRequest' responses: @@ -15314,59 +16932,112 @@ paths: application/xml: examples: example: - value: |- - - - - BJDHM3 - CMHSJ9 - PUBLIC_PROFIT - 111111111 - DUNS - MEDIUM_ACCOUNT - Raleigh - Bandwidth - US - Bandwidth - 123456789 - 111111111 - user@mail.com - +19195551234 - 27616 - NC - 123 street - NASDAQ - BAND - TECHNOLOGY - www.my.website.com - true - - + $ref: '#/components/examples/BrandResponse' schema: $ref: '#/components/schemas/BrandResponse' description: OK '400': + '404': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/Brand404Error' + schema: + $ref: '#/components/schemas/BrandErrorResponse' + description: Not Found content: application/xml: examples: example: - value: |- - - - - 1003 - CompanyName is required - - + $ref: '#/components/examples/Brand400Error' schema: $ref: '#/components/schemas/BrandErrorResponse' - description: Error Response + description: Bad Request + summary: Update Brand + tags: + - 10DLC + /accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/campaigns: + get: + description: The GET method is used to retrieve Campaign resource on the account. + operationId: getCampaignsByBrandId + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + - description: '' + example: null + in: path + name: brandId + required: true + schema: + default: null + type: string + - description: Number of page + example: 1 + in: query + name: page + required: false + schema: + default: null + type: integer + - description: Number of records per page + example: 8 + in: query + name: size + required: false + schema: + default: null + type: integer + responses: + '200': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignsListResponse' + description: example + description: OK + summary: Fetch Campaigns by BrandId + tags: + - 10DLC + /accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/revet: + put: + description: Request Brand Re-Vet + operationId: requestBrandRevet + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + - description: Brand id. + example: B5DG4HH + in: path + name: brandId + required: true + schema: + type: string + responses: + '200': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/BrandRevetResponse' + schema: + $ref: '#/components/schemas/Brand' + description: OK + '400': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/BrandRevet400Error' + schema: + $ref: '#/components/schemas/BrandRevetErrorResponse' + description: Bad Request + summary: Request Brand Re-Vet tags: - 10DLC /accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/vetting: get: description: Retrieve brand external vetting records - operationId: Retrieve brand vettings + operationId: retrieveBrandVettings parameters: - $ref: '#/components/parameters/AccountIdPathParam' - description: Brand id. @@ -15394,14 +17065,7 @@ paths: application/xml: examples: example: - value: |- - - - - 69823255-96b3-412f-9120-3e77f94c6be5 - PENDING - - + $ref: '#/components/examples/BrandVettingResponse' schema: $ref: '#/components/schemas/BrandVettingsResponse' description: OK @@ -15410,22 +17074,16 @@ paths: application/xml: examples: example: - value: |- - - - - 12055 - 'LONG_CODE' feature is not enabled on account 900000 - - + $ref: '#/components/examples/BrandVetting400Error' schema: $ref: '#/components/schemas/BrandVettingsErrorResponse' - description: Error Response + description: Bad Request + summary: Retrieve Brand Vettings tags: - 10DLC post: description: Create brand an external vetting - operationId: Create brand vetting + operationId: createBrandVetting parameters: - $ref: '#/components/parameters/AccountIdPathParam' - description: Brand id. @@ -15440,12 +17098,7 @@ paths: application/xml: examples: example: - value: |- - - - AEGIS - STANDARD - + $ref: '#/components/examples/BrandVettingRequest' schema: $ref: '#/components/schemas/BrandVettingRequest' responses: @@ -15454,16 +17107,7 @@ paths: application/xml: examples: example: - value: |- - - - - BJDHM3 - CMHSJ9 - ACTIVE - 111111111 - - + $ref: '#/components/examples/BrandVettingPostResponse' schema: $ref: '#/components/schemas/BrandVettingsResponse' description: OK @@ -15472,22 +17116,16 @@ paths: application/xml: examples: example: - value: |- - - - - 12055 - 'LONG_CODE' feature is not enabled on account 900000 - - + $ref: '#/components/examples/BrandVettingPost400Error' schema: $ref: '#/components/schemas/BrandVettingsErrorResponse' - description: Error Response + description: Bad Request + summary: Create Brand Vetting tags: - 10DLC put: description: Import brand external vetting records - operationId: Import brand vetting + operationId: importBrandVetting parameters: - $ref: '#/components/parameters/AccountIdPathParam' - description: Brand id. @@ -15502,12 +17140,7 @@ paths: application/xml: examples: example: - value: |- - - - AEGIS - b62ed6ba-20f7-4031-a5fa-68e96cd6c036 - + $ref: '#/components/examples/BrandVettingImportRequest' schema: $ref: '#/components/schemas/BrandVettingImportRequest' responses: @@ -15516,16 +17149,7 @@ paths: application/xml: examples: example: - value: |- - - - - BJDHM3 - CMHSJ9 - PUBLIC_PROFIT - 111111111 - - + $ref: '#/components/examples/BrandVettingImportResponse' schema: $ref: '#/components/schemas/BrandVettingImportResponse' description: OK @@ -15534,17 +17158,91 @@ paths: application/xml: examples: example: - value: |- - - - - 12055 - 'LONG_CODE' feature is not enabled on account 900000 - - + $ref: '#/components/examples/BrandVettingPost400Error' schema: $ref: '#/components/schemas/BrandVettingsErrorResponse' - description: Error Response + description: Bad Request + summary: Import Brand Vetting + tags: + - 10DLC + /accounts/{accountId}/campaignManagement/10dlc/campaigns: + get: + description: >- + This endpoint fetches a paginated list of all campaigns for your + account. + operationId: fetchCampaignList + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + - description: The page number of the results to return. + in: query + name: page + required: false + schema: + default: 0 + type: number + - description: The maximum number of results to return. + in: query + name: size + required: false + schema: + default: 25 + type: number + responses: + '200': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignsListResponse' + description: example + description: OK + '404': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignNotFound404Error' + description: example + schema: + $ref: '#/components/schemas/CampaignErrorResponse' + description: Not Found + summary: Fetch Campaign List + tags: + - 10DLC + post: + description: The POST method is used to add a new Campaign resource to the account. + operationId: createCampaign + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + requestBody: + content: + application/xml: + examples: + My Campaign: + $ref: '#/components/examples/CreateCampaignRequest' + summary: My Campaign + schema: + $ref: '#/components/schemas/CampaignRequest' + responses: + '201': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignResponse' + description: example + description: Created + '400': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CreateCampaign400Error' + description: example + schema: + $ref: '#/components/schemas/CampaignErrorResponse' + description: Bad Request + summary: Create Campaign tags: - 10DLC /accounts/{accountId}/campaignManagement/10dlc/campaigns/imports: @@ -15577,55 +17275,20 @@ paths: application/xml: examples: example: - value: |- - - - - CA114BN - Test 1 - Campaign-E - 2021-03-18T12:50:45Z - ACTIVE - - - ATT - 10017 - APPROVED - - - TMO - 10035 - APPROVED - - - - + $ref: '#/components/examples/CampaignImportResponse' schema: $ref: '#/components/schemas/LongCodeImportCampaignsResponse' - description: >- - A 200 OK response will contains a list of Imported Campaigns and a - count of the total number of Imported Campaigns available to be - returned via paging. + description: OK '400': content: application/xml: examples: example: - value: |- - - - - 12055 - 10DLCImportCampaign feature is not enabled on account - - + $ref: '#/components/examples/CampaignImport400Error' schema: $ref: '#/components/schemas/LongCodeImportCampaignsErrorResponse' - description: >- - A 400 BAD REQUEST response will be returned if one of the query - parameters is invalid. The response body will contain a description - of the error. - summary: Retrieve imported campaigns + description: Bad Request + summary: Retrieve Imported Campaigns tags: - 10DLC post: @@ -15640,11 +17303,7 @@ paths: application/xml: examples: example: - value: |- - - - CJEUMDK - + $ref: '#/components/examples/CampaignImportRequest' schema: $ref: '#/components/schemas/ImportedCampaignRequest' responses: @@ -15653,58 +17312,22 @@ paths: application/xml: examples: example: - value: |- - - - - CA114BN - Test 1 - Campaign-E - 2021-03-18T12:50:45Z - ACTIVE - - - ATT - 10017 - APPROVED - - - TMO - 10035 - APPROVED - - - - + $ref: '#/components/examples/CreateCampaignImportResponse' schema: $ref: '#/components/schemas/LongCodeImportCampaignResponse' - description: >- - A 201 CREATED if the campaign is successfully imported. The created - resource will be returned. + description: Created '400': content: application/xml: examples: example: - value: |- - - - - 1011 - CampaignId is too long. Max length 12 characters. - - + $ref: '#/components/examples/CampaignImport400CampaignTooLongError' schema: $ref: '#/components/schemas/LongCodeImportCampaignErrorResponse' - description: >- - A 400 BAD REQUEST will be returned with a descriptive payload if the - error contains an ID with an invalid format. The error contains an - error code and description. + description: Bad Request '404': - description: >- - A 404 NOT FOUND will be returned if the campaign cannot be found in - the TCR database or if it has not been correctly shared. - summary: Import campaign + description: Not Found + summary: Import Campaign tags: - 10DLC /accounts/{accountId}/campaignManagement/10dlc/campaigns/imports/{campaignId}: @@ -15715,62 +17338,161 @@ paths: operationId: GetImportedCampaign parameters: - $ref: '#/components/parameters/AccountIdPathParam' - - description: The campaign id. - example: CA114BN - in: path - name: campaignId - required: true - schema: - type: string + - $ref: '#/components/parameters/CampaignIdPathParam' responses: '200': content: application/xml: examples: example: - value: |- - - - - CA114BN - Test 1 - Campaign-E - 2021-03-18T12:50:45Z - ACTIVE - - - ATT - 10017 - APPROVED - - - TMO - 10035 - APPROVED - - - - + $ref: '#/components/examples/CampaignImportResponse' schema: $ref: '#/components/schemas/LongCodeImportCampaignResponse' - description: Successful retrieve imported campaign. + description: OK '400': content: application/xml: examples: example: - value: |- - - - - 12055 - 10DLCImportCampaign feature is not enabled on account - - + $ref: '#/components/examples/CampaignImport400Error' schema: $ref: '#/components/schemas/LongCodeImportCampaignErrorResponse' - description: Bad request. - summary: Retrieve imported campaign + description: Bad request + summary: Retrieve Imported Campaign + tags: + - 10DLC + /accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId}: + delete: + description: >- + The DELETE method is used to deactivate a Campaign with the specified + ID. + operationId: deleteCampaign + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + - $ref: '#/components/parameters/CampaignIdPathParam' + responses: + '204': + description: No Content + '403': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/Campaign403Error' + description: example + schema: + $ref: '#/components/schemas/CampaignErrorResponse' + description: Forbidden + '404': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignNotFound404Error' + description: example + schema: + $ref: '#/components/schemas/CampaignErrorResponse' + description: Not Found + summary: Delete Campaign + tags: + - 10DLC + get: + description: The GET method is used to fetch a Campaign with the specified ID. + operationId: fetchCampaign + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + - $ref: '#/components/parameters/CampaignIdPathParam' + responses: + '200': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignResponse' + description: example + description: OK + '404': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignNotFound404Error' + description: example + schema: + $ref: '#/components/schemas/CampaignErrorResponse' + description: Not Found + summary: Fetch Campaign + tags: + - 10DLC + put: + description: The PUT method is used to modify an existing Campaign resource. + operationId: updateCampaign + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + requestBody: + content: + application/xml: + examples: + My Campaign: + $ref: '#/components/examples/CampaignUpdateRequest' + summary: My Campaign + schema: + $ref: '#/components/schemas/CampaignRequest' + responses: + '200': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignResponse' + description: example + description: Created + '400': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CreateCampaign400Error' + description: example + schema: + $ref: '#/components/schemas/CampaignErrorResponse' + description: Bad Request + summary: Update Campaign + tags: + - 10DLC + /accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId}/revet: + put: + description: >- + The PUT method is used to send a request to TCR for reverification of + DCA2 declined campaign + operationId: revetCampaign + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + - $ref: '#/components/parameters/CampaignIdPathParam' + responses: + '204': + description: No Content + '403': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/Campaign403Error' + description: example + schema: + $ref: '#/components/schemas/CampaignErrorResponse' + description: Forbidden + '404': + content: + application/xml: + examples: + example: + $ref: '#/components/examples/CampaignNotFound404Error' + description: example + schema: + $ref: '#/components/schemas/CampaignErrorResponse' + description: Not Found + summary: Revet Campaign tags: - 10DLC /accounts/{accountId}/csrs: @@ -18076,28 +19798,30 @@ paths: Address, and Identifier are required. Default value of PreferredLanguage is 'en'. Non-PIDF-LO: CallbackNumber is required. Identifier can only contain alphanumeric characters and must be - between 6 and 30 characters. PIDF-LO: PIDFLOEnabled is required and + between 4 and 30 characters. PIDF-LO: PIDFLOEnabled is required and must be 'true'. Identifier can only contain alphanumeric characters and must be between 1 and 30 characters.

7. PIDF-LO and SIMPLE AEUI. PIDF-LO and Non-PIDF-LO endpoint-deletion order

AlternateEndUserIdentifiers, AlternateEndUserIdentifier, and Identifier are required. DeleteTNSpecificE911Address is required and must be 'true'. Non-PIDF-LO: CallbackNumber is required. - Identifier can only contain alphanumeric characters 6 and 30 + Identifier can only contain alphanumeric characters 4 and 30 characters. PIDF-LO: PIDFLOEnabled is required and must be 'true'. Identifier can only contain alphanumeric characters and must be between 1 and 30 characters.

8. PIDF-LO. address-provisioning - order

AdditionalAddresses and Address are required.

9. - PIDF-LO. address-editing order

Address and LocationId are - required. Allows a user to update all address fields except PlusFour - and Country.

10. PIDF-LO. address-deletion + order

AdditionalAddresses and Address are required. If a + LocationId specified matches an existing record, the current address + will be overwritten with the new values.

9. PIDF-LO. + address-editing order

Address and LocationId are required. + Allows a user to update all address fields except PlusFour and + Country.

10. PIDF-LO. address-deletion order

AdditionalAddresses, Address, and LocationId are required. DeleteTNSpecificE911Address is required and must be 'true'.

11. SIMPLE AEUI. Non-PIDF-LO endpoint-provisioning order

AlternateEndUserIdentifiers, AlternateEndUserIdentifier, Address, CallbackNumber, and Identifier are required Identifier can only contain alphanumeric characters, must contain at least one - letter, and must be between 6 and 30 characters.

+ letter, and must be between 4 and 30 characters.

responses: '201': content: @@ -21765,6 +23489,37 @@ paths: Query parameter or header documentType can be used to specify type of document on upload. + +

When uploading documents using the /loas resource, you must specify + the MIME type of the document being upload using the Content-Type HTTP + header.

+ +

The LOA document must be uploaded using one of the following MIME + types:

+ + operationId: CreateImportTnOrderLoas parameters: - $ref: '#/components/parameters/AccountIdPathParam' @@ -25785,7 +27540,7 @@ paths: enddate=2020-01-16, you will only see the latest of the entries for the same order. - example: '`2020-01-15` or `2020-01-15T02:00:01.353Z`' + example: '2020-01-15' in: query name: date required: false @@ -26896,6 +28651,39 @@ paths: +

When uploading documents using the /loas resource, you must specify + the MIME type of the document being upload using the Content-Type HTTP + header.

+ +

Information for non-toll free port-in customers:

+ +

The LOA document must be uploaded using one of the following MIME + types:

+ + +

Information for toll free port-in customers:

If you are porting toll free numbers and either of the following are @@ -30852,6 +32640,100 @@ paths: summary: Download Report Instance File tags: - Reports + /accounts/{accountId}/shortcodes: + get: + description: Retrieves all the short codes registered with an account. + operationId: getAllShortCodesByAccount + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + - $ref: '#/components/parameters/shortCodeOffsetQueryParam' + - $ref: '#/components/parameters/shortCodeLimitQueryParam' + responses: + '200': + $ref: '#/components/responses/shortCodeGetAllShortCodesByAccountResponse' + '400': + $ref: '#/components/responses/shortCode400' + '401': + $ref: '#/components/responses/shortCode401' + '403': + $ref: '#/components/responses/shortCode403' + '404': + $ref: '#/components/responses/shortCode404' + '405': + $ref: '#/components/responses/shortCode405' + '429': + $ref: '#/components/responses/shortCode429' + '500': + $ref: '#/components/responses/shortCode500' + summary: Retrieve short codes by account. + tags: + - Short Codes + /accounts/{accountId}/shortcodes/{shortCode}/{country}: + get: + description: >- + Retrieve the details of an account's registration of a short code for a + single country. + operationId: getShortCodeByAccountIdCountryAndShortCode + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + - $ref: '#/components/parameters/shortCodePathParam' + - $ref: '#/components/parameters/shortCodeCountryPathParam' + responses: + '200': + $ref: >- + #/components/responses/shortCodeGetShortCodeByAccountIdCountryAndShortCodeResponse + '400': + $ref: '#/components/responses/shortCode400' + '401': + $ref: '#/components/responses/shortCode401' + '403': + $ref: '#/components/responses/shortCode403' + '404': + $ref: '#/components/responses/shortCode404' + '405': + $ref: '#/components/responses/shortCode405' + '429': + $ref: '#/components/responses/shortCode429' + '500': + $ref: '#/components/responses/shortCode500' + summary: Retrieve short code details. + tags: + - Short Codes + /accounts/{accountId}/shortcodes/{shortCode}/{country}/history: + get: + description: >- + Retrieves a complete history of all updates associated with an account's + registration of a short code for a single country. + operationId: getShortCodeHistoryAccountIdCountryAndShortCode + parameters: + - $ref: '#/components/parameters/AccountIdPathParam' + - $ref: '#/components/parameters/shortCodePathParam' + - $ref: '#/components/parameters/shortCodeCountryPathParam' + - $ref: '#/components/parameters/shortCodeOffsetQueryParam' + - $ref: '#/components/parameters/shortCodeLimitQueryParam' + - $ref: '#/components/parameters/shortCodeHistoryShortCodeSortParam' + - $ref: '#/components/parameters/shortCodeHistoryVersionSortParam' + responses: + '200': + $ref: >- + #/components/responses/shortCodeGetShortCodeHistoryAccountIdCountryAndShortCodeResponse + '400': + $ref: '#/components/responses/shortCode400' + '401': + $ref: '#/components/responses/shortCode401' + '403': + $ref: '#/components/responses/shortCode403' + '404': + $ref: '#/components/responses/shortCode404' + '405': + $ref: '#/components/responses/shortCode405' + '429': + $ref: '#/components/responses/shortCode429' + '500': + $ref: '#/components/responses/shortCode500' + summary: Retrieve short code history. + tags: + - Short Codes /accounts/{accountId}/sipcredentials: get: description: Retrieve all SIP credentials for the account @@ -32721,25 +34603,6 @@ paths: - ENH_VERSTAT_AND_IDENTITY - IDENTITY type: string - TerminationHosts: - description: >- - These addresses, comprised of IP or Subnet(CIDR format) and - optional Port, are used by the Bandwidth network to send - calls to for Termination services. Maximum of 10 hosts - can - be IP address or subnets. In case of subnet you should - specify NetworkAddress of subnet as IP - items: - properties: - TerminationHost: - properties: - CustomerTrafficAllowed: - type: string - HostName: - type: string - Port: - type: string - type: object - type: array VoiceHostGroups: description: >- The VoiceHostGroups element is comprised of one @@ -40213,6 +42076,7 @@ tags: description: Reports guide url: /docs/numbers/guides/setup-reports/accountReports/ name: Reports + - name: Short Codes - externalDocs: description: Sip Registrar guide url: /docs/account/sipRegistrar/#create-sip-credentials @@ -40227,3 +42091,4 @@ tags: - name: Tn Reservation - name: Tns - name: Admin Data + - name: Tn Vendor Assignment diff --git a/site/specs/one-identity-management.yml b/site/specs/one-identity-management.yml index f23446a0a..ea8c72a5e 100644 --- a/site/specs/one-identity-management.yml +++ b/site/specs/one-identity-management.yml @@ -2,28 +2,20 @@ openapi: 3.0.3 info: title: Identity Management description: Bandwidth Identity API - contact: {} - version: 2.0.0-alpha - x-server-configuration: - default-environment: Production - default-server: Production - environments: - - name: Production - - name: Custom - servers: - - name: default - url: '{base_url}' - parameters: - - name: base_url - description: '' - type: string - example: https://www.example.com + contact: + name: Bandwidth + version: 4.1.2 + termsOfService: https://www.bandwidth.com/legal/terms-of-use-bandwidthcom-web-sites/ +servers: + - url: https://management.id.bandwidth.com +tags: + - name: Identity Provider Management paths: /idps: get: tags: - Identity Provider Management - summary: getIdps + summary: List IdPs description: Returns all the IdPs that the requesting user has access to. operationId: getIdps parameters: @@ -48,19 +40,17 @@ paths: $ref: '#/components/responses/tooManyRequestsResponse' '500': $ref: '#/components/responses/internalErrorResponse' - deprecated: false post: tags: - Identity Provider Management - summary: postIdps + summary: Create IdP description: Creates a new IdP. operationId: postIdps - parameters: [] requestBody: $ref: '#/components/requestBodies/createIdpRequest' responses: '201': - $ref: '#/components/responses/createdResponse' + $ref: '#/components/responses/createdIdpResponse' '400': $ref: '#/components/responses/badRequestResponse' '401': @@ -75,12 +65,11 @@ paths: $ref: '#/components/responses/tooManyRequestsResponse' '500': $ref: '#/components/responses/internalErrorResponse' - deprecated: false /idps/{idpId}: put: tags: - Identity Provider Management - summary: putIdp + summary: Replace IdP description: Modifies an IdP. operationId: putIdp parameters: @@ -106,11 +95,10 @@ paths: $ref: '#/components/responses/tooManyRequestsResponse' '500': $ref: '#/components/responses/internalErrorResponse' - deprecated: false get: tags: - Identity Provider Management - summary: getIdp + summary: Get IdP description: Returns the IdP with the given id. operationId: getIdp parameters: @@ -132,20 +120,17 @@ paths: $ref: '#/components/responses/tooManyRequestsResponse' '500': $ref: '#/components/responses/internalErrorResponse' - deprecated: false delete: tags: - Identity Provider Management - summary: deleteIdp + summary: Delete IdP description: Deletes the IdP with the given id. operationId: deleteIdp parameters: - $ref: '#/components/parameters/idpId' responses: '204': - $ref: '#/components/responses/deleteResponse' - '400': - $ref: '#/components/responses/badRequestResponse' + $ref: '#/components/responses/deleteIdpResponse' '401': $ref: '#/components/responses/unauthorizedResponse' '403': @@ -160,44 +145,12 @@ paths: $ref: '#/components/responses/tooManyRequestsResponse' '500': $ref: '#/components/responses/internalErrorResponse' - deprecated: false - /.well-known/webfinger: - get: - tags: - - Webfinger - summary: Webfinger - description: Returns a Webfinger response for the provided resource. - operationId: webfinger - parameters: - - $ref: '#/components/parameters/webfingerResource' - responses: - '200': - $ref: '#/components/responses/webfingerResponse' - '400': - $ref: '#/components/responses/badRequestResponse' - '401': - $ref: '#/components/responses/unauthorizedResponse' - '403': - $ref: '#/components/responses/forbiddenResponse' - '404': - $ref: '#/components/responses/notFoundResponse' - '405': - $ref: '#/components/responses/methodNotAllowedResponse' - '429': - $ref: '#/components/responses/tooManyRequestsResponse' - '500': - $ref: '#/components/responses/internalErrorResponse' - deprecated: false - security: [] components: parameters: limit: in: query name: limit - required: false description: The maximum records requested in search result. - style: form - explode: true schema: type: integer format: int32 @@ -207,38 +160,29 @@ components: offset: in: query name: offset - required: false description: >- The amount of records to skip in search result. Combine with limit to fetch results one page at a time. - style: form - explode: true schema: type: integer example: 50 active: in: query name: active - required: false description: >- Set this to true to find only active IdPs. Or false to find only inactive ones. - style: form - explode: true schema: type: boolean example: true accountId: in: query name: accountId - required: false description: >- The accountId associated with a specific IdP. If you have access to multiple accounts with their own IdPs, use this filter to narrow the results down to just a particular account or accounts (can be specified multiple times). - style: form - explode: true schema: type: string example: '9999999' @@ -247,37 +191,29 @@ components: in: path description: The IdP id. required: true - style: simple schema: type: string - webfingerResource: - name: resource - in: query - description: The resource to get information about - required: true - style: form - explode: true - schema: - type: string - example: okta:acct:user@company.com + format: uuid + pattern: >- + ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89AB][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$ requestBodies: createIdpRequest: - description: '' + description: Create Idp request body. content: application/json: schema: $ref: '#/components/schemas/newIdP' required: true updateIdpRequest: - description: '' + description: Update Idp request body. content: application/json: schema: $ref: '#/components/schemas/updateIdP' required: true responses: - createdResponse: - description: Successful Response. Returns the newly created IdP resource. + createdIdpResponse: + description: Created. headers: Location: description: The URL of the created resource. @@ -289,154 +225,188 @@ components: content: application/json: schema: - $ref: '#/components/schemas/idP' - deleteResponse: - description: Successful response. The IdP resource was deleted. - headers: {} - content: {} + $ref: '#/components/schemas/idpResponse' + deleteIdpResponse: + description: No Content getIdpResponse: - description: Successful response. The IdP resource, if it exists. - headers: {} + description: OK content: application/json: schema: - $ref: '#/components/schemas/idP' + $ref: '#/components/schemas/idpResponse' getIdpsResponse: - description: >- - Successful response. A list of IdPs is returned. If there are no IdPs to - return, an empty list is returned. - headers: {} + description: OK content: application/json: schema: - type: object - properties: - items: - type: array - items: - $ref: '#/components/schemas/idP' - totalCount: - type: integer - description: The total number of IdPs found with the specified filters - description: '' + $ref: '#/components/schemas/listIdpResponse' putIdpsResponse: - description: Successful Response. Returns the modified IdP resource. - headers: {} - content: - application/json: - schema: - $ref: '#/components/schemas/idP' - webfingerResponse: - description: A webfinger standard response for the requested resource. - headers: {} + description: OK content: application/json: schema: - oneOf: - - $ref: '#/components/schemas/webfingerIdPEnabledResponse' + $ref: '#/components/schemas/idpResponse' badRequestResponse: description: Bad Request - headers: {} content: application/json: schema: - $ref: '#/components/schemas/badRequestResponse' + $ref: '#/components/schemas/errorResponse' + examples: + badRequestResponseExample: + $ref: '#/components/examples/badRequestResponse' conflictResponse: - description: >- - Conflict. You are attempting to modify an IdP in a way it cannot be - changed - headers: {} + description: Conflict content: application/json: schema: - $ref: '#/components/schemas/conflictResponse' + $ref: '#/components/schemas/errorResponse' + examples: + conflictResponseExample: + $ref: '#/components/examples/conflictResponse' forbiddenResponse: description: Forbidden - headers: {} content: application/json: schema: - $ref: '#/components/schemas/forbiddenResponse' + $ref: '#/components/schemas/errorResponse' + examples: + forbiddenResponseExample: + $ref: '#/components/examples/forbiddenResponse' internalErrorResponse: - description: An internal error occurred attempting to process a request - headers: {} + description: Internal Server Error content: application/json: schema: - $ref: '#/components/schemas/internalErrorResponse' + $ref: '#/components/schemas/errorResponse' + examples: + internalErrorResponseExample: + $ref: '#/components/examples/internalErrorResponse' methodNotAllowedResponse: description: Method Not Allowed - headers: {} content: application/json: schema: - $ref: '#/components/schemas/methodNotAllowedResponse' + $ref: '#/components/schemas/errorResponse' + examples: + methodNotAllowedResponseExample: + $ref: '#/components/examples/methodNotAllowedResponse' notFoundResponse: - description: IdP not found. - headers: {} + description: Not Found content: application/json: schema: - $ref: '#/components/schemas/notFoundResponse' + $ref: '#/components/schemas/errorResponse' + examples: + notFoundResponseExample: + $ref: '#/components/examples/notFoundResponse' tooManyRequestsResponse: description: Too Many Requests - headers: {} - content: - application/json: - schema: - $ref: '#/components/schemas/tooManyRequestsResponse' unauthorizedResponse: description: Unauthorized - headers: {} content: application/json: schema: - $ref: '#/components/schemas/unauthorizedResponse' + $ref: '#/components/schemas/errorResponse' + examples: + unauthorizedResponseExample: + $ref: '#/components/examples/unauthorizedResponse' schemas: - newSAMLIdP: + idpResponse: + required: + - links + - data + - errors + type: object + properties: + links: + type: array + items: + $ref: '#/components/schemas/link' + example: [] + data: + $ref: '#/components/schemas/idP' + errors: + type: array + items: + $ref: '#/components/schemas/error' + example: [] + listIdpResponse: + required: + - links + - data + - errors + type: object + properties: + links: + type: array + items: + $ref: '#/components/schemas/link' + example: [] + data: + type: object + properties: + items: + type: array + items: + $ref: '#/components/schemas/idP' + totalCount: + type: integer + description: The total number of IdPs found with the specified filters + format: int32 + example: 0 + errors: + type: array + items: + $ref: '#/components/schemas/error' + example: [] + errorResponse: + required: + - links + - data + - errors + type: object + properties: + links: + type: array + items: + $ref: '#/components/schemas/link' + example: [] + data: + type: object + nullable: true + errors: + type: array + items: + $ref: '#/components/schemas/error' + example: [] + newSamlIdp: title: NewSAMLIdP required: - accountIds - active - issuerUri - singleSignOnUrl + - name type: object properties: protocol: - enum: - - SAML2 - type: string - description: >- - The protocol used by this Identity Provider. Only SAML2 is supported - for now. - example: SAML2 + $ref: '#/components/schemas/protocol' + name: + $ref: '#/components/schemas/name' accountIds: $ref: '#/components/schemas/accountIds' active: - type: boolean - description: >- - Whether this IdP is active or not. Only one IdP can be active for a - given accountId. - example: false + $ref: '#/components/schemas/active' usernameField: - type: string - description: The field in the SAML assertion that contains the username + $ref: '#/components/schemas/usernameField' issuerUri: - type: string - description: >- - URI of the Identity Provider. This value is usually the SAML - Metadata EntityID of the IdP EntityDescriptor. + $ref: '#/components/schemas/issuerUri' singleSignOnUrl: - type: string - description: >- - The binding-specific IdP Authentication Request Protocol endpoint - that receives SAML AuthnRequest messages. + $ref: '#/components/schemas/singleSignOnUrl' signatureCertificate: - type: string - description: >- - The PEM or DER encoded public key certificate of the Identity - Provider used to verify SAML message and assertion signatures. - updateSAMLIdP: + $ref: '#/components/schemas/signatureCertificate' + updateSamlIdp: title: UpdateSAMLIdP required: - accountIds @@ -444,43 +414,26 @@ components: - issuerUri - singleSignOnUrl - signatureCertificate + - name type: object properties: protocol: - enum: - - SAML2 - type: string - description: >- - The protocol used by this Identity Provider. Only SAML2 is supported - for now. - example: SAML2 + $ref: '#/components/schemas/protocol' + name: + $ref: '#/components/schemas/name' accountIds: $ref: '#/components/schemas/accountIds' active: - type: boolean - description: >- - Whether this IdP is active or not. Only one IdP can be active for a - given accountId. - example: false + $ref: '#/components/schemas/active' usernameField: - type: string - description: The field in the SAML assertion that contains the username + $ref: '#/components/schemas/usernameField' issuerUri: - type: string - description: >- - URI of the Identity Provider. This value is usually the SAML - Metadata EntityID of the IdP EntityDescriptor. + $ref: '#/components/schemas/issuerUri' singleSignOnUrl: - type: string - description: >- - The binding-specific IdP Authentication Request Protocol endpoint - that receives SAML AuthnRequest messages. + $ref: '#/components/schemas/singleSignOnUrl' signatureCertificate: - type: string - description: >- - The PEM or DER encoded public key certificate of the Identity - Provider used to verify SAML message and assertion signatures. - SAMLIdP: + $ref: '#/components/schemas/signatureCertificate' + samlIdp: title: SAMLIdP required: - accountIds @@ -488,47 +441,81 @@ components: - id - entityId - acsUrl + - name type: object properties: accountIds: $ref: '#/components/schemas/accountIds' active: - type: boolean - description: >- - Whether this IdP is active or not. Only one IdP can be active for a - given accountId. - example: false + $ref: '#/components/schemas/active' id: type: string description: The identifier for this Identity Provider. + example: 12345678-abcd-47e9-8fab-87654321cbab + format: uuid + pattern: >- + ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89AB][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$ + name: + $ref: '#/components/schemas/name' entityId: type: string description: >- The IdP entity id. This should be used as input to configure the source provider. + example: https://youridentityprovider.com/saml2/idp-provider/123456abcd acsUrl: type: string description: >- The SAML Assertion Consumer Service URL. This should be used as input to configure the source provider. + example: https://login.bandwidth.com/sso/saml2/12345678abcdef usernameField: - type: string - description: The field in the SAML assertion that contains the username + $ref: '#/components/schemas/usernameField' issuerUri: - type: string - description: >- - URI of the Identity Provider. This value is usually the SAML - Metadata EntityID of the IdP EntityDescriptor. + $ref: '#/components/schemas/issuerUri' singleSignOnUrl: - type: string - description: >- - The binding-specific IdP Authentication Request Protocol endpoint - that receives SAML AuthnRequest messages. + $ref: '#/components/schemas/singleSignOnUrl' signatureCertificate: - type: string - description: >- - The PEM or DER encoded public key certificate of the Identity - Provider used to verify SAML message and assertion signatures. + $ref: '#/components/schemas/signatureCertificate' + active: + title: active + type: boolean + description: >- + Whether this IdP is active or not. Only one IdP can be active for a + given accountId. + example: false + usernameField: + title: usernameField + type: string + description: The field in the SAML assertion that contains the username + example: user1 + issuerUri: + title: issuerUri + type: string + format: uri + description: >- + URI of the Identity Provider. This value is usually the SAML Metadata + EntityID of the IdP EntityDescriptor. + example: https://your.provider.com/ + singleSignOnUrl: + title: singleSignOnUrl + type: string + format: uri + description: >- + The binding-specific IdP Authentication Request Protocol endpoint that + receives SAML AuthnRequest messages. This must be a valid RFC 3986 + value. + example: https://login.example.com/ + signatureCertificate: + title: signatureCertificate + type: string + minLength: 1 + maxLength: 2147483647 + description: >- + The PEM or DER encoded public key certificate of the Identity Provider + used to verify SAML message and assertion signatures. + example: >- + MIIF1DCCA7wCCQDUe/gZ7Z9qrTANBgkqhkiG9w0BAQsFADCBqzELMAkGA1UEBhMCVVMxFzAVB...... accountIds: title: accountIds type: array @@ -536,266 +523,72 @@ components: example: - 123456 - 654321 - badRequestResponse: - title: badRequestResponse + protocol: + title: protocol + enum: + - SAML2 + type: string + description: >- + The protocol used by this Identity Provider. Only SAML2 is supported for + now. + example: SAML2 + name: + title: name + type: string + description: >- + A short description to uniquely identify an Identity Provider + configuration. Max 40 characters + example: IDP for Developers + link: + title: link type: object - properties: - statusCode: - type: integer - description: >- - The HTTP status code returned by the server for the error - encountered - format: int32 - example: 400 - conflictResponse: - title: conflictResponse + error: + title: error type: object properties: - timestamp: - type: string - description: The timestamp in ISO 8601 format of when the error was encountered - format: date-time - statusCode: - type: integer - description: >- - The HTTP status code returned by the server for the error - encountered - format: int32 - example: 409 - statusText: + type: type: string - description: A short description about the error encountered - traceId: - type: string - description: A unique trace ID used to identify the request and response. - example: b77a5ea79036d5b9 - forbiddenResponse: - title: forbiddenResponse - type: object - properties: - statusCode: - type: integer - description: >- - The HTTP status code returned by the server for the error - encountered - format: int32 - example: 403 - methodNotAllowedResponse: - title: methodNotAllowedResponse - type: object - properties: - statusCode: - type: integer - description: >- - The HTTP status code returned by the server for the error - encountered - format: int32 - example: 405 - notFoundResponse: - title: notFoundResponse - type: object - properties: - statusCode: - type: integer - description: >- - The HTTP status code returned by the server for the error - encountered - format: int32 - example: 404 - tooManyRequestsResponse: - title: tooManyRequestsResponse - type: object - properties: - statusCode: - type: integer - description: >- - The HTTP status code returned by the server for the error - encountered - format: int32 - example: 429 - unauthorizedResponse: - title: unauthorizedResponse - type: object - properties: - timestamp: + description: A short human-readable summary of the problem encountered + example: Error + description: type: string - description: The timestamp in ISO 8601 format of when the error was encountered - format: date-time - statusCode: - type: integer description: >- - The HTTP status code returned by the server for the error - encountered - format: int32 - example: 401 - error: - type: string - description: A short description about the error encountered - example: Invalid credentials - traceId: - type: string - description: A unique trace ID used to identify the request and response. - example: b77a5ea79036d5b9 - path: - type: string - description: the path that was requested - example: /api/v1/idps/1 - internalErrorResponse: - title: internalErrorResponse - type: object - properties: - timestamp: - type: string - description: The timestamp in ISO 8601 format of when the error was encountered - format: date-time - statusCode: - type: integer - description: >- - The HTTP status code returned by the server for the error - encountered - format: int32 - example: 500 - statusText: - type: string - description: A short description about the error encountered - traceId: - type: string - description: A unique trace ID used to identify the request and response. - example: b77a5ea79036d5b9 + A human-readable detailed description that SHOULD be specific to the + problem encountered + example: There was a problem with your request. Please try again + code: + type: string + description: An Identity Management API specific error code + example: E0001 + source: + type: object + description: Information about the source of the error + example: {} idP: title: IdP + type: object oneOf: - - $ref: '#/components/schemas/SAMLIdP' + - $ref: '#/components/schemas/samlIdp' discriminator: propertyName: protocol mapping: - SAML2: '#/components/schemas/SAMLIdP' + SAML2: '#/components/schemas/samlIdp' newIdP: title: NewIdP oneOf: - - $ref: '#/components/schemas/newSAMLIdP' + - $ref: '#/components/schemas/newSamlIdp' discriminator: propertyName: protocol mapping: - SAML2: '#/components/schemas/newSAMLIdP' + SAML2: '#/components/schemas/newSamlIdp' updateIdP: title: UpdateIdP oneOf: - - $ref: '#/components/schemas/updateSAMLIdP' + - $ref: '#/components/schemas/updateSamlIdp' discriminator: propertyName: protocol mapping: - SAML2: '#/components/schemas/updateSAMLIdP' - webfingerIdPEnabledResponse: - title: webfingerIdPEnabledResponse - required: - - subject - - links - type: object - properties: - subject: - type: string - description: The resource - xml: - attribute: true - wrapped: false - links: - type: array - items: - $ref: '#/components/schemas/webfingerLinks' - description: '' - example: - - href: >- - https://login.bandwidth.com/sso/idps/0oahx4rqfARaXDIas4x6?login_hint=user%40company.com# - rel: okta:idp - properties: - okta:idp:id: 0obhx4rqfARaXDIas4x2 - okta:idp:metadata: >- - https://login.bandwidth.com/api/v1/idps/0obhx4rqfARaXDIas4x2/metadata.xml - okta:idp:type: SAML2 - titles: - und: Company IdP - description: The response from the Webfinger for a resource with BYOIdP enabled - example: - subject: okta:acct:user@company;com - links: - - href: >- - https://login.bandwidth.com/sso/idps/0oahx4rqfARaXDIas4x6?login_hint=user%40company.com# - rel: okta:idp - properties: - okta:idp:id: 0obhx4rqfARaXDIas4x2 - okta:idp:metadata: >- - https://login.bandwidth.com/api/v1/idps/0obhx4rqfARaXDIas4x2/metadata.xml - okta:idp:type: SAML2 - titles: - und: Company IdP - webfingerLinksTitles: - title: webfinger_links_titles - required: - - und - type: object - properties: - und: - type: string - description: Title of the link of the resource - xml: - attribute: true - wrapped: false - description: '' - webfingerLinksProperties: - title: webfinger_links_properties - required: - - okta:idp:id - - okta:idp:metadata - - okta:idp:type - type: object - properties: - okta:idp:id: - type: string - description: The IdP ID - xml: - attribute: true - wrapped: false - okta:idp:metadata: - type: string - description: Link to the IdP metadata - xml: - attribute: true - wrapped: false - okta:idp:type: - type: string - description: The IdP type or protocol - xml: - attribute: true - wrapped: false - example: SAML2 - description: '' - webfingerLinks: - title: webfinger_links - required: - - href - - rel - - properties - - titles - type: object - properties: - href: - type: string - description: Direct link to initiate resource login process - xml: - attribute: true - wrapped: false - rel: - type: string - xml: - attribute: true - wrapped: false - example: okta:idp - properties: - $ref: '#/components/schemas/webfingerLinksProperties' - titles: - $ref: '#/components/schemas/webfingerLinksTitles' - description: Links for the resource in the subject + SAML2: '#/components/schemas/updateSamlIdp' securitySchemes: bearerAuth: type: http @@ -804,20 +597,72 @@ components: basicAuth: type: http scheme: basic + examples: + badRequestResponse: + value: + links: [] + data: null + errors: + - type: Validation + description: >- + failed to validate input: provided SignatureCertificate has + expired + code: E0001 + source: null + conflictResponse: + value: + links: [] + data: null + errors: + - type: Conflict + description: invalid account(s) provided + code: E0002 + source: null + forbiddenResponse: + value: + links: [] + data: null + errors: + - type: Error + description: '' + code: '' + source: null + internalErrorResponse: + value: + links: [] + data: null + errors: + - type: Internal Error + description: An error occurred. Please refresh and try again. + code: E0003 + source: null + methodNotAllowedResponse: + value: + links: [] + data: null + errors: + - type: Error + description: the HTTP method used is not supported by this resource + code: E0004 + source: null + notFoundResponse: + value: + links: [] + data: null + errors: + - type: Error + description: the specified resource could not be found. + code: E0005 + source: null + unauthorizedResponse: + value: + links: [] + data: null + errors: + - type: Authorization, + description: Invalid credentials + code: E0006 + source: null security: - basicAuth: [] - bearerAuth: [] -tags: - - name: Identity Provider Management - description: '' - - name: Webfinger - description: '' -servers: - - description: Production - url: https://management.id.bandwidth.com - variables: {} - - url: '{base_url}' - variables: - base_url: - default: https://www.example.com - description: ''