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

Requests users within the branch the API token is created for. Filtering the response is possible by using the query parameters described below.

Query Parameters

limit number default: 100 The amount of users that should be returned.
offset number default: 0 Define an offset for getting the users starting at this number.
query string A string that is used for searching in any profile field available for users, such as firstname, lastname, or location.
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)$
status string default: activated The status of a user could be activated, pending, or deactivated. This query parameter could also contain multiple comma-separated values. For example status=activated,pending will query for all users that are activated or pending.

Responses

200 OK

Returns a list of users that are matching the query parameters. Each user in the response matches our user model.

Example:

{
  "total": 1,
  "limit": 100,
  "offset": 0,
  "data": [
    {
      "id": "5791e3ffd4c61f21c3df8b90",
      "externalID": "jd123",
      "firstName": "John",
      "lastName": "Doe",
      "publicEmailAddress": "john@doe.com",
      "gender": "male",
      "position": "Developer",
      "department": "Development & Research",
      "location": "Chemnitz",
      "phoneNumber": "+491234567890",
      "status": "activated",
      "role": {
        "type": "admin"
      },
      "created": "2016-07-22T09:14:39.146Z",
      "updated": "2016-08-16T15:15:45.668Z"
    }
  ]
}
401 Unauthorized

This may occur when a valid token is missing.

Example:

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

This may occur 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

Inviting new users. When using an email address, the user will receive an email to register with their desired organisation once.

Body

{
  "email": "foo@bar.de",
  "firstName": "Foo",
  "lastName": "Bar"
}

Responses

201 Created

The user has been successfully created. When using an email address within the user profile an email is sent to that address. Thus, the user can register using the link in the email. The response contains the URI of the newly created user in the HTTP Location header.

Example:

HTTP/1.1 201 CREATED
Location: https://backend.staffbase.com/api/users/5791e3ffd4c61f21c3df8b90
401 Unauthorized

This may occur when the token has not enough permissions to perform this action or a valid token is missing.

Example:

{
  "identifier": 40102,
  "statusCode": 401,
  "message": "This end point 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.

Example:

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

/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 if set the user’s externalID.

Responses

200 OK

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

Example:

{
  "id": "5791e3ffd4c61f21c3df8b90",
  "externalID": "jd123",
  "firstName": "John",
  "lastName": "Doe",
  "publicEmailAddress": "john@doe.com",
  "gender": "male",
  "position": "Developer",
  "department": "Development & Research",
  "location": "Chemnitz",
  "phoneNumber": "+491234567890",
  "status": "activated",
  "role": {
    "type": "admin"
  },
  "created": "2016-07-22T09:14:39.146Z",
  "updated": "2016-08-16T15:15:45.668Z"
}
401 Unauthorized

This may occur when a valid token is missing.

Example:

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

This may occur when the requested user does not exist.

Example:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "user",
  "type": "NotFoundException"
}

PUT

Updates a user’s profile by an incremental update.

URI Parameters

userId string required This could be either the user’s ID defined by the API or if set the user’s externalID.

Body

Contains the data as key-value-pairs that should be changed for the desired user. The content-type should be application/jsonapplication/x-www-form-urlencoded, or multipart/form-data.

Example application/json

{
  "externalID": "12345"
}

Responses

200 OK

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

401 Unauthorized

This may occur when the token has not enough permissions to perform this action or a valid token is missing.

Example:

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

This may occur when the requested user does not exist.

Example:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "user",
  "type": "NotFoundException"
}

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 if set the user’s externalID.

Responses

202 Accepted

The user has been successfully removed from the system.

401 Unauthorized

This may occur when the token has not enough permissions to perform this action or a valid token is missing.

Example:

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

This may occur 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 may occur when the requested user does not exist.

Example:

{
  "identifier": 40408,
  "statusCode": 404,
  "message": "user",
  "type": "NotFoundException"
}

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.

Example:

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