API Resources

Author - Users API

Interfaces

Object Synopses

UserResponse

  • id Integer

    User id

  • uid String

    Unique login id

  • first_name String

    First name of user

  • last_name String

    Last name of user

  • email String

    Email of user

  • bio String

    Short bio (biography) of user

  • locale String

    The user’s language code

  • roles String[]

    Array of roles

  • name string

    Full name of user

  • avatar_url String

    URL to avatar image

  • deleted_at DateTime or null

    Date and time of deletion

  • updated_at DateTime

    Date and time of last update

  • unsubscribed Boolean

    Whether the user has unsubscribed from Bridge emails

  • hire_date Date

    Date that user was hired

  • job_title string

    Job title of user

  • links Object

    Provides links to additional detail in response object

  • meta Object

    Map of additional values

  • next_due_date DateTime or null

    Returned only if includes[]=course_summary was set in query string.

  • completed_courses_count Integer

    Returned only if includes[]=course_summary was set in query string.

  • manager_name String

    Returned only if includes[]=manager was set in query string.

  • manager_id Integer

    Returned only if includes[]=manager was set in query string.

  • current_session Object

    Returned only if includes[]=current_session was set in query string.

CustomFieldValueRequest

  • id String

    The custom field value to update. An id is required to update a currently existing value. If no id is included, a new custom field value object will be created, if possible.

  • custom_field_id String

    The custom field to which this value is attached.

  • value String

    The value to be displayed in the custom field.

Fetch all users

GET /api/author/users

This endpoint returns a list of extant (active, not deleted) users

Response Codes

  • 200 OK
  • 304 Not Modified

Parameters

  • sort String [ name, complete_courses_count, next_due_date ]

    Query parameter causes list to be returned in ascending order. Values may be prepended with - for descending order.

  • search String

    Finds users with matching values in first name, last name, uid, or email.

  • includes[] String [ course_summary, custom_fields ]

    Indicates additional information to be returned. Course_summary includes the next due date and completed courses count in the response, and custom_fields includes linked custom field values and custom fields in the response.

  • only_deleted Boolean

    Filters list to only include deleted users.

  • with_deleted Boolean

    Filters list to also include deleted users.

  • role String [ account_admin, admin, author ]

    Filters list to only include users with having role.

  • updated_after DateTime

    Filters list to only include users updated after the given RFC 3339 compliant timestamp.

  • created_after DateTime

    Filters list to only include users created after the given RFC 3339 compliant timestamp.

  • deleted_after DateTime

    Filters list to only include users deleted after the given RFC 3339 compliant timestamp.

  • updated_before DateTime

    Filters list to only include users updated before the given RFC 3339 compliant timestamp.

  • created_before DateTime

    Filters list to only include users created before the given RFC 3339 compliant timestamp.

  • deleted_before DateTime

    Filters list to only include users deleted before the given RFC 3339 compliant timestamp.

  • only_deleted Boolean

    Filters list to only include deleted users.

  • with_deleted Boolean

    Filters list to also include deleted users.

  • only_managers Boolean

    Filters list to only include users who are managers.

Example Response

{
  "meta": {
    "next": "http://bridge.bridgeapp.com/api/author/users?after=eyJ0eXAiOiJKV1QiLCJhSDiQQ"
  },
  "linked": {
    "custom_fields": [
      {
        "id": "1",
        "name": "Title"
      }
    ],
    "custom_field_values": [
      {
        "id": "2",
        "value": "Senator",
        "links": {
          "custom_field": {
            "id": "1",
            "type": "custom_fields"
          }
        }
      }
    ]
  },
  "users": [
    "{API::UserResponse}"
  ]
}

Fetch an existing user

GET /api/author/users/:id

This endpoint returns a user listing

Response Codes

  • 200 OK if the request was successful.

Parameters

  • id Integer Required

    The ID of an existing user. Alternatively, a user’s uid, prefixed with “uid:” or a user’s HRIS ID, prefixed with “hris:”.

  • includes[] String [ course_summary, custom_fields ]

    Indicates additional information to be returned. Course_summary includes the next due date and completed courses count in the response, and custom_fields includes linked custom field values and custom fields in the response.

Example Response

{
  "meta": {},
  "linked": {
    "custom_fields": [
      {
        "id": "1",
        "name": "Title"
      }
    ],
    "custom_field_values": [
      {
        "id": "2",
        "value": "Senator",
        "links": {
          "custom_field": {
            "id": "1",
            "type": "custom_fields"
          }
        }
      }
    ]
  },
  "users": [
    "{API::UserResponse}"
  ]
}

Update a user

PATCH /api/author/users/:id
PUT /api/author/users/:id

Response Codes

  • 200 OK if user was updated
  • 404 Not Found if user no longer exists

Parameters

  • id Integer Required

    The unique Bridge id of the user to update. Alternatively, a user’s uid, prefixed with “uid:”.

  • includes[] String [ course_summary, custom_fields ]

    Indicates additional information to be returned. Course_summary includes the next due date and completed courses count in the response, and custom_fields includes linked custom field values and custom fields in the response.

  • user[uid] String

    The ID/login for the user

  • user[first_name] String

    The user’s first name

  • user[last_name] String

    The user’s last name

  • user[bio] String

    The user’s bio

  • user[manager_id] String

    The user ID of the user’s manager. Alternatively, the manager’s uid, prefixed with “uid:”.

  • user[hire_date] String

    The user’s hire date, formatted YYYY-MM-DD

  • user[job_title] String

    The user’s job title

  • user[custom_field_values] CustomFieldValueRequest[]

    Values for custom fields.

Example Request

JSON cURL 
{
  "user":
  {
    "email": "hrh.leia.organa@alderaan-gov.com",
    "uid": "lorgana",
    "first_name": "Leia",
    "last_name": "Organa",
    "bio": "Loves pepperoni pizza with jalapeños and long walks on the beach.",
    "locale": "en",
    "manager_id": "uid:mmothma",
    "hire_date": "2015-01-31",
    "job_title": "Software Engineer",
    "custom_field_values": [
      "{API::CustomFieldValueRequest}"
    ]
  }
}
curl \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"user":{"email":"hrh.leia.organa@alderaan-gov.com","uid":"lorgana","first_name":"Leia","last_name":"Organa","bio":"Loves pepperoni pizza with jalapeños and long walks on the beach.","locale":"en","manager_id":"uid:mmothma","hire_date":"2015-01-31","job_title":"Software Engineer","custom_field_values":["{API::CustomFieldValueRequest}"]}}' \
  http://<bridge>/api/author/users/:id

Example Response

{
  "meta": {},
  "users": [
    "{API::UserResponse}"
  ]
}

Restore a user

POST /api/author/users/:id/restore

Response Codes

  • 200 OK if user was restored
  • 404 Not Found if user is not deleted
  • 422 Unprocessable Entity if user could not be restored

Parameters

  • id Integer Required

    The unique Bridge id of the user to restore. Alternatively, a user’s uid, prefixed with “uid:”.

  • includes[] String [ course_summary, custom_fields ]

    Indicates additional information to be returned. Course_summary includes the next due date and completed courses count in the response, and custom_fields includes linked custom field values and custom fields in the response.

Example Response

{
  "meta": {},
  "linked": {
    "custom_fields": [
      {
        "id": "1",
        "name": "Title"
      }
    ],
    "custom_field_values": [
      {
        "id": "2",
        "value": "Princess",
        "links": {
          "custom_field": {
            "id": "1",
            "type": "custom_fields"
          }
        }
      }
    ]
  },
  "users": [
    "{API::UserResponse}"
  ]
}