The Company Settings API manage the account information set up for your organization. Formerly known as Enterprise Information.
ESPER API REFERENCE (1.0.0)
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:
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.
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. |
We use standard HTTP status codes for success or failure. A typical error response may look something like this:
{
"errors": [],
"message": "error message",
"status": 400
}errors- List of error detailsmessage- Error descriptionstatus- 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.
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.
Download OpenAPI description
Overview
Languages
Servers
Mock server
https://develop-api.esper.io/_mock/openapi
https://{foo}-api.esper.cloud/api
This is the API for the former Blueprints service.
⚠️ Deprecation Notice: The following APIs will soon be deprecated. Use Blueprints API instead.
Operations
APIs to manage blueprints. Learn more about blueprints.
Operations
- Mock serverhttps://develop-api.esper.io/_mock/openapi/pipelines/v0/operationlists/{operationlist_id}/operations/
- https://develop-api.esper.cloud/api/pipelines/v0/operationlists/{operationlist_id}/operations/
curl -i -X GET \
'https://develop-api.esper.io/_mock/openapi/pipelines/v0/operationlists/{operationlist_id}/operations/?operation_type=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'Response
application/json
{ "code": 0, "message": "string", "content": { "count": 0, "previous": "string", "next": "string", "results": [ … ] } }
- Mock serverhttps://develop-api.esper.io/_mock/openapi/pipelines/v0/operationlists/{operationlist_id}/operations/
- https://develop-api.esper.cloud/api/pipelines/v0/operationlists/{operationlist_id}/operations/
curl -i -X POST \
'https://develop-api.esper.io/_mock/openapi/pipelines/v0/operationlists/{operationlist_id}/operations/' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"args": {},
"operation_type": "LOCK"
}'Response
application/json
{ "code": 0, "message": "string", "content": { "id": "string", "operation_list_id": "string", "pipeline_id": "string", "operation_type": "string", "args": "string", "created_by": 0, "updated_by": 0, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } }
- Mock serverhttps://develop-api.esper.io/_mock/openapi/pipelines/v0/operationlists/{operationlist_id}/operations/{operation_id}/
- https://develop-api.esper.cloud/api/pipelines/v0/operationlists/{operationlist_id}/operations/{operation_id}/
curl -i -X GET \
'https://develop-api.esper.io/_mock/openapi/pipelines/v0/operationlists/{operationlist_id}/operations/{operation_id}/' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'Response
application/json
{ "code": 0, "message": "string", "content": { "id": "string", "operation_list_id": "string", "pipeline_id": "string", "operation_type": "string", "args": "string", "created_by": 0, "updated_by": 0, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } }
APIs to manage Pipeline Runs. Pipeline run status descriptions
- PENDING - Pipeline run created.
- QUEUED - Pipeline run queued for processing.
- PROCESSING - Pipeline run received by scheduler for processing. (Processing a pipeline involves performing the operations required before starting a pipeline)
- RUNNING - Pipeline run has started running.
- WAITING - Pipeline run is waiting for an action (manual/automatic).
- COMPLETE - The pipeline run has completed processing i.e. All stage runs are processed. A complete pipeline run can move to success or failure.
- SUCCESS - A completed pipeline run moves to success if all stage runs are successful.
- FAILURE - A completed pipeline run moves to failure if all stage runs are not successful.
- CANCELLED - Pipeline run is cancelled by the user.
- TIMEOUT - The pipeline run has a timed out. This happens when the pipeline has not completed processing even after the timeout period (Default 21 days).
- INVALID - A pipeline run moves to invalid state when Pipeline run has no stageruns i.e pipeline has zero stages.
Operations
APIs to manage Stage Runs. Stage run status descriptions
- PENDING - Stage run created.
- QUEUED - Stage run queued for processing.
- PROCESSING - Stage run received by scheduler for processing.(Processing a stage run can involve performing the operations required before starting a stage run. In this case creating the target runs for the stage.)
- RUNNING - Stage run has started running.
- COMPLETE - Stage run moves to complete if all target runs are complete (target runs are complete if they are in a terminal state).
- SUCCESS - A completed stage run moves to success if all target runs are successful.
- FAILURE - A completed stage moves to failure if all target runs are not successful.
- CANCELLED - Stage run cancelled by user.
- TIMEOUT - The stage run has a timed out. This happens when the stage run has not completed processing even after the timeout period (Default 7 days).
- INVALID - A stage run moves to invalid state when a. The associated stage has no targets. b. The associated stage has no operations.
Operations
APIs to manage Target Runs. Target run status descriptions
- PENDING - Target run created.
- QUEUED - Target run queued for processing.
- PROCESSING - Target run received by scheduler for processing (During target run processing the command request for the target run is created).
- DISPATCHED - Target run moves to dispatched when a command is successfully queued for the target run. (Command status - QUEUED)
- RUNNING - Target run moves to running state when the command has been sent to the device (Command status - INITIATED, ACKNOWLEDGED, INPROGRESS)
- COMPLETE - Target run moves to complete state when it has completed running (Command status - FAILURE, SUCCESS, TIMEOUT, CANCELLED)
- SUCCESS - A completed target run moves to success when the associated command is successful (Command status - SUCCESS)
- FAILURE - A completed target run moves to success when the associated command is unsuccessful (Command status - FAILED, TIMEOUT, CANCELLED)
- CANCELLED - Target run cancelled by the user (Target runs ind Pending, Queued and Processing state can be cancelled by the user)
- TIMEOUT - The target run has a timed out. This happens when the target run has not completed processing even after the timeout period (7 days).
- INVALID - Target run is invalid.
Operations
APIs to get apps installed on iOS devices. Use Application to get apps for Android devices.
Operations
APIs for managing VPP licenses for apps. Learn more about VPP licenses.
Operations
APIs for getting information about VPP apps. Learn more about VPP apps.
Operations
APIs to view and manage command requests. Learn more about commands or how to schedule a command.
Scheduled commands are currently compatible with Android devices.
Operations
APIs to list and create converge actions for devices. Learn more about converge.
Operations
APIs to perform ABM provisioning. Learn more about ABM provisioning
Operations
APIs for managing APNS certificates. Learn more about APNS certificates
Operations
APIs to create and access DEP tokens. Learn more about DEP tokens
Operations
APIs to create, access, and delete VPP tokens. Learn more about VPP tokens.
Operations
APIs for managing reports.
Currently supports App Reports.
Operations