> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hologram.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send TCP/UDP cloud message to a SIM

> Send a cloud message (data) to one or more SIMs using device IDs. Messages can be sent as plain text using the `data` parameter or as base64-encoded content using the `base64data` parameter. Port must be between 1 and 65535. Protocol must be TCP or UDP. Max data size is 10K.



## OpenAPI

````yaml /api/1/openapi.yaml post /devices/messages
openapi: 3.0.0
info:
  title: Hologram REST API v1
  description: >-
    The Hologram HTTP API is a REST-style interface for managing Hologram SIMs,
    accounts, and cloud data. Using this API, you can activate SIMs, get your
    devices' approximate location, send SMS messages to your devices, update
    data usage limits, and much more.


    In Hologram's API, a "device" represents a SIM card. Each item returned by
    `/devices` endpoints represents a single SIM card. You can find more
    information about Hologram terminology in our
    [Glossary](https://docs.hologram.io/guides/get-started/glossary) and the
    Hologram [Connectivity
    overview](https://docs.hologram.io/guides/get-started/sim-connectivity-overview).
    The device ID and SIM ID are effectively the same and represent one SIM, but
    device ID is used in older API endpoints and SIM ID is used in newer API
    endpoints.


    ## Base URL


    ```

    https://dashboard.hologram.io/api/1

    ```


    ## Authentication


    Hologram supports **HTTP Basic authentication** using API keys. Set the
    username to `apikey` and use your API key as the password.


    ### Using cURL


    ```

    curl --verbose GET \

    'https://dashboard.hologram.io/api/1/users/me' \

    -u apikey:YOUR_API_KEY

    ```


    ### Using authorization header


    You can also base64 encode `apikey:YOUR_API_KEY` and include it in the
    Authorization header:


    ```

    curl --verbose GET \

    'https://dashboard.hologram.io/api/1/users/me' \

    --header "Authorization: Basic BASE64_ENCODED_CREDENTIALS"

    ```


    ## API access levels


    - **Read Access**: Available to Editor roles and higher.

    - **Write Access**: Varies by endpoint based on role access, generally
    limited to Admin and Manager roles.


    Users without appropriate permissions will receive 403 errors for restricted
    operations.


    ## Requests


    Request bodies can be provided in either JSON or form-urlencoded formats:


    ### JSON format (recommended)


    ```

    curl --request POST \

    --header "Content-Type: application/json" \

    --header "Authorization: Basic YOUR_ENCODED_CREDENTIALS" \

    --data '{"deviceid": 56668, "body": "Hello SIM!"}' \

    'https://dashboard.hologram.io/api/1/sms/incoming'

    ```


    ### Form-urlencoded format


    ```

    curl --request POST \

    --header "Content-Type: application/x-www-form-urlencoded" \

    --header "Authorization: Basic YOUR_ENCODED_CREDENTIALS" \

    --data 'deviceid=56668&body=Hello%20SIM!' \

    'https://dashboard.hologram.io/api/1/sms/incoming'

    ```


    ## Responses


    **Important:** All Hologram dates and times are stored and displayed in
    **UTC**.


    ### Response format


    All API responses are JSON objects that include the following fields:


    * `success` (boolean) - Indicates whether the request was successful.

    * `data` (object or array) - Contains the requested data or information
    about the operation performed. Only present when `success` is true.

    * `error` (string) - Information about why the request failed. Only present
    when `success` is false.


    ### Limited responses


    Most GET responses will also include the following fields if a limit is
    included as part of the query string:


    * `limit` (number) - The query limit. Some endpoints have this value built
    in and others often have a maximum value.

    * `size` (number) - The number of values returned by the query.

    * `continues` (boolean, optional) - Only returned if there are more values
    than were returned in the response.

    * `links` (object) - Contains information related to the query performed.
      * `path` (string) - The API endpoint path.
      * `base` (string) - API base URL.
      * `next` (string) - URL with query string to get the next results.

    ## Rate limiting


    In order to provide a consistent quality of service to all of our customers,
    we enforce a rate limit on all API requests. If you exceed the rate limit
    you will receive a HTTP 429 response with a JSON response body like this:


    ```

    {
      "success": false,
      "error": "API rate limit exceeded"
    }

    ```


    If you receive this response, you should refrain from making requests for
    5-10 seconds and then retry the request.


    ## Generating an API key


    Find your account API key in your
    [dashboard](https://dashboard.hologram.io/settings/api) under the
    **Settings** section in the main menu, then opening the **API** page.


    Your API can be used to access all organizations you are a member of.


    **Caution:** **Keep your API key secure** and never store it in publicly
    accessible places like GitHub repositories.


    ## Organization IDs


    Your API key gives you access to all organizations you are a member of. If
    no organization is specified in an API request, the request will be
    performed for your personal organization.


    Many endpoints accept an `orgid` parameter to filter for SIMs within a
    specific organization. Learn how to find your organization's ID in [this
    guide](https://docs.hologram.io/dashboard/orgs-and-users/organization-overview).


    ## OpenAPI and Swagger links


    OpenAPI -
    [https://dashboard.hologram.io/api/1/docs/openapi.json](https://dashboard.hologram.io/api/1/docs/openapi.json)


    Swagger -
    [https://dashboard.hologram.io/api/1/docs](https://dashboard.hologram.io/api/1/docs)


    ## Support


    For API support, questions, or additional assistance, please [contact our
    support team](https://docs.hologram.io/guides/get-started/contact-support).
  version: '1'
servers:
  - url: https://dashboard.hologram.io/api/1
    description: Hologram REST API v1
security: []
tags:
  - name: SIMs (Devices)
    description: SIMs (Devices)
  - name: SIM Configuration
    description: SIM Configuration
    x-group: SIM Configuration - Conductor
  - name: Organizations
    description: Organizations
  - name: Personal account
    description: Personal account
  - name: Async Change Requests
    description: Async Change Requests
  - name: Events and Alerts
    description: Events and Alerts
paths:
  /devices/messages:
    post:
      tags:
        - SIMs (Devices)
      summary: Send TCP/UDP cloud message to a SIM
      description: >-
        Send a cloud message (data) to one or more SIMs using device IDs.
        Messages can be sent as plain text using the `data` parameter or as
        base64-encoded content using the `base64data` parameter. Port must be
        between 1 and 65535. Protocol must be TCP or UDP. Max data size is 10K.
      operationId: postDeviceMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - deviceids
                - port
                - protocol
              properties:
                deviceids:
                  description: List of device IDs to send the message to
                  type: array
                  items:
                    type: integer
                port:
                  description: Destination port number (1–65535)
                  type: integer
                  maximum: 65535
                  minimum: 1
                protocol:
                  description: Transport protocol for the message
                  type: string
                  enum:
                    - TCP
                    - UDP
                  example: TCP
                data:
                  description: Data to send (plain text). Max 10K
                  type: string
                base64data:
                  description: Data to send encoded in base64. Max 10K
                  type: string
                encrypted:
                  description: When true (default), encrypt the message payload
                  type: boolean
                  default: true
              type: object
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDeviceMessageResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
        - apiKeyAuth: []
components:
  schemas:
    PostDeviceMessageResponse:
      properties:
        success:
          $ref: '#/components/schemas/SuccessProperty'
        data:
          description: One entry per device the message was queued for
          type: array
          items:
            $ref: '#/components/schemas/PostDeviceMessageResult'
      type: object
    SuccessProperty:
      description: Indicates whether the request was successful.
      type: boolean
      example: true
    PostDeviceMessageResult:
      properties:
        deviceid:
          description: Device ID the message was sent to
          type: integer
        messageid:
          description: UUID assigned to the queued message
          type: string
      type: object
  securitySchemes:
    apiKeyAuth:
      type: http
      description: >-
        HTTP Basic authentication using API keys. Set the username to `apikey`
        and the password to your API key. You can find your API key on the
        Hologram Dashboard under Account Settings.
      scheme: basic

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.