Provision optical credentials

Third-party optical credentials — barcodes and QR codes — are decoded string values that your system creates and controls. You can add them to Kisi and assign them to users entirely through the API, with no physical card to encode or scan during setup.

info

Optical credentials are scanned at a Kisi Terminal Pro with the scanner module. For the product overview and hardware requirements, see Third-party optical credentials.

Create an optical credential

Send a POST request to the Create card endpoint with the decoded credential value.

Example

curl --request POST \
  --url https://api.kisi.io/cards \
  --header 'Accept: application/json' \
  --header 'Authorization: KISI-LOGIN <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "card": {
    "uid": "MEMBER-12345-ABCDE",
    "type": "third_party_barcode"
  }
}'

• uid - the decoded value of the barcode or QR code (up to 2000 characters)
• type - the optical credential type, either third_party_barcode or third_party_qr_code

note

The example above creates a barcode credential. To create a QR code credential instead, change type to third_party_qr_code.

Response

If your request was successful, you'll receive a 200 OK response with the created card object. Keep the id, since you'll need it to assign the credential to a user.

{
  "id": 0,
  "uid": "MEMBER-12345-ABCDE",
  "type": "third_party_barcode",
  "model": "credential-third-party-optical",
  "frequency": "optical",
  "third_party": true,
  "created_at": "2026-07-07T14:15:22Z"
}

Assign the credential to a user

Send a POST request to the Create card assignment endpoint to assign the credential to a user. Use the card id from the previous step and the user's ID.

Example

curl --request POST \
  --url https://api.kisi.io/card_assignments \
  --header 'Accept: application/json' \
  --header 'Authorization: KISI-LOGIN <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "card_assignment": {
    "assignee_type": "User",
    "assignee_id": 0,
    "card_id": 0
  }
}'

• assignee_type - the type of assignee. To assign the credential to a user, use User
• assignee_id - the id of the user you're assigning the credential to. To find a user's id, see Add or remove users
• card_id - the id of the card you created in the previous step

note

This endpoint replaces the deprecated POST /cards/{id}/assign action. It identifies the user by assignee_id, not by email.

Response

If your request was successful, you'll receive a 200 OK response with the created card assignment object.

{
  "id": 0,
  "resource_type": "CardAssignment",
  "created_at": "2026-07-08T14:15:22Z",
  "updated_at": "2026-07-08T14:15:22Z",
  "status": "activated",
  "two_factor_pin": null,
  "send_two_factor_pin_notification": false,
  "assignee_type": "User",
  "assignee_id": 0,
  "card_id": 0,
  "created_by_type": "User",
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "resource_type": "User",
    "email": "user@example.com",
    "name": "string"
  },
  "guest_id": null,
  "user_id": 0
}

On to the next step

Assigning a credential to a user does not grant access on its own. As with any Kisi user, access comes from group membership. To grant access, add the user to a group by following Assign access rights.