API Documentation

Everything you need to interact with AccessGrid via API.

Install our SDK in your preferred language

Authentication

We use a dual authentication mechanism, it consists of two parts:

  1. A static account id to be sent in the X-ACCT-ID header
  2. A shared secret scheme to authenticate every API request with a signed payload in the X-PAYLOAD-SIG header

You can find both keys in your AccessGrid console on the API keys page. If you're logged in, they're automatically embedded into this documentation.

List NFC keys

Retrieve a list of NFC keys for a specific card template. You can optionally filter by current state.

template_id

string

All

Required. The card template ID to list keys for


state

nullable string

All

Filter keys by state (active, suspended, unlink, deleted)

Issue NFC key

Enable a pass to be added to be created and installed on their mobile device with the constraints set in the AccessGrid console and this API call. Returns a landing page for installing the access pass.

card_template_id

string

All

Unique identifier for the card template to use


employee_id

string

Corporate

Unique identifier for the employee


tag_id

nullable string

All

Tag identifier associated with the NFC key card, only allowed if your card template has key diversification enabled. Must be 7 bytes, 14 chars, ex: DF517FC87144DF


site_code

nullable string

All

Site code from H10301 (26 bit) format. Must be number under 255. Required if `file_data` not present.


card_number

string

All

Site code from H10301 (26 bit) format. Must be number under 65,535


file_data

nullable string

All

Up to 64 bytes of data. Only used when using your own proprietary data format


full_name

string

All

Full name of the NFC key card owner


email

nullable string

All

Email address of the NFC key card owner - if you have a SendGrid or Postmark integration, then we will send a text message on your behalf


phone_number

nullable string

All

Contact phone number for the NFC key card owner - if you have a Twilio integration, then we will send a text message on your behalf


classification

string

Corporate
Apple

Employment classification (e.g., full_time, contractor)


start_date

string

All

ISO8601 timestamp when the key card becomes active


expiration_date

string

All

ISO8601 timestamp when the key card expires


employee_photo

string

Corporate
Apple

Base64 encoded image of the employee


member_id

nullable string

Hotel
Apple

Only for 'hotel' use case. Loyalty/membership ID of the guest


membership_status

nullable string

Hotel
Apple

Only for 'hotel' use case. Status of the guest's membership


is_pass_ready_to_transact

nullable boolean

Hotel
Apple

Only for 'hotel' use case. Whether the pass is ready to be used for NFC transactions


tile_data

nullable object

Hotel

Only for 'hotel' use case. Data for the hotel tile display

checkInAvailableWindowStartDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone. Required if isCheckedIn is missing or false


checkInAvailableWindowEndDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone. Required if isCheckedIn is missing or false


checkInDateTime

nullable string

Hotel
Android

ISO8601 timestamp with timezone. Required if isCheckedIn is true


checkInURL

nullable string

Hotel
All

URL for remote check-in. Only used if isCheckedIn is missing or false


isCheckedIn

nullable boolean

Hotel
All

Whether the guest has checked in


numberOfRoomsReserved

nullable integer

Hotel
All

Number of rooms reserved. Must match the number of roomNumbers if both are present


roomNumbers

nullable array

Hotel
All

Array of room numbers. Must match the number of numberOfRoomsReserved if both are present


reservations

nullable object

Hotel
Apple

Only for 'hotel' use case. Data for the hotel reservation

checkInDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone. Required if isCheckedIn is true


isCheckedIn

nullable boolean

Hotel
Apple

Whether the guest has checked in


numberOfRoomsReserved

nullable integer

Hotel
Apple

Number of rooms reserved. Must match the number of roomNumbers if both are present


propertyLocation

nullable string

Hotel
Apple

Location of the property (e.g., 'Key West')


propertyName

nullable string

Hotel
Apple

Name of the property (e.g., 'Hyatt Centric Resort & Spa')


propertyMapUrl

nullable string

Hotel
Apple

URL to a map of the property


