REST API

Using the Beekeeper API, you can synchronise users in bulk. 

Please visit our Developers Portal for information on how to structure and authenticate requests.

Like a regular CSV/Excel upload or FTP sync, this endpoint creates an import, which you can see in the admin dashboard, under Users > Imports.

Users are sent to the server as a multipart file, in JSON format (see below). They are then imported asynchronously.

File structure

The bulk import endpoint accepts a file which contains a JSON user object on every line. Each user object is structured as given in the code block below. Note that the structure of the ‘user_data’ object is identical to that of the /users endpoint.

User content:

{
  "type": "update|delete",
  "options": {
    "id_field": "name|email|tenantuserid", 
    "id_field_fallbacks": [
      "name|email|tenantuserid"
    ]
  }, 
  "user_data": {},
  "groups": []
}

File content:

{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": []}
...

Users are identified via the ‘id_field’ value. You can choose to identify a user via name, email or tenantuserid (an explanation of each is below). This field must be present in the ‘user_data’ object.

If the user cannot be matched according to the given id_field, it will be matched according to the id_field_fallbacks list, in order. The same values (name, email, tenantuserid) can be used for the id_field_fallbacks list, or the list can be left empty.

The cURL below shows the JSON user objects for create, update, suspend and delete, with the same Max Mustermann user as before:

curl -X POST -H "Authorization: Token <access_key>" \
-H "Content-Type: multipart/form-data; boundary=3d1a8e334ce84031bdce8eb049467620" \
-d '--3d1a8e334ce84031bdce8eb049467620
Content-Disposition: form-data; name="file"; filename="user_data.json"
Content-Type: application/json

{"type": "update", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_mustermann", "email": "max_mustermann@example.com", "custom_fields": [{"key": "firstname", "value": "Max"}, {"key": "lastname", "value": "Mustermann"}]}}
{"type": "update", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_mustermann", "tenantuserid": "max_1", "custom_fields": [{"key": "firstname", "value": "Maxine"}]}}
{"type": "update", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_musterman", "suspended":true}}
{"type": "delete", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_mustermann"}}

--3d1a8e334ce84031bdce8eb049467620--
' 'https://your-company.beekeeper.io/api/2/users/force-import'

To create/update users:

To create or update a user, set the type to ‘update’. If the user does not exist, it will be created automatically.

{
  "type": "update",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
    "email": "max_mustermann@example.com",
    "suspended": false,
    "custom_fields": [
      {
        "key": "firstname",
        "value": "Max"
      },
      {
        "key": "lastname",
        "value": "Mustermann"
      },
      {
        "key": "position",
        "value": "IT Support"
      },
    ]
  },
  "groups": [
    { "name": "Honeybees" }
  ]
}

To suspend users:

As before, include the ‘suspended=true’ field in the JSON user object.

{
  "type": "update",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
    "suspended": true
  }
}

To delete users:

Set the type to ‘delete’, and the user will be deleted.

{
  "type": "delete",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
  }
}

To add users to groups:

Set the type to ‘update’, and list all the names of the groups the user should belong to.

To remove a user from a group, simply do not include it in the list - the group memberships are overwritten every time.

{
  "type": "update",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
  },
  "groups": [
   { "name" : "Honeybees" },
   { "name": "Bumblebees" }
  ]
}

Locations

If you have Locations activated, then your users will be assigned to the default Location. However, you can assign them to other locations as well. As mentioned before in the user content and file content. Locations values are added as follow:

User content:

{
  "type": "update|delete",
  "options": {
    "id_field": "name|email|tenantuserid", 
    "id_field_fallbacks": [
      "name|email|tenantuserid"
    ]
  }, 
  "user_data": {},
  "groups": [],
  "locations": []
}

File content:

{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": [], "locations": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": [], "locations": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": [], "locations": []}
...

To add users to locations:

Set the type to 'update' and list all the unique names of the Locations, where the user should belong to. By default, all the users initially are assigned to the default location. One user can belong to many Locations.

{
  "type": "update",
  "options": {
  "id_field": "name"
 },
  "user_data": {
  "name": "max_mustermann",
 },
  "locations": [
   {"unique_name": "Asia"},
   {"unique_name": "America"}
 ]
}