Esper esper_cloud_api_Directory Record API

openapi: 3.2.0
info:
  title: ESPER API REFERENCE esper_cloud_api_Directory Record API
  x-logo:
    url: esper-logo-white.svg
    backgroundColor: '#141418'
    altText: Logo
  description: '# Introduction

    Welcome to Esper’s API documentation. The Esper API allows users to accomplish operations outside of the console. Some common uses for our APIs include observing device information and console activity, installing and updating apps, uploading files, and sending files to devices. Our users have also used the API to automate app updates, perform bulk actions, and more. Esper API endpoints use REST-based architecture and return JSON responses. See our documentation for:


    * Getting started guides

    * Commonly used API examples

    * API command examples

    * Automated Script examples

    * And more


    # Authentication


    You need to create an API Key to interact with our APIs. Learn more about generating an API Key. You can also learn more about Esper and sign up for an account at esper.io/signup. Some endpoints also require an Enterprise ID. This ID can be found in the API Management section of the Esper console. # Lifecycle Labels


    Esper uses lifecycle labels to communicate the support status of each API endpoint. Use the following table to understand what each label means and how to respond. Badge

    What it means

    Recommended action


    Stable

    This endpoint is fully supported and safe for production use. No action needed. Beta

    This endpoint is publicly available but may change. It is not recommended for production integrations. Use with caution. Monitor the API changelog for updates before relying on this endpoint. Legacy

    This endpoint uses an older architecture and is still supported, but a newer equivalent exists. It is not recommended for new integrations. Plan migration to the recommended replacement when possible. See the endpoint description for the alternative. Deprecated

    This endpoint has stopped being supported. A removal date may be added at a later time. A replacement is available or the feature is entirely retired. Migrate before the removal date listed in the endpoint description. Do not use this endpoint in new integrations. # Pagination


    Responses may be paginated. Use the following parameters to query the data. A full list of parameters can be found on the endpoint’s documentation page. Parameter

    Data Type

    Explanation


    limit

    integer

    Limit the data returned. Default = 20. offset

    integer

    Offset to the first item returned. Default = 0. ordering

    string

    Order the results set by the field name. Varies by endpoint. next

    string

    Paginate to the next response set. previous

    string

    Paginate to the last set response. # Errors

    We use standard HTTP status codes for success or failure. A typical error response may look something like this:


    ```json

    {

    "errors": [],

    "message": "error message",

    "status": 400

    }

    ```

    * `errors` - List of error details

    * `message` - Error description

    * `status` - HTTP status code


    Some common status codes and messages are:


    Number

    Message

    Explanation


    200

    OK

    The request succeeded. 201

    Resource creation

    A resource was created. 401

    Unauthorized

    The API key is invalid. 404

    Not found

    The resource was not found. 429

    Rate limit exceeded

    Too many requests. Wait a moment and try again. 500

    Server error

    Internal error. Wait a moment and try again. If the issue persists, contact Esper. See how our systems are doing by checking our status page. # Rate Limits

    To ensure quality of service for all customers, we enforce rate limits for API requests. Most customers won’t hit this limit with normal use. In case you experience 429 or rate limit exceeded errors, we recommend the following:

    * Try sending requests in batches. * Begin with about 20 requests at a time and building up from there. * Ensure your scripts are efficient and don’t contain redundant calls. * Reach out to your account manager to discuss your options.'
  termsOfService: https://esper.io/terms-of-service
  contact:
    email: developer@esper.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
  x-prefix-tag: esper cloud api
servers:
- url: https://{foo}-api.esper.cloud/api
  variables:
    foo:
      default: develop
      description: Custom end point
tags:
- name: esper_cloud_api_Directory Record
  description: APIs for Directory Record management. These APIs are only available to the customers using the new Onboarding experience.
  x-displayName: Directory Record
