The Basic Update Process

You have a database of people that you want to use with DoorFlow and you want to use the API to update DoorFlow to match your database.

This example highlights a very simple update paradigm for one DoorFlow Group. For more advanced update mechanisms and when working with more than one DoorFlow Group, you will need to be careful about when to remove and when to delete people records.

If you need help at any point, please get in touch via email.

Overview of a simple update process

1. Request a full list of people
2. Create and Update
3. Cleanup

1. Request a full list of People

Understand what already exists

Before considering any updates you should understand the state of the DoorFlow account, and you can do this by calling:

GET /api/3/people.json

See the people endpoint for more information

The resulting data set is an array of Person objects within the DoorFlow account.

A Person only has two required fields first_name and last_name

In order to control a Person's access, consider using some of the following fields which can prove helpful:

• valid_from (as a DATE in ISO format)
• valid_to (as a DATE in ISO format)
• enabled (as a boolean)

valid_from and valid_to allow you to set a period of access. For example if you have a new employee starting 2 weeks from now, you can send them (or just prepare) their access card now, but only have it activate when they start.

Additionally when you're aware of someone leaving, you can elect to populate the valid_to field. When that day arrives, DoorFlow will consider that person inactive from that date.

enabled is a toggle that allows you to retain the data within DoorFlow, but prevent access. In this case data includes the data you set, but also meta data like photographs, access history or any manually entered field data that you don't remove via your integration.

Credentials

Credentials can be of many types - a card, a keyfob, pin, a multi-factor pin, a magstripe, a phone, a vehicle number plate or a QR code to name a few.

See the credential_types endpoint to determine which credentials are available for this account

A Person can have any number of credentials, but traditionally is given 3 by default:

• a card
• a key fob
• a pin

None of these fields are required, and you can use all 3 of these fields at the same time if you like, but please don't enter duplicate data across the fields.

In the case of most prox technologies these fields are generally numeric only. In the case of some sites using bespoke magstripe formats, these fields can contain alpha-numeric strings. For more information, please contact DoorFlow Support

There are many other fields that you might choose to update and further information can be found in People

2. Create and Update

Iterate through the data set and either Create or Update

Once you have a full list of people, compare the records in your database with those of DoorFlow. If no record exists create one and where a record already exists update the DoorFlow record.

When Creating or Updating, it's important that one system contains a common reference field. Typically you could choose to record the DoorFlow person_id into your own database or alternatively record your person-reference into DoorFlow.

If you choose to save your person-reference into DoorFlow, a good field to do this in is system_id. This is a special field included especially for this purpose and is not editable in the UI.

3. Cleanup

Iterate throught the data sets again and remove any that no longer match

Once you've created or updated the People records in DoorFlow you will then want to run through and compare one last time in order to delete any records that you no longer need.

---

Post Create, Update and Cleanup steps

Once DoorFlow has been updated, you need to do one last thing - call a Sync.

A Sync promotes any necessary changes to the Channels and typically takes a from a few seconds to a few minutes depending on the size of the account.

---

How often should I update?

How often you update DoorFlow is largely up to you, but please note that we reserve the right to rate-limit for over-use or abuse of the API - this is done automatically and if your requests are rate limited you'll receive a 429 response.

Typically in most cases updating in the manner described in the steps above is something that you might want to do every hour. If you have rapidly changing data, you might choose to run it more frequently or only during office hours.

Syncing more than once every 5 minutes is considered over-use. That said if this is important to you, please get in touch and we can work with you to find the best way to do what you need.

Remember that after you have updated the DoorFlow records, the Channels must Sync and this can take several minutes.