> ## Documentation Index > Fetch the complete documentation index at: https://docs.seam.co/llms.txt > Use this file to discover all available pages before exploring further. # List Access Groups > Returns a list of all [access groups](https://docs.seam.co/low-level-apis/access-systems/user-management/assigning-users-to-access-groups). ## OpenAPI ````yaml /openapi.json post /acs/access_groups/list openapi: 3.0.0 info: title: Seam Connect version: 1.0.0 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/access_groups/list: post: tags: - /acs summary: List Access Groups description: >- Returns a list of all [access groups](https://docs.seam.co/low-level-apis/access-systems/user-management/assigning-users-to-access-groups). operationId: acsAccessGroupsListPost requestBody: content: application/json: schema: properties: acs_system_id: description: >- ID of the access system for which you want to retrieve all access groups. format: uuid type: string acs_user_id: description: >- ID of the access system user for which you want to retrieve all access groups. format: uuid type: string search: description: >- String for which to search. Filters returned access groups to include all records that satisfy a partial match using `name` or `acs_access_group_id`. minLength: 1 type: string user_identity_id: description: >- ID of the user identity for which you want to retrieve all access groups. format: uuid type: string type: object responses: '200': content: application/json: schema: properties: acs_access_groups: items: $ref: '#/components/schemas/acs_access_group' type: array ok: type: boolean required: - acs_access_groups - ok type: object description: OK '400': description: Bad Request '401': description: Unauthorized security: - pat_with_workspace: [] - console_session_with_workspace: [] - api_key: [] x-codeSamples: - lang: javascript label: Seam SDK source: |- await seam.acs.accessGroups.list({ acs_system_id: "1b529056-1b04-450b-b3da-016b65a5017f", acs_user_id: "ebe506e1-33ba-44e8-892b-2d12c1709cd8", user_identity_id: "9b1deda4-07e2-4e90-acde-5724b6ab7305", }); /* [ { "access_group_type": "salto_ks_access_group", "access_group_type_display_name": "Salto KS Access Group", "acs_access_group_id": "3f448826-9875-4947-9519-e468090a4f7d", "acs_system_id": "1b529056-1b04-450b-b3da-016b65a5017f", "connected_account_id": "daba7bd0-edb6-4bb9-a70b-f9ae08a0e301", "created_at": "2025-06-15T16:54:17.946453Z", "display_name": "Main Group", "external_type": "salto_ks_access_group", "external_type_display_name": "Salto KS Access Group", "is_managed": true, "name": "My Access Group", "pending_mutations": [], "warnings": [], "workspace_id": "ac19352c-869a-4209-9ce7-44c740a8b5d0" } ] */ - lang: bash label: cURL source: >- curl --include --request POST "https://connect.getseam.com/acs/access_groups/list" \ --header "Authorization: Bearer $SEAM_API_KEY" \ --json @- < [ { "access_group_type" => "salto_ks_access_group", "access_group_type_display_name" => "Salto KS Access Group", "acs_access_group_id" => "3f448826-9875-4947-9519-e468090a4f7d", "acs_system_id" => "1b529056-1b04-450b-b3da-016b65a5017f", "connected_account_id" => "daba7bd0-edb6-4bb9-a70b-f9ae08a0e301", "created_at" => "2025-06-15T16:54:17.946453Z", "display_name" => "Main Group", "external_type" => "salto_ks_access_group", "external_type_display_name" => "Salto KS Access Group", "is_managed" => true, "name" => "My Access Group", "pending_mutations" => [], "warnings" => [], "workspace_id" => "ac19352c-869a-4209-9ce7-44c740a8b5d0", }, ] - lang: php label: Seam SDK source: |- $seam->acs->access_groups->list( acs_system_id: "1b529056-1b04-450b-b3da-016b65a5017f", acs_user_id: "ebe506e1-33ba-44e8-892b-2d12c1709cd8", user_identity_id: "9b1deda4-07e2-4e90-acde-5724b6ab7305", ); // [ [ "access_group_type" => "salto_ks_access_group", "access_group_type_display_name" => "Salto KS Access Group", "acs_access_group_id" => "3f448826-9875-4947-9519-e468090a4f7d", "acs_system_id" => "1b529056-1b04-450b-b3da-016b65a5017f", "connected_account_id" => "daba7bd0-edb6-4bb9-a70b-f9ae08a0e301", "created_at" => "2025-06-15T16:54:17.946453Z", "display_name" => "Main Group", "external_type" => "salto_ks_access_group", "external_type_display_name" => "Salto KS Access Group", "is_managed" => true, "name" => "My Access Group", "pending_mutations" => [], "warnings" => [], "workspace_id" => "ac19352c-869a-4209-9ce7-44c740a8b5d0", ], ]; - lang: bash label: Seam CLI source: >- seam acs access-groups list --acs_system_id "1b529056-1b04-450b-b3da-016b65a5017f" --acs_user_id "ebe506e1-33ba-44e8-892b-2d12c1709cd8" --user_identity_id "9b1deda4-07e2-4e90-acde-5724b6ab7305" # [ # { # "access_group_type": "salto_ks_access_group", # "access_group_type_display_name": "Salto KS Access Group", # "acs_access_group_id": "3f448826-9875-4947-9519-e468090a4f7d", # "acs_system_id": "1b529056-1b04-450b-b3da-016b65a5017f", # "connected_account_id": "daba7bd0-edb6-4bb9-a70b-f9ae08a0e301", # "created_at": "2025-06-15T16:54:17.946453Z", # "display_name": "Main Group", # "external_type": "salto_ks_access_group", # "external_type_display_name": "Salto KS Access Group", # "is_managed": true, # "name": "My Access Group", # "pending_mutations": [], # "warnings": [], # "workspace_id": "ac19352c-869a-4209-9ce7-44c740a8b5d0" # } # ] components: schemas: acs_access_group: description: >- Group that defines the entrances to which a set of users has access and, in some cases, the access schedule for these entrances and users. properties: access_group_type: deprecated: true enum: - pti_unit - pti_access_level - salto_ks_access_group - brivo_group - salto_space_group - dormakaba_community_access_group - dormakaba_ambiance_access_group - avigilon_alta_group type: string x-deprecated: Use `external_type`. access_group_type_display_name: deprecated: true type: string x-deprecated: Use `external_type_display_name`. access_schedule: description: '`starts_at` and `ends_at` timestamps for the access group''s 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_access_group_id: description: ID of the access group. format: uuid type: string acs_system_id: description: ID of the access control system that contains the access group. format: uuid type: string connected_account_id: description: >- ID of the [connected account](https://docs.seam.co/core-concepts/connected-accounts) that contains the access group. format: uuid type: string created_at: description: Date and time at which the access group was created. format: date-time type: string display_name: type: string errors: description: Errors associated with the `acs_access_group`. items: description: Error associated with the `acs_access_group`. discriminator: propertyName: error_code oneOf: - description: >- Indicates that the [access group](https://docs.seam.co/low-level-apis/access-systems/user-management/assigning-users-to-access-groups) was not created on the [access system](https://docs.seam.co/low-level-apis/access-systems). This is likely due to an internal unexpected error. Contact Seam [support](mailto:support@seam.co). properties: created_at: description: Date and time at which Seam created the error. format: date-time type: string error_code: description: >- Unique identifier of the type of error. Enables quick recognition and categorization of the issue. enum: - failed_to_create_on_acs_system type: string message: description: >- Detailed description of the error. Provides insights into the issue and potentially how to rectify it. type: string required: - created_at - message - error_code type: object type: array external_type: description: Brand-specific terminology for the access group type. enum: - pti_unit - pti_access_level - salto_ks_access_group - brivo_group - salto_space_group - dormakaba_community_access_group - dormakaba_ambiance_access_group - avigilon_alta_group type: string external_type_display_name: description: >- Display name that corresponds to the brand-specific terminology for the access group type. type: string is_managed: enum: - true type: boolean name: description: Name of the access group. type: string pending_mutations: description: >- Collection of pending mutations for the access group. Represents operations that have been requested but not yet completed on the integrated access system. items: discriminator: propertyName: mutation_code oneOf: - description: >- Seam is in the process of pushing an access group 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 an access group 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 an access group 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 an access group deletion to the integrated access system. enum: - deleting type: string required: - created_at - message - mutation_code type: object - description: >- This access group is scheduled for automatic deletion when its access window expires. 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 this access group is scheduled for automatic deletion when its access window expires. enum: - deferring_deletion type: string required: - created_at - message - mutation_code type: object - description: >- Seam is in the process of pushing an access group information 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 information. properties: name: description: Name of the access group. 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 access group information to the integrated access system. enum: - updating_group_information type: string to: description: New access group information. properties: name: description: Name of the access group. 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: Ending 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: Ending 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 user 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 user membership. properties: acs_user_id: description: Old user ID. format: uuid nullable: true type: string required: - acs_user_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 user membership information to the integrated access system. enum: - updating_user_membership type: string to: description: New user membership. properties: acs_user_id: description: New user ID. format: uuid nullable: true type: string required: - acs_user_id type: object required: - created_at - message - mutation_code - from - to type: object - description: >- Seam is in the process of pushing an entrance 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 entrance membership. properties: acs_entrance_id: description: Old entrance ID. format: uuid nullable: true type: string required: - acs_entrance_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 entrance membership information to the integrated access system. enum: - updating_entrance_membership type: string to: description: New entrance membership. properties: acs_entrance_id: description: New entrance ID. format: uuid nullable: true type: string required: - acs_entrance_id type: object required: - created_at - message - mutation_code - from - to type: object - description: >- A scheduled user membership change is pending for this access group. properties: acs_user_id: description: ID of the user 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 user membership change is pending for this access group. enum: - deferring_user_membership_update type: string variant: description: >- Whether the user is scheduled to be added to or removed from this access group. enum: - adding - removing type: string required: - created_at - message - mutation_code - acs_user_id - variant type: object type: array warnings: description: Warnings associated with the `acs_access_group`. items: description: Warning associated with the `acs_access_group`. oneOf: - description: >- An unknown issue occurred while syncing the state of this access group with the provider. This issue may affect the proper functioning of this access group. properties: created_at: description: Date and time at which Seam created the warning. format: date-time type: string message: description: >- Detailed description of the warning. Provides insights into the issue and potentially how to rectify it. type: string warning_code: description: >- Unique identifier of the type of warning. Enables quick recognition and categorization of the issue. enum: - unknown_issue_with_acs_access_group type: string required: - created_at - message - warning_code type: object - description: >- Indicates that the access group is being deleted from the access system. This is a temporary state, and the access group will be deleted shortly. properties: created_at: description: Date and time at which Seam created the warning. format: date-time type: string message: description: >- Detailed description of the warning. Provides insights into the issue and potentially how to rectify it. type: string warning_code: description: >- Unique identifier of the type of warning. Enables quick recognition and categorization of the issue. enum: - being_deleted type: string required: - created_at - message - warning_code type: object type: array workspace_id: description: >- ID of the [workspace](https://docs.seam.co/core-concepts/workspaces) that contains the access group. format: uuid type: string required: - acs_access_group_id - acs_system_id - workspace_id - connected_account_id - name - access_group_type - access_group_type_display_name - display_name - external_type - external_type_display_name - created_at - errors - warnings - pending_mutations - is_managed type: object x-route-path: /acs/access_groups securitySchemes: 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 ````