paths:
  /v1/enterprise/{enterprise_id}/directory_record/:
    get:
      x-badges:
      - name: Deprecated
        color: red
      tags:
      - esper_cloud_api_Directory Record
      summary: Get all Directory Records
      description: '⚠️ **Deprecation Notice:** The following endpoint is deprecated.


        Lists all Directory Record instances for an enterprise.


        Returns a paginated list (count/next/previous/results) of Directory Records, which are used for device registration and approval workflows before a device is fully onboarded.


        **About Directory Records**


        A Directory Record represents a device that has been identified for onboarding via a unique identifier (IMEI, serial number, MEI, or MAC address) before or during enrollment, tracking its approval status as it moves toward being provisioned. Each record can be linked to a device group and carries its own online status, alias, and tags.'
      operationId: getDirectoryRecords
      security:
      - esper_cloud_api_apiKey: []
      parameters:
      - $ref: '#/components/parameters/esper_cloud_api_EnterpriseID'
      responses:
        '200':
          description: Directory records
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  previous:
                    type: string
                  next:
                    type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/esper_cloud_api_DirectoryRecord'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
    post:
      x-badges:
      - name: Deprecated
        color: red
      tags:
      - esper_cloud_api_Directory Record
      summary: Create a new Directory Record
      description: '⚠️ **Deprecation Notice:** The following endpoint is deprecated.


        Creates a new Directory Record for an enterprise.


        Registers a device ahead of enrollment by submitting its unique identifiers, and returns the created Directory Record instance including its assigned approval status.


        **About Directory Records**


        A Directory Record represents a device identified for onboarding, typically before it has completed enrollment, and is used to drive device registration/approval workflows. Creating one associates one or more unique identifiers with an optional device group, alias, and tags.'
      operationId: createDirectoryRecord
      security:
      - esper_cloud_api_apiKey: []
      parameters:
      - $ref: '#/components/parameters/esper_cloud_api_EnterpriseID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/esper_cloud_api_DirectoryRecordCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_DirectoryRecord'
        '400':
          description: Directory record create error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
        '401':
          description: Directory record create error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
  /v1/enterprise/{enterprise_id}/directory_record/{directory_record_id}/:
    get:
      x-badges:
      - name: Deprecated
        color: red
      tags:
      - esper_cloud_api_Directory Record
      summary: Get details about a Directory Record
      description: '⚠️ **Deprecation Notice:** The following endpoint is deprecated.


        Retrieves the details of a single Directory Record.


        Returns the full Directory Record instance for the given ID, including its approval status, unique identifiers, and linked device (if any).


        **About Directory Records**


        A Directory Record represents a device tracked through the registration/approval workflow ahead of or during enrollment. Once approved and enrolled, the record''s device_id field links it to the corresponding device.'
      operationId: getDirectoryRecord
      security:
      - esper_cloud_api_apiKey: []
      parameters:
      - $ref: '#/components/parameters/esper_cloud_api_EnterpriseID'
      - $ref: '#/components/parameters/esper_cloud_api_DirectoryRecordID'
      responses:
        '200':
          description: Directory record information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_DirectoryRecord'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
    put:
      x-badges:
      - name: Deprecated
        color: red
      tags:
      - esper_cloud_api_Directory Record
      summary: Update a Directory Record
      description: '⚠️ **Deprecation Notice:** The following endpoint is deprecated.


        Updates an existing Directory Record.


        Replaces the editable fields (unique identifiers, group assignment, alias, tags) on a Directory Record and returns the updated instance.


        **About Directory Records**


        A Directory Record tracks a device through the registration/approval workflow. Updating one is typically used to change its unique identifiers, reassign it to a different device group, or update its alias/tags — it does not directly change approval_status, which is system-managed.'
      operationId: updateDirectoryRecord
      security:
      - esper_cloud_api_apiKey: []
      parameters:
      - $ref: '#/components/parameters/esper_cloud_api_EnterpriseID'
      - $ref: '#/components/parameters/esper_cloud_api_DirectoryRecordID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/esper_cloud_api_DirectoryRecordUpdate'
      responses:
        '200':
          description: Updated Directory Record Information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_DirectoryRecord'
        '400':
          description: Directory record update error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
        '401':
          description: Directory record update error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
    delete:
      x-badges:
      - name: Deprecated
        color: red
      tags:
      - esper_cloud_api_Directory Record
      summary: Delete a Directory Record
      description: '⚠️ **Deprecation Notice:** The following endpoint is deprecated.


        Deletes a specific Directory Record.


        Permanently removes the identified Directory Record from the enterprise; returns a 204 with no content on success.


        **About Directory Records**


        A Directory Record tracks a device through the registration/approval process ahead of or during enrollment. Deleting one removes that pending or historical registration entry — it does not, by itself, delete an already-enrolled device.'
      operationId: deleteDirectoryRecord
      security:
      - esper_cloud_api_apiKey: []
      parameters:
      - $ref: '#/components/parameters/esper_cloud_api_EnterpriseID'
      - $ref: '#/components/parameters/esper_cloud_api_DirectoryRecordID'
      responses:
        '204':
          description: Deleted Directory Record
        '401':
          description: Directory record delete error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
