Admin API

API Access is currently available on Enterprise plans.

All requests are simple HTTP REST type requests sent as content type application/x-www-form-urlencoded. For GET requests all parameters are passed in the query string. For PUT/POST/DELETE requests all parameters are sent in the body of the request in query string format.

For any HTTP API requests, The access token should always be the one generated for your Company Admin. You can pass the access token with the parameter api_key or with the Authorization: Bearer HTTP header (ex: Authorization: Bearer <access_token>).

All endpoints are only accessible via https and are located at dialpad.com. For instance: you can get a list of your Users by requesting the following URL with your access token:

https://dialpad.com/api/v1/admin/user?api_key=<ACCESS-TOKEN>

 

User Management

Add a New User

POST Request
 
/api/v1/admin/user
 
Parameters
 
Field Value Required? Description
email adam@example.com Required User's primary email address.
first_name Adam Optional First name
last_name Johnson Optional Last name


This adds a user to your Domain but doesn't specify an Office. To assign them to a specific Office, make sure to navigate back to your Dialpad portal. 
 
 
Add a User Phone Number
 
POST Request
 
/api/v1/admin/did
 
Parameters
 
Field Value Required? Description
target_key <target_key_string> Required The user that you want to add a phone number to.

 

This will add a phone number to a user, not a room or Office. The number will automatically be taken from the company's reserved block if they have reserved numbers else it will auto assign a number from the same area code as the Office. To access the target_key, Admins will need to call the /user to get the user key and pass it as target_key.
 
 
Delete a User Phone Number
 
DELETE Request
 
/api/v1/admin/did
 
Parameters
 
Field Value Required? Description
target_key <target_key_string> Required The user that you want to delete all phone numbers on.
 
Deletes all the phone numbers that belong to a user. The target_key can be obtained via the GET request to the /user.
 
 
Transfer a User to Another Office
 
PUT Request
 
/api/v1/admin/user
 
Parameters
 
Field Value Required? Description
target_key <target_key_string> Required The target_key that represents the user
office_key <office_key_string> Required Office key of the destination office
 
Use this API for times when you need to migrate a user to a different Office. The office_key can be retrieved via the /office API call.
 
For international offices, the user must have phone/fax numbers removed. Once the transfer is complete, your Admin can add the phone numbers via POST on /did.
 
Keep the following in mind:
  • Only for paid accounts and must have enough licenses to transfer a user to another Office (we'll alert you if you don't)

  • Admin running the API must also be Admin of Target Office for the transfer and adding/removing phone numbers, as well as access permissions to the user itself

Dialpad Tip: Please note that all available licenses will be billed even if they are not used. If you wish to permanently remove the available licenses, let our support team know.

 
Get Info About a User
 
GET Request
 
/api/v1/admin/user
 
Parameters
 
Field Value Required? Description
email adam@example.com Required The user that you want to delete all phone numbers on.
 
 
Get a List of your Users
 
GET Request
 
/api/v1/admin/user
 

Parameters 

Field Value Required? Description
limit <number> Optional Number of users
cursor <cursor_string> Optional The pagination cursor used to get the next set of users. If there are more users than the first request returns, a cursor is passed back in the result. Pass that cursor as the parameter to get the next set of users
 
 
Edit User Info
 
PUT Request
 
/api/v1/admin/user
 

Parameters 

Field Value Required? Description
email brian@example.com Required User's primary email address
first_name ex: Brian Optional Change a user's first name
last_name ex: Anderson Optional Change a user's last name
extension ex: 41000 Optional The user's new extension number.*
 
*Extensions are optional in Dialpad and turned off by default. If you want extensions please contact support to enable them. 
 
 
Suspend a User
 
PUT Request
 
/api/v1/admin/user
 
Parameters
 
Field Value Required? Description
email adam@example.com Required The primary email address of the user.
action suspend Required  
  
 
Reactive a suspended User
 
PUT Request
 
/api/v1/admin/user
 
Parameters
 
Field Value Required? Description
email adam@example.com Required The primary email address of the user.
action reactivate Required  
 
 
Delete a User
 
DELETE Request
 
