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:
Set up an and create a with the access_method set to card.
See the for your ACS provider to learn specific requirements, such as configuring entrances and access schedules.
See .
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 .
Use the /acs/encoders/encode_credential endpoint to encode the credential on the card, using the encoder that you have chosen.
See .
Confirm that the card was encoded successfully using polling or a .
See . Also, see a list of .
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.
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, save the acs_encoder_id of the chosen encoder for the next step.
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.
A card with an incompatible card format was placed on the encoder.
uncategorized_error
Any other encoding error.
Depending on your specific access control system, creating an ACS user or credential may require additional parameters. For details, see the for your ACS.
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 .
When you make an /acs/encoders/encode_credential request, Seam returns an . To confirm that the card encoding was successful, you can poll this action attempt, until its status becomes success.
To confirm successful encoding, you can use a to listen for an acs_credential.issued event that contains the acs_credential_id in the payload. If you are re-encoding a card, listen for acs_credential.reissued instead of acs_credential.issued.
