Sift API (1.0.0)

Download OpenAPI specification:Download

This page outlines usage of the Sift API for giving your applications programatic access to search and retrieve information about your organization's people. If you have any questions or feedback about this document or using our API, please email support@justsift.com

Access

Administrators for an organization's Sift instance have access to manage applications with access to their data. To read more about creating and managing applications and their associated permissions, see our help documentation. If you are a non-administrator with access to your organization's Sift directory and have a valid use case for the API, please reach out to one of your administrators to request access!

Authentication

After an administrator grants access to an application, a separate API Token will be created for accessing media and data (if permission is given). The media token will be appended as a query parameter on media URLs returned in data responses for convenience. The data token may not be sent as a query parameter. An API token should be provided as a Bearer token in the Authorization header

Authorization: Bearer {token}

Demo Data Access

If you would like to try using the API with sample data before provisioning an application in your instance, you may use the tokens provided below. Additionally, if you would like to log into our demo directory to compare your API responses against the familiar Sift interface, you may use username "apidemo@justsift.com" and password "DemoPass123". The experience will be read-only.

Token Type Secret Key
Data f132d7a1ee0141f698349cb8e0358e93
Media 99ce146b2e634cafb69ba799f96cea75

GraphQL API

Check out the GraphQL Playground for our GraphQL API documentation. You may access Docs and Schema using the controls on the right-hand side of the playground.

Note on Dynamic Schema

Because of the extensive customization ability of Sift, the GraphQL schema is dynamic based on the organization who is accessing the API. Therefore, you will need an API token to access the full docs and schema in the playground. The playground has been pre-populated with the Data token for the demo directory.

REST API

The remainder of this page documents our REST API. The base path is

https://api.justsift.com/v1

Note on Dynamic Request and Response properties

Although more uniform than the GraphQL schema, additional response properties and a couple of specific request properties are dynamic based on the organization. Most notably, person object responses contain a base set of standardized properties, but also contain additional properties for customized fields in Sift. You can retrieve more information related to these fields by retrieving the fields list. Instances of this dynamic behavior will also be documented in each individual case.

people

Get a person by id or email.

Retrieves a person by their unique id or email address. Standard properties are shown in the schema. Additional dynamic properties are also included. See the /fields route for more information about these properties.

Authorizations:
path Parameters
idOrEmail
required
string

The person's id or email address

Responses

Response Schema: application/json
required
object (PersonResponse)
id
required
string

The unique identifier

directoryId
required
string

The identifier of the person's directory

firstName
required
string

The person's first name

lastName
required
string

The person's last name

email
required
string

The person's email address

pictureUrl
string Nullable

If the person has a custom photo, then the custom photo, else the official photo

customPictureUrl
string Nullable

The person's custom photo

officialPictureUrl
string Nullable

The person's official photo

teamLeaderId
string

The identifier of the person's direct leader

isTeamLeader
boolean

true if the person has any direct reports, false otherwise

directReportCount
number

The number of direct reports the person has

totalReportCount
number

The number of total direct and indirect reports the person has

reportingPath
Array of strings

A collection of ids representing a person's "chain" of leaders, in hierarchy order, the first being the top of the org chart

property name*
any

Response samples

Content type
application/json
{
  • "data":
    {
    • "id": "string",
    • "directoryId": "string",
    • "firstName": "string",
    • "lastName": "string",
    • "email": "string",
    • "pictureUrl": "string",
    • "customPictureUrl": "string",
    • "officialPictureUrl": "string",
    • "teamLeaderId": "string",
    • "isTeamLeader": true,
    • "directReportCount": 0,
    • "totalReportCount": 0,
    • "reportingPath":
      [
      • "string"
      ]
    }
}

search

Perform a simple people search

Performs a simple search operation and returns a matching search result. Standard response properties are shown in the schema. Additional dynamic properties are also included. See the /fields route for more information about these properties.

Authorizations:
query Parameters
q
string

A generic term that searches against most fields. See the searchable property in the /fields response for an exact summary.

page
number >= 1
Default: 1

The page to retrieve

pageSize
number [ 0 .. 100 ]
Default: 10

The page size to retrieve

sortBy
string

The objectKey of a field to sort by

sortDirection
string
Enum: "asc" "desc"

The sort direction

orQuery
boolean

If set to true, will use OR for provided filters instead of AND

(fieldObjectKey)
string

Filters the search result. You may provide multiple parameters. The key of this parameter should be the objectKey of the field to filter on and the value should be an EXACT search term against that field. For example, ?department=Marketing will filter your result for people whos department is exactly marketing

Responses

Response Schema: application/json
required
Array of objects (PersonResponse)
required
object (PagingLinksResponse)
required
object

Response samples

Content type
application/json
{
  • "data":
    [
    • {
      • "id": "string",
      • "directoryId": "string",
      • "firstName": "string",
      • "lastName": "string",
      • "email": "string",
      • "pictureUrl": "string",
      • "customPictureUrl": "string",
      • "officialPictureUrl": "string",
      • "teamLeaderId": "string",
      • "isTeamLeader": true,
      • "directReportCount": 0,
      • "totalReportCount": 0,
      • "reportingPath":
        [
        • "string"
        ]
      }
    ],
  • "links":
    {
    • "next": "string",
    • "prev": "string",
    • "first": "string",
    • "last": "string"
    },
  • "meta":
    {
    • "totalLength": 0,
    • "pages":
      {
      • "next": 0,
      • "prev": 0,
      • "first": 0,
      • "last": 0,
      • "size": 0
      }
    }
}

Perform a complex people search

Performs a search operation and returns a matching search result. Standard response properties are shown in the schema. Additional dynamic properties are also included. See the /fields route for more information about these properties.

Authorizations:
Request Body schema: application/json

An object containing search parameters. The example on the right is: People whose profile contains anything with "Product" AND (who are in the "Business Development" department OR are located in "Detroit") AND have at least 5 direct reports

q
string

A generic term that searches against most fields. See the searchable property in the /fields response for an exact summary.

page
number (Page) >= 1
Default: 1

The page to retrieve

pageSize
number (PageSize) [ 0 .. 100 ]
Default: 10

The page size to retrieve

sortBy
string

The objectKey of a field to sort by

sortDirection
string
Enum: "asc" "desc"

The sort direction

PeopleFilterChild (object) or PeopleFilterAnd (object) or PeopleFilterOr (object) or PeopleFilterNot (object) (PeopleFilters)

Responses

Response Schema: application/json
required
Array of objects (PersonResponse)
required
object

Request samples

Content type
application/json
{
  • "q": "Product",
  • "page": 2,
  • "pageSize": 20,
  • "sortBy": "firstName",
  • "filter":
    {
    • "and":
      [
      • {
        • "or":
          [
          • {
            • "field": "department",
            • "comparison": "eq",
            • "value": "Business Development"
            },
          • {
            • "field": "officeCity",
            • "comparison": "eq",
            • "value": "Detroit"
            }
          ]
        },
      • {