/api/v1/admin/user
 
Parameters
 
Field Value Required? Description
email adam@example.com Required The primary email address for the account.

 

Offices

Get list of Offices
 
GET Request
 
/api/v1/admin/office
 
List all the offices in your domain. Each entry contains a key parameter that uniquely identifies each office. 

Create a new user and associate them with a specific office. For the office_key parameter, use the value for key mentioned above.

Parameters

Field Value Required? Description
office_key (unique to each Office in your domain) Optional

Include if you want to associate an Office with a user (only when first adding a user)

action add | delete | suspend | reactivate Optional

Action to take on given email address (user)

Note: Suspended users cannot log in and cannot accept calls or texts. All other functions (including data retention) remain, including billing for the suspended account.

email   Required

Email address (user) you want to perform the action on

first_name   Optional

Optional first name to associate with the user

last_name   Optional

Optional last name to associate with the user

 

Departments

Get list of Departments
 
GET Request
 
/api/v1/admin/department
 
List all the Departments and Call Queues in an Office. Each entry contains a key parameter that uniquely identifies each Department or Call Queue. 

Parameters

Field Value Required? Description
office_key (unique to each Office in your domain) Optional

Default is the primary office. Pass office_key to get Departments for other offices.

 

Operators

Get list of Operators assigned to a Department/Call Queue
 
GET Request
 
/api/v1/admin/operators
 
List all the Operators assigned to a Departments or Call Queue. This returns a list of User objects.

Parameters

Field Value Required? Description
target_key <target_key_string> Required

The target key of the Main Line, Department, or Call Queue

 

Response

The HTTP request will return a JSON blob. For example, the request:
 
POST https://dialpad.com/api/v1/admin/user?email=sample@sample.com

 returns the following: 

{
  "office_count": 34,
  "pending_user": "sample@sample.com",
  "message": "creating user...check back in a moment please",
  # Adding a new user is asynchronous. Check the user status later.
  "company_count": 34
}
If the action parameter is not specified, then it will return the status for that user
{
  # Company account information
  office_count: 34,
  company_count: 34,
  # User information
  user: {
    last_name: "",
    first_name: "",
    primary_email: "sample@sample.com",
    primary_phone: "+14154292691",
    # ... etc
  }
}
If the user doesn't exist, then there will be no user key. Only the Company account information.
 
If the request fails for any reason, then it will return an HTTP error code in the 400s or 500s with following JSON.
{
  status: 1,
  errors: [
    "email_conflict"
  ]
}
 
 

Analytics

Get summary stats and call/text logs

GET Request

/api/v1/admin/stats

First request for stats or records will return this:

{
"kind": "stats",
"status": "processing"
}

Follow-up requests will return “processing” until it is ready, which shouldn’t take more than two minutes for any request. When it is ready it will return this with a link to the CSV download.

{
  "download_url": ""
  "file_type": "csv",
  "kind": "stats",
  "status": "complete"
}
 

Parameters

Field Values Required? Description
stat_type "calls" or "texts" Required

Type of stats.

target <string> Optional

The target key associated with the user or Department you are requesting analytics for. 

is_company 1 Optional

Include if you want to display analytics for your entire Company.

office_id <string> Optional

The ID of the selected Office. 

Note: If you do not supply target, is_company, or office_id, Dialpad will default to your own Office.

export_type "stats" or "records" Optional

"stats" or "records"

is_today 1 Optional

Set if you want today's data.

Note: You cannot combine today's data with historical data. is_today overrides days_ago_start and days_ago_end.

days_ago_start <number> Optional 

Number. 

Ex: 1 = yesterday

Note: The lowest you can set this value is 1. If you want today's real time data, set the is_today parameter instead.

days_ago_end <number> Optional 

Number. 

Ex: Set to 1 as well for yesterday. Setting it to 2 would be two days ago until yesterday if days ago start is set to 1.  

Dialpad Tip: The timezone displayed will be the local time of the Office of the user key you're using.


Verification 

Open Dialpad.com/accounts to verify that all accounts have been added correctly. For testing purposes, we'd suggest opening an incognito browser in Chrome.