components:
  schemas:
    esper_cloud_api_DirectoryRecord:
      title: DirectoryRecord
      type: object
      properties:
        id:
          title: Directory Record ID
          type: string
        name:
          title: Device name
          type: string
        online_status:
          type: string
          enum:
          - ONLINE
          - OFFLINE
          - NONE
        alias:
          title: Alias name
          type: string
        tags:
          title: Tags
          type: array
          items:
            type: string
        group_id:
          title: Group ID
          type: string
          format: uuid
        device_id:
          title: Device ID
          type: string
          format: uuid
        approval_status:
          title: Approval Status
          type: string
          enum:
          - WAITING_FOR_APPROVAL
          - APPROVED
          - REJECTED
          - BLOCKED
        provisioned_on:
          title: Provisioned on
          type: string
          format: date-time
          readOnly: true
        unique_identifiers:
          title: Unique Identifiers
          type: array
          items:
            type: object
            allOf:
            - $ref: '#/components/schemas/esper_cloud_api_UniqueIdentifier'
    esper_cloud_api_ErrorResponse:
      type: object
      properties:
        errors:
          title: Messages describing the error
          type: array
          items:
            type: string
        message:
          title: Message describing the error
          type: string
        status:
          title: alias name
          type: integer
    esper_cloud_api_DirectoryRecordCreate:
      title: DirectoryRecordCreate
      type: object
      properties:
        unique_identifiers:
          title: Unique Identifiers
          type: array
          items:
            type: object
            allOf:
            - $ref: '#/components/schemas/esper_cloud_api_UniqueIdentifierCreate'
        group_id:
          title: Group ID
          type: string
          format: uuid
        alias:
          title: Alias name
          type: string
        tags:
          title: Tags
          type: array
          items:
            type: string
    esper_cloud_api_UniqueIdentifierCreate:
      title: UniqueIdentifierCreate
      type: object
      properties:
        unique_id:
          title: Unique identifier
          type: string
        type:
          title: Unique identifier type
          type: integer
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
          description: 'Following are the valid Unique Identifier Types:


            ```

            IMEI1 = 0

            IMEI2 = 1

            SERIAL = 2

            MEI = 3

            WIFI_MAC_ID = 4

            ETHERNET_MAC_ID = 5

            ```

            '
    esper_cloud_api_UniqueIdentifier:
      title: UniqueIdentifier
      type: object
      properties:
        unique_id:
          title: Unique identifier
          type: string
        type:
          title: Unique identifier type
          type: string
          enum:
          - IMEI1
          - IMEI2
          - SERIAL
          - MEI
          - WIFI_MAC_ID
          - ETHERNET_MAC_ID
    esper_cloud_api_DirectoryRecordUpdate:
      title: DirectoryRecordUpdate
      type: object
      properties:
        unique_identifiers:
          title: Unique Identifiers
          type: array
          items:
            type: object
            allOf:
            - $ref: '#/components/schemas/esper_cloud_api_UniqueIdentifierCreate'
        group_id:
          title: Group ID
          type: string
          format: uuid
        alias:
          title: Alias name
          type: string
        tags:
          title: Tags
          type: array
          items:
            type: string
  parameters:
    esper_cloud_api_EnterpriseID:
      name: enterprise_id
      description: Enterprise ID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    esper_cloud_api_DirectoryRecordID:
      name: directory_record_id
      description: Directory record ID
      in: path
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    esper_cloud_api_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    pipelines_SCAPIAuthToken:
      type: http
      scheme: bearer
    device_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    apps_management_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    commands_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    drift_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    device_onboarding_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    tenant_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    foundation_AuthToken:
      type: apiKey
      in: header
      name: Authorization
    reports_bearerAuth:
      type: http
      scheme: bearer
    geofence_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-tagGroups:
