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.

Python

Request:

seam.acs.systems.list()

Response:

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

cURL (bash)

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
}

JavaScript

Request:

await seam.acs.systems.list();

Response:

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

Ruby

Request:

# Coming soon!

Response:

# Coming soon!

PHP

Request:

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

Response:

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

C#

Request:

seam.SystemsAcs.List();

Response:

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

Java

Request:

// Coming soon!

Response:

// Coming soon!

Go

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.

Python

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="[e-mail]",
  phone_number="[phone]"
)

Response:

AcsUser(
  acs_user_id='33333333-3333-3333-3333-333333333333',
  full_name='Jane Doe',
  email_address='[e-mail]',
  phone_number='[phone]',
  acs_system_id='11111111-1111-1111-1111-111111111111',
  ...
)

cURL (bash)

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": "[e-mail]",
  "phone_number": "[phone]"
}'

Response:

{
  "acs_user": {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "[e-mail]",
    "phone_number": "[phone]",
    "acs_system_id": "11111111-1111-1111-1111-111111111111",
    ...
  },
  "ok": true
}

JavaScript

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: "[e-mail]",
  phone_number: "[phone]"
});

Response:

{
  acs_user_id: '33333333-3333-3333-3333-333333333333',
  full_name: 'Jane Doe',
  email_address: '[e-mail]',
  phone_number: '[phone]',
  acs_system_id: '11111111-1111-1111-1111-111111111111',
  ...
}

Ruby

Request:

# Coming soon!

Response:

# Coming soon!

PHP

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: "[e-mail]",
  phone_number: "[phone]"
);

Response:

{
  "acs_user_id": "33333333-3333-3333-3333-333333333333",
  "full_name": "Jane Doe",
  "email_address": "[e-mail]",
  "phone_number": "[phone]",
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  ...
}

C#

Request:

seam.UsersAcs.Create(
  acsSystemId: "11111111-1111-1111-1111-111111111111",
  userIdentityId: "22222222-2222-2222-2222-222222222222",
  fullName: "Jane Doe",
  emailAddress: "[e-mail]",
  phoneNumber: "[phone]"
);

Response:

{
  "acs_user_id": "33333333-3333-3333-3333-333333333333",
  "full_name": "Jane Doe",
  "email_address": "[e-mail]",
  "phone_number": "[phone]",
  "acs_system_id": "11111111-1111-1111-1111-111111111111",
  ...
}

Java

Request:

// Coming soon!

Response:

// Coming soon!

Go

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("[e-mail]"),
    PhoneNumber: api.String("[phone]")
  },
)

Response:

{
  "acs_user": {
    "acs_user_id": "33333333-3333-3333-3333-333333333333",
    "full_name": "Jane Doe",
    "email_address": "[e-mail]",
    "phone_number": "[phone]",
    "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.

Python

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='[e-mail]',
    ...
  ),
  ...
]

cURL (bash)

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": "[e-mail]",
      ...
    },
    ...
  ],
  "ok": true
}

JavaScript

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: '[e-mail]',
    ...
  },
  ...
]

Ruby

Request:

# Coming soon!

Response:

# Coming soon!

PHP

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": "[e-mail]",
    ...
  },
  ...
]

C#

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": "[e-mail]",
  ...
}
...

Java

Request:

// Coming soon!

Response:

// Coming soon!

Go

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": "[e-mail]",
      ...
    },
    ...
  ],
  "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.

Python

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='[e-mail]',
  phone_number='[phone]',
  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',
  ...
)

cURL (bash)

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": "[e-mail]",
    "phone_number": "[phone]",
    "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
}

JavaScript

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: '[e-mail]',
  phone_number: '[phone]',
  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',
  ...
}

Ruby

Request:

# Coming soon!

Response:

# Coming soon!

PHP

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": "[e-mail]",
  "phone_number": "[phone]",
  "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",
  ...
}

C#

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": "[e-mail]",
  "phone_number": "[phone]",
  "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",
  ..
}

Java

Request:

// Coming soon!

Response:

// Coming soon!

Go

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": "[e-mail]",
    "phone_number": "[phone]",
    "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.

Python

Request:

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

Response:

None

cURL (bash)

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
}

JavaScript

Request:

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

Response:

void

Ruby

Request:

# Coming soon!

Response:

# Coming soon!

PHP

Request:

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

Response:

void

C#

Request:

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

Response:

void

Java

Request:

// Coming soon!

Response:

// Coming soon!

Go

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.

Python

Request:

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

Response:

None

cURL (bash)

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
}

JavaScript

Request:

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

Response:

void

Ruby

Request:

# Coming soon!

Response:

# Coming soon!

PHP

Request:

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

Response:

void

C#

Request:

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

Response:

void

Java

Request:

// Coming soon!

Response:

// Coming soon!

Go

Request:

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

Response:

{
  "ok": true
}