People
A Person defines an access control participant. People represent real world users of the access control system.
When creating or updating a person you can provide the pin number as ****** and a unique random pin will be generated.
Updating credentials via the person object is only possible for simple credential types like cards, keyfobs and pins. For more advanced credentials, use the credentials endpoint
Listing people
Scopes required : account.person.readonly or account.person
Returns a list of all people in your account.
GET /api/3/people
Example Shell Request
$ curl -H "Content-Type:application/json" \
-H "Accept:application/json" \
https://api.doorflow.com/api/3/people
You can supply either the since or since_utc parameter to filter people by the updated_at field. The dates should be in ISO 8601 format. For instance, if you wanted to return all people updated since 9:00am on the 12th of May 2014 in your local time, you would perform the following request:
Optional parameters
You can additionally pass parameters in the URL to filter the list returned
| Parameter | Unique | Description |
|---|---|---|
| since | n/a | Any records updated since the date passed (assumes the timezone of the account) |
| since_utc | n/a | Any records updated since the date passed (assumes UTC) |
| Yes | The email address of a person | |
| system_id | Yes | The system_id is a special field that can only be set via the API |
For example to return all people that have been updated since 2014-05-12 at 9am:
GET /api/3/people.json?api_key=key&since=2014-05-12T09:00:00
The since_utc parameter will interpret the date as being in UTC time, whereas since will use your account's time zone.
Remember that this endpoint might be paginated
Requesting a single person
Scopes required : account.person.readonly or account.person
You can call a single person's record by passing the id of the record in the URL:
GET /api/3/people/:id
Example Response
[
{
"created_at": "2011-09-28T10:39:20Z",
"card": "3332",
"pin": "687687",
"email": "",
"enabled": true,
"first_name": "John",
"id": 26,
"last_name": "Smith",
"mobile": "",
"notes": "",
"telephone": "",
"organisation_id": "",
"system_id": "",
"updated_at": "2011-11-01T12:24:46Z",
"valid_from": "2011-11-01",
"valid_to": "2011-11-02",
"groups": [],
"roles": [],
"credentials": [
{
"id": 1000,
"credential_type_id": 3,
"label": "Pin",
"person_id": 2,
"value": "1266"
},
{
"id": 9900000180,
"person_id": 2,
"credential_type_id": 14,
"label": "HID Mobile Access",
"status": "invited",
"invitation_code": "AGEW-54UE-WRQQ-ATFA",
"invitation_expires_at": "2022-08-06T21:51:52+01:00"
}
]
}
]
Creating a person
Scopes required : account.person
POST /api/3/people
Example POST data
{
"first_name": "New",
"last_name": "User",
"pin": "******",
"enabled": true,
"mobile": "",
"notes": "",
"telephone": "",
"email": "",
"valid_from": "2011-11-01",
"valid_to": "2011-11-25",
"role_ids": [
1,
3
]
}
Only first_name and last_name are required. All others optional. You can supply any or all of:
- card
- key_fob_number
- pin
Note that the credentials fields you can use are defined in the credential_types endpoint
Updating a person
No required parameters.
PUT /api/3/people/:id
Example PUT data to update Role memberships:
{
"first_name": "Renamed",
"last_name": "User",
"credentials_number": "121212",
"image_remote_url": "http://www.gravatar.com/avatar",
"role_ids": [
1,
3
]
}
Example PUT data to update Group memberships:
{
"first_name": "Renamed",
"last_name": "User",
"credentials_number": "121212",
"image_remote_url": "http://www.gravatar.com/avatar",
"group_ids": [
4001,
4002
]
}
Deleting a person
Scopes required : account.person
DELETE /api/3/people/[user_id]
See also: Should I delete or disable a person record?
Adding or removing person images
Providing the person image as a URL
Scopes required : account.person
If you want to provide an image for the person as a URL you can use the image_remote_url attribute.
This will then download the image from the URL provided.
PUT /api/3/people/:id
Example POST data
{
"first_name": "New",
"last_name": "User",
"enabled": true,
"image_remote_url": "http://www.gravatar.com/avatar"
}
Removing the image for a person.
Provide a blank string for image_remote_url to remove the image associated with that person.
As with all attributes if you do not provide the image_remote_url attribute then no changes will be made to the image for that person
Invite to Passport
Scopes required : account.person
DoorFlow Passport is a service that allows anyone with a linked Passport account to gain access to doors on DoorFlow enabled sites via a mobile device.
Passport access must be enabled for your site, for the following to work properly.
There are obviously lots of restrictions in place and access is only allowed for those people that are bona-fide credential-holders of a respective site.
In order to use Passport, a person must have
- a Passport account
- been invited to a site by the site admin
A Passport account is available to anyone to sign up for:
You can invite a DoorFlow person to Passport by calling the invite method:
POST /api/3/people/26/passport_invite
NB: Please note that a valid email address must be entered in the email field of a DoorFlow Person for the invote to be successful.
On receiving the invitation, a person has the facility to either link to an existing Passport account or signup for a new one.
A Passport user only needs one Passport account to hold access to any DoorFlow sites that they have been invited to.
For more information about Passport, please drop an email to api@doorflow.com