openapi: 3.0.0
info:
  title: URL Shortening
  description: >-
    We support URL shortening for both SMS and SMS Campaign, making it easier to
    craft a more digestible message for your recipients and also allowing you to
    save characters in your messages.


    Some limitations to be aware of are:

    * Only valid links are processed. A valid URL must include a proper protocol
    (e.g., `http://` or `https://`) or a valid domain (e.g., `example.com`).
      * `https://example.com`
      * `example.com`
      * `www.example.com`
    * We can shorten links up to 250 characters in length.



    ### SMS

    For SMS messages, URL shortening automatically detects and replaces one URL
    in each message with a shortened link in the format `smsu.io/xxxxxx`. The
    `xxxxxx` placeholder represents a unique six-character alphanumeric string
    that is generated for each recipient during the actual sending process. 


    You should use this endpoint if you wish to send out a link that is specific
    to the recipient, such as order tracking links, or customised feedback
    forms.


    To use short URLs on SMS sending, refer
    [here](/messaging/sms/other/send-sms).



    ### SMS Campaign

    We support URL shortening and subsequent link tracking within SMS
    campaigns. 


    When using the short URL functionality in SMS Campaign, all recipients will
    receive a shortened link in the format `smsu.io/xxxxx`. The `xxxxx`
    placeholder represents a unique five-character alphanumeric string that is
    generated for each recipient during the actual sending process.


    You should use this endpoint if you're sending out the same link to many
    recipients and wish to track its engagement such as whether the link was
    opened.


    To use short URLs when sending an SMS campaign, refer
    [here](/messaging/sms-campaigns/other/send-sms-campaign).
