Esper esper_cloud_api_Company Settings API

openapi: 3.2.0
info:
  title: ESPER API REFERENCE esper_cloud_api_Company Settings 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_Company Settings
  description: The Company Settings API manage the account information set up for your organization. Formerly known as Enterprise Information.
  externalDocs:
    description: Find out more about Company Settings
    url: https://help.esper.io/hc/en-us/articles/12656541757457-Introduction-to-Company-Settings
  x-displayName: Company Settings
paths:
  /v1/enterprise/{enterprise_id}/:
    get:
      x-badges:
      - name: Stable
        color: green
      tags:
      - esper_cloud_api_Company Settings
      summary: Get your company settings
      description: 'Retrieves the current company settings for the specified enterprise.


        Use this endpoint to read enterprise-level configuration including contact information, location details, EMM enrollment status, and the enterprise''s display name.


        **About Get Company Settings**

        This endpoint (formerly "Get Enterprise Information") returns the EnterpriseV1 object for your enterprise — the root configuration record that identifies your organization within Esper. It includes both read-only system fields (id, short_code, created_on, updated_on, emm) and user-editable fields such as name, contact details, and location. The emm field surfaces whether the enterprise is enrolled in Google EMM and, if so, its google_enterprise_id. All editable fields can be updated via PATCH /v1/enterprise/{enterprise_id}/.


        **Key Fields**


        enterprise_id (path, required) — UUID of the enterprise to retrieve


        id (read-only) — UUID of the enterprise record


        short_code (read-only) — Auto-generated 10-character identifier for the enterprise


        name — Display name of the enterprise


        registered_name — Formal legal name of the organization


        registered_address — Registered business address


        location — City, state, and country of the enterprise


        contact_person / contact_number / contact_email — Primary point-of-contact details


        wifi_lte_toggle_flag — Whether the data saver mode feature is enabled (only present if the feature is active)


        emm — Google EMM enrollment details, including google_enterprise_id; null if not EMM-enrolled


        **Common Use Cases**


        Reading enterprise metadata to populate an integration''s configuration or audit log


        Confirming EMM enrollment status and retrieving the linked google_enterprise_id


        Retrieving the current values of all editable fields before issuing a PATCH update


        **Best Practices**


        Use this endpoint to read current state before calling PATCH — it ensures you don''t unknowingly overwrite values you didn''t intend to change


        Treat id, short_code, created_on, updated_on, and emm as read-only; they cannot be updated via PATCH


        Cache the enterprise_id at integration setup time rather than fetching it on every request


        **Workflow**


        Call GET /v1/enterprise/{enterprise_id}/ with the enterprise UUID


        Inspect the response for the fields relevant to your use case (e.g., emm for EMM enrollment status, contact_email for contact details)


        Use the returned field values as the baseline if you plan to follow up with a PATCH update'
      operationId: getEnterprise
      parameters:
      - name: enterprise_id
        in: path
        description: A UUID string identifying this enterprise.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_EnterpriseV1'
        '401':
          description: Authorization information is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
      security:
      - esper_cloud_api_apiKey: []
    patch:
      x-badges:
      - name: Stable
        color: green
      tags:
      - esper_cloud_api_Company Settings
      summary: Partially update company settings
      description: 'Partially updates the company settings for the specified enterprise, returning the full updated record.

        Supply only the fields you want to change — all omitted fields retain their current values.


        **About Partial Update Company Settings**


        This endpoint (formerly "Partial Update Enterprise Information") applies sparse updates to the EnterpriseV1 record using the EnterpriseUpdateV1 schema. All fields in the request body are optional; only those included will be changed. Read-only fields (id, short_code, created_on, updated_on, emm) cannot be modified and should be omitted from the request body. The response returns the complete updated EnterpriseV1 object. Call GET /v1/enterprise/{enterprise_id}/ first to retrieve current values before making changes.


        **Key Fields**


        enterprise_id (path, required) — UUID of the enterprise to update


        name (optional) — Display name of the enterprise (max 255 chars)


        registered_name (optional) — Formal legal name of the organization


        registered_address (optional) — Registered business address


        location (optional) — City, state, and country


        zipcode (optional) — Postal code for the enterprise location (max 8 chars)


        contact_person (optional, nullable) — Primary point-of-contact name


        contact_number (optional, nullable) — Contact phone number


        contact_email (optional) — Contact email address


        wifi_lte_toggle_flag (optional) — Toggles data saver mode; only effective if the feature is enabled for the enterprise


        **Common Use Cases**


        Updating enterprise contact details after an organizational change


        Correcting the registered name or address on file


        Toggling wifi_lte_toggle_flag when enabling or disabling data saver mode


        **Best Practices**


        Call GET /v1/enterprise/{enterprise_id}/ first to confirm current values before issuing a PATCH


        Include only the fields you intend to change; PATCH is safe to use for single-field updates


        Do not include id, short_code, created_on, updated_on, or emm in the request body — they are read-only and will be ignored or may cause errors


        Verify the update took effect by inspecting the returned EnterpriseV1 object in the response


        **Workflow**


        Call GET /v1/enterprise/{enterprise_id}/ to retrieve the current enterprise record


        Construct a partial payload containing only the fields to update


        Call PATCH /v1/enterprise/{enterprise_id}/ with the payload


        Confirm the changes in the returned EnterpriseV1 response object'
      operationId: partialUpdateEnterprise
      parameters:
      - name: enterprise_id
        in: path
        description: A UUID string identifying this enterprise.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/esper_cloud_api_EnterpriseUpdateV1'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_EnterpriseV1'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
        '401':
          description: Authorization information is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/esper_cloud_api_ErrorResponse'
      security:
      - esper_cloud_api_apiKey: []
      x-codegen-request-body-name: data
