Managing ACS Users

Learn how to manage your ACS users to grant or revoke physical access for people.

An ACS user typically refers to an individual who requires access, like an employee or resident. Each user can possess multiple credentials that serve as their keys or identifiers for access. The type of credential can vary widely. For example, in the Salto system, a user can have a PIN code, a mobile app account, and a fob. In other platforms, it is not uncommon for a user to have more than one of the same credential type, such as multiple key cards. Additionally, these credentials can have a schedule or validity period.

This guide explains how to create and manage ACS users. Using the Access Control Systems API, you can automate issuing access to long-term tenants or visitors.

Before You Begin: Identify the ACS System ID

To add ACS users to your access control system, first retrieve the acs_system_id of the ACS that you want to configure. To retrieve the ACS details, use Get a System or List Systems. Then, continue to the remaining sections in this topic to learn how to manage ACS users.

Request:

seam.acs.systems.list()

Response:

[
  AcsSystem(
    acs_system_id='11111111-1111-1111-1111-111111111111',
    name='Visionline System',
    ...
  ),
  ...
]

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/acs/systems/list' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{}'

Response:

{
  "acs_systems": [
    {
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "name": "Visionline System",
      ...
    },
    ...
  ],
  "ok": true
}

Request:

await seam.acs.systems.list();

Response:

[
  {
    acs_system_id: '11111111-1111-1111-1111-111111111111',
    name: 'Visionline System',
    ...
  },
  ...
]

Request:

# Coming soon!

Response:

# Coming soon!

Request:

$seam->acs->systems->list();

Response:

[
  {
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "name": "Visionline System",
    ...
  },
  ...
]

Request:

seam.SystemsAcs.List();

Response:

{
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  "name": "Visionline System",
  ...
}
...

Request:

// Coming soon!

Response:

// Coming soon!

Request:

acs_systems, uErr := client.Acs.Systems.List(
  context.Background(), &acs.SystemsListRequest{},
)

Response:

{
  "acs_systems": [
    {
      "acs_system_id": "11111111-1111-1111-1111-111111111111",
      "name": "Visionline System",
      ...
    },
    ...
  ],
  "ok": true
}

Create an ACS User

To create an ACS user, provide the acs_system_id of the ACS system and the attributes of the user, such as the full_name, email_address, phone_number, and so on.

Also, if your ACS architecture supports access groups, you can also assign an ACS user to one or more access groups. To do so, when you create the user, include the IDs of the access group to which you want add the user. The acs_access_group_ids parameter accepts an array of strings.

In addition, if your ACS architecture supports assigning access schedules directly to ACS users, you can specify an access_schedule for the user, including a starts_at and ends_at date and time.

Further, you can use the user_identity_id parameter to associate a new ACS user with a user identity. You can use a user identity to link an ACS user with an app user in your system, such as a mobile access app user or an app user who needs access to multiple ACSs.

Request:

seam.acs.users.create(
  acs_system_id="11111111-1111-1111-1111-111111111111",
  user_identity_id="22222222-2222-2222-2222-222222222222",
  full_name="Jane Doe",
  email_address="jane@example.com",
  phone_number="+15555550101"
)

Response:

AcsUser(
  acs_user_id='33333333-3333-3333-3333-333333333333',
  full_name='Jane Doe',
  email_address='jane@example.com',
  phone_number='+15555550101',
  acs_system_id='11111111-1111-1111-1111-111111111111',
  ...
)

Request:

curl -X 'POST' \
  'https://connect.getseam.com/acs/users/create' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  "user_identity_id": "22222222-2222-2222-2222-222222222222",
  "full_name": "Jane Doe",
  "email_address": "jane@example.com",
  "phone_number": "+15555550101"
}'

Response:

{
  "acs_user": {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    "phone_number": "+15555550101",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    ...
  },
  "ok": true
}

Request:

await seam.acs.users.create({
  acs_system_id: "11111111-1111-1111-1111-111111111111",
  user_identity_id: "22222222-2222-2222-2222-222222222222",
  full_name: "Jane Doe",
  email_address: "jane@example.com",
  phone_number: "+15555550101"
});

Response:

{
  acs_user_id: '33333333-3333-3333-3333-333333333333',
  full_name: 'Jane Doe',
  email_address: 'jane@example.com',
  phone_number: '+15555550101',
  acs_system_id: '11111111-1111-1111-1111-111111111111',
  ...
}

Request:

# Coming soon!

Response:

# Coming soon!

Request:

$seam->acs->users->create(
  acs_system_id: "11111111-1111-1111-1111-111111111111",
  user_identity_id: "22222222-2222-2222-2222-222222222222",
  full_name: "Jane Doe",
  email_address: "jane@example.com",
  phone_number: "+15555550101"
);

Response:

{
  "acs_user_id": "33333333-3333-3333-3333-333333333333",
  "full_name": "Jane Doe",
  "email_address": "jane@example.com",
  "phone_number": "+15555550101",
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  ...
}

