User API

User API

The Staffbase API is available under the URI https://backend.staffbase.com/api/. For sending requests to the resources described here please add the desired resource to the end of this base path, e.g. the absolute URI for the /users-resource will be https://backend.staffbase.com/api/users.

If your app is hosted on our German infrastructure, please use https://de.staffbase.com/api/ as base URI for all requests.

All end points for our User API require authentication. To learn how authentication works with the Staffbase API please consider the authentication section.

/users

GET

Returns a list of the users for the API token's branch.

Query Parameters

query string 

A string that is used for searching in any profile field available for users, such as firstname, lastname, or location. You can combine this with the filter parameter if needed.

filter string 

Content filter in SCIM notation. You can combine this with the query parameter if needed. Available properties to filter: groups, externalId, staffbase.creationType, staffbase.invitorType, staffbase.role, staffbase.status and staffbase.space. For the following properties only the existence check 'present' is allowed: emails, userName, password and staffbase.recoveryCode. The staffbase.role parameter can be one of the following: admin, managingEditor, moderator, reader. For the property 'staffbase.status' the value can be activated, pending, or deactivated. If no value is provided 'activated' be used as default value. The staffbase.space parameter can be used to search for users within a space. Currently only the operator 'eq' is allowed.

limit number  default: 100

The amount of items that should be returned.

offset number  default: 0

Define an offset for getting the items starting at this number.

sort string  default: lastName_ASC_firstName_ASC

The sort parameter can sort the request regarding two parameters following this regex: ^\w_(ASC|DESC)_\w_(ASC|DESC)$

Responses

200 OK

Returns a list of users matching the query and/or filter parameters. Each user in the response matches our user model.

Example:

{
                "total": 1,
                "limit": 100,
                "offset": 0,
                "data": [
                  {
                    "id": "20e6504df8a90a4345aa4b49",
                    "externalID": "jd123",
                    "firstName": "John",
                    "lastName": "Doe",
                    "publicEmailAddress": "john@doe.com",
                    "config": {
                      "locale": "en_US"
                    },
                    "emails": [
                      {
                        "value": "john@doe.com",
                        "primary": true,
                        "providerID": "staffbase"
                      }
                    ],
                    "groupIDs": [
                      "c69e7b20e6504345aa4b4938",
                      "9e7b20e6504dfa90a4345aa3"
                    ],
                    "mandatoryGroupIDs": [
                      "c69e7b20e6504345aa4b4938"
                    ],
                    "position": "Developer",
                    "department": "Development & Research",
                    "location": "Chemnitz",
                    "phoneNumber": "+491234567890",
                    "status": "activated",
                    "role": {
                      "type": "admin"
                    },
                    "created": "2018-07-22T09:14:39.146Z",
                    "updated": "2018-08-16T15:15:45.668Z",
                    "activated" : "2018-07-28T06:49:15.462Z"
                  }
                ]
              }
              
401 Unauthorized

This occurs when a valid token is missing.

Example:

{
                "identifier": 40102,
                "statusCode": 401,
                "message": "This endpoint requires authentication.",
                "type": "NotLoggedInException"
              }
              
403 Forbidden

This occurs when the used token has not the required permissions to perform this action.

Example:

{
                "identifier": 40308,
                "statusCode": 403,
                "message": "Access to branch 'null' is restricted.",
                "type": "AccessDeniedException"
              }
              

POST

Invites new users to the API token's branch. To invite a user, use an email address and set the parameter sendMail to true. The user will receive an email to signup in the app.

Body

Content-type: application/json

Example:

{
                "email": "john@doe.com",
                "firstName": "John",
                "lastName": "Doe"
              }
              

Responses

201 Created

The user has been successfully created. To invite a user, define an email address and set the parameter sendMail to true. The user will receive an email with a link that leads to the signup in the app. The response contains the URI of the newly created user in the HTTP Location header.

Examples


              HTTP/1.1 201 Created
              Location: https://backend.staffbase.com/api/users/5784adb377c875f663918176
401 Unauthorized

This occurs when a valid token is missing.

Example:

{
                "identifier": 40102,
                "statusCode": 401,
                "message": "This endpoint requires authentication.",
                "type": "NotLoggedInException"
              }
              

OPTIONS

Requests meta data for the resource to provide information which operations are allowed or not.

Responses

204 No Content

The response contains the HTTP Allow header that defines which HTTP operation is allowed for the desired operation.

Examples


              HTTP/1.1 204 No Content
              Allow: OPTIONS,HEAD,POST,GET
401 Unauthorized

This occurs when a valid token is missing.

Example:

{
                "identifier": 40102,
                "statusCode": 401,
                "message": "This endpoint requires authentication.",
                "type": "NotLoggedInException"
              }
              

/users/{userID}

GET

Requests a specific user that is identified by his userID.

URI Parameters

userID string  required

This could be either the user's ID defined by the API or the externalID of the user, if it is set.

Responses

200 OK

Returns the user that was requested. The response follows our user model.

Example:

