> ## 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. # Search for devices ## OpenAPI ````yaml /api/1/openapi.yaml post /devices/search openapi: 3.0.0 info: title: Hologram REST API v1 description: >- The Hologram HTTP API is a REST-style interface for managing Hologram devices, accounts, and cloud data. Using the Hologram REST API, you can activate SIMs, get your devices approximate location, send SMS to your devices, update a device's usage limit, and much more. ## Authentication Hologram supports **HTTP Basic authentication** using API keys. Simply set the username of the request to `apikey`. The password field is the API key itself. You can find your API key on the Hologram Dashboard under [Account Settings](https://dashboard.hologram.io/settings/api). Your API key gives you access to your personal account, as well as any organizations you are a member of. Make sure you don't store your API key in a publicly accessible place like GitHub. If you are a member of multiple organizations, many endpoints accept an `orgid` argument to filter for devices or other objects within a specific organization. You can find your `orgid` by following [this guide from our Help Center](https://support.hologram.io/hc/en-us/articles/360035421234-What-is-my-organization-ID-orgid). ### Header Example ``` curl --verbose GET \ 'https://dashboard.hologram.io/api/1/users/me' \ -u apikey:YOUR_API_KEY ``` You can also base64 encode "apikey:YOUR_API_KEY" and include it directly in the header. ``` curl --verbose GET \ 'https://dashboard.hologram.io/api/1/users/me' \ --header "Authorization: Basic BASE64(apikey:YOUR_API_KEY)" ``` ## Requests Request bodies can be provided in either JSON or form-urlencoded formats. Please note that the examples in this documentation will only display JSON bodies. ### **JSON body** ``` curl --verbose --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Basic BASE64(apikey:YOUR_API_KEY)" \ --data '{"deviceid": 56668, "body": "Hello device!"}' \ 'https://dashboard.hologram.io/api/1/sms/incoming' ``` ### **form-urlencoded body** ``` curl --verbose --request POST \ --header "Content-Type: application/x-form-urlencoded" \ --header "Authorization: Basic BASE64(apikey:YOUR_API_KEY)" \ --data 'deviceid=56668&body=Hello%20device!' \ 'https://dashboard.hologram.io/api/1/sms/incoming' ``` ## Responses All API responses are returned as JSON objects with the following fields: * `success` (boolean) - Indicates whether the request was successful. * `data` (object or array) - Contains the requested data or information about the operation that was performed. Only present when `success` is true. * `error` (string) - Information about why the request failed. Only present when `success` is false. 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 have this value built in and others often have a maximum value that the limit can be * `size` (number) - The number of values returned by the query * `continues` (boolean, optional) - This is only returned if there are more values than were returned * `links` (array) - 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 Note that all dates and times are returned in UTC. ## Rate Limiting In order to provide a good 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. Hologram's REST API provides methods to perform many requests in bulk. For example, you can change the data plans of multiple SIMs at once using https://dashboard.hologram.io/api/1/links/cellular/changeplan. If there is request you would like to make in bulk but cannot, please reach out to [support@hologram.io](mailto:support@hologram.io) for assistance. version: '1' servers: - url: https://dashboard.hologram.io/api/1 description: Hologram REST API v1 security: [] tags: - name: Devices description: 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 paths: /devices/search: post: tags: - Devices summary: Search for devices operationId: postSearchDevices requestBody: required: false content: application/json: schema: properties: orgid: description: Filter results to this organization ID type: integer limit: description: Maximum number of results to return (max 10000) type: integer maximum: 10000 example: 5000 type: object responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListDevicesResponse' '401': description: Unauthorized security: - apiKeyAuth: [] components: schemas: ListDevicesResponse: properties: success: $ref: '#/components/schemas/SuccessProperty' limit: type: integer size: type: integer continues: type: boolean lastid: description: ID of the last record returned, for cursor-based pagination type: integer links: $ref: '#/components/schemas/PaginationLinks' data: type: array items: $ref: '#/components/schemas/DeviceObject' type: object SuccessProperty: description: Indicates whether the request was successful. type: boolean example: true PaginationLinks: properties: path: description: The API endpoint path type: string base: description: The API base URL type: string next: description: URL to retrieve the next page of results type: string type: object DeviceObject: properties: id: description: Unique device ID type: integer name: description: Device name type: string orgid: description: Organization ID type: integer type: description: Device type type: string whencreated: description: Device creation timestamp (UTC) type: string tags: description: Tags associated with this device type: array items: type: string links: properties: cellular: type: array items: $ref: '#/components/schemas/CellularLinkInDevice' type: object imei: description: IMEI of the device type: string imei_sv: description: IMEI Software Version (IMEISV) of the device type: string tunnelable: description: 1 if the device supports SpaceBridge tunneling type: integer enum: - 0 - 1 hidden: description: 1 if the device is hidden on the Dashboard type: integer enum: - 0 - 1 phonenumber: description: Phone number assigned to the device, empty string if none type: string phonenumber_cost: description: Monthly cost of the assigned phone number type: string simcardid: description: SIM card ID associated with the device type: integer euicc_tested: description: eUICC test status for the device type: string is_hyper: description: >- True if the device uses a Hyper eUICC SIM rather than a standard UICC type: boolean model: description: Device model derived from IMEI TAC lookup, "Unknown" if not found type: string manufacturer: description: >- Device manufacturer derived from IMEI TAC lookup, "Unknown" if not found type: string preflight_starttime: description: >- Timestamp when the preflight period started, null if not in preflight type: string nullable: true preflight_scheduled_endtime: description: >- Timestamp when the preflight period is scheduled to end, null if not in preflight type: string nullable: true async_change_requests: description: Non-terminal async change requests associated with this device type: array items: $ref: '#/components/schemas/AsyncChangeRequestObject' type: object CellularLinkInDevice: description: A cellular link (SIM profile) associated with a device. properties: id: description: Cellular link ID type: integer deviceid: description: Device ID type: integer orgid: description: Organization ID type: integer sim: description: SIM ICCID type: string msisdn: description: Phone number assigned to this SIM type: string imsi: description: International Mobile Subscriber Identity type: integer state: description: Current SIM state (e.g. LIVE, PAUSED, DEACTIVATED) type: string apn: description: Access Point Name type: string zone: description: Coverage zone ID type: integer overagelimit: description: Data overage limit in bytes (-1 for unlimited) type: integer carrier: description: Carrier backend ID type: integer whencreated: description: SIM activation timestamp (UTC) type: string whenexpires: description: SIM expiry timestamp (UTC) type: string async_change_requests: description: >- Non-terminal async change requests associated with this cellular link type: array items: $ref: '#/components/schemas/AsyncChangeRequestObject' type: object AsyncChangeRequestObject: description: A non-terminal async change request record. properties: id: description: Async change request ID type: integer parent_id: description: Parent request ID for child requests type: integer nullable: true orgid: description: Organization ID type: integer nullable: true userid: description: User ID who initiated the request type: integer nullable: true request_type: description: Type of async change request type: string enum: - plan_change - euicc_audit - sim_configuration_update - configure_sim - sim_state_pause - sim_state_unpause - sim_state_activation reference_type: description: Type of the referenced object type: string enum: - device - link - simcard - sim_configuration reference_id: description: ID of the referenced object type: integer state: description: Current state of the request type: string enum: - initialized - in_progress start_time: description: Timestamp when the request was created (UTC) type: string update_time: description: Timestamp of the last state update (UTC) type: string metadata: description: Request-type-specific metadata type: object nullable: true 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 ````