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

REST API

The base path is

https://api.justsift.com/v1

Note on Dynamic Request and Response properties

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"
            }
          ]
        },
      • {
        • "field": "directReportCount",
        • "comparison": "gte",
        • "value": 5
        }
      ]
    }
}

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"
        ]
      }
    ],
  • "meta":
    {
    • "totalLength": 0,
    • "pages":
      {
      • "next": 0,
      • "prev": 0,
      • "first": 0,
      • "last": 0,
      • "size": 0
      }
    }
}

media

Retrieve photos for a person

Currently supported media types include profile and background photos. By default, the profile photo returned will prefer a custom photo over an official photo, if you need to specify this type, use the preferredType parameter

path Parameters
idOrEmail
required
string

The person's id or email address

mediaKind
required
string
Enum: "profile-photo" "background-photo"

The kind of media to retrieve

query Parameters
token
string

The image token. Can also be provided via the Authorization header

preferredType
string
Enum: "custom" "official"

A sub-type query for each media kind. If provided, allows a preference between custom or official profile photo

height
number <= 1000

The height of the image to return, defaults to the image's original height

width
number <= 1000

The width of the image to return, defaults to the image's original width

fit
string
Enum: "crop" "scale"

Responses

Response Schema: image/jpeg
string <binary>

Response samples

Content type
application/json
{
  • "errors":
    [
    • {
      • "statusCode": 0,
      • "message": "string"
      }
    ]
}

fields

Retrieve the list of person fields

Retrieves a list of fields associated to person profile information. This list is dynamic per organization.

Authorizations:

Responses

Response Schema: application/json
required
Array of objects (FieldResponse)
Array ()
id
required
string

The unique identifier

objectKey
required
string

The corresponding property name on the Person object

displayName
required
string

A short readable representation of the field

type
required
string

Describes the type of the field's value

filterable
required
boolean

Indicates whether the field may be filtered by in a search

searchable
required
boolean

Indicates whether the field is searched against in a generic term search

Response samples

Content type
application/json
{
  • "data":
    [
    • {
      • "id": "string",
      • "objectKey": "string",
      • "displayName": "string",
      • "type": "string",
      • "filterable": true,
      • "searchable": true
      }
    ]
}