--- updatedAt: 2026-09-26T02:51:07.000Z agentTools: projectIndex: https://developers.dialpad.com/llms.txt --- # User -- List Gets company users, optionally filtering by email. NOTE: The `limit` parameter has been soft-deprecated. Please omit the `limit` parameter, or reduce it to `100` or less. - Limit values of greater than `100` will only produce a page size of `100`, and a `400 Bad Request` response will be produced 20% of the time in an effort to raise visibility of side-effects that might otherwise go un-noticed by solutions that had assumed a larger page size. - The `cursor` value is provided in the response, and can be passed as a parameter to retrieve subsequent pages of results. Rate limit: 1200 per minute. # OpenAPI definition ```json { "components": { "schemas": { "protos.user.GroupDetailsProto": { "properties": { "do_not_disturb": { "description": "Whether the user is currently in do-not-disturb mode for this group.", "type": [ "boolean", "null" ] }, "group_id": { "description": "The ID of the group.", "format": "int64", "type": [ "integer", "null" ] }, "group_type": { "description": "The group type.", "enum": [ "callcenter", "callrouter", "channel", "coachinggroup", "coachingteam", "department", "office", "room", "staffgroup", "unknown", "user", null ], "type": [ "null", "string" ] }, "role": { "description": "The user's role in the group.", "enum": [ "admin", "operator", "supervisor", null ], "type": [ "null", "string" ] } }, "type": "object" }, "protos.user.UserCollection": { "properties": { "cursor": { "description": "A token used to return the next page of a previous request. Use the cursor provided in the previous response.", "type": [ "null", "string" ] }, "items": { "description": "A list of users.", "items": { "$ref": "#/components/schemas/protos.user.UserProto", "type": "object" }, "type": [ "array", "null" ] } }, "title": "Collection of users.", "type": "object" }, "protos.user.UserProto": { "properties": { "admin_office_ids": { "description": "A list of office IDs for which this user has admin privileges.", "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "company_id": { "description": "The id of the user's company.", "format": "int64", "type": [ "integer", "null" ] }, "country": { "description": "The country in which the user resides.", "type": [ "null", "string" ] }, "date_active": { "description": "The date when the user activated their Dialpad account.", "format": "date-time", "type": [ "null", "string" ] }, "date_added": { "description": "A timestamp indicating when this user was created.", "format": "date-time", "type": [ "null", "string" ] }, "date_first_login": { "description": "A timestamp indicating the first time that this user logged in to Dialpad.", "format": "date-time", "type": [ "null", "string" ] }, "date_last_login": { "description": "The date when the user last logged in to Dialpad. Omitted if the user has never logged in.", "format": "date-time", "type": "string" }, "display_name": { "description": "The user's name, for display purposes.", "type": [ "null", "string" ] }, "do_not_disturb": { "description": "A boolean indicating whether the user is currently in \"Do not disturb\" mode.", "type": [ "boolean", "null" ] }, "duty_status_reason": { "description": "[single-line only]\n\nA description of this status.", "type": [ "null", "string" ] }, "duty_status_started": { "description": "The timestamp, in UTC, when the current on duty status changed.", "format": "date-time", "type": [ "null", "string" ] }, "emails": { "description": "A list of email addresses belonging to this user.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "extension": { "description": "The extension that should be associated with this user in the company or office IVR directory.", "type": [ "null", "string" ] }, "first_name": { "description": "[single-line only]\n\nThe given name of the user.", "type": [ "null", "string" ] }, "forwarding_numbers": { "description": "A list of phone numbers that should be dialed in addition to the user's Dialpad number(s)\nupon receiving a call. Only present when the user has forwarding numbers configured.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "group_details": { "description": "Details regarding the groups that this user is a member of.", "items": { "$ref": "#/components/schemas/protos.user.GroupDetailsProto", "type": "object" }, "type": [ "array", "null" ] }, "id": { "description": "The user's id.", "format": "int64", "type": [ "integer", "null" ] }, "image_url": { "description": "The url of the user's profile image.", "type": [ "null", "string" ] }, "international_dialing_enabled": { "description": "Whether or not the user is enabled to dial internationally.", "type": [ "boolean", "null" ] }, "is_admin": { "description": "A boolean indicating whether this user has administrator privileges.", "type": [ "boolean", "null" ] }, "is_available": { "description": "A boolean indicating whether the user is not currently on a call.", "type": [ "boolean", "null" ] }, "is_on_duty": { "description": "A boolean indicating whether this user is currently acting as an operator.", "type": [ "boolean", "null" ] }, "is_online": { "description": "A boolean indicating whether the user currently has an active Dialpad device.", "type": [ "boolean", "null" ] }, "is_super_admin": { "description": "A boolean indicating whether this user has company-wide administrator privileges.", "type": [ "boolean", "null" ] }, "job_title": { "description": "[single-line only]\n\nThe user's job title.", "type": [ "null", "string" ] }, "language": { "description": "The preferred spoken language of the user.", "type": [ "null", "string" ] }, "last_name": { "description": "[single-line only]\n\nThe family name of the user.", "type": [ "null", "string" ] }, "license": { "description": "The license type that has been allocated to this user.", "enum": [ "admins", "agents", "dpde_all", "dpde_one", "lite_lines", "lite_support_agents", "magenta_lines", "talk", "user", null ], "type": [ "null", "string" ] }, "location": { "description": "[single-line only]\n\nThe self-reported location of the user. Only present when the user has set a self-reported location.", "type": [ "null", "string" ] }, "muted": { "description": "A boolean indicating whether the user has muted their microphone.", "type": [ "boolean", "null" ] }, "office_id": { "description": "The ID of the user's office.", "format": "int64", "type": [ "integer", "null" ] }, "on_duty_started": { "description": "The timestamp, in UTC, when this operator became available for contact center calls.", "format": "date-time", "type": [ "null", "string" ] }, "on_duty_status": { "description": "A description of operator's on duty status.", "enum": [ "available", "busy", "occupied", "occupied-end", "unavailable", "wrapup", "wrapup-end", null ], "type": [ "null", "string" ] }, "onboarding_completed": { "description": "True if user has completed the onboarding process.", "type": "boolean" }, "phone_numbers": { "description": "A list of phone numbers belonging to this user.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "remote_service": { "description": "The remote service provider for this user (Google or Microsoft).", "type": [ "null", "string" ] }, "session_type": { "description": "The session type of operator's current occupied call or digital. Only present for contact center operators currently in an active call session (occupied or occupied-end duty status).", "enum": [ "call", "digital", null ], "type": [ "null", "string" ] }, "state": { "description": "The current enablement state of the user.", "enum": [ "active", "cancelled", "deleted", "pending", "suspended", null ], "type": [ "null", "string" ] }, "status_message": { "description": "[single-line only]\n\nA message indicating the activity that the user is currently engaged in.", "type": [ "null", "string" ] }, "timezone": { "description": "The timezone that this user abides by.", "type": [ "null", "string" ] }, "voicemail": { "$ref": "#/components/schemas/protos.user.VoicemailSettings", "description": "Voicemail settings for the user.", "type": "object" } }, "required": [ "onboarding_completed", "voicemail" ], "title": "User.", "type": "object" }, "protos.user.VoicemailSettings": { "properties": { "is_default_voicemail": { "description": "Whether the user is using the default voicemail or a custom one.", "type": "boolean" }, "name": { "description": "The display name for the voicemail.", "type": [ "null", "string" ] }, "voicemail_notifications_enabled": { "description": "Whether voicemail notifications are active or not.", "type": "boolean" } }, "title": "Voicemail settings for user.", "type": "object" } }, "securitySchemes": { "bearer_token": { "description": "The API key can be put in the Authorization header.\ni.e. Authorization: Bearer ", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Dialpad's APIs for customer and third-party developer use", "title": "Dialpad", "version": "v2", "x-logo": { "altText": "Dialpad", "url": "https://storage.googleapis.com/dialpad_openapi_specs/logo.png" } }, "openapi": "3.1.0", "paths": { "/api/v2/users": { "get": { "deprecated": false, "description": "Gets company users, optionally filtering by email.\n\nNOTE: The `limit` parameter has been soft-deprecated. Please omit the `limit` parameter, or reduce it to `100` or less.\n\n- Limit values of greater than `100` will only produce a page size of `100`, and a\n `400 Bad Request` response will be produced 20% of the time in an effort to raise visibility of side-effects that might otherwise go un-noticed by solutions that had assumed a larger page size.\n\n- The `cursor` value is provided in the response, and can be passed as a parameter to retrieve subsequent pages of results.\n\nRate limit: 1200 per minute.", "operationId": "users.list", "parameters": [ { "description": "A token used to return the next page of a previous request. Use the cursor provided in the previous response.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Filter results by first name prefix (e.g. \"jo\" matches \"John\", \"Jose\"). Uses Elasticsearch prefix matching. Cannot be combined with email or number.", "in": "query", "name": "first_name", "required": false, "schema": { "type": "string" } }, { "description": "Filter results by last name prefix (e.g. \"sm\" matches \"Smith\", \"Smythe\"). Uses Elasticsearch prefix matching. Cannot be combined with email or number.", "in": "query", "name": "last_name", "required": false, "schema": { "type": "string" } }, { "description": "Filter results by the specified user state (e.g. active, suspended, deleted)", "in": "query", "name": "state", "required": false, "schema": { "default": "active", "enum": [ "active", "all", "cancelled", "deleted", "pending", "suspended" ], "type": "string" } }, { "description": "If provided, filter results by the specified value to return only company admins or only non-company admins.", "in": "query", "name": "company_admin", "required": false, "schema": { "type": "boolean" } }, { "description": "The user's email.", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "The user's phone number, in e164 format.", "in": "query", "name": "number", "required": false, "schema": { "type": "string" } }, { "description": "When true, `number` is also matched against the forwarding numbers users have added to their profile, instead of only the numbers assigned to them by Dialpad. Only applies together with `number`.", "in": "query", "name": "forwarding_number", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "json_example": { "value": { "items": [ { "admin_office_ids": [ "6422934115149452" ], "company_id": "4508591728425653", "country": "us", "date_active": "2021-06-20T19:18:00", "date_added": "2021-06-20T19:18:00", "date_first_login": "2021-06-20T19:18:00", "display_name": "テÉst Bot", "do_not_disturb": false, "emails": [ "bot@fuzz-ball.com" ], "first_name": "テÉst", "forwarding_numbers": [ "+14152301358" ], "group_details": [ { "do_not_disturb": false, "group_id": "6422934115149452", "group_type": "office", "role": "admin" } ], "has_rbac": false, "id": "5835806903417907", "image_url": "https://dialpad.com/avatar/user/ag5kZXZ-dWJlci12b2ljZXIYCxILVXNlclByb2ZpbGUYs_jS66r0rgoM.png?version=36c0561fb8e0f5765ccfb3a5316f6d5d", "international_dialing_enabled": false, "is_admin": true, "is_available": true, "is_on_duty": false, "is_online": false, "is_super_admin": true, "job_title": "Mock Job Title", "language": "en", "last_name": "Bot", "license": "talk", "location": "Mock Location", "muted": false, "office_id": "6422934115149452", "onboarding_completed": true, "phone_numbers": [ "+14155551001" ], "remote_service": "google", "state": "active", "status_message": "Mock Status", "timezone": "US/Pacific", "voicemail": { "is_default_voicemail": true, "name": "default", "voicemail_notifications_enabled": true } }, { "admin_office_ids": [ "6422934115149452" ], "company_id": "4508591728425653", "country": "us", "date_active": "2021-06-20T19:18:00", "date_added": "2021-06-20T19:18:00", "date_first_login": "2021-06-20T19:18:00", "display_name": "テÉst Bot", "do_not_disturb": false, "emails": [ "test_contact@fuzz-ball.com" ], "first_name": "テÉst", "forwarding_numbers": [ "+14152301358" ], "group_details": [ { "do_not_disturb": false, "group_id": "6422934115149452", "group_type": "office", "role": "admin" } ], "has_rbac": false, "id": "4335858969377504", "image_url": "https://dialpad.com/avatar/user/ag5kZXZ-dWJlci12b2ljZXIYCxILVXNlclByb2ZpbGUY4PWprY3u2QcM.png?version=36c0561fb8e0f5765ccfb3a5316f6d5d", "international_dialing_enabled": false, "is_admin": true, "is_available": true, "is_on_duty": false, "is_online": false, "is_super_admin": false, "job_title": "Mock Job Title", "language": "en", "last_name": "Bot", "license": "talk", "location": "Mock Location", "muted": false, "office_id": "6422934115149452", "onboarding_completed": false, "phone_numbers": [ "+14155551002" ], "remote_service": "", "state": "active", "status_message": "Mock Status", "timezone": "US/Pacific", "voicemail": { "is_default_voicemail": true, "name": "default", "voicemail_notifications_enabled": true } } ] } } }, "schema": { "$ref": "#/components/schemas/protos.user.UserCollection" } } }, "description": "A successful response" } }, "summary": "User -- List", "tags": [ "users" ], "x-access": [ "user" ], "x-ratelimit": [ [ 20, 1 ] ] } } }, "servers": [ { "url": "https://dialpad.com" }, { "url": "https://sandbox.dialpad.com" } ], "security": [ { "bearer_token": [] } ], "x-readme": { "apply-tag-changes": true, "explorer-enabled": true, "proxy-enabled": false } } ```