openapi: 3.0.1 info: title: connect Address Management Outbound API description: "The Cloud Connect Service is a comprehensive multi-cloud one-stop-shop solution that provides a unique combination of layer 2 transport, which is provided by BICS, and dedicated connectivity (hosted connection) directly to the Cloud Service Provider (CSP) infrastructure. This service bypasses the public internet, ensuring reliable, secure, and fast connectivity.\n\nWithin each Cloud Connect Service, the Ethernet Virtual Private Line (EVPL) is provisioned on BICS network defined by MEF 6.2. The EVPL is a secure, point-to-point Ethernet service that provides a high-performance, low-latency connection between your on-premises infrastructure and the CSP infrastructure. \n\nThank you for considering BICS Cloud Connect Service and using our API. If you have any questions or concerns, please contact BICS customer support." version: v1 servers: - url: https://api.bics.com/connect/v1 tags: - name: Outbound paths: /outbound/{senderAddress}/requests: parameters: [] post: description: Sends a text message to one or more destination numbers. operationId: Send Message parameters: - name: senderAddress in: path description: 'The address to use as the sender of the message. This can be either a number up to 15 characters, or an alphanumeric text up to 11 characters from the GSM 7bit alphabet. However, most destination networks will only allow valid phone numbers or short codes. Keep in mind that any replies will end up being delivered to this address. If the address is a phone number, you can optionally prefix it with tel: for clarity (e.g. tel:+1234567). senderAddress path variable must be a valid URL chars sequence. If it contains non-latin letters or special/punctuation characters, they are required to be URL-encoded (e.g. /outbound/ALPHA NUMERIC/requests -> /outbound/ALPHA%20NUMERIC/requests). ' required: true allowEmptyValue: false style: simple explode: false schema: type: string example: null example: '321234567' requestBody: description: Request Parameters content: application/json: schema: $ref: '#/components/schemas/OutboundRequest' example: '{"outboundSMSMessageRequest":{"address":["tel:+13500000991","tel:+13500000992"],"senderAddress":"tel:321234567","outboundSMSTextMessage":{"message":"Hello World"},"senderName":"web app name"}}' required: true responses: '201': description: CREATED content: application/json: schema: $ref: '#/components/schemas/OutboundRequest' examples: async: value: "{\n \"outboundSMSMessageRequest\": {\n \"resourceURL\": \"https://opensms.api.bics.com/sms/v3/outbound/321234567/requests/4c279a5f-1502-4679-8077-a63fa399369e\",\n \"address\": [\"tel:+13500000991\", \"tel:+13500000992\"],\n \"senderAddress\": \"tel:321234567\",\n \"outboundSMSTextMessage\": {\"message\": \"Hello World\"},\n \"senderName\": \"web app name\",\n \"callbackData\":\"xxxx-xxxxxxx-xxxxxxx-xxx\",\n \"notifyURL\":\"https://some-address.url/some-endpoint\",\n \"asynchronous\" : true\n }\n}\n" sync: value: "{\n \"outboundSMSMessageRequest\": {\n \"resourceURL\": \"https://opensms.api.bics.com/sms/v3/outbound/321234567/requests/4c279a5f-1502-4679-8077-a63fa399369e\",\n \"address\": [\"tel:+13500000991\", \"tel:+13500000992\"],\n \"senderAddress\": \"tel:321234567\",\n \"outboundSMSTextMessage\": {\"message\": \"Hello World\"},\n \"senderName\": \"web app name\",\n \"asynchronous\" : false\n }\n}\n" example: null '400': description: 'Bad request: request validation failed, or initial response from SMS HUB fails with delivery impossible. (For asynchronous requests - if initial request validation failed, or message contains correlationId for which previous response from SMS HUB failed with delivery impossible)' content: {} '401': description: 'Unauthorized: the API Key was not mentioned or is invalid (see authentication)' content: {} '403': description: 'Forbidden: this service cannot be used according to your API Key' content: {} '429': description: 'Too Many Requests: more requests were made in the last hour than is permitted with your API key' content: {} x-request-id-header: true tags: - Outbound /outbound/subscriptions: parameters: [] get: description: Your subscription for delivery infos operationId: Get Delivery Info Subscription parameters: [] responses: '200': description: subscription content: application/json: schema: $ref: '#/components/schemas/Callback' example: "{\n \"callback\": {\n \"finalDelivery\": true,\n \"url\": \"string\",\n \"securityToken\": \"string\"\n }\n}\n" '401': description: Not authorized content: {} '404': description: No subscription found content: {} x-request-id-header: true tags: - Outbound post: description: 'Subscribe for delivery info notifications. This is an alternative way to the Get Delivery Infos method to retrieve delivery infos. A delivery infos will be sent to the specified URL whenever the message''s state changes. You will typically receive 2 notifications with the states DeliveredToNetwork and DeliveredToTerminal respectively for each sent message. For large messages that are split into parts, you will receive a notification for each part with the state PartiallyDelivered except for the last part which will have the state DeliveredToTerminal. Each notification will also contain the total number of parts and the number of parts that arrived at the recipient. Additionally "finalDelivery" : This flag will determine if customer wants to only receive some of the delivery status that he considers “final”. ### Be aware that * There is no retry mechanism on the delivery notifications. If we fail to send the notification to your URL (e.g. 404 not found, timeout, network issues) we will not send it again. * The notifications might arrive in random order. E.g. for a message split in 3 parts, you might receive the notification of the 3rd part with the state DeliveredToTerminal before the notification of the 2nd part with the state PartiallyDelivered. This requires you to build some logic on your end to not simply overwrite the state DeliveredToTerminal with PartiallyDelivered and wrongfully conclude that the message is still in the state PartiallyDelivered. ' operationId: Create Delivery Info Subscription parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/DeliveryCallback' example: "{\n \"callback\": {\n \"finalDelivery\": true,\n \"url\": \"https: //your-callback-url.com\",\n \"securityToken\": \"string\"\n }\n}\n" required: true responses: '201': description: subscription created content: application/json: schema: $ref: '#/components/schemas/DeliveryCallback' example: "{\n \"callback\": {\n \"finalDelivery\": true,\n \"url\": \"https://your-callback-url.com\",\n \"securityToken\": \"string\"\n }\n}\n" '400': description: The request is not well formed. content: {} '406': description: The request is not accepted. content: application/json: schema: $ref: '#/components/schemas/NotAcceptableCallback' example: null x-request-id-header: true tags: - Outbound delete: description: Delete your subscription for delivery infos operationId: Delete Delivery Info Subscription parameters: [] responses: '401': description: Not authorized content: {} '204': description: Subscription removed content: {} '404': description: Delivery subscription not found content: {} x-request-id-header: true tags: - Outbound /outbound/{senderAddress}/requests/{requestId}/deliveryInfos: parameters: [] get: description: 'Retrieves the delivery information per recipient for a previously transmitted message. For each message sent, you can poll this URL until the message has one of the 2 final states: * DeliveredToTerminal : the message arrived on the recipient''s device * DeliveryImpossible : the message could not be delivered (e.g. the recipient''s number is not an active number) Polling for the status can be resource intensive, alternatively you can also create a delivery subscription which will post the same delivery info to a URL you specify. ' operationId: Get Delivery Infos parameters: - name: senderAddress in: path description: The sender of the message used in the original SendMessage request required: true allowEmptyValue: false style: simple explode: false schema: type: string example: null example: '321234567' - name: requestId in: path description: The requestId of the submitted message which can be found in the reponse or the location header of the original SendMessage request required: true allowEmptyValue: false style: simple explode: false schema: type: string example: null example: 4c279a5f-1502-4679-8077-a63fa399369e responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DeliveryInfoList' example: '{"deliveryInfoList":{"resourceURL":"https://opensms.api.bics.com/sms/v3/outbound/%2B321234567/requests/4c279a5f-1502-4679-8077-a63fa399369e/deliveryInfos","smsParts":3,"deliveryInfo":[{"address":"tel:+331234568","deliveryStatus":"PartiallyDelivered","deliveryStatusCode":13,"smsPartsDeliveredToTerminal":2,"callbackData":"xxxx-xxxx-xxxx-xxxx-xxxx-xxxx"},{"address":"tel:+331234567","deliveryStatus":"DeliveredToNetwork","deliveryStatusCode":6,"smsPartsDeliveredToTerminal":0,"callbackData":"xxxx-xxxx-xxxx-xxxx-xxxx-xxxx"}]}}' '401': description: 'Unauthorized: the API Key was not mentioned or is invalid (see authentication)' content: {} '403': description: 'Forbidden: this service cannot be used according to your API Key' content: {} '404': description: no such message was found content: {} '429': description: 'Too Many Requests: more requests were made in the last hour than is permitted with your API key' content: {} x-request-id-header: true tags: - Outbound components: schemas: OutboundRequest: required: - address - outboundSMSTextMessage - senderAddress type: object properties: senderAddress: type: string description: For the sender address, we allow both numeric and alphanumeric senders. Keep in mind that not all destination networks accept alphanumeric senders, and some will even refuse to terminate messages if you try to use it. example: null senderName: type: string example: null finalDelivery: type: boolean example: null address: type: array description: Recipient addresses nullable: false items: type: string description: Required. Recipient address example: null example: null resourceURL: type: string description: A resource URL for this specific request. example: null deliveryInfoList: $ref: '#/components/schemas/DeliveryInfoList' outboundSMSTextMessage: $ref: '#/components/schemas/SmsTextMessage' asynchronous: type: boolean description: Optional, default value is false. Reduces HTTP response time by acknowledging the message directly as it enters our system, doesn't influence on actual sending time of message to destination, HTTP response is sent before message validation by the routing engine. Delivery results are available on subscription, by calling 'getDeliveryResults' endpoint or by using notifyURL field. default: false example: null clientCorrelator: type: string description: 'Suppose a network issue occurs just as you''re sending a message, and you did not receive your http response. In this case you will not know whether the sms was effectively sent or not. You could send the message again, but then you risk the recipient receiving the message twice. The solution for this is the clientCorrelator. Add this optional parameter with a unique value for each message you transmit. If you transmit the message again with the same correlator, bics will not send the message again. Instead, if the message was sent before, you will simply receive the response as you would''ve received it in the original sending. Correlators stay valid for 24 hours. ' example: null callbackData: type: string description: Optional. Will be passed back in this notification, so you can use it to identify the message the receipt relates to or any other useful data, such as a function name. example: null notifyURL: type: string description: Optional. The URL-escaped URL to which a notification of delivery sent. notifyURL has presedence over delivery notification subscription that may already exist for the senderAddress. example: null x-class-extra-annotation: '@com.fasterxml.jackson.annotation.JsonRootName("outboundSMSMessageRequest")' example: null DeliveryState: type: string description: ' Status codes for the delivery state: ' enum: - MessageAccepted - DeliveredToNetwork - PartiallyDelivered - DeliveredToTerminal - DeliveryUncertain - DeliveryImpossible - InvalidSrcAddress - InvalidDestAddress example: null DeliveryInfoList: type: object properties: securityToken: type: string description: Present if this delivery info is sent as part of a delivery info subscription callback. It will contain the same value as the securityToken used to create the delivery subscription. example: null deliveryInfo: type: array items: $ref: '#/components/schemas/DeliveryInfo' example: null resourceURL: type: string description: The DeliveryInfoList can also be accessed on this resource URL. example: null smsParts: type: integer description: The number of SMS'es sent to deliver this message. An SMS has a maximum length, if your message exceeds this length, it will be split into multiple SMS'es and merged again on the recipient's device. example: null description: 'When a message was sent, the response contains a list of deliveryInfos. Use the ResourceURL of the DeliveryInfoList section of the response to check back later for updates on this list. (keep in mind that this URL will not contain your ApiKey, so if you come back for the delivery receipts you will still need to authenticate. Delivery receipts are kept for 7 days. ' x-class-extra-annotation: '@com.fasterxml.jackson.annotation.JsonRootName("deliveryInfoList")' example: null NotAcceptableCallback: type: object properties: code: type: string enum: - NOT_HTTPS example: null description: type: string example: null example: null SmsTextMessage: type: object properties: message: type: string example: null description: 'The text message to send. It will be encoded using the GSM 7-bit encoding standard. Note: The tab character (\t) will be replaced by four space characters during encoding. The backspace character (\b) will be omitted, as neither has a direct representation in GSM 7-bit encoding. ' example: null Callback: required: - securityToken - url type: object properties: securityToken: type: string description: This token will be sent in the delivery info or used as an authorization header in the inbound message as a means to secure the callback. nullable: false example: null url: type: string description: The URL to which the delivery info or an inbound message will be sent. The method will be POST and the content type application/json. nullable: false example: null x-class-extra-annotation: '@com.fasterxml.jackson.annotation.JsonRootName("callback")' example: null DeliveryInfo: type: object properties: smsPartsUncertain: type: integer description: The number of parts that is uncertain of delivery for messages split into multiple parts. x-include-if-not-null: true example: null address: type: string description: The recipient address. example: null smsPartsUndeliverable: type: integer description: The number of parts undeliverable to terminal for messages split into multiple parts. x-include-if-not-null: true example: null callbackData: type: string description: Data from original sendMessage request example: null deliveryStatus: $ref: '#/components/schemas/DeliveryState' smsPartsDeliveredToTerminal: type: integer description: The number of parts delivered to terminal for messages split into multiple parts. example: null deliveryStatusCode: type: integer example: null example: null DeliveryCallback: type: object allOf: - $ref: '#/components/schemas/Callback' - type: object properties: finalDelivery: type: boolean description: This flag will determine if customer wants to only receive some of the delivery status that he considers “final”. example: null example: null x-class-extra-annotation: '@com.fasterxml.jackson.annotation.JsonRootName("callback")' example: null