Twilio Sims API

openapi: 3.0.1
info:
  title: Twilio - Accounts A2p Sims API
  description: This is the public Twilio REST API.
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio Support
    url: https://support.twilio.com
    email: support@twilio.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.52.0
servers:
- url: https://accounts.twilio.com
tags:
- name: Sims
paths:
  /v1/Sims/{SimSid}/BillingPeriods:
    servers:
    - url: https://supersim.twilio.com
    description: Billing Period for an IoT Super SIM
    x-twilio:
      defaultOutputProperties:
      - sid
      - sim_sid
      - start_time
      - end_time
      - period_type
      pathType: list
      parent: /Sims/{Sid}
    get:
      description: Retrieve a list of Billing Periods for a Super SIM.
      tags:
      - Sims
      parameters:
      - name: SimSid
        in: path
        description: The SID of the Super SIM to list Billing Periods for.
        schema:
          type: string
        required: true
      - name: PageSize
        in: query
        description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: Page
        in: query
        description: The page index. This value is simply for client state.
        schema:
          type: integer
          minimum: 0
      - name: PageToken
        in: query
        description: The page token. This is provided by the API.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBillingPeriodResponse'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: ListBillingPeriod
      x-maturity:
      - GA
  /v1/Sims:
    servers:
    - url: https://supersim.twilio.com
    description: Individual IoT Super SIMs
    x-twilio:
      defaultOutputProperties:
      - sid
      - unique_name
      - status
      pathType: list
      dependentProperties:
        billing_periods:
          mapping:
            sim_sid: sid
          resource_url: /v1/Sims/{sim_sid}/BillingPeriods
        sim_ip_addresses:
          mapping:
            sim_sid: sid
          resource_url: /v1/Sims/{sim_sid}/IpAddresses
    post:
      description: Register a Super SIM to your Account
      tags:
      - Sims
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/supersim.v1.sim'
          description: Created
      security:
      - accountSid_authToken: []
      operationId: CreateSim
      x-maturity:
      - Beta
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateSimRequest'
    get:
      description: Retrieve a list of Super SIMs from your account.
      tags:
      - Sims
      parameters:
      - name: Status
        in: query
        description: The status of the Sim resources to read. Can be `new`, `ready`, `active`, `inactive`, or `scheduled`.
        schema:
          type: string
          $ref: '#/components/schemas/sim_enum_status'
      - name: Fleet
        in: query
        description: The SID or unique name of the Fleet to which a list of Sims are assigned.
        schema:
          type: string
      - name: Iccid
        in: query
        description: The [ICCID](https://en.wikipedia.org/wiki/Subscriber_identity_module#ICCID) associated with a Super SIM to filter the list by. Passing this parameter will always return a list containing zero or one SIMs.
        schema:
          type: string
        x-twilio:
          pii:
            handling: standard
            deleteSla: 30
      - name: PageSize
        in: query
        description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: Page
        in: query
        description: The page index. This value is simply for client state.
        schema:
          type: integer
          minimum: 0
      - name: PageToken
        in: query
        description: The page token. This is provided by the API.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSimResponse'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: ListSim
      x-maturity:
      - Beta
  /v1/Sims/{Sid}:
    servers:
    - url: https://supersim.twilio.com
    description: Individual IoT Super SIMs
    x-twilio:
      defaultOutputProperties:
      - sid
      - unique_name
      - status
      pathType: instance
      dependentProperties:
        billing_periods:
          mapping:
            sim_sid: sid
          resource_url: /v1/Sims/{sim_sid}/BillingPeriods
        sim_ip_addresses:
          mapping:
            sim_sid: sid
          resource_url: /v1/Sims/{sim_sid}/IpAddresses
    get:
      description: Fetch a Super SIM instance from your account.
      tags:
      - Sims
      parameters:
      - name: Sid
        in: path
        description: The SID of the Sim resource to fetch.
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/supersim.v1.sim'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: FetchSim
      x-maturity:
      - Beta
    post:
      description: Updates the given properties of a Super SIM instance from your account.
      tags:
      - Sims
      parameters:
      - name: Sid
        in: path
        description: The SID of the Sim resource to update.
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/supersim.v1.sim'
          description: OK
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/supersim.v1.sim'
          description: Accepted
      security:
      - accountSid_authToken: []
      operationId: UpdateSim
      x-maturity:
      - Beta
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateSimRequest'
    delete:
      description: Delete a Sim resource on your Account.
      tags:
      - Sims
      parameters:
      - name: Sid
        in: path
        description: The SID or the `unique_name` of the Sim resource to delete.
        schema:
          type: string
        required: true
      responses:
        '204':
          description: The resource was deleted successfully.
      security:
      - accountSid_authToken: []
      operationId: DeleteSim
      x-maturity:
      - GA
  /v1/Sims/{SimSid}/IpAddresses:
    servers:
    - url: https://supersim.twilio.com
    description: IP Addresses for a Super SIM configured to use a VPN connection
    x-twilio:
      defaultOutputProperties:
      - ip_address
      - ip_address_version
      pathType: list
      parent: /Sims/{Sid}
      mountName: sim_ip_addresses
    get:
      description: Retrieve a list of IP Addresses for the given Super SIM.
      tags:
      - Sims
      parameters:
      - name: SimSid
        in: path
        description: The SID of the Super SIM to list IP Addresses for.
        schema:
          type: string
        required: true
      - name: PageSize
        in: query
        description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: Page
        in: query
        description: The page index. This value is simply for client state.
        schema:
          type: integer
          minimum: 0
      - name: PageToken
        in: query
        description: The page token. This is provided by the API.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSimIpAddressResponse'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: ListSimIpAddress
      x-maturity:
      - Beta
  /v1/Sims/{SimSid}/DataSessions:
    servers:
    - url: https://wireless.twilio.com
    description: Data session information for SIMs
    x-twilio:
      defaultOutputProperties:
      - sid
      - packets_uploaded
      - packets_downloaded
      - start
      - end
      pathType: list
      parent: /Sims/{Sid}
    get:
      description: ''
      tags:
      - Sims
      parameters:
      - name: SimSid
        in: path
        description: The SID of the [Sim resource](https://www.twilio.com/docs/iot/wireless/api/sim-resource) with the Data Sessions to read.
        schema:
          type: string
        required: true
      - name: PageSize
        in: query
        description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: Page
        in: query
        description: The page index. This value is simply for client state.
        schema:
          type: integer
          minimum: 0
      - name: PageToken
        in: query
        description: The page token. This is provided by the API.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDataSessionResponse'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: ListDataSession
      x-maturity:
      - GA
  /v1/Sims/{SimSid}/UsageRecords:
    servers:
    - url: https://wireless.twilio.com
    description: Usage information for SIMs
    x-twilio:
      defaultOutputProperties:
      - period
      pathType: list
      parent: /Sims/{Sid}
    get:
      description: ''
      tags:
      - Sims
      parameters:
      - name: SimSid
        in: path
        description: The SID of the [Sim resource](https://www.twilio.com/docs/iot/wireless/api/sim-resource)  to read the usage from.
        schema:
          type: string
        required: true
      - name: End
        in: query
        description: Only include usage that occurred on or before this date, specified in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). The default is the current time.
        schema:
          type: string
          format: date-time
      - name: Start
        in: query
        description: Only include usage that has occurred on or after this date, specified in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). The default is one month before the `end` parameter value.
        schema:
          type: string
          format: date-time
      - name: Granularity
        in: query
        description: 'How to summarize the usage by time. Can be: `daily`, `hourly`, or `all`. The default is `all`. A value of `all` returns one Usage Record that describes the usage for the entire period.'
        schema:
          type: string
          $ref: '#/components/schemas/usage_record_enum_granularity'
      - name: PageSize
        in: query
        description: How many resources to return in each list page. The default is 50, and the maximum is 1000.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: Page
        in: query
        description: The page index. This value is simply for client state.
        schema:
          type: integer
          minimum: 0
      - name: PageToken
        in: query
        description: The page token. This is provided by the API.
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUsageRecordResponse'
          description: OK
      security:
      - accountSid_authToken: []
      operationId: ListUsageRecord
      x-maturity:
      - GA
components:
  schemas:
    sim_ip_address_enum_ip_address_version:
      type: string
      enum:
      - IPv4
      - IPv6
    wireless.v1.sim.data_session:
      type: object
      properties:
        sid:
          type: string
          nullable: true
          description: The unique string that we created to identify the DataSession resource.
        sim_sid:
          type: string
          nullable: true
          description: The SID of the [Sim resource](https://www.twilio.com/docs/iot/wireless/api/sim-resource) that the Data Session is for.
        account_sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          nullable: true
          description: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that created the DataSession resource.
        radio_link:
          type: string
          nullable: true
          description: The generation of wireless technology that the device was using.
        operator_mcc:
          type: string
          nullable: true
          description: 'The ''mobile country code'' is the unique ID of the home country where the Data Session took place. See: [MCC/MNC lookup](http://mcc-mnc.com/).'
        operator_mnc:
          type: string
          nullable: true
          description: The 'mobile network code' is the unique ID specific to the mobile operator network where the Data Session took place.
        operator_country:
          type: string
          nullable: true
          description: The three letter country code representing where the device's Data Session took place. This is determined by looking up the `operator_mcc`.
        operator_name:
          type: string
          nullable: true
          description: The friendly name of the mobile operator network that the [SIM](https://www.twilio.com/docs/iot/wireless/api/sim-resource)-connected device is attached to. This is determined by looking up the `operator_mnc`.
        cell_id:
          type: string
          nullable: true
          description: The unique ID of the cellular tower that the device was attached to at the moment when the Data Session was last updated.
        cell_location_estimate:
          nullable: true
          description: 'An object that describes the estimated location in latitude and longitude where the device''s Data Session took place. The location is derived from the `cell_id` when the Data Session was last updated. See [Cell Location Estimate Object](https://www.twilio.com/docs/iot/wireless/api/datasession-resource#cell-location-estimate-object). '
        packets_uploaded:
          type: integer
          nullable: true
          description: The number of packets uploaded by the device between the `start` time and when the Data Session was last updated.
        packets_downloaded:
          type: integer
          nullable: true
          description: The number of packets downloaded by the device between the `start` time and when the Data Session was last updated.
        last_updated:
          type: string
          format: date-time
          nullable: true
          description: The date that the resource was last updated, given as GMT in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        start:
          type: string
          format: date-time
          nullable: true
          description: The date that the Data Session started, given as GMT in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        end:
          type: string
          format: date-time
          nullable: true
          description: The date that the record ended, given as GMT in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        imei:
          type: string
          nullable: true
          description: 'The ''international mobile equipment identity'' is the unique ID of the device using the SIM to connect. An IMEI is a 15-digit string: 14 digits for the device identifier plus a check digit calculated using the Luhn formula.'
    sim_enum_status:
      type: string
      enum:
      - new
      - ready
      - active
      - inactive
      - scheduled
    sim_enum_status_update:
      type: string
      enum:
      - ready
      - active
      - inactive
    ListUsageRecordResponse:
      type: object
      properties:
        usage_records:
          type: array
          items:
            $ref: '#/components/schemas/wireless.v1.sim.usage_record'
        meta:
          type: object
          properties:
            first_page_url:
              type: string
              format: uri
            next_page_url:
              type: string
              format: uri
              nullable: true
            page:
              type: integer
            page_size:
              type: integer
            previous_page_url:
              type: string
              format: uri
              nullable: true
            url:
              type: string
              format: uri
            key:
              type: string
    billing_period_enum_bp_type:
      type: string
      enum:
      - ready
      - active
    ListDataSessionResponse:
      type: object
      properties:
        data_sessions:
          type: array
          items:
            $ref: '#/components/schemas/wireless.v1.sim.data_session'
        meta:
          type: object
          properties:
            first_page_url:
              type: string
              format: uri
            next_page_url:
              type: string
              format: uri
              nullable: true
            page:
              type: integer
            page_size:
              type: integer
            previous_page_url:
              type: string
              format: uri
              nullable: true
            url:
              type: string
              format: uri
            key:
              type: string
    CreateSimRequest:
      type: object
      required:
      - Iccid
      - RegistrationCode
      properties:
        Iccid:
          type: string
          description: The [ICCID](https://en.wikipedia.org/wiki/Subscriber_identity_module#ICCID) of the Super SIM to be added to your Account.
        RegistrationCode:
          type: string
          description: The 10-digit code required to claim the Super SIM for your Account.
    UpdateSimRequest:
      type: object
      properties:
        UniqueName:
          type: string
          description: An application-defined string that uniquely identifies the resource. It can be used in place of the resource's `sid` in the URL to address the resource.
        Status:
          type: string
          $ref: '#/components/schemas/sim_enum_status_update'
          description: 'The new status of the resource. Can be: `ready`, `active`, or `inactive`. See the [Super SIM Status Values](https://www.twilio.com/docs/iot/supersim/api/sim-resource#status-values) for more info.'
        Fleet:
          type: string
          description: The SID or unique name of the Fleet to which the SIM resource should be assigned.
        CallbackUrl:
          type: string
          format: uri
          description: The URL we should call using the `callback_method` after an asynchronous update has finished.
        CallbackMethod:
          type: string
          format: http-method
          enum:
          - HEAD
          - GET
          - POST
          - PATCH
          - PUT
          - DELETE
          description: 'The HTTP method we should use to call `callback_url`. Can be: `GET` or `POST` and the default is POST.'
        AccountSid:
          type: string
          description: The SID of the Account to which the Sim resource should belong. The Account SID can only be that of the requesting Account or that of a Subaccount of the requesting Account. Only valid when the Sim resource's status is new.
    usage_record_enum_granularity:
      type: string
      enum:
      - hourly
      - daily
      - all
    ListBillingPeriodResponse:
      type: object
      properties:
        billing_periods:
          type: array
          items:
            $ref: '#/components/schemas/supersim.v1.sim.billing_period'
        meta:
          type: object
          properties:
            first_page_url:
              type: string
              format: uri
            next_page_url:
              type: string
              format: uri
              nullable: true
            page:
              type: integer
            page_size:
              type: integer
            previous_page_url:
              type: string
              format: uri
              nullable: true
            url:
              type: string
              format: uri
            key:
              type: string
    supersim.v1.sim.billing_period:
      type: object
      properties:
        sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^HB[0-9a-fA-F]{32}$
          nullable: true
          description: The SID of the Billing Period.
        account_sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          nullable: true
          description: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) the Super SIM belongs to.
        sim_sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^HS[0-9a-fA-F]{32}$
          nullable: true
          description: The SID of the Super SIM the Billing Period belongs to.
        start_time:
          type: string
          format: date-time
          nullable: true
          description: The start time of the Billing Period specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        end_time:
          type: string
          format: date-time
          nullable: true
          description: The end time of the Billing Period specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        period_type:
          type: string
          $ref: '#/components/schemas/billing_period_enum_bp_type'
          nullable: true
          description: The type of Billing Period. Can be `ready` or `active`.
        date_created:
          type: string
          format: date-time
          nullable: true
          description: The date and time in GMT when the resource was created specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        date_updated:
          type: string
          format: date-time
          nullable: true
          description: The date and time in GMT when the resource was last updated specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
    supersim.v1.sim:
      type: object
      properties:
        sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^HS[0-9a-fA-F]{32}$
          nullable: true
          description: The unique string that identifies the Sim resource.
        unique_name:
          type: string
          nullable: true
          description: An application-defined string that uniquely identifies the resource. It can be used in place of the resource's `sid` in the URL to address the resource.
        account_sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          nullable: true
          description: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that the Super SIM belongs to.
        iccid:
          type: string
          nullable: true
          description: The [ICCID](https://en.wikipedia.org/wiki/Subscriber_identity_module#ICCID) associated with the SIM.
          x-twilio:
            pii:
              handling: standard
              deleteSla: 30
        status:
          type: string
          $ref: '#/components/schemas/sim_enum_status'
          nullable: true
          description: The status of the Super SIM. Can be `new`, `ready`, `active`, `inactive`, or `scheduled`. See the [Super SIM Status Values](https://www.twilio.com/docs/iot/supersim/api/sim-resource#status-values) for a description of each.
        fleet_sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^HF[0-9a-fA-F]{32}$
          nullable: true
          description: The unique ID of the Fleet configured for this SIM.
        date_created:
          type: string
          format: date-time
          nullable: true
          description: The date and time in GMT when the resource was created specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        date_updated:
          type: string
          format: date-time
          nullable: true
          description: The date and time in GMT when the resource was last updated specified in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
        url:
          type: string
          format: uri
          nullable: true
          description: The absolute URL of the Sim Resource.
        links:
          type: object
          format: uri-map
          nullable: true
    ListSimIpAddressResponse:
      type: object
      properties:
        ip_addresses:
          type: array
          items:
            $ref: '#/components/schemas/supersim.v1.sim.sim_ip_address'
        meta:
          type: object
          properties:
            first_page_url:
              type: string
              format: uri
            next_page_url:
              type: string
              format: uri
              nullable: true
            page:
              type: integer
            page_size:
              type: integer
            previous_page_url:
              type: string
              format: uri
              nullable: true
            url:
              type: string
              format: uri
            key:
              type: string
    ListSimResponse:
      type: object
      properties:
        sims:
          type: array
          items:
            $ref: '#/components/schemas/supersim.v1.sim'
        meta:
          type: object
          properties:
            first_page_url:
              type: string
              format: uri
            next_page_url:
              type: string
              format: uri
              nullable: true
            page:
              type: integer
            page_size:
              type: integer
            previous_page_url:
              type: string
              format: uri
              nullable: true
            url:
              type: string
              format: uri
            key:
              type: string
    supersim.v1.sim.sim_ip_address:
      type: object
      properties:
        ip_address:
          type: string
          nullable: true
          description: IP address assigned to the given Super SIM
        ip_address_version:
          type: string
          $ref: '#/components/schemas/sim_ip_address_enum_ip_address_version'
          nullable: true
          description: IP address version of the corresponding IP address
    wireless.v1.sim.usage_record:
      type: object
      properties:
        sim_sid:
          type: string
          nullable: true
          description: The SID of the [Sim resource](https://www.twilio.com/docs/iot/wireless/api/sim-resource) that this Usage Record is for.
        account_sid:
          type: string
          minLength: 34
          maxLength: 34
          pattern: ^AC[0-9a-fA-F]{32}$
          nullable: true
          description: The SID of the [Account](https://www.twilio.com/docs/iam/api/account) that created the UsageRecord resource.
        period:
          nullable: true
          description: The time period for which the usage is reported. Contains `start` and `end` datetime values given as GMT in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
        commands:
          nullable: true
          description: An object that describes the SIM's usage of Commands during the specified period. See [Commands Usage Object](https://www.twilio.com/docs/iot/wireless/api/sim-usagerecord-resource#commands-usage-object).
        data:
          nullable: true
          description: An object that describes the SIM's data usage during the specified period. See [Data Usage Object](https://www.twilio.com/docs/iot/wireless/api/sim-usagerecord-resource#data-usage-object).
  securitySchemes:
    accountSid_authToken:
      type: http
      scheme: basic
x-maturity:
- name: GA
  description: This product is Generally Available.
- name: Beta
  description: PLEASE NOTE that this is a Beta product that is subject to change. Use it with caution.