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.acs_user=$(curl-X'POST' \'https://connect.getseam.com/acs/users/create' \-H'accept: application/json' \-H"Authorization: Bearer ${SEAM_API_KEY}" \-H'Content-Type: application/json' \-d"{ \"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.# In allowed_entrance_ids, list the IDs of the entrances to# which you want to grant access.credential=$(curl-X'POST' \'https://connect.getseam.com/acs/credentials/create' \-H'accept: application/json' \-H"Authorization: Bearer ${SEAM_API_KEY}" \-H'Content-Type: application/json' \-d"{ \"acs_user_id\": \"$(jq-r '.acs_user.acs_user_id' <<<${acs_user})\", \"access_method\": \"card\", \"allowed_acs_entrance_ids\": [ \"${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.constacsUser=awaitseam.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.constcredential=awaitseam.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:newList<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.
