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
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!
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}
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 |
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.
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.
idOrEmail required | string The person's id or email address |
required | object (PersonResponse) | ||||||||||||||||||||||||||||
|
{- "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"
]
}
}
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.
q | string A generic term that searches against most fields. See the |
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 |
required | Array of objects (PersonResponse) |
required | object (PagingLinksResponse) |
required | object |
{- "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
}
}
}
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.
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 |
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) |
required | Array of objects (PersonResponse) |
required | object |
{- "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
}
]
}
}
{- "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
}
}
}
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
idOrEmail required | string The person's id or email address |
mediaKind required | string Enum: "profile-photo" "background-photo" The kind of media to retrieve |
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" |
{- "errors": [
- {
- "statusCode": 0,
- "message": "string"
}
]
}
Retrieves a list of fields associated to person profile information. This list is dynamic per organization.
required | Array of objects (FieldResponse) | ||||||||||||
Array ()
|
{- "data": [
- {
- "id": "string",
- "objectKey": "string",
- "displayName": "string",
- "type": "string",
- "filterable": true,
- "searchable": true
}
]
}