components:
  schemas:
    esper_cloud_api_EnterpriseV1:
      required:
      - id
      - name
      - short_code
      type: object
      properties:
        id:
          title: Id
          type: string
          description: Id of the enterprise
          format: uuid
          readOnly: true
        name:
          title: Name
          maxLength: 255
          minLength: 1
          type: string
          description: Name of the enterprise
        short_code:
          title: Short code
          maxLength: 10
          minLength: 1
          type: string
          description: A short 10-char representation of the enterprise, separated by hyphens. Field is optional, as system will auto-generate a value if none is provided.
          readOnly: true
        registered_name:
          title: Registered name of the enterprise
          maxLength: 255
          minLength: 1
          type: string
          description: Registered Name of the enterprise
        registered_address:
          title: Registered address
          maxLength: 255
          minLength: 1
          type: string
          description: Registered address of the enterprise.
        location:
          title: Enterprise location
          maxLength: 255
          minLength: 1
          type: string
          description: City, State, Country location of the enterprise
        zipcode:
          title: Enterprise zipcode
          maxLength: 8
          minLength: 1
          type: string
          description: Zip code of enterprise location
        contact_person:
          title: Contact person
          maxLength: 255
          minLength: 1
          type:
          - string
          - 'null'
          description: Person who is the point of contact for the enterprise
        contact_number:
          title: Contact number
          maxLength: 20
          minLength: 1
          type:
          - string
          - 'null'
          description: Contact number of the enterprise
        contact_email:
          title: Contact email
          maxLength: 254
          minLength: 1
          type: string
          description: Contact email address of the enterprise
          format: email
        wifi_lte_toggle_flag:
          title: Enable data saver mode
          type: boolean
          description: Will only be available if feature is enabled
        emm:
          title: Google EMM
          type:
          - object
          - 'null'
          properties:
            google_enterprise_id:
              type: string
          description: This field will have details about emm enrollment if the enterprise is emm enrolled
          readOnly: true
        created_on:
          title: Created on
          type: string
          description: Date and time of when this resource was created
          format: date-time
          readOnly: true
        updated_on:
          title: Updated on
          type: string
          description: Date and time of when this resource was updated
          format: date-time
          readOnly: true
    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_EnterpriseUpdateV1:
      type: object
      properties:
        id:
          title: Id
          type: string
          description: Id of the enterprise
          format: uuid
          readOnly: true
        name:
          title: Enterprise Name
          maxLength: 255
          minLength: 1
          type: string
          description: Name of the enterprise
        registered_name:
          title: Registered name
          maxLength: 255
          minLength: 1
          type: string
          description: Registered Name of the enterprise
        registered_address:
          title: Registered address
          maxLength: 255
          minLength: 1
          type: string
          description: Registered address of the enterprise.
        location:
          title: Enterprise location
          maxLength: 255
          minLength: 1
          type: string
          description: City, State, Country location of the enterprise
        zipcode:
          title: Enterprise zipcode
          maxLength: 8
          minLength: 1
          type: string
          description: Description of the enterprise
        contact_person:
          title: Contact person
          maxLength: 255
          minLength: 1
          type:
          - string
          - 'null'
          description: Person who is the point of contact for the enterprise
        contact_number:
          title: Contact number
          maxLength: 20
          minLength: 1
          type:
          - string
          - 'null'
          description: Contact number of the enterprise
        contact_email:
          title: Contact email
          maxLength: 254
          minLength: 1
          type: string
          description: Contact email address of the enterprise
          format: email
        wifi_lte_toggle_flag:
          title: Enable data saver mode
          type: boolean
          description: Will only be available if feature is enabled
  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)