Admin API

API Access is currently available on Enterprise plans.

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

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>).

GET Request

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

Basic User Management

Add a New User

POST Request
 
/api/v1/admin/user
 
Parameters:
 
email=adam@example.com&first_name=Adam&last_name=Johnson

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:
 
target_key=<target_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
 
/api/v1/admin/did
 
Parameters:
 
target_key=<target_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
 
/api/v1/admin/user
 
Parameters:
 
target_key=<target_key>&office_key=<office_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 (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:
 
email=adam@example.com
 
Get a List of your Users
 
GET Request
 
/api/v1/admin/user
 
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
 
PUT Request
 
/api/v1/admin/user
 
Parameters:
 
email=crookedemployee@example.com&action=suspend
  
Delete a User
 
DELETE Request
 
/api/v1/admin/user
 
Parameters:
 
email=bademployee

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.

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
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:
 
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 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": "<url>", "file_type": "csv","kind": "stats","status": "complete"}

Parameters

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.  


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.