{
                  "id": "20e6504df8a90a4345aa4b49",
                  "externalID": "jd123",
                  "firstName": "John",
                  "lastName": "Doe",
                  "publicEmailAddress": "john@doe.com",
                  "config": {
                    "locale": "en_US"
                  },
                  "emails": [
                    {
                      "value": "john@doe.com",
                      "primary": true,
                      "providerID": "staffbase"
                    }
                  ],
                  "groupIDs": [
                    "c69e7b20e6504345aa4b4938",
                    "9e7b20e6504dfa90a4345aa3"
                  ],
                  "mandatoryGroupIDs": [
                    "c69e7b20e6504345aa4b4938"
                  ],
                  "position": "Developer",
                  "department": "Development & Research",
                  "location": "Chemnitz",
                  "phoneNumber": "+491234567890",
                  "status": "activated",
                  "role": {
                    "type": "admin"
                  },
                  "created": "2018-07-22T09:14:39.146Z",
                  "updated": "2018-08-16T15:15:45.668Z",
                  "activated" : "2018-07-28T06:49:15.462Z"
                }
                
401 Unauthorized

This occurs when a valid token is missing.

Example:

{
                  "identifier": 40102,
                  "statusCode": 401,
                  "message": "This endpoint requires authentication.",
                  "type": "NotLoggedInException"
                }
                
403 Forbidden

This occurs when the used token has not the required permissions to perform this action.

Example:

{
                  "identifier": 40308,
                  "statusCode": 403,
                  "message": "Access to branch 'null' is restricted.",
                  "type": "AccessDeniedException"
                }
                
404 Not found

This occurs when the requested resource does not exist.

Example:

{
                  "identifier": 40408,
                  "statusCode": 404,
                  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
                  "type": "NotFoundException"
                }
                

OPTIONS

Requests meta data for the resource to provide information which operations are allowed or not.

URI Parameters

userID string  required

This could be either the user's ID defined by the API or the externalID of the user, if it is set.

Responses

204 No Content

Examples


                HTTP/1.1 204 No Content
                Allow: GET, PUT, DELETE

DELETE

Removes a user from the system.

URI Parameters

userID string  required

This could be either the user's ID defined by the API or the externalID of the user, if it is set.

Responses

202 Accepted

The user has been successfully removed from the system.

401 Unauthorized

This occurs when a valid token is missing.

Example:

{
                  "identifier": 40102,
                  "statusCode": 401,
                  "message": "This endpoint requires authentication.",
                  "type": "NotLoggedInException"
                }
                
403 Forbidden

This occurs when the used token has not the required permissions to perform this action.

Example:

{
                  "identifier": 40308,
                  "statusCode": 403,
                  "message": "Access to branch 'null' is restricted.",
                  "type": "AccessDeniedException"
                }
                
404 Not found

This occurs when the requested resource does not exist.

Example:

{
                  "identifier": 40408,
                  "statusCode": 404,
                  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
                  "type": "NotFoundException"
                }
                
405

Your branch needs at least one admin.

PUT

Updates a user by an incremental update.

URI Parameters

userID string  required

This could be either the user's ID defined by the API or the externalID of the user, if it is set.

Body

Content-type: application/json

Example:

{
                  "externalID": "12345",
                  "userName": "JohnDoe"
                }
                

Responses

200 OK

Returns the updated user resource. The response follows our user model.

Example:

{
                  "id": "20e6504df8a90a4345aa4b49",
                  "externalID": "jd123",
                  "firstName": "John",
                  "lastName": "Doe",
                  "publicEmailAddress": "john@doe.com",
                  "config": {
                    "locale": "en_US"
                  },
                  "emails": [
                    {
                      "value": "john@doe.com",
                      "primary": true,
                      "providerID": "staffbase"
                    }
                  ],
                  "groupIDs": [
                    "c69e7b20e6504345aa4b4938",
                    "9e7b20e6504dfa90a4345aa3"
                  ],
                  "mandatoryGroupIDs": [
                    "c69e7b20e6504345aa4b4938"
                  ],
                  "position": "Developer",
                  "department": "Development & Research",
                  "location": "Chemnitz",
                  "phoneNumber": "+491234567890",
                  "status": "activated",
                  "role": {
                    "type": "admin"
                  },
                  "created": "2018-07-22T09:14:39.146Z",
                  "updated": "2018-08-16T15:15:45.668Z",
                  "activated" : "2018-07-28T06:49:15.462Z"
                }
                
401 Unauthorized

This occurs when a valid token is missing.

Example:

{
                  "identifier": 40102,
                  "statusCode": 401,
                  "message": "This endpoint requires authentication.",
                  "type": "NotLoggedInException"
                }
                
403 Forbidden

This occurs when the used token has not the required permissions to perform this action.

Example:

{
                  "identifier": 40308,
                  "statusCode": 403,
                  "message": "Access to branch 'null' is restricted.",
                  "type": "AccessDeniedException"
                }
                
404 Not found

This occurs when the requested resource does not exist.

Example:

{
                  "identifier": 40408,
                  "statusCode": 404,
                  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
                  "type": "NotFoundException"
                }
                

/users/recovery

POST

Will send a recovery email to the specified user.

Responses

202 Accepted

The recovery mail was successfully sent to the user.

400

Password recovery is not possible for this user. This happens when the user has no email address set or when the app configuration doesn't allow password recovery.

401 Unauthorized

This occurs when a valid token is missing.

Example:

{
                  "identifier": 40102,
                  "statusCode": 401,
                  "message": "This endpoint requires authentication.",
                  "type": "NotLoggedInException"
                }
                
404 Not found

This occurs when the requested resource does not exist.

Example:

{
                  "identifier": 40408,
                  "statusCode": 404,
                  "message": "User '5791e3ffd4c61f21c3df8b9' could not be found.",
                  "type": "NotFoundException"
                }