propertyCategory

nullable string

Hotel
Apple

Category of the property. If provided, must be 'travel'


restaurantVoucher

nullable string

Hotel
Apple

Optional voucher for restaurant services


reservationEndDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone for reservation end


reservationNumber

nullable string

Hotel
Apple

Confirmation number for the reservation


reservationStartDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone for reservation start


roomNumbers

nullable array

Hotel
Apple

Array of room numbers. Must match the number of numberOfRoomsReserved if both are present

Update NFC key

When you need to make an informational update to an NFC key such as name, photo, etc

card_id

string

All

Unique identifier of the NFC key card to update, sent as part of the URL


employee_id

nullable string

Corporate

Updated unique identifier for the employee


full_name

nullable string

All

Updated full name of the NFC key card owner


classification

nullable string

Corporate
Apple

Updated employment classification (e.g., full_time, contractor)


expiration_date

nullable string

All

Updated ISO8601 timestamp when the card expires


employee_photo

nullable string

Corporate
Apple

Updated base64 encoded image of the employee


is_pass_ready_to_transact

nullable boolean

Hotel
Apple

Only for 'hotel' use case. Whether the pass is ready to be used for NFC transactions


tile_data

nullable object

Hotel

Only for 'hotel' use case. Data for the hotel tile display

checkInAvailableWindowStartDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone. Required if isCheckedIn is missing or false


checkInAvailableWindowEndDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone. Required if isCheckedIn is missing or false


checkInDateTime

nullable string

Hotel
Android

ISO8601 timestamp with timezone. Required if isCheckedIn is true


checkInURL

nullable string

Hotel
All

URL for remote check-in. Only used if isCheckedIn is missing or false


isCheckedIn

nullable boolean

Hotel
All

Whether the guest has checked in


numberOfRoomsReserved

nullable integer

Hotel
All

Number of rooms reserved. Must match the number of roomNumbers if both are present


roomNumbers

nullable array

Hotel
All

Array of room numbers. Must match the number of numberOfRoomsReserved if both are present


reservations

nullable object

Hotel
Apple

Only for 'hotel' use case. Data for the hotel reservation

checkInDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone. Required if isCheckedIn is true


isCheckedIn

nullable boolean

Hotel
Apple

Whether the guest has checked in


numberOfRoomsReserved

nullable integer

Hotel
Apple

Number of rooms reserved. Must match the number of roomNumbers if both are present


propertyLocation

nullable string

Hotel
Apple

Location of the property (e.g., 'Key West')


propertyName

nullable string

Hotel
Apple

Name of the property (e.g., 'Hyatt Centric Resort & Spa')


propertyMapUrl

nullable string

Hotel
Apple

URL to a map of the property


propertyCategory

nullable string

Hotel
Apple

Category of the property. If provided, must be 'travel'


restaurantVoucher

nullable string

Hotel
Apple

Optional voucher for restaurant services


reservationEndDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone for reservation end


reservationNumber

nullable string

Hotel
Apple

Confirmation number for the reservation


reservationStartDateTime

nullable string

Hotel
Apple

ISO8601 timestamp with timezone for reservation start


roomNumbers

nullable array

Hotel
Apple

Array of room numbers. Must match the number of numberOfRoomsReserved if both are present

Suspend NFC key

When you need to temporarily disable an NFC key for a short period of time

card_id

string

All

Unique identifier of the NFC key card to suspend, sent as part of the URL

Resume NFC key

If you have previously suspended an NFC key, you can re-enable it with the resume action

card_id

string

All

Unique identifier of the NFC key card to resume, sent as part of the URL

Unlink NFC key

If you'd like to force the removal of an NFC key from it's current holder

card_id

string

All

Unique identifier of the NFC key card to unlink from its current holder, sent as part of the URL

Create Card Template Enterprise only

Contact Us

Only available for enterprise customers - allows you to create an empty card template using our console API.

name

string

All

