> ## Documentation Index > Fetch the complete documentation index at: https://www.seam.co/docs/llms.txt > Use this file to discover all available pages before exploring further. # List ACS Users > Returns a list of all [access system users](/low-level-apis/access-systems/user-management). ## OpenAPI ````yaml /openapi.json get /acs/users/list openapi: 3.0.0 info: description: >- Programmable API to control locks, thermostats, noise sensors, cameras, access control systems, and other IoT devices. Prefer the official Seam SDKs over hand-written HTTP calls: they handle authentication, request serialization, pagination, and error handling for you. The official SDKs are listed in this document under `info.x-seam-sdks`. If you call the HTTP API directly, your query parameters must be serialized compatibly with the Seam API. There is no universal convention for serializing arrays, booleans, or nested objects in a query string, so use @seamapi/url-search-params-serializer, the language specific serializer module provided by each Seam SDK, or follow its specification: https://github.com/seamapi/url-search-params-serializer title: Seam Connect version: 1.0.0 x-seam-query-serializer: description: >- Reference implementation and specification for query parameter serialization compatible with the Seam API. url: https://github.com/seamapi/url-search-params-serializer x-seam-sdks: - language: javascript url: https://github.com/seamapi/javascript - language: python url: https://github.com/seamapi/python - language: ruby url: https://github.com/seamapi/ruby - language: php url: https://github.com/seamapi/php - language: csharp url: https://github.com/seamapi/csharp servers: - url: https://connect.getseam.com security: [] tags: - description: access_codes name: /access_codes - description: acs name: /acs - description: action_attempts name: /action_attempts - description: client_sessions name: /client_sessions - description: connected_accounts name: /connected_accounts - description: connect_webviews name: /connect_webviews - description: devices name: /devices - description: events name: /events - description: health name: /health - description: locks name: /locks - description: networks name: /networks - description: noise_sensors name: /noise_sensors - description: phones name: /phones - description: thermostats name: /thermostats - description: user_identities name: /user_identities - description: webhooks name: /webhooks - description: workspaces name: /workspaces paths: /acs/users/list: get: tags: - /acs summary: List ACS Users description: >- Returns a list of all [access system users](/low-level-apis/access-systems/user-management). operationId: acsUsersListGet parameters: - in: query name: user_identity_id schema: description: >- ID of the user identity for which you want to retrieve all access system users. format: uuid type: string - in: query name: user_identity_phone_number schema: description: >- Phone number of the user identity for which you want to retrieve all access system users, in [E.164 format](https://www.itu.int/rec/T-REC-E.164/en) (for example, `+15555550100`). Specify `null` to retrieve access system users whose user identity has no phone number. nullable: true type: string - in: query name: user_identity_email_address schema: description: >- Email address of the user identity for which you want to retrieve all access system users. Specify `null` to retrieve access system users whose user identity has no email address. nullable: true type: string - in: query name: acs_system_id schema: description: >- ID of the `acs_system` for which you want to retrieve all access system users. format: uuid type: string - in: query name: search schema: description: >- String for which to search. Filters returned access system users to include all records that satisfy a partial match using `full_name`, `phone_number`, `email_address`, `acs_user_id`, `user_identity_id`, `user_identity_full_name` or `user_identity_phone_number`. minLength: 1 type: string - in: query name: limit schema: default: 500 description: Maximum number of records to return per page. exclusiveMinimum: true minimum: 0 type: integer - in: query name: created_before schema: description: >- Timestamp by which to limit returned access system users. Returns users created before this timestamp. format: date-time type: string - in: query name: page_cursor schema: description: >- Identifies the specific page of results to return, obtained from the previous page's `next_page_cursor`. nullable: true type: string responses: '200': content: application/json: schema: properties: acs_users: items: $ref: '#/components/schemas/acs_user' type: array pagination: $ref: '#/components/schemas/pagination' required: - acs_users - pagination type: object description: OK '400': description: Bad Request '401': description: Unauthorized security: - client_session: [] - pat_with_workspace: [] - console_session_with_workspace: [] - api_key: [] - support_read_only_token: [] x-codeSamples: - lang: javascript label: Seam SDK source: |- await seam.acs.users.list({ user_identity_id: "0dcb435f-0aef-4ae6-8d6e-9c605b78c94e", }); /* [ { "access_schedule": { "ends_at": "2025-06-12T11:00:00.000Z", "starts_at": "2025-06-10T15:00:00.000Z" }, "acs_system_id": "62d3384f-267f-4a4a-a946-d35819ec9981", "acs_user_id": "6a5d9697-3cc4-436a-8165-4375ff424870", "connected_account_id": "c0175797-30f0-49f7-a228-2df115443ca7", "created_at": "2025-06-15T16:54:17.946482Z", "display_name": "Jane Doe", "email_address": "jane@example.com", "errors": [], "external_type": "salto_site_user", "external_type_display_name": "Salto site user", "full_name": "Jane Doe", "hid_acs_system_id": "2acbe47f-612c-422a-9205-7af292f74e7f", "is_managed": true, "is_suspended": false, "last_successful_sync_at": "2025-06-18T17:45:00.582Z", "pending_mutations": [], "phone_number": "+1555551000", "user_identity_email_address": "jane@example.com", "user_identity_full_name": "Jane Doe", "user_identity_id": "0dcb435f-0aef-4ae6-8d6e-9c605b78c94e", "user_identity_phone_number": "+1555551000", "warnings": [], "workspace_id": "8d4868e3-2f95-4f33-8689-19420b3101cd" } ] */ - lang: bash label: cURL source: >- curl --include --request POST "https://connect.getseam.com/acs/users/list" \ --header "Authorization: Bearer $SEAM_API_KEY" \ --json @- <- seam.acs.users.list(user_identity_id="0dcb435f-0aef-4ae6-8d6e-9c605b78c94e") # [ AcsUser( access_schedule={ "ends_at": "2025-06-12T11:00:00.000Z", "starts_at": "2025-06-10T15:00:00.000Z", }, acs_system_id="62d3384f-267f-4a4a-a946-d35819ec9981", acs_user_id="6a5d9697-3cc4-436a-8165-4375ff424870", connected_account_id="c0175797-30f0-49f7-a228-2df115443ca7", created_at="2025-06-15T16:54:17.946482Z", display_name="Jane Doe", email_address="jane@example.com", errors=[], external_type="salto_site_user", external_type_display_name="Salto site user", full_name="Jane Doe", hid_acs_system_id="2acbe47f-612c-422a-9205-7af292f74e7f", is_managed=true, is_suspended=false, last_successful_sync_at="2025-06-18T17:45:00.582Z", pending_mutations=[], phone_number="+1555551000", user_identity_email_address="jane@example.com", user_identity_full_name="Jane Doe", user_identity_id="0dcb435f-0aef-4ae6-8d6e-9c605b78c94e", user_identity_phone_number="+1555551000", warnings=[], workspace_id="8d4868e3-2f95-4f33-8689-19420b3101cd", ) ] - lang: ruby label: Seam SDK source: >- seam.acs.users.list(user_identity_id: "0dcb435f-0aef-4ae6-8d6e-9c605b78c94e") # => [ { "access_schedule" => { ends_at: "2025-06-12T11:00:00.000Z", starts_at: "2025-06-10T15:00:00.000Z", }, "acs_system_id" => "62d3384f-267f-4a4a-a946-d35819ec9981", "acs_user_id" => "6a5d9697-3cc4-436a-8165-4375ff424870", "connected_account_id" => "c0175797-30f0-49f7-a228-2df115443ca7", "created_at" => "2025-06-15T16:54:17.946482Z", "display_name" => "Jane Doe", "email_address" => "jane@example.com", "errors" => [], "external_type" => "salto_site_user", "external_type_display_name" => "Salto site user", "full_name" => "Jane Doe", "hid_acs_system_id" => "2acbe47f-612c-422a-9205-7af292f74e7f", "is_managed" => true, "is_suspended" => false, "last_successful_sync_at" => "2025-06-18T17:45:00.582Z", "pending_mutations" => [], "phone_number" => "+1555551000", "user_identity_email_address" => "jane@example.com", "user_identity_full_name" => "Jane Doe", "user_identity_id" => "0dcb435f-0aef-4ae6-8d6e-9c605b78c94e", "user_identity_phone_number" => "+1555551000", "warnings" => [], "workspace_id" => "8d4868e3-2f95-4f33-8689-19420b3101cd", }, ] - lang: php label: Seam SDK source: |- $seam->acs->users->list( user_identity_id: "0dcb435f-0aef-4ae6-8d6e-9c605b78c94e", ); // [ [ "access_schedule" => [ "ends_at" => "2025-06-12T11:00:00.000Z", "starts_at" => "2025-06-10T15:00:00.000Z", ], "acs_system_id" => "62d3384f-267f-4a4a-a946-d35819ec9981", "acs_user_id" => "6a5d9697-3cc4-436a-8165-4375ff424870", "connected_account_id" => "c0175797-30f0-49f7-a228-2df115443ca7", "created_at" => "2025-06-15T16:54:17.946482Z", "display_name" => "Jane Doe", "email_address" => "jane@example.com", "errors" => [], "external_type" => "salto_site_user", "external_type_display_name" => "Salto site user", "full_name" => "Jane Doe", "hid_acs_system_id" => "2acbe47f-612c-422a-9205-7af292f74e7f", "is_managed" => true, "is_suspended" => false, "last_successful_sync_at" => "2025-06-18T17:45:00.582Z", "pending_mutations" => [], "phone_number" => "+1555551000", "user_identity_email_address" => "jane@example.com", "user_identity_full_name" => "Jane Doe", "user_identity_id" => "0dcb435f-0aef-4ae6-8d6e-9c605b78c94e", "user_identity_phone_number" => "+1555551000", "warnings" => [], "workspace_id" => "8d4868e3-2f95-4f33-8689-19420b3101cd", ], ]; - lang: bash label: Seam CLI source: >- seam acs users list --user_identity_id "0dcb435f-0aef-4ae6-8d6e-9c605b78c94e" # [ # { # "access_schedule": { # "ends_at": "2025-06-12T11:00:00.000Z", # "starts_at": "2025-06-10T15:00:00.000Z" # }, # "acs_system_id": "62d3384f-267f-4a4a-a946-d35819ec9981", # "acs_user_id": "6a5d9697-3cc4-436a-8165-4375ff424870", # "connected_account_id": "c0175797-30f0-49f7-a228-2df115443ca7", # "created_at": "2025-06-15T16:54:17.946482Z", # "display_name": "Jane Doe", # "email_address": "jane@example.com", # "errors": [], # "external_type": "salto_site_user", # "external_type_display_name": "Salto site user", # "full_name": "Jane Doe", # "hid_acs_system_id": "2acbe47f-612c-422a-9205-7af292f74e7f", # "is_managed": true, # "is_suspended": false, # "last_successful_sync_at": "2025-06-18T17:45:00.582Z", # "pending_mutations": [], # "phone_number": "+1555551000", # "user_identity_email_address": "jane@example.com", # "user_identity_full_name": "Jane Doe", # "user_identity_id": "0dcb435f-0aef-4ae6-8d6e-9c605b78c94e", # "user_identity_phone_number": "+1555551000", # "warnings": [], # "workspace_id": "8d4868e3-2f95-4f33-8689-19420b3101cd" # } # ] components: schemas: acs_user: description: >- Represents a [user](/low-level-apis/access-systems/user-management) in an [access system](/low-level-apis/access-systems). See the [acs_user object](/api/acs/users/object). properties: access_schedule: description: >- `starts_at` and `ends_at` timestamps for the [access system user's](/low-level-apis/access-systems/user-management) access. properties: ends_at: description: >- Date and time at which the user's access ends, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. format: date-time nullable: true type: string starts_at: description: >- Date and time at which the user's access starts, in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. format: date-time type: string required: - starts_at - ends_at type: object acs_system_id: description: >- ID of the [access system](/low-level-apis/access-systems) that contains the [access system user](/low-level-apis/access-systems/user-management). format: uuid type: string acs_user_id: description: >- ID of the [access system user](/low-level-apis/access-systems/user-management). format: uuid type: string connected_account_id: description: |2- The ID of the connected account that is associated with the [access system user](/low-level-apis/access-systems/user-management). format: uuid type: string created_at: description: >- Date and time at which the [access system user](/low-level-apis/access-systems/user-management) was created. format: date-time type: string display_name: description: >- Display name for the [access system user](/low-level-apis/access-systems/user-management). type: string email: deprecated: true format: email type: string description: Deprecated. use email_address. email_address: description: >- Email address of the [access system user](/low-level-apis/access-systems/user-management). format: email type: string errors: type: array description: >- Errors associated with the [access system user](/low-level-apis/access-systems/user-management). items: type: object properties: error_code: type: string description: Error or warning code. message: type: string description: Human-readable description. created_at: type: string format: date-time description: When this error or warning was generated. external_type: description: >- Brand-specific terminology for the [access system user](/low-level-apis/access-systems/user-management) type. enum: - pti_user - brivo_user - hid_credential_manager_user - salto_site_user - latch_user - dormakaba_community_user - salto_space_user - avigilon_alta_user - kisi_user type: string external_type_display_name: description: >- Display name that corresponds to the brand-specific terminology for the [access system user](/low-level-apis/access-systems/user-management) type. type: string full_name: description: >- Full name of the [access system user](/low-level-apis/access-systems/user-management). minLength: 1 type: string hid_acs_system_id: description: ID of the HID access control system associated with the user. format: uuid type: string is_managed: description: Indicates whether Seam manages the access system user. enum: - true type: boolean is_suspended: description: >- Indicates whether the [access system user](/low-level-apis/access-systems/user-management) is currently [suspended](/low-level-apis/access-systems/user-management/suspending-and-unsuspending-users). type: boolean pending_mutations: description: >- Pending mutations associated with the [access system user](/low-level-apis/access-systems/user-management). Seam is in the process of pushing these mutations to the integrated access system. items: discriminator: propertyName: mutation_code oneOf: - description: >- Seam is in the process of pushing a user creation to the integrated access system. properties: created_at: description: Date and time at which the mutation was created. format: date-time type: string message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is in the process of pushing a user creation to the integrated access system. enum: - creating type: string required: - created_at - message - mutation_code type: object - description: >- Seam is in the process of pushing a user deletion to the integrated access system. properties: created_at: description: Date and time at which the mutation was created. format: date-time type: string message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is in the process of pushing a user deletion to the integrated access system. enum: - deleting type: string required: - created_at - message - mutation_code type: object - description: >- User exists in Seam but has not been pushed to the provider yet. Will be created when a credential is issued. properties: created_at: description: Date and time at which the mutation was created. format: date-time type: string message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is intentionally deferring the creation of the user on the access control system until the appropriate time. enum: - deferring_creation type: string scheduled_at: description: 'Optional: When the user creation is scheduled to occur.' format: date-time nullable: true type: string required: - created_at - message - mutation_code type: object - properties: created_at: description: Date and time at which the mutation was created. format: date-time type: string from: description: Old access system user information. properties: email_address: description: Email address of the access system user. format: email nullable: true type: string full_name: description: Full name of the access system user. nullable: true type: string phone_number: description: Phone number of the access system user. nullable: true type: string type: object message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is in the process of pushing updated user information to the integrated access system. enum: - updating_user_information type: string to: description: New access system user information. properties: email_address: description: Email address of the access system user. format: email nullable: true type: string full_name: description: Full name of the access system user. nullable: true type: string phone_number: description: Phone number of the access system user. nullable: true type: string type: object required: - created_at - message - mutation_code - from - to type: object - description: >- Seam is in the process of pushing an access schedule update to the integrated access system. properties: created_at: description: Date and time at which the mutation was created. format: date-time type: string from: description: Old access schedule information. properties: ends_at: description: Starting time for the access schedule. format: date-time nullable: true type: string starts_at: description: Starting time for the access schedule. format: date-time nullable: true type: string required: - starts_at - ends_at type: object message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is in the process of pushing updated access schedule information to the integrated access system. enum: - updating_access_schedule type: string to: description: New access schedule information. properties: ends_at: description: Starting time for the access schedule. format: date-time nullable: true type: string starts_at: description: Starting time for the access schedule. format: date-time nullable: true type: string required: - starts_at - ends_at type: object required: - created_at - message - mutation_code - from - to type: object - description: >- Seam is in the process of pushing a suspension state update to the integrated access system. properties: created_at: description: Date and time at which the mutation was created. format: date-time type: string from: description: Old user suspension state information. properties: is_suspended: type: boolean required: - is_suspended type: object message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is in the process of pushing updated user suspension state information to the integrated access system. enum: - updating_suspension_state type: string to: description: New user suspension state information. properties: is_suspended: type: boolean required: - is_suspended type: object required: - created_at - message - mutation_code - from - to type: object - description: >- Seam is in the process of pushing an access group membership update to the integrated access system. properties: created_at: description: Date and time at which the mutation was created. format: date-time type: string from: description: Old access group membership. properties: acs_access_group_id: description: Old access group ID. format: uuid nullable: true type: string required: - acs_access_group_id type: object message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is in the process of pushing updated access group membership information to the integrated access system. enum: - updating_group_membership type: string to: description: New access group membership. properties: acs_access_group_id: description: New access group ID. format: uuid nullable: true type: string required: - acs_access_group_id type: object required: - created_at - message - mutation_code - from - to type: object - description: >- A scheduled access group membership change is pending for this user. properties: acs_access_group_id: description: ID of the access group involved in the scheduled change. format: uuid type: string created_at: description: Date and time at which the mutation was created. format: date-time type: string message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that a scheduled access group membership change is pending for this user. enum: - deferring_group_membership_update type: string variant: description: >- Whether the user is scheduled to be added to or removed from the access group. enum: - adding - removing type: string required: - created_at - message - mutation_code - acs_access_group_id - variant type: object - description: >- Seam is in the process of assigning or unassigning a credential to the user on the integrated access system. properties: created_at: description: Date and time at which the mutation was created. format: date-time type: string from: description: Previous credential assignment. properties: acs_credential_id: description: Previous credential ID. format: uuid nullable: true type: string required: - acs_credential_id type: object message: description: Detailed description of the mutation. type: string mutation_code: description: >- Mutation code to indicate that Seam is in the process of assigning or unassigning a credential to the user on the integrated access system. enum: - updating_credential_assignment type: string to: description: New credential assignment. properties: acs_credential_id: description: New credential ID. format: uuid nullable: true type: string required: - acs_credential_id type: object required: - created_at - message - mutation_code - from - to type: object type: array phone_number: description: >- Phone number of the [access system user](/low-level-apis/access-systems/user-management) in E.164 format (for example, `+15555550100`). type: string salto_ks_metadata: description: >- Salto KS-specific metadata associated with the [access system user](/low-level-apis/access-systems/user-management). properties: is_subscribed: description: >- Indicates whether the user holds an active subscription slot on the Salto KS site. Only subscribed users can unlock doors and count against the site's user-subscription limit. A user may not be subscribed because their access schedule has not started or has ended, the site has reached its subscription limit, or they were manually unsubscribed. This is distinct from `is_suspended`, which reflects whether the user has been explicitly blocked. type: boolean type: object salto_space_metadata: description: >- Salto Space-specific metadata associated with the [access system user](/low-level-apis/access-systems/user-management). properties: audit_openings: description: >- Indicates whether AuditOpenings is enabled for the user in the Salto Space access system. type: boolean user_id: description: User ID in the Salto Space access system. type: string type: object user_identity_email_address: description: >- Email address of the user identity associated with the [access system user](/low-level-apis/access-systems/user-management). nullable: true type: string user_identity_full_name: description: >- Full name of the user identity associated with the [access system user](/low-level-apis/access-systems/user-management). nullable: true type: string user_identity_id: description: >- ID of the user identity associated with the [access system user](/low-level-apis/access-systems/user-management). type: string user_identity_phone_number: description: >- Phone number of the user identity associated with the [access system user](/low-level-apis/access-systems/user-management) in E.164 format (for example, `+15555550100`). nullable: true type: string warnings: type: array description: >- Warnings associated with the [access system user](/low-level-apis/access-systems/user-management). items: type: object properties: error_code: type: string description: Error or warning code. message: type: string description: Human-readable description. created_at: type: string format: date-time description: When this error or warning was generated. workspace_id: description: >- ID of the workspace that contains the [access system user](/low-level-apis/access-systems/user-management). format: uuid type: string required: - acs_user_id - acs_system_id - workspace_id - created_at - display_name - warnings - errors - connected_account_id - is_managed type: object x-route-path: /acs/users pagination: description: Information about the current page of results. properties: has_next_page: description: Indicates whether there is another page of results after this one. type: boolean next_page_cursor: description: >- Opaque value that can be used to select the next page of results via the `page_cursor` parameter. nullable: true type: string next_page_url: description: URL to get the next page of results. format: uri nullable: true type: string required: - next_page_cursor - has_next_page - next_page_url type: object securitySchemes: client_session: bearerFormat: Client Session Token scheme: bearer type: http pat_with_workspace: bearerFormat: API Token scheme: bearer type: http console_session_with_workspace: bearerFormat: Console Session Token scheme: bearer type: http api_key: bearerFormat: API Key scheme: bearer type: http support_read_only_token: bearerFormat: Support Read-Only Token scheme: bearer type: http ````