Gain Admin API Access

API Access is currently available on Enterprise plans.

Manage users programmatically. All requests are simple HTTP REST type requests. 

For any HTTP API requests, api_key should always be the one generated for your Company Admin.

Basic User Management

Add a New User

https://dialpad.com/api/v1/admin/user?api_key=<api_key>&email=adam@example.com&action=add&first_name=Adam

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.
 
dialpad.com/api/v1/admin/did?target_key=<target_key>&api_key=<api_key>
 
This will add a phone number to a user, not a room or 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
 
dialpad.com/api/v1/admin/did?target_key=<target_key>&api_key=<api_key>
 
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.
 
dialpad.com/api/v1/admin/user?target_key=<target_key>&office_key=<office_key>&api_key=<api_key>
 
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

  • 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
 
https://dialpad.com/api/v1/admin/user?email=adam@example.com&api_key=<api_key>
 
Get a List of your Users
 
https://dialpad.com/api/v1/admin/user?api_key=
 
Optional Parameters:

limit Number of users
cursor 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
 
 
 
Suspend a User
 
https://dialpad.com/api/v1/admin/userapi_key<api_key>&email=crookedemployee@example.com&action=suspend
  
Delete a User
 
https://dialpad.com/api/v1/admin/user?email=bademployee@example.com&action=delete&api_key=<api_key>

Offices

List all the offices in your domain. Each entry contains a key parameter that uniquely identifies each office. 

https://dialpad.com/api/v1/admin/office?api_key=<api_key>

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

https://dialpad.com/api/v1/admin/user?office_key<office_key>&email=alice@example.com&action=add&api_key=<api_key> 

Parameters
 
Parameter Possible Values Required? Description
api_key (provided by Dialpad) Required

The API key associated with the domain you are managing. Send a request to our support team to access API key.

Note: Please keep this API key confidential within your Organization to avoid unauthorized usage. This API is secure during use since HTTPS encrypts the URL  before transmission.

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

Response

The HTTP request will return a JSON blob. For example, the request:
 
https://dialpad.com/api/v1/admin/user?email=sample@sample.com&api_key=<your_key>&action=add

 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

First request for stats or records (/api/v1/admin/stats) 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

api_key Required

The API key associated with the domain you are managing. Send a request to our support team to access API key.

Note: Please keep this API key confidential within your Organization to avoid unauthorized usage. This API is secure during use since HTTPS encrypts the URL  before transmission

stat_type Required

"calls" or "texts"

target Optional

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

is_company Optional

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

office_id 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"

days_ago_start  

Number. 

Ex: 1=yesterday

days_ago_end  

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: To display real-time analytics, pass days_ago_start and days_ago_end with the value 0 for both. 

Verification 

Open dialpad.com/accounts to check that all accounts have been added correctly. For testing purposes, we suggest opening an incognito window in Chrome.