Request:

seam.UsersAcs.Create(
  acsSystemId: "11111111-1111-1111-1111-111111111111",
  userIdentityId: "22222222-2222-2222-2222-222222222222",
  fullName: "Jane Doe",
  emailAddress: "jane@example.com",
  phoneNumber: "+15555550101"
);

Response:

{
  "acs_user_id": "33333333-3333-3333-3333-333333333333",
  "full_name": "Jane Doe",
  "email_address": "jane@example.com",
  "phone_number": "+15555550101",
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  ...
}

Request:

// Coming soon!

Response:

// Coming soon!

Request:

acs_user, uErr := client.Acs.Users.Create(
  context.Background(), &acs.UsersCreateRequest{
    AcsSystemId: "11111111-1111-1111-1111-111111111111",
    UserIdentityId: api.String("22222222-2222-2222-2222-222222222222"),
    FullName: api.String("Jane Doe"),
    EmailAddress: api.String("jane@example.com"),
    PhoneNumber: api.String("+15555550101")
  },
)

Response:

{
  "acs_user": {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    "phone_number": "+15555550101",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    ...
  },
  "ok": true
}

List ACS Users

To list all ACS users within an acs_system, provide the acs_system_id of the ACS. You can also filter users by user_identity_id, user_identity_email_address, or user_identity_phone_number.

Request:

seam.acs.users.list(
  acs_system_id="11111111-1111-1111-1111-111111111111"
)

Response:

[
  AcsUser(
    acs_user_id='33333333-3333-3333-3333-333333333333',
    full_name='Jane Doe',
    email_address='jane@example.com',
    ...
  ),
  ...
]

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/acs/users/list' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "acs_system_id": "11111111-1111-1111-1111-111111111111"
}'

Response:

{
  "acs_users": [
    {
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "full_name": "Jane Doe",
      "email_address": "jane@example.com",
      ...
    },
    ...
  ],
  "ok": true
}

Request:

await seam.acs.users.list({
  acs_system_id: "11111111-1111-1111-1111-111111111111"
});

Response:

[
  {
    acs_user_id: '33333333-3333-3333-3333-333333333333',
    full_name: 'Jane Doe',
    email_address: 'jane@example.com',
    ...
  },
  ...
]

Request:

# Coming soon!

Response:

# Coming soon!

Request:

$seam->acs->users->list(
  acs_system_id: "11111111-1111-1111-1111-111111111111"
);

Response:

[
  {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    ...
  },
  ...
]

Request:

seam.UsersAcs.List(
  acsSystemId: "11111111-1111-1111-1111-111111111111"
);

Response:

{
  "acs_user_id": "33333333-3333-3333-3333-333333333333",
  "full_name": "Jane Doe",
  "email_address": "jane@example.com",
  ...
}
...

Request:

// Coming soon!

Response:

// Coming soon!

Request:

acs_users, uErr := client.Acs.Users.List(
  context.Background(), &acs.UsersListRequest{
    AcsSystemId: api.String("11111111-1111-1111-1111-111111111111"),
  },
)

Response:

{
  "acs_users": [
    {
      "acs_user_id": "33333333-3333-3333-3333-333333333333",
      "full_name": "Jane Doe",
      "email_address": "jane@example.com",
      ...
    },
    ...
  ],
  "ok": true
}

Get an ACS User

To get an ACS user, provide the acs_user_id of the user that you want to retrieve. These details include the contact details for the user, the user's access schedule, the associated user identity, if applicable, and so on.

Request:

seam.acs.users.get(
 acs_user_id="33333333-3333-3333-3333-333333333333"
)

Response:

AcsUser(
  acs_user_id='33333333-3333-3333-3333-333333333333',
  full_name='Jane Doe',
  email_address='jane@example.com',
  phone_number='+15555550100',
  acs_system_id='11111111-1111-1111-1111-111111111111',
  access_schedule={
    'starts_at': '2024-03-01T10:40:00.000Z',
    'ends_at': '2024-03-04T10:40:00.000Z'
  },
  user_identity_id='22222222-2222-2222-2222-222222222222',
  ...
)

Request:

# Use GET or POST.
curl -X 'GET' \
  'https://connect.getseam.com/acs/users/get' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "acs_user_id": "33333333-3333-3333-3333-333333333333"
}'

Response:

{
  "acs_user": {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    "phone_number": "+15555550100",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_schedule": {
      "starts_at": "2024-03-01T10:40:00.000Z",
      "ends_at": "2024-03-04T10:40:00.000Z"
    },
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    ...
  },
  "ok": true
}

Request:

await seam.acs.users.get({
  acs_user_id: "33333333-3333-3333-3333-333333333333"
});

Response:

{
  acs_user_id: '33333333-3333-3333-3333-333333333333',
  full_name: 'Jane Doe',
  email_address: 'jane@example.com',
  phone_number: '+15555550100',
  acs_system_id: '11111111-1111-1111-1111-111111111111',
  access_schedule: {
    "starts_at": "2024-03-01T10:40:00.000Z",
    "ends_at": "2024-03-04T10:40:00.000Z"
  },
  user_identity_id: '22222222-2222-2222-2222-222222222222',
  ...
}

Request:

# Coming soon!

Response:

# Coming soon!

Request:

$seam->acs->users->get(
  acs_user_id: "33333333-3333-3333-3333-333333333333"
);

Response:

{
  "acs_user_id": "33333333-3333-3333-3333-333333333333",
  "full_name": "Jane Doe",
  "email_address": "jane@example.com",
  "phone_number": "+15555550100",
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  "access_schedule": {
    "starts_at": "2024-03-01T10:40:00.000Z",
    "ends_at": "2024-03-04T10:40:00.000Z"
  },
  "user_identity_id": "22222222-2222-2222-2222-222222222222",
  ...
}

Request:

seam.AcsUsers.Get(
  acsUserId: "33333333-3333-3333-3333-333333333333"
);

Response:

{
  "acs_user_id": "33333333-3333-3333-3333-333333333333",
  "full_name": "Jane Doe",
  "email_address": "jane@example.com",
  "phone_number": "+15555550100",
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  "access_schedule": {
    "starts_at": "2024-03-01T10:40:00.000Z",
    "ends_at": "2024-03-04T10:40:00.000Z"
  },
  "user_identity_id": "22222222-2222-2222-2222-222222222222",
  ..
}

Request:

// Coming soon!

Response:

// Coming soon!

Request:

acs_user, uErr := client.Acs.Users.Get(
  context.Background(), &acs.UsersGetRequest{
    AcsUserId: "33333333-3333-3333-3333-333333333333",
  },
)

Response:

{
  "acs_user": {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "jane@example.com",
    "phone_number": "+15555550100",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    "access_schedule": {
      "starts_at": "2024-03-01T10:40:00.000Z",
      "ends_at": "2024-03-04T10:40:00.000Z"
    },
    "user_identity_id": "22222222-2222-2222-2222-222222222222",
    ...
  },
  "ok": true
}

Update an ACS User

To update an ACS user, provide the acs_user_id of the user that you want to update, along with the attributes that you want to modify, such as the contact details for the user or the user's access schedule.

Request:

seam.acs.users.update(
  acs_user_id="33333333-3333-3333-3333-333333333333",
  full_name="Jack Doe"
)

Response:

None

Request:

curl -X 'POST' \
  "https://connect.getseam.com/acs/users/update" \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "acs_user_id": "33333333-3333-3333-3333-333333333333",
  "full_name": "Jack Doe"
}'

Response:

{
  "ok": true
}

Request:

await seam.acs.users.update({
  acs_user_id: "33333333-3333-3333-3333-333333333333",
  full_name: "Jack Doe"
});

Response:

void

Request:

# Coming soon!

Response:

# Coming soon!

Request:

$seam->acs->users->update(
  acs_user_id: "33333333-3333-3333-3333-333333333333",
  full_name: "Jack Doe"
);

Response:

void

Request:

seam.UsersAcs.Update(
  acsUserId: "33333333-3333-3333-3333-333333333333",
  fullName: "Jack Doe"
);

Response:

void

Request:

// Coming soon!

Response:

// Coming soon!

Request:

acs_user, uErr := client.Acs.Users.Update(
  context.Background(), &acs.UsersUpdateRequest{
    AcsUserId: "33333333-3333-3333-3333-333333333333",
    FullName: api.String("Jack Doe"),
  },
)

Response:

{
  "acs_user": {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jack Doe",
    ...
  },
  "ok": true
}

Delete an ACS User

To delete an ACS user, provide the acs_user_id of the user that you want to delete.

Request:

seam.acs.users.delete(
  acs_user_id="33333333-3333-3333-3333-333333333333"
)

Response:

None

Request:

curl -X 'POST' \
  'https://connect.getseam.com/acs/users/delete' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "acs_user_id": "33333333-3333-3333-3333-333333333333"
}'

Response:

{
  "ok": true
}

Request:

await seam.acs.users.delete({
  acs_user_id: "33333333-3333-3333-3333-333333333333"
});

Response:

void

Request:

# Coming soon!

Response:

# Coming soon!

Request:

$seam->acs->users->delete(
  acs_user_id: "33333333-3333-3333-3333-333333333333"
);

Response:

void

Request:

seam.UsersAcs.Delete(
  acsUserId: "33333333-3333-3333-3333-333333333333"
);

Response:

void

Request:

// Coming soon!

Response:

// Coming soon!

Request:

deletion, uErr := client.Acs.Users.Delete(
  context.Background(), &acs.UsersDeleteRequest{
    AcsUserId: "33333333-3333-3333-3333-333333333333",
  },
)

Response:

{
  "ok": true
}

PreviousRetrieving ACS System Details NextSuspending and Unsuspending ACS Users

Last updated 1 month ago