servers:
  - url: https://rest.clicksend.com
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    get-statistics:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              long_url_id:
                type: string
                description: ID of a URL under the specified source and source_id
                example: >-
                  quick_sms-26d1bc9a-d858-4b93-9368-1f31377a78c5-5908b13f05e7318be49bd1cb3a693d7c
              links:
                type: object
                description: Link statistics
                properties:
                  total:
                    type: number
                    description: Total number of recipients
                    example: 2
                  opened_unique:
                    type: number
                    description: Total number of recipients that clicked the short URL
                    example: 2
                  opened_total:
                    type: number
                    description: >-
                      Total number of clicks on the short URL (e.g. when a
                      recipient clicked the short URL twice, then it will add 2
                      here)
                    example: 5
                  unopened:
                    type: number
                    description: >-
                      Total number of recipients that did not click the short
                      URL (i.e. `total` - `opened_unique`)
                    example: 0
              device:
                type: array
                description: Device statistics of the recipients that clicked the short URL
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      description: Device name
                      example: mobile
                    count:
                      type: number
                      description: >-
                        Total number of clicks on the short URL where the
                        recipient has the specified device name
                      example: 2
              os:
                type: array
                description: OS statistics of the recipients that clicked the short URL
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      description: OS name
                      example: android
                    count:
                      type: number
                      description: >-
                        Total number of clicks on the short URL where the
                        recipient has the specified OS name
                      example: 2
              browser:
                type: array
                description: >-
                  Browser statistics of the recipients that clicked the short
                  URL
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      description: Browser name
                      example: chrome
                    count:
                      type: number
                      description: >-
                        Total number of clicks on the short URL where the
                        recipient has the specified browser name
                      example: 2
              country:
                type: array
                description: >-
                  Country statistics of the recipients that clicked the short
                  URL
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      description: Country name
                      example: AU
                    count:
                      type: number
                      description: >-
                        Total number of clicks on the short URL where the
                        recipient has the specified country name
                      example: 2
              region:
                type: array
                description: Region statistics of the recipients that clicked the short URL
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      description: Region name
                      example: western_australia
                    count:
                      type: number
                      description: >-
                        Total number of clicks on the short URL where the
                        recipient has the specified region name
                      example: 2
    get-tracking:
      type: object
      properties:
        total:
          type: number
          description: Total number of short URLs associated with the long URL ID
          example: 500
        per_page:
          type: number
          description: The limit of tracking data per page
          maximum: 100
          example: 20
        current_page_size:
          type: number
          description: The number of data in the current page
          maximum: 100
          example: 1
        prev_page_url:
          type: string
          description: >-
            Link to the previous page. This attribute will not be present if
            there is no previous page.
          example: >-
            https://rest.clicksend.com/v3/short-url/tracking/quick_sms-4961a11d-45bb-4d34-9d23-98dc9b277c38-123456-caee6179deb28e135538cb74e2eca2bd?offset=eyJsb25nX3VybF9pZCI6InNtc19jYW1wYWlnbi00OTYxYTExZC00NWJiLTRkMzQtOWQyMy05OGRjOWIyNzdjMzgtMTIzNDU2LWNhZWU2MTc5ZGViMjhlMTM1NTM4Y2I3NGUyZWNhMmJkIiwic2hvcnRfdXJsIjoic21zdS5pby9EdXBOR1YifQ&limit=100&direction=backward
        next_page_url:
          type: string
          description: >-
            Link to the next page. This attribute will not be present if there
            is no next page.
          example: >-
            https://rest.clicksend.com/v3/short-url/tracking/quick_sms-4961a11d-45bb-4d34-9d23-98dc9b277c38-123456-caee6179deb28e135538cb74e2eca2bd?offset=eyJsb25nX3VybF9pZCI6InNtc19jYW1wYWlnbi00OTYxYTExZC00NWJiLTRkMzQtOWQyMy05OGRjOWIyNzdjMzgtMTIzNDU2LWNhZWU2MTc5ZGViMjhlMTM1NTM4Y2I3NGUyZWNhMmJkIiwic2hvcnRfdXJsIjoic21zdS5pby9ROFVOdEcifQ&limit=100&direction=forward
        data:
          type: array
          description: >-
            Tracking data of the short URLs associated with the specified long
            URL ID. Note that only the data from the most recent click of the
            recipient (country, region, device, browser, and os) is recorded.
          items:
            type: object
            properties:
              open_count:
                type: number
                description: Number of times the short URL was opened
                example: 5
              date_opened:
                type: number
                description: >-
                  Date in unix seconds when the short URL was first opened. Null
                  if the short URL was never opened.
                example: 1733981414
              user_geo_country:
                type: string
                description: >-
                  Country where the recipient is located when the short URL was
                  opened. Null if the short URL was never opened.
                example: AU
              user_geo_region:
                type: string
                description: >-
                  Geographical region where the recipient is located when the
                  short URL was opened. Null if the short URL was never opened.
                example: western_australia
              user_device:
                type: string
                description: >-
                  Deviced used by the recipient to open the short URL. Null if
                  the short URL was never opened.
                example: mobile
              user_browser:
                type: string
                description: >-
                  Browser used by the recipient to open the short URL. Null if
                  the short URL was never opened.
                example: chrome
              user_os:
                type: string
                description: >-
                  Opearating system used by the recipient to open the short URL.
                  Null if the short URL was never opened.
                example: android
              contact:
                type: object
                properties:
                  contact_id:
                    type: string
                    description: >-
                      Contact ID of the recipient. Null if the recipient is not
                      a contact.
                    example: '224466'
                  first_name:
                    type: string
                    description: >-
                      First name of the recipient. Null if the recipient has no
                      data for first name.
                    example: John
                  last_name:
                    type: string
                    description: >-
                      Last name of the recipient. Null if the recipient has no
                      data last name.
                    example: Doe
                  phone_number:
                    type: string
                    description: Phone number of the recipient
                    example: '+1234567890'
paths:
  /v3/short-url/statistics/{source}/{source_id}:
    get:
      summary: Get Statistics
      operationId: short-url-get-statistics
      description: >-
        Use this endpoint to get the aggregated statistics for a shortened URL.
        This allows you to track the total number of clicks on the link. You can
        gather details such as the device type and where it was opened from as
        well.
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: source
          in: path
          description: Source of the request.
          schema:
            type: string
            enum:
              - quick_sms
          required: true
        - name: source_id
          in: path
          description: ID of the source (e.g. message ID).
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-statistics'
      x-codeSamples:
        - lang: curl
          source: >-
            curl --include \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
            'https://rest.clicksend.com/v3/short-url/statistics/{source}/{source_id}'
  /v3/short-url/tracking/{long_url_id}:
    get:
      summary: Get Tracking
      operationId: short-url-get-tracking
      description: >-
        Use this endpoint to track how individual recipients interact with the
        link.  It returns data from the most recent click, including statistics
        such as how many times they’ve visited the link and when it was last
        opened. To use this endpoint, reference the _long_url_id_ provided in
        the [GET
        /short-url/statistics](/messaging/url-shortening/other/short-url-get-statistics)
        endpoint.
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: long_url_id
          description: >-
            ID of the long URL (uniquely defined by the source, source ID, and
            long URL). Obtained from the GET statistics endpoint.
          in: path
          schema:
            type: string
          required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-tracking'
      x-codeSamples:
        - lang: curl
          source: |-
            curl --include \
                 --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
            'https://rest.clicksend.com/v3/short-url/tracking/{long_url_id}'