- name: ESPER CLOUD API
  tags:
  - esper_cloud_api_Company Settings
  - esper_cloud_api_Application
  - esper_cloud_api_Application V1
  - esper_cloud_api_AndroidDevice
  - esper_cloud_api_Device Group
  - esper_cloud_api_Token (Deprecated)
  - esper_cloud_api_Commands V2
  - esper_cloud_api_Enterprise Policy
  - esper_cloud_api_Geofence
  - esper_cloud_api_Content
  - esper_cloud_api_User (Deprecated)
  - esper_cloud_api_User
  - esper_cloud_api_Blueprint (Deprecated)
  - esper_cloud_api_Directory Record
  - esper_cloud_api_Tile Icon
  - esper_cloud_api_Alerts
  - esper_cloud_api_Alarms
  - esper_cloud_api_Wallpapers
  - esper_cloud_api_Device Telemetry
  - esper_cloud_api_Daily and Custom Reports
  - esper_cloud_api_SSO Connections
  - esper_cloud_api_Roles
  - esper_cloud_api_Personal Access Token
- name: BLUEPRINTS
  tags:
  - blueprints_Blueprints API
  - blueprints_Custom Actions API
  - blueprints_Background Scripts API
- name: PIPELINES
  tags:
  - pipelines_System Status Code
  - pipelines_System
  - pipelines_Pipelines
  - pipelines_Stages
  - pipelines_Target Lists
  - pipelines_Targets
  - pipelines_Device Groups
  - pipelines_Operation Lists
  - pipelines_Operations
  - pipelines_Pipeline Runs
  - pipelines_Stage Runs
  - pipelines_Target Runs
- name: DEVICE
  tags:
  - device_Device
  - device_Device Heartbeat
  - device_Device Apps
  - device_Device Enrollment in EMM
  - device_Operations
  - device_DeviceOperations
  - device_MultiOS Remote Viewer
- name: APPS MANAGEMENT
  tags:
  - apps_management_VPP License Management
  - apps_management_VPP App Management
  - apps_management_Tenant Apps
  - apps_management_Apple App Store
  - apps_management_App List
  - apps_management_Webclips
  - apps_management_Provisioning Profiles
  - apps_management_Preferred Regions
  - apps_management_OEM Config Schema
  - apps_management_Esper Apps
  - apps_management_Tenant Esper Apps
- name: COMMANDS
  tags:
  - commands_Command Request
  - commands_Command Status
- name: DRIFT
  tags:
  - drift_Converge
  - drift_Converge Command
  - drift_Blueprint Drift
- name: DEVICE ONBOARDING
  tags:
  - device_onboarding_DEP Sync Request
  - device_onboarding_ABM Provisioning
- name: TENANT
  tags:
  - tenant_APNs certificate
  - tenant_DEP Profile
  - tenant_DEP Tokens
  - tenant_VPP Token Management
  - tenant_Google Enterprise
  - tenant_MDM Service Config
- name: FOUNDATION
  tags:
  - foundation_FoundryBuilds
  - foundation_FoundryDeviceModels
  - foundation_FoundryEvents
- name: REPORTS
  tags:
  - reports_Reports API
- name: GEOFENCE
  tags:
  - geofence_Geofences
  - geofence_Device State
x-provenance:
  method: harvested
  publisher: Esper
  source: https://api.esper.io/_bundle/openapi.json?download
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)