openapi: 3.0.3
info:
  title: 46elks API
  version: a1
  description: >-
    A faithful, representative OpenAPI description of the 46elks CPaaS REST API.
    46elks exposes a simple HTTP API for SMS, MMS, voice calls, phone number
    provisioning, and media. All requests use HTTP Basic authentication with an
    API username and API password issued in the 46elks dashboard. Request bodies
    are sent as application/x-www-form-urlencoded and responses are JSON.
  contact:
    name: 46elks
    url: https://46elks.com/docs
  license:
    name: Proprietary
    url: https://46elks.com/terms
servers:
- url: https://api.46elks.com/a1
  description: 46elks production API (version a1)
security:
- basicAuth: []
tags:
- name: SMS
  description: Send and receive text messages.
- name: MMS
  description: Send and receive picture messages.
- name: Calls
  description: Make and receive programmable voice calls.
- name: Numbers
  description: Allocate and manage virtual phone numbers.
- name: Media
  description: Access recordings and MMS images.
paths:
  /sms:
    post:
      tags:
      - SMS
      operationId: sendSms
      summary: Send an SMS
      description: >-
        Send a text message to one or more mobile phones. The sender may be an
        alphanumeric sender ID (up to 11 characters) or an E.164 number you own.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SmsRequest'
      responses:
        '200':
          description: SMS accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sms'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      tags:
      - SMS
      operationId: listSms
      summary: List sent and received SMS
      parameters:
      - name: start
        in: query
        schema:
          type: string
          format: date-time
      - name: end
        in: query
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: A paged list of SMS objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsList'
  /sms/{id}:
    get:
      tags:
      - SMS
      operationId: getSms
      summary: Retrieve a single SMS
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A single SMS object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sms'
  /mms:
    post:
      tags:
      - MMS
      operationId: sendMms
      summary: Send an MMS
      description: Send a picture message to a mobile phone.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MmsRequest'
      responses:
        '200':
          description: MMS accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mms'
    get:
      tags:
      - MMS
      operationId: listMms
      summary: List sent and received MMS
      responses:
        '200':
          description: A paged list of MMS objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MmsList'
  /mms/{id}:
    get:
      tags:
      - MMS
      operationId: getMms
      summary: Retrieve a single MMS
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A single MMS object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mms'
  /calls:
    post:
      tags:
      - Calls
      operationId: makeCall
      summary: Make a voice call
      description: >-
        Place an outbound call. voice_start is either a URL that returns the
        first call action or an inline JSON call-action object.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CallRequest'
      responses:
        '200':
          description: Call initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
    get:
      tags:
      - Calls
      operationId: listCalls
      summary: List calls
      responses:
        '200':
          description: A paged list of call objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallList'
  /calls/{id}:
    get:
      tags:
      - Calls
      operationId: getCall
      summary: Retrieve a single call
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A single call object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
  /numbers:
    post:
      tags:
      - Numbers
      operationId: allocateNumber
      summary: Allocate a phone number
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/NumberRequest'
      responses:
        '200':
          description: Number allocated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Number'
    get:
      tags:
      - Numbers
      operationId: listNumbers
      summary: List allocated phone numbers
      responses:
        '200':
          description: A list of number objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberList'
  /numbers/{id}:
    post:
      tags:
      - Numbers
      operationId: updateNumber
      summary: Reconfigure a phone number
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/NumberRequest'
      responses:
        '200':
          description: Number updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Number'
    delete:
      tags:
      - Numbers
      operationId: deallocateNumber
      summary: Deallocate a phone number
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Number released.
  /recordings:
    get:
      tags:
      - Media
      operationId: listRecordings
      summary: List call recordings
      responses:
        '200':
          description: A list of recording objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Recording'
  /images:
    get:
      tags:
      - Media
      operationId: listImages
      summary: List MMS images
      responses:
        '200':
          description: A list of image objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Image'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication using your 46elks API username and API
        password from the dashboard.
  responses:
    Unauthorized:
      description: Missing or invalid API credentials.
  schemas:
    SmsRequest:
      type: object
      required:
      - from
      - to
      - message
      properties:
        from:
          type: string
          description: Alphanumeric sender ID (max 11 chars) or E.164 number.
          example: Elks
        to:
          type: string
          description: Recipient number in E.164 format.
          example: '+46700000000'
        message:
          type: string
          example: Hello from 46elks!
        dryrun:
          type: string
          enum:
          - 'yes'
          description: Validate without sending.
        flashsms:
          type: string
          enum:
          - 'yes'
          description: Send as a flash SMS shown immediately, not stored.
        whendelivered:
          type: string
          format: uri
          description: Webhook URL notified with the delivery status.
        dontlog:
          type: string
          enum:
          - message
          description: Do not store the message text in history.
    Sms:
      type: object
      properties:
        id:
          type: string
          example: s123abc456def
        from:
          type: string
        to:
          type: string
        message:
          type: string
        status:
          type: string
          enum:
          - created
          - sent
          - delivered
          - failed
        direction:
          type: string
          enum:
          - outgoing
          - incoming
        cost:
          type: integer
          description: Cost in 10,000ths of the account currency.
        parts:
          type: integer
        created:
          type: string
          format: date-time
    SmsList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Sms'
    MmsRequest:
      type: object
      required:
      - from
      - to
      properties:
        from:
          type: string
        to:
          type: string
        message:
          type: string
        image:
          type: string
          description: Base64 image data or a hosted image URL.
    Mms:
      type: object
      properties:
        id:
          type: string
        from:
          type: string
        to:
          type: string
        message:
          type: string
        status:
          type: string
        created:
          type: string
          format: date-time
    MmsList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Mms'
    CallRequest:
      type: object
      required:
      - from
      - to
      - voice_start
      properties:
        from:
          type: string
          example: '+46700000000'
        to:
          type: string
          example: '+46766861004'
        voice_start:
          description: >-
            First call action - a URL returning a call action, or an inline
            call-action JSON object (connect, play, ivr, record, hangup).
          oneOf:
          - type: string
            format: uri
          - $ref: '#/components/schemas/CallAction'
        whenhangup:
          type: string
          format: uri
          description: Webhook URL notified when the call ends.
        timeout:
          type: integer
          description: Seconds to wait before abandoning an unanswered call.
    CallAction:
      type: object
      description: >-
        A 46elks call action returned by voice_start or a webhook. Exactly one
        of connect, play, ivr, record, or hangup is typically present.
      properties:
        connect:
          type: string
          description: E.164 number or SIP address (sip:...) to connect the call to.
        play:
          type: string
          format: uri
          description: URL of an audio file to play to the caller.
        ivr:
          type: string
          format: uri
          description: Audio prompt for an interactive voice menu; digits post back.
        next:
          type: string
          format: uri
          description: URL to fetch the next action from.
        record:
          type: string
          description: Enable recording of the caller's response.
        hangup:
          type: string
          description: Terminate the call.
    Call:
      type: object
      properties:
        id:
          type: string
        from:
          type: string
        to:
          type: string
        state:
          type: string
          enum:
          - ongoing
          - success
          - busy
          - failed
        direction:
          type: string
        created:
          type: string
          format: date-time
    CallList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Call'
    NumberRequest:
      type: object
      properties:
        country:
          type: string
          description: ISO country code for the number to allocate (e.g. se, gb, us).
          example: se
        sms_url:
          type: string
          format: uri
          description: Webhook URL for inbound SMS to this number.
        voice_start:
          type: string
          format: uri
          description: Webhook URL for inbound calls to this number.
        active:
          type: string
          enum:
          - 'yes'
          - 'no'
    Number:
      type: object
      properties:
        id:
          type: string
          example: nadaf5cd3c86dd7f0c805823647d15b1e
        number:
          type: string
          example: '+46766861004'
        country:
          type: string
        capabilities:
          type: array
          items:
            type: string
            enum:
            - sms
            - mms
            - voice
        active:
          type: string
        sms_url:
          type: string
        voice_start:
          type: string
        cost:
          type: integer
    NumberList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Number'
    Recording:
      type: object
      properties:
        id:
          type: string
        callid:
          type: string
        created:
          type: string
          format: date-time
        wav:
          type: string
          format: uri
        mp3:
          type: string
          format: uri
    Image:
      type: object
      properties:
        id:
          type: string
        mmsid:
          type: string
        created:
          type: string
          format: date-time
        url:
          type: string
          format: uri