The name to display for this card template in the AccessGrid console UI


platform

string

All

Must be one of `apple` or `google`


use_case

string

All

Must be `employee_badge` or `hotel`


protocol

string

Apple

Must be `desfire` or `seos` - HID Seos only available for enterprise customers


allow_on_multiple_devices

nullable boolean

All

False by default. Set to true if you'd like to enable the NFC key cards issued using this template to exist on multiple devices (think phone and watch)


watch_count

nullable integer

Apple

Only allowed to be set if `allow_on_multiple_devices` is set to true. Any number between 1-5 is acceptable.


iphone_count

nullable integer

Apple

Only allowed to be set if `allow_on_multiple_devices` is set to true. Any number between 1-5 is acceptable.


design

nullable object

All

Object representing card template design

background_color

nullable string

Apple

Must be a 6 character hexadecimal value for the background color of the template, in the event that there is no background_image provided, i.e. #FFFFFF


label_color

nullable string

Apple

Must be a 6 character hexadecimal value for the label color for the template, i.e. #000000


label_secondary_color

nullable string

Apple

Must be a 6 character hexadecimal value for the secondary label color for the template, i.e. #333333


background_image

nullable string

All

Base64 encoded image of the card templates background


logo_image

nullable string

All

Base64 encoded image of the card templates logo (located in the top left)


icon_image

nullable string

Apple

Base64 encoded image of the card templates icon (used in sharing and notifications)


support_info

nullable object

Apple

Information for users that shows up on the back of the NFC key card

support_url

nullable string

Apple

Shows on the back of the issued NFC key.


support_phone_number

nullable string

Apple

Shows on the back of the issued NFC key.


support_email

nullable string

Apple

Shows on the back of the issued NFC key.


privacy_policy_url

nullable string

Apple

Shows on the back of the issued NFC key.


terms_and_conditions_url

nullable string

Apple

Shows on the back of the issued NFC key.

Update Card Template Enterprise only

Contact Us

Only available for enterprise customers - allows you to update certain attributes of an existing card template using our console API.

card_template_id

string

All

The card template id you want to update


name

string

All

The name to display for this card template in the AccessGrid console UI


allow_on_multiple_devices

nullable boolean

All

False by default. Set to true if you'd like to enable the NFC key cards issued using this template to exist on multiple devices (think phone and watch)


watch_count

nullable integer

Apple

Only allowed to be set if `allow_on_multiple_devices` is set to true. Any number between 1-5 is acceptable.


iphone_count

nullable integer

Apple

Only allowed to be set if `allow_on_multiple_devices` is set to true. Any number between 1-5 is acceptable.


support_info

nullable object

Apple

Information for users that shows up on the back of the NFC key card

support_url

nullable string

Apple

Shows on the back of the issued NFC key.


support_phone_number

nullable string

Apple

Shows on the back of the issued NFC key.


support_email

nullable string

Apple

Shows on the back of the issued NFC key.


privacy_policy_url

nullable string

Apple

Shows on the back of the issued NFC key.


terms_and_conditions_url

nullable string

Apple

Shows on the back of the issued NFC key.

Read Card Template Enterprise only

Contact Us

Only available for enterprise customers - allows you to read basic info about an existing card template using our console API.

card_template_id

nullable string

All

Unique identifier for the card template to look up

Read Event Log Enterprise only

Contact Us

Only available for enterprise customers - allows you to read full event log for a given card template, including which passes were issued, how and by whom using our console API.

card_template_id

nullable string

All

Unique identifier for the card template to look up


filters

nullable object

All

Filters to reduce result size of event logs

device

nullable string

All

Must be either `mobile` or `watch`


start_date

nullable datetime

All

Must be in ISO8601 format


end_date

nullable datetime

All

Must be in ISO8601 format


event_type

nullable string

All

Must be either `issue`, `install`, `update`, `suspend`, `resume`, or `unlink`

© AccessGrid 2024
Privacy
Terms