openapi: 3.0.0
servers:
  - url: https://gateway.seven.io/api
info:
  contact:
    email: support@seven.io
    name: Support
    url: https://seven.io/en/company/contact
  description: seven.io Swagger API. Get your API-Key now at seven.io.
  license:
    name: Licensed by Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://seven.io/en/company/terms/
  title: seven.io API
  version: 1.0.0
  x-apisguru-categories:
    - telecom
  x-logo:
    url: https://www.sms77.io/wp-content/uploads/integrationen_sms77_logo.png
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/sms77io/api-schemes/master/json/openapi.json
      version: "3.0"
  x-providerName: sms77.io
externalDocs:
  description: Find out more about the seven.io SMS gateway.
  url: https://seven.io/en/docs/gateway/http-api
security:
  - ApiKeyAuth: []
tags:
  - externalDocs:
      description: Retrieve analytics
      url: https://www.seven.io/en/docs/gateway/http-api/analytics
    name: analytics
  - externalDocs:
      description: Send one/multiple SMS
      url: https://seven.io/en/docs/gateway/http-api/sms-disptach
    name: sms
  - externalDocs:
      description: Retrieve account balance
      url: https://seven.io/en/docs/gateway/http-api/credit-balance
    name: balance
  - externalDocs:
      description: Retrieve/edit/delete contact(s)
      url: https://seven.io/en/docs/gateway/http-api/contacts
    name: contacts
  - externalDocs:
      description: Retrieve pricing information
      url: https://seven.io/en/docs/gateway/http-api/pricing
    name: pricing
  - externalDocs:
      description: Retrieve the status for a sent SMS with the given ID
      url: https://seven.io/en/docs/gateway/http-api/status-reports
    name: status
  - externalDocs:
      description: Validate caller ID for voice Voice API
      url: https://seven.io/en/docs/gateway/http-api/caller-ids
    name: validate_for_voice
  - externalDocs:
      description: Issue voice call to phone number
      url: https://seven.io/en/docs/gateway/http-api/voice
    name: voice
  - externalDocs:
      description: Get number format, CNAM,- HLR- or MNP information for given phone number
      url: https://seven.io/en/docs/gateway/http-api
    name: lookup
  - externalDocs:
      description: Create, view and delete webhooks
      url: https://www.seven.io/en/docs/gateway/http-api/webhooks/
    name: hooks
paths:
  /analytics:
    get:
      operationId: Analytics
      parameters:
        - description: Start date of the statistics in the format YYYY-MM-DD. By default, the date of 30 days ago is set.
          in: query
          name: start
          schema:
            type: string
        - description: End date of the statistics in the format YYYY-MM-DD. By default, the current day.
          in: query
          name: end
          schema:
            type: string
        - description: Shows only data of a specific label.
          in: query
          name: label
          schema:
            type: string
        - description: Receive the data only for the main account, all your (sub-)accounts or only for specific subaccounts.
          in: query
          name: subaccounts
          schema:
            type: string
        - description: Defines the grouping of the data.
          in: query
          name: group_by
          schema:
            enum:
              - date
              - label
              - subaccount
              - country
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  date:
                    type: string
                  direct:
                    type: integer
                  economy:
                    type: integer
                  hlr:
                    type: integer
                  inbound:
                    type: integer
                  mnp:
                    type: integer
                  usage_eur:
                    format: float
                    type: number
                  voice:
                    type: integer
                type: object
          description: OK
      tags:
        - analytics
  /balance:
    get:
      operationId: Balance
      responses:
        "200":
          content:
            text/plain:
              schema:
                example: 12.34
                format: float
                type: number
          description: OK
      tags:
        - balance
  /contacts:
    get:
      operationId: ContactsGet
      parameters:
        - description: Determines the action to execute.
          in: query
          name: action
          required: true
          schema:
            enum:
              - read
            type: string
        - description: Defines whether to return the response as JSON or CSV separated by semicolon.
          in: query
          name: json
          schema:
            default: 0
            enum:
              - 0
              - 1
            type: number
      responses:
        "200":
          content:
            application/json:
              schema:
                example: '"1";"Tommy Tester";"0049179876543210"'
                type: string
            text/csv:
              schema:
                example: '"1";"Tommy Tester";"0049179876543210"'
                type: string
          description: OK (CSV)
      tags:
        - contacts
    post:
      operationId: ContactsPOST
      parameters:
        - description: Determines the action to execute.
          in: query
          name: action
          required: true
          schema:
            enum:
              - del
              - write
            type: string
        - description: Defines whether to return the response as JSON or CSV separated by semicolon.
          in: query
          name: json
          schema:
            default: 0
            enum:
              - 0
              - 1
            type: number
        - description: The contact ID for editing/deletion.
          in: query
          name: id
          schema:
            type: string
        - description: The contacts name.
          in: query
          name: nick
          schema:
            type: string
        - description: The contacts phone number.
          in: query
          name: empfaenger
          schema:
            type: string
        - description: The contacts email address.
          in: query
          name: email
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                example: 152
                type: string
            text/plain:
              schema:
                example: 152
                type: string
          description: OK
      tags:
        - contacts
  /hooks:
    get:
      operationId: HooksGet
      parameters:
        - description: Determines the action to execute.
          in: query
          name: action
          required: true
          schema:
            enum:
              - read
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  hooks:
                    items:
                      properties:
                        created:
                          type: string
                        event_type:
                          type: string
                        id:
                          type: string
                        request_method:
                          type: string
                        target_url:
                          type: string
                      type: object
                    type: array
                  success:
                    type: boolean
                type: object
          description: OK
      tags:
        - hooks
    post:
      operationId: HooksPOST
      parameters:
        - description: Determines the action to execute.
          in: query
          name: action
          required: true
          schema:
            enum:
              - subscribe
              - unsubscribe
            type: string
        - description: The Webhook ID you wish to unsubscribe.
          in: query
          name: id
          schema:
            type: integer
        - description: Target URL of your Webhook.
          in: query
          name: target_url
          schema:
            type: string
        - description: Type of event for which you would like to receive a webhook.
          in: query
          name: event_type
          schema:
            enum:
              - all
              - sms_mo
              - dlr
              - voice_status
            type: string
        - description: Request method in which you want to receive the webhook.
          in: query
          name: request_method
          schema:
            default: POST
            enum:
              - POST
              - JSON
              - GET
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                  success:
                    type: boolean
                type: object
          description: Hook subscribed
      tags:
        - hooks
  /lookup:
    post:
      operationId: Lookup
      parameters:
        - description: Allowed values are "cnam", "format", "hlr" and "mnp".
          in: query
          name: type
          required: true
          schema:
            type: string
        - description: The phone number to look up.
          explode: false
          in: query
          name: number
          required: true
          schema:
            items:
              type: string
            type: array
          style: form
        - description: Determines whether the response shall be returned in JSON format. Does not work with type "format".
          in: query
          name: json
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    schema:
                      properties:
                        carrier:
                          description: The (former) mobile carrier the number got issued to on initial number release.
                          type: string
                        code:
                          enum:
                            - 100
                            - 202
                            - 500
                            - 600
                          type: number
                        country_code:
                          description: The area code of the number belonging country. This value is numeric.
                          type: string
                        country_code_iso3:
                          type: string
                        country_iso:
                          description: The two digit ISO 3166-1 alpha-2 country code.
                          type: string
                        country_name:
                          description: The full english name if the number belonging country.
                          type: string
                        country_prefix:
                          type: string
                        current_carrier:
                          schema:
                            $ref: "#/components/schemas/Carrier"
                        international:
                          description: The number formatted accordingly to the E.164 standard.
                          type: string
                        international_format_number:
                          type: string
                        international_formatted:
                          description: The number formatted accordingly to the E.164 standard in a human readable format.
                          type: string
                        lookup_outcome:
                          type: string
                        lookup_outcome_message:
                          type: string
                        name:
                          description: The carrier name
                          type: string
                        national:
                          description: The number in a domestic number format.
                          type: string
                        national_format_number:
                          type: string
                        number:
                          description: The number formatted accordingly to the E.164 standard in a human readable format.
                          type: string
                        original_carrier:
                          schema:
                            $ref: "#/components/schemas/Carrier"
                        ported:
                          enum:
                            - unknown
                            - ported
                            - not_ported
                            - assumed_not_ported
                            - assumed_ported
                          type: string
                        reachable:
                          enum:
                            - unknown
                            - reachable
                            - undeliverable
                            - absent
                            - bad_number
                            - blacklisted
                          type: string
                        roaming:
                          schema:
                            $ref: "#/components/schemas/Roaming"
                        status:
                          type: string
                        success:
                          description: Determines if the request was successful.,
                          type: boolean
                        valid_number:
                          type: string
                      type: object
          description: OK
      tags:
        - lookup
  /lookup/cnam:
    post:
      operationId: LookupCnam
      parameters:
        - description: The phone number to look up.
          explode: false
          in: query
          name: number
          required: true
          schema:
            items:
              type: string
            type: array
          style: form
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    schema:
                      properties:
                        code:
                          description: The API status code
                          enum:
                            - 100
                          type: number
                        name:
                          description: The country for given phone number
                          type: string
                        number:
                          description: The phone number that was looked up
                          type: string
                        success:
                          description: Whether the request was successful or not
                          enum:
                            - true
                            - false
                          type: string
                      type: object
          description: OK
      tags:
        - lookup
  /lookup/format:
    post:
      operationId: LookupFormat
      parameters:
        - description: The phone number to look up.
          explode: false
          in: query
          name: number
          required: true
          schema:
            items:
              type: string
            type: array
          style: form
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    schema:
                      properties:
                        carrier:
                          description: Network operator to whom the call number was originally assigned.
                          type: string
                        country_code:
                          description: Country code of the queried number – international without leading “00”.
                          type: string
                        country_iso:
                          description: Country code of the phone number in the format ISO 3166-1 alpha-2 (two letters).
                          type: string
                        country_name:
                          description: The full name of the country of the queried phone number in English.
                          type: string
                        international:
                          description: International E.164 format of the queried phone number.
                          type: string
                        international_formatted:
                          description: The international number.
                          type: string
                        national:
                          description: National format of the queried phone number.
                          type: string
                        network_type:
                          description: The type of network for the requested number.
                          type: string
                        success:
                          description: Whether the request was successful or not.
                          type: boolean
                      type: object
          description: OK
      tags:
        - lookup
  /lookup/hlr:
    post:
      operationId: LookupHlr
      parameters:
        - description: The phone number to look up.
          explode: false
          in: query
          name: number
          required: true
          schema:
            items:
              type: string
            type: array
          style: form
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    schema:
                      properties:
                        country_code:
                          description: The area code of the number belonging country. This value is numeric.
                          type: string
                        country_code_iso3:
                          type: string
                        country_name:
                          description: The full english name if the number belonging country.
                          type: string
                        country_prefix:
                          type: string
                        current_carrier:
                          schema:
                            $ref: "#/components/schemas/Carrier"
                        gsm_code:
                          type: string
                        gsm_message:
                          type: string
                        international_format_number:
                          type: string
                        international_formatted:
                          description: The number formatted accordingly to the E.164 standard in a human readable format.
                          type: string
                        lookup_outcome:
                          type: string
                        lookup_outcome_message:
                          type: string
                        national_format_number:
                          type: string
                        original_carrier:
                          schema:
                            $ref: "#/components/schemas/Carrier"
                        ported:
                          enum:
                            - unknown
                            - ported
                            - not_ported
                            - assumed_not_ported
                            - assumed_ported
                          type: string
                        reachable:
                          enum:
                            - unknown
                            - reachable
                            - undeliverable
                            - absent
                            - bad_number
                            - blacklisted
                          type: string
                        roaming:
                          schema:
                            $ref: "#/components/schemas/Roaming"
                        status:
                          type: boolean
                        status_message:
                          type: string
                        valid_number:
                          type: string
                      type: object
          description: OK
      tags:
        - lookup
  /lookup/mnp:
    post:
      operationId: LookupMnp
      parameters:
        - description: The phone number to look up.
          explode: false
          in: query
          name: number
          required: true
          schema:
            items:
              type: string
            type: array
          style: form
        - description: Determines whether the response shall be returned in JSON format.
          in: query
          name: json
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    schema:
                      properties:
                        code:
                          enum:
                            - 100
                            - 202
                            - 500
                            - 600
                          type: number
                        mnp:
                          schema:
                            $ref: "#/components/schemas/Mnp"
                        price:
                          type: float
                        success:
                          description: Determines if the request was successful.,
                          type: boolean
                      type: object
          description: OK
      tags:
        - lookup
  /pricing:
    get:
      operationId: Pricing
      parameters:
        - description: The countries ISO code to get pricings for. Allowed values are de, fr, at. Omit to show pricings for all channels.
          in: query
          name: country
          schema:
            type: string
        - description: Determines the response format. Allowed values are json and csv. The default value is json.
          in: query
          name: format
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                response:
                  value:
                    schema:
                      properties:
                        countCountries:
                          description: The number if countries in total.
                          type: integer
                        countNetworks:
                          description: The number of total networks.
                          type: integer
                        countries:
                          items:
                            properties:
                              countryCode:
                                description: The countries ISO code.
                                type: string
                              countryName:
                                description: The countries full name.
                                type: string
                              countryPrefix:
                                description: The countries number prefix.
                                type: string
                              networks:
                                items:
                                  properties:
                                    comment:
                                      description: Any information which might be of interest.
                                      type: string
                                    features:
                                      description: The features supported by this network.
                                      items:
                                        type: string
                                      type: array
                                    mcc:
                                      description: The mobile country code.
                                      type: string
                                    mncs:
                                      description: The mobile network code(s).
                                      items:
                                        type: string
                                      type: array
                                    networkName:
                                      description: The full name of the carrier.
                                      type: string
                                    price:
                                      format: float
                                      type: number
                                  type: object
                                type: array
                            type: object
                          type: array
                      type: object
            text/csv:
              examples:
                response:
                  value: |
                    countryCode,countryName,countryPrefix,mcc,mncs,networkName,price,features,comment "DE";"Germany";"49";"262";"15";" (Airdata)";"0.075";"";""
          description: OK
      tags:
        - pricing
  /sms:
    post:
      operationId: Sms
      parameters:
        - description: The actual text message to send.
          in: query
          name: text
          required: true
          schema:
            type: string
        - description: The recipient number or group name.
          in: query
          name: to
          required: true
          schema:
            type: string
        - description: Set a custom sender name.
          in: query
          name: from
          schema:
            type: string
        - description: Identifier to return in callbacks.
          in: query
          name: foreign_id
          schema:
            pattern: ^[A-Z|a-z|0-9|.|\-|_|@]+
            type: string
        - description: A custom label.
          in: query
          name: label
          schema:
            pattern: ^[A-Z|a-z|0-9|.|\-|_|@]+
            type: string
        - description: A custom User Data Header.
          in: query
          name: udh
          schema:
            type: string
        - description: Date/Time for delayed dispatch.
          in: query
          name: delay
          schema:
            type: string
        - description: Disable message sending.
          in: query
          name: debug
          schema:
            default: 0
            enum:
              - 1
              - 0
            type: number
        - description: Enable sending of duplicated messages within 180 seconds.
          in: query
          name: no_reload
          schema:
            default: 0
            enum:
              - 1
              - 0
            type: number
        - description: Force unicode encoding. Reduces sms length to 70 chars.
          in: query
          name: unicode
          schema:
            default: 0
            enum:
              - 1
              - 0
            type: number
        - description: Send as flash.
          in: query
          name: flash
          schema:
            default: 0
            enum:
              - 1
              - 0
            type: number
        - description: Force UTF8 encoding.
          in: query
          name: utf8
          schema:
            default: 0
            enum:
              - 1
              - 0
            type: number
        - description: Attach message details to response.
          in: query
          name: details
          schema:
            default: 0
            enum:
              - 1
              - 0
            type: number
        - description: Attach message ID to second row in a text response.
          in: query
          name: return_msg_id
          schema:
            default: 0
            enum:
              - 1
              - 0
            type: number
        - description: Return a detailed JSON response.
          in: query
          name: json
          schema:
            default: 0
            enum:
              - 1
              - 0
            type: number
        - description: Enable performance tracking for found URLs.
          in: query
          name: performance_tracking
          schema:
            default: 0
            enum:
              - 1
              - 0
            type: number
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  balance:
                    format: float
                    type: number
                  debug:
                    type: string
                  messages:
                    items:
                      properties:
                        encoding:
                          type: string
                        error:
                          type: string
                        error_text:
                          type: string
                        id:
                          type: string
                        messages:
                          items:
                            type: string
                          type: array
                        parts:
                          type: integer
                        price:
                          type: integer
                        recipient:
                          type: string
                        sender:
                          type: string
                        success:
                          type: boolean
                        text:
                          type: string
                      type: object
                    type: array
                  sms_type:
                    enum:
                      - economy
                      - direct
                    type: string
                  success:
                    type: string
                  total_price:
                    format: float
                    type: number
                type: object
            text/plain:
              schema:
                properties:
                  balance:
                    format: float
                    type: number
                  debug:
                    type: string
                  messages:
                    items:
                      properties:
                        encoding:
                          type: string
                        error:
                          type: string
                        error_text:
                          type: string
                        id:
                          type: string
                        messages:
                          items:
                            type: string
                          type: array
                        parts:
                          type: integer
                        price:
                          type: integer
                        recipient:
                          type: string
                        sender:
                          type: string
                        success:
                          type: boolean
                        text:
                          type: string
                      type: object
                    type: array
                  sms_type:
                    enum:
                      - economy
                      - direct
                    type: string
                  success:
                    type: string
                  total_price:
                    format: float
                    type: number
                type: object
          description: OK
      tags:
        - sms
  /status:
    get:
      operationId: Status
      parameters:
        - description: The ID from the SMS.
          in: query
          name: msg_id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            text/plain:
              schema:
                example: |
                  DELIVERED
                  2020-01-09 15:41:30.656
                type: string
          description: OK
      tags:
        - status
  /validate_for_voice:
    post:
      operationId: ValidateForVoice
      parameters:
        - description: Determines the recipient. Can only be a number, not a contact from your address book.
          in: query
          name: number
          required: true
          schema:
            type: string
        - description: The callback URL which gets queried right after validation.
          in: query
          name: callback
          schema:
            format: uri
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  success:
                    type: boolean
                type: object
          description: OK
      tags:
        - validate_for_voice
  /voice:
    post:
      operationId: Voice
      parameters:
        - description: Determines the receiver. Must be a valid phone number or contact from the address book.
          in: query
          name: to
          required: true
          schema:
            type: string
        - description: The text to convert to a voice message. Accepts valid XML too.
          in: query
          name: text
          required: true
          schema:
            maxLength: 10000
            type: string
        - description: Decides whether the parameter "text" is plain text or XML. The default value is 0.
          in: query
          name: xml
          schema:
            enum:
              - 1
              - 0
            type: number
        - description: Sets the sender. Must be a verified sender. Use an inbound number of yours or one of ours.
          in: query
          name: from
          schema:
            type: string
      responses:
        "200":
          content:
            text/plain:
              schema:
                example: |
                  100
                  123456789
                  0
                type: string
          description: OK
      tags:
        - voice
components:
  schemas:
    Carrier:
      properties:
        country:
          type: string
        name:
          type: string
        network_code:
          type: string
        network_type:
          enum:
            - fixed_line
            - fixed_line_or_mobile
            - mobile
            - pager
            - personal_number
            - premium_rate
            - shared_cost
            - toll_free
            - uan
            - unknown
            - voicemail
            - voip
          type: string
      type: object
    Mnp:
      properties:
        country:
          type: string
        international_formatted:
          type: string
        isPorted:
          type: boolean
        mccmnc:
          type: string
        national_format:
          type: string
        network:
          type: string
        number:
          type: string
      type: object
    Roaming:
      properties:
        roaming_country_code:
          type: string
        roaming_network_code:
          type: string
        roaming_network_name:
          type: string
        status:
          enum:
            - unknown
            - roaming
            - not_roaming
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
