Some access control systems require encoding a plastic card credential with the data necessary to enable access. This process involves creating a credential with the required access permissions and then using a card encoder to write the credential to the card.
This process consists of the following basic steps:
Use the /acs/encoders/list endpoint to retrieve a list of available encoders. Then, choose the encoder that you want to use to write the credential to the card.
See Retrieve Encoders.
Use the /acs/encoders/encode_credential endpoint to encode the credential on the card, using the encoder that you have chosen.
See Encode the Card.
Once you have written a credential to a card, you cannot reuse the credential for another card. That is, you must create a separate credential for each card. However, you can reuse a card by re-encoding the card with a new credential.
1. Set Up an ACS User and Card Credential
This example shows how to create an ACS user and card-based credential. Note that the is_issued property of the resulting credential is false, which means the the credential is ready to be written to a card and has not yet been used to encode a card.
Depending on your specific access control system, creating an ACS user or credential may require additional parameters. For details, see the system integration guide for your ACS.
Code:
# Step 1:
# Create the new ACS user.
acs_user = seam.acs.users.create(
acs_system_id = "11111111-1111-1111-1111-111111111111",
full_name = "Jane Doe",
email_address = "jane@example.com"
)
# Step 2:
# Create a card-based credential for each entrance for the ACS user.
credential = seam.acs.credentials.create(
acs_user_id = acs_user.acs_user_id,
access_method = "card",
# List the IDs of the entrances to which
# you want to grant access.
allowed_acs_entrance_ids = [
room_101.seam_acs_entrance_id
],
starts_at = "2024-12-01T15:00:00.000Z",
ends_at = "2024-12-04T12:00:00.000Z"
)
// Step 1:
// Create the new ACS user.
const acsUser = await seam.acs.users.create({
acs_system_id: "11111111-1111-1111-1111-111111111111",
full_name: "Jane Doe",
email_address: "jane@example.com"
});
// Step 2:
// Create a card-based credential for each entrance for the ACS user.
const credential = await seam.acs.credentials.create({
acs_user_id: acsUser.acs_user_id,
access_method: "card",
allowed_acs_entrance_ids: [
// List the IDs of the entrances to which
// you want to grant access.
room101.seam_acs_entrance_id
],
starts_at: "2024-12-01T15:00:00.000Z",
ends_at: "2024-12-04T12:00:00.000Z"
});
# Step 1:
# Create the new ACS user.
acs_user = seam.acs.users.create(
acs_system_id: "11111111-1111-1111-1111-111111111111",
full_name: "Jane Doe",
email_address: "jane@example.com"
)
# Step 2:
# Create a card-based credential for each entrance for the ACS user.
credential = seam.acs.credentials.create(
acs_user_id: acs_user.acs_user_id,
access_method: "card",
# List the IDs of the entrances to which
# you want to grant access.
allowed_acs_entrance_ids: [
room_101.seam_acs_entrance_id
],
starts_at: "2024-12-01T15:00:00.000Z",
ends_at: "2024-12-04T12:00:00.000Z"
)
// Step 1:
// Create the new ACS user.
$acs_user = $seam->acs->users->create(
acs_system_id: "11111111-1111-1111-1111-111111111111",
full_name: "Jane Doe",
email_address: "jane@example.com"
);
// Step 2:
// Create a card-based credential for each entrance for the ACS user.
$credential = $seam->acs->credentials->create(
acs_user_id: $acs_user->acs_user_id,
access_method: "card",
allowed_acs_entrance_ids: [
// List the IDs of the entrances to which
// you want to grant access.
$room_101->seam_acs_entrance_id
],
starts_at: "2024-12-01T15:00:00.000Z",
ends_at: "2024-12-04T12:00:00.000Z"
);
// Step 1:
// Create the new ACS user.
AcsUser acsUser = seam.UsersAcs.Create(
acsSystemId: "11111111-1111-1111-1111-111111111111",
fullName: "Jane Doe",
emailAddress: "jane@example.com"
);
// Step 2:
// Create a card-based credential for each entrance for the ACS user.
AcsCredential credential = seam.CredentialsAcs.Create(
acsUserId: acsUser.acsUserId,
accessMethod: "card",
allowedAcsEntranceIds: new List<string>
{
// List the IDs of the entrances to which
// you want to grant access.
room_101.acsEntranceId
},
startsAt: "2024-12-01T15:00:00.000Z",
endsAt: "2024-12-04T12:00:00.000Z"
);
There may be multiple encoders at a location, so it’s important to select the right one to encode the credential.
This example shows how to retrieve all encoders in a building connected to a single ACS system. Once you've identified the encoder you'd like to use, grab the acs_encoder_id of the chosen encoder for the next step.
Once you issue a request to encode the credential onto the card, it is important to confirm that the encoding process completes successfully. You can use polling or a webhook.
Confirm Successful Encoding by Polling
When you make an /acs/encoders/encode_credential request, Seam returns an action attempt. To confirm that the card encoding was successful, you can poll this action attempt, until its status becomes success.
It is also useful to note that Seam assigns values to various card-related properties on the credential when the encoder has finished encoding the card. For example, acs_credential.is_issued becomes true, and acs_credential.card_number and acs_credential.issued_at receive values. You can retrieve the credential to view these properties.
