Welcome to the documentation for the SCIM API. This documentation describes the functionality available only in the current versions of API methods. You can also review the documentation for all API methods for information about both current and deprecated API methods.
The System for Cross-domain Identity Management (SCIM) is a specification designed to make it easier to manage user identities in cloud-based applications and services. By setting up SCIM integration with your Quip site, you can make employee access changes in an identity service (like Okta, Active Directory, or OneLogin), and those changes will propagate to the employees' Quip accounts.
Specifically, that means you can automate the following processes:
Quip supports SCIM integration using either version 1.1 or version 2.0 (preferred) of the specification, with some limitations - see Limitations and Known Issues below. Quip decides what version to use based on the request path: paths containing "/2" use version 2.0, while paths containing "/1" use version 1.1.
Operations for SCIM v1.1. For reference, general SCIM v1.1 specifications can be found here:
Operations for SCIM v2.0. For reference, general SCIM v2.0 specifications can be found here:
Quip's APIs have rate limits to help ensure fair and reliable access to APIs for all of our customers.
Quip's APIs are also subject to a per-company rate limit with a default of 600 requests per minute. The API responses include these custom headers to help developers implement backoffs in their code:
X-Scim-RateLimit-Limit
: The number of requests per minute that your company can makeX-Scim-RateLimit-Remaining
: The number of requests remaining for your company within the minuteX-Scim-RateLimit-Reset
: The UTC timestamp for when the rate limit resetsX-Scim-Retry-After
: The number of seconds after which your company can make API calls againAuthorization tokens are only available for Quip Enterprise customers.
To get an authorization token, head over to:
{yourcompany}.quip.com/business/admin/scim
Note that:
Authorization: Bearer {your token}
.userName
field is set by Quip and may
not be modified. If a request attempts to specify the userName
field,
that portion of the request will be ignored. If the request would be
otherwise successful, or if that was the only modification requested,
the request will return as successful. Note that this failure behavior
may change in future releases. (When integrating with Active Directory,
we have seen AD make PATCH
requests that attempt to update this field.
The failure of these requests may cause problems.)givenName
, familyName
, and formatted
are not
stored as separate fields. The value of formatted is always the same as
givenName
, followed by a space, followed by familyName
.externalId
attribute.GET /Groups
does not support sorting or filtering.roles
field has been deprecated and shouldn’t be used in the SCIM requests.
To adjust admin roles for users, please review the Admin API documentation.PATCH
operation is not supported for the /Users
resource.PATCH /Users/:userId
can be used to update the primary email.PATCH
operation is not supported for the /Groups
resource.PATCH /2/Users
, paths with expressions are not supported. e.g.
no path: email[value sw foo]
This section gives information on how to perform common operations.
To perform any operations on a user, first you will need to know its user ID. This is the unique ID of the user in the Quip system, and it will be different from the ID used in an external system. You can use the Get Users API to do this. Some examples:
GET /2/Users
GET /2/Users?count=10
GET /2/Users?count=10&startIndex=11
GET /2/Users?filter=emails+eq+test@hello.com
GET /2/Users?filter=externalid+eq+1234ABCD
Once you have a user ID, you can use the Update User, Patch User, or Disable User Account operation to make changes. See those specific API descriptions for more details.
To disable active user sessions, you can call V2 Patch User twice in
succession, once to set active
to false
, and again to set active
to true
.
If there's an existing disabled account that has an email that you want to assign to a new account, because the new person with that email is different from the old, you will need to modify the old account. One way to do this is:
GET /2/Users?filter=emails+eq+test@hello.com
This API call is used to get information about current Quip user accounts.
This call can be performed with no parameters, in which case all users
will be returned, or with a "filter" parameter, which limits the response
to a subset of the current users. (Note: if you have a lot of users, you
probably don't want to call this without a "count").
Deactivated users willl be returned from some calls and not others.
filter | string Example: filter=emails co @hello.com Returned users will be limited to those that match the specified filter. The service supports a subset of the behavior described here in the SCIM v1.1 specification. A filter expression must be of the format "< attribute > < operator > < value >". The following attributes are supported:
The full list of operators from Section 3.2.2.1 of the SCIM v1.1 specification is supported, with the exception of the "is present" operator "pr". |
count | integer Example: count=1 Limits the number of results returned. |
startIndex | integer Example: startIndex=2 1-based index used with "count" to fetch results in a paged fashion |
sortBy | string Example: sortBy=emails Indicates the field used to sort results. The following values are supported:
|
sortOrder | string Example: sortOrder=ascending Indicates the direction of sorting. May be "ascending" or "descending"; if not present, the sort will be ascending. |
{- "Resources": [
- {
- "active": true,
- "emails": [
- "test@hello.com"
], - "id": "atestuserid",
- "name": {
- "familyName": "User",
- "formatted": "Test User",
- "givenName": "Test"
}, - "schemas": [
- "urn:scim:schemas:core:1.0"
], - "userName": "atestuserid",
}
], - "itemsPerPage": 1,
- "startIndex": 1,
- "totalResults": 22,
- "schemas": [
- "urn:scim:schemas:core:1.0"
]
}
This API call is used to set up a new Quip user account.
When creating credentials in your identity service for a new employee, you can use
this call to automatically set up a new Quip account for that user.
If you attempt to create a user who has an email that is already associated with an active user at your site, the operation will fail with HTTP status code 409 (Conflict).
If you attempt to create a user who has an email that is already associated
with a deactivated user at your site, the prior user will be reactivated
by providing active
parameter. Other information from your request
will be ignored.
required | formatted_name (string) or json_name (object) Specifies the name for the user to be created. Must be a string containing the full name, or a JSON dictionary containing the key "formatted", or a JSON dictionary containing the keys "givenName" and "familyName". |
required | Array of strings or email (object)[ items ] JSON list of all valid email addresses for the user to be created. This parameter must be present and non-empty. |
active | boolean Whether a user is enabled / disabled. Note this MUST be a JSON boolean, not a string |
externalId | string a ID value that will be stored with the user and returned when the user is queried |
schemas | Array of strings |
{- "name": "Test User",
- "emails": [
- "test@scimpizzaplanet.com"
], - "schemas": [
- "urn:scim:schemas:core:1.0"
]
}
{- "active": true,
- "emails": [
- "test@scimpizzaplanet.com"
], - "id": "atestuserid",
- "name": {
- "familyName": "User",
- "formatted": "Test User",
- "givenName": "Test"
}, - "schemas": [
- "urn:scim:schemas:core:1.0"
], - "userName": "atestuserid"
}
This operation can be used to get information for a single user.
Data will be returned from this call whether or not the specified user is active.
userId required | string Example: atestuserid ID of the user account for which infomation will be returned. |
{- "active": true,
- "emails": [
- "testuser@testpizzaplanet.com"
], - "id": "atestuserid",
- "name": {
- "familyName": "User",
- "formatted": "Test User",
- "givenName": "Test"
}, - "schemas": [
- "urn:scim:schemas:core:1.0"
], - "userName": "atestuserid",
}
Update all fields on an existing user.
Notes:
primary
subfield of a user email cannot be updated using this API; use PATCH /2/Users/:userId
insteadtype
subfield of a user email cannot be updated at all. The type of every email is work
roles
field has been deprecated and shouldn’t be used in the SCIM requests.
To adjust admin roles for users, please review the Admin API documentation.userId required | string Example: atestuserid ID of the user to update |
formatted_name (string) or json_name (object) Specifies the name for the user to be updated. Must be a string containing the full name, or a JSON dictionary containing the key "formatted", or a JSON dictionary containing the keys "givenName" and "familyName". | |
Array of strings or email (object) non-empty [ items ] JSON list of all valid email addresses for the user to be updated. Note that an account must have at least one email address at all times. | |
externalId | string |
active | boolean Whether a user is enabled / disabled. |
persist | string |
schemas | Array of strings |
{- "active": true,
- "emails": [
- "test@testpizzaplanet.com",
- "test@personalpizzaplanet.com"
], - "name": {
- "formatted": "Test User"
}, - "schemas": [
- "urn:scim:schemas:core:1.0"
]
}
{- "active": true,
- "emails": [
- "test@testpizzaplanet.com",
- "test@personalpizzaplanet.com"
], - "id": "atestuserid",
- "name": {
- "familyName": "User",
- "formatted": "Test User",
- "givenName": "Test"
}, - "schemas": [
- "urn:scim:schemas:core:1.0"
], - "userName": "atestuserid"
}
This operation allows specific updates to be made to a user without supplying the whole user definition again.
The structure of this request consists of one or more "operations". Each operation contains:
op
field. This can be add
, replace
, or remove
add
and replace
operations, a value
field containing the
value to use in the operationpath
fieldNote that if "path" is active
, "value" must be true
or false
, not
"true"
or "false"
- i.e. a boolean, not a string.
The roles
field has been deprecated and shouldn’t be used in the SCIM requests.
To adjust admin roles for users, please review the Admin API documentation.
There's a special format of the add
and replace
operations that does
not require a path. In this case, the field names in the value
object
specify what is to be changed. See the example patch_without_paths
.
userId required | string Unique ID of the user that will be updated |
required | Array of objects[ items ] |
persist | string |
schemas | Array of strings |
{- "Operations": [
- {
- "op": "replace",
- "path": "name.formatted",
- "value": "New Name"
}, - {
- "op": "remove",
- "path": "emails",
- "value": {
- "value": "old_email@testing.org"
}
}, - {
- "op": "add",
- "path": "emails",
- "value": {
- "value": "new_email@testing.org"
}
}
], - "schemas": [
- "urn:scim:schemas:core:1.0"
]
}
{- "active": true,
- "emails": [
- "new_email@testing.org"
], - "id": "atestuserid",
- "name": {
- "familyName": "Name",
- "formatted": "New Name",
- "givenName": "New"
}, - "schemas": [
- "urn:scim:schemas:core:1.0"
], - "userName": "atestuserid"
}
This call will disable a user's account, but will not delete it. That user will lose access to Quip and will not be able to log in, but none of their data will be deleted or lost, and any content they shared with other users will remain shared with those users.
To re-enable a user account, use the Update User operation to set the
active
field back to true.
userId required | string Example: atestuserid Unique ID of the user account to disable. |
{- "error_code": 400,
- "description": "string"
}
This API call is used to get information about current Quip user accounts.
This call can be performed with no parameters, in which case all users
will be returned, or with a "filter" parameter, which limits the response
to a subset of the current users. (Note: if you have a lot of users, you
probably don't want to call this without a "count".)
Deactivated users willl be returned from some calls and not others.
filter | string Example: filter=emails co @hello.com Returned users will be limited to those that match the specified filter. The service supports a subset of the behavior described here in the SCIM specification. A filter expression must be of the format "< attribute > < operator > < value >". The following attributes are supported:
The full list of operators from Section 3.2.2.1 of the SCIM v1.1 specification is supported, with the exception of the "is present" operator "pr". |
count | integer Example: count=1 Limits the number of results returned. |
startIndex | integer Example: startIndex=1 1-based index used with "count" to fetch results in a paged fashion. |
sortBy | string Example: sortBy=username Indicates the field used to sort results. The following values are supported:
|
sortOrder | string Example: sortOrder=ascending Indicates the direction of sorting. May be "ascending" or "descending"; if not present, the sort will be ascending. |
{- "Resources": [
- {
- "active": true,
- "emails": [
- {
- "primary": true,
- "type": "work",
- "value": "test@hello.com"
}
], - "id": "atestuserid",
- "name": [
- {
- "familyName": "User",
- "formatted": "Test User",
- "givenName": "Test"
}
], - "schemas": [
- "urn:ietf:params:scim:schemas:core:2.0:User"
], - "userName": "atestuserid",
- "groups": [
- {
- "value": "atestgroupid",
- "display": "My Group"
}
],
}
], - "itemsPerPage": 1,
- "schemas": [
- "urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
}
This API call is used to set up a new Quip user account.
When creating credentials in your identity service for a new employee,
you can use this call to automatically set up a new Quip account for that user.
If you attempt to create a user who has an email that is already associated with an active user at your site, the operation will fail with HTTP status code 409 (Conflict).
If you attempt to create a user who has an email that is already
associated with a deactivated user at your site, the prior user will be
reactivated by providing active
parameter. Other information from your
request will be ignored.
required | formatted_name (string) or json_name (object) Specifies the name for the user to be created. Must be a string containing the full name, or a JSON dictionary containing the key "formatted", or a JSON dictionary containing the keys "givenName" and "familyName". |
required | Array of strings or email (object) non-empty [ items ] JSON list of all valid email addresses for the user to be created. This parameter must be present and non-empty. |
externalId | string An ID value that will be stored with the user and returned when the user is queried. |
active | boolean Whether a user is enabled / disabled. Note this MUST be a JSON boolean, not a string. |
sch |