SCIM API (Current)

License: Proprietary

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.

Overview

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:

  1. Account Creation: Creating a new employee's corporate credentials through an identity provider triggers the creation of a new Quip account for that employee
  2. Account Disable: Disabling an employee's corporate credentials through an identity provider automatically triggers the disabling of that employee's Quip account
  3. Group Membership: SCIM can be used to synchronize group membership between your identity service and Quip.
  4. Accounts Merge: Merge one account into another. The account that was merged into the other will be disabled after.

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:

Rate Limits

Quip's APIs have rate limits to help ensure fair and reliable access to APIs for all of our customers.

Per-company Rate Limit

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 make
  • X-Scim-RateLimit-Remaining: The number of requests remaining for your company within the minute
  • X-Scim-RateLimit-Reset: The UTC timestamp for when the rate limit resets
  • X-Scim-Retry-After: The number of seconds after which your company can make API calls again

Authentication

BearerAuth

Authorization tokens are only available for Quip Enterprise customers.

To get an authorization token, head over to: {yourcompany}.quip.com/business/admin/scim

Note that:

  • All requests to the SCIM APIs should include the token in the Authorization header, i.e. Authorization: Bearer {your token}.
  • You'll need to be an administrator of your company's Quip site to access this page.

Limitations and Known Issues

All Versions

  • Per the v2.0 specification, the 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.)
  • User emails must be unique within each company in the quip system. This includes email addresses assigned to disabled users. If you attempt to create a new user with the same email address as a disabled user in your company, the previously disabled user will be reactivated and any information included in the Create User request will be discarded. Also see How To, below.
  • For names, the fields 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.
  • Groups must have at least one member. Thus, flows where a group is initially created with no members, and members are added on subsequent calls, are not supported. (This may cause issues with Active Directory integration.)
  • Groups do not support the externalId attribute.
  • GET /Groups does not support sorting or filtering.
  • 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.

v1.1

  • the PATCH operation is not supported for the /Users resource.
  • nothing in the v1.1 API allows the primary email to be changed. Workaround: v2 PATCH /Users/:userId can be used to update the primary email.

v2.0

  • The PATCH operation is not supported for the /Groups resource.
  • In PATCH /2/Users, paths with expressions are not supported. e.g. no path: email[value sw foo]

How Tos

This section gives information on how to perform common operations.

Work With Users

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 all users: GET /2/Users
  • Get ten users: GET /2/Users?count=10
  • Get the next ten users: GET /2/Users?count=10&startIndex=11
  • Get the user with the matching email (will always return a list of 1 or 0): GET /2/Users?filter=emails+eq+test@hello.com
  • Get the user with the matching external ID (will always return a list of 1 or 0): 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.

Disable Active User Sessions

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.

Deal with Duplicate Emails

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:

  • look for a disabled account with the new email: GET /2/Users?filter=emails+eq+test@hello.com
  • if the response is not an empty list, get the user ID and use a Patch User request against that ID to replace the disabled user's email with a unique but harmless value.

Users

Get Users

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

Deactivated users willl be returned from some calls and not others.

  • requests with no filter, and requests that filter by name or username, will not return deactivated users.
  • requests that filter by email will return deactivated users.
query Parameters
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:

  • emails (NOT email)
  • username
  • name.familyname
  • name.givenname
  • externalid
  • or

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:

  • emails
  • username
  • name.familyname
  • name.givenname
  • name.formatted
sortOrder
string
Example: sortOrder=ascending

Indicates the direction of sorting. May be "ascending" or "descending"; if not present, the sort will be ascending.

Responses

Response samples

Content type
application/json
{
  • "Resources": [
    ],
  • "itemsPerPage": 1,
  • "startIndex": 1,
  • "totalResults": 22,
  • "schemas": [
    ]
}

Create User

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.

Email Collisions

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.

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "name": "Test User",
  • "emails": [
    ],
  • "schemas": [
    ]
}

Response samples

Content type
application/json
{
  • "active": true,
  • "emails": [
    ],
  • "id": "atestuserid",
  • "name": {
    },
  • "schemas": [
    ],
  • "userName": "atestuserid"
}

Get Single User

This operation can be used to get information for a single user.

Deactivated Users

Data will be returned from this call whether or not the specified user is active.

path Parameters
userId
required
string
Example: atestuserid

ID of the user account for which infomation will be returned.

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "emails": [
    ],
  • "id": "atestuserid",
  • "name": {
    },
  • "schemas": [
    ],
  • "userName": "atestuserid",
}

Update User

Update all fields on an existing user.

Notes:

  • the primary subfield of a user email cannot be updated using this API; use PATCH /2/Users/:userId instead
  • the type subfield of a user email cannot be updated at all. The type of every email is work
  • 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.
path Parameters
userId
required
string
Example: atestuserid

ID of the user to update

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "emails": [
    ],
  • "name": {
    },
  • "schemas": [
    ]
}

Response samples

Content type
application/json
{
  • "active": true,
  • "emails": [
    ],
  • "id": "atestuserid",
  • "name": {
    },
  • "schemas": [
    ],
  • "userName": "atestuserid"
}

Patch User v1

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:

  • an op field. This can be add, replace, or remove
  • for add and replace operations, a value field containing the value to use in the operation
  • (usually) a path field

Note 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.

Operations With No Path

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.

path Parameters
userId
required
string

Unique ID of the user that will be updated

Request Body schema: application/json
One of
required
Array of objects[ items ]
persist
string
schemas
Array of strings

Responses

Request samples

Content type
application/json
Example
{
  • "Operations": [
    ],
  • "schemas": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "active": true,
  • "emails": [
    ],
  • "id": "atestuserid",
  • "name": {
    },
  • "schemas": [
    ],
  • "userName": "atestuserid"
}

Disable User

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.

path Parameters
userId
required
string
Example: atestuserid

Unique ID of the user account to disable.

Responses

Response samples

Content type
application/json
{
  • "error_code": 400,
  • "description": "string"
}

Get Users v2

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

Deactivated users willl be returned from some calls and not others.

  • requests with no filter, and requests that filter by name or username, will not return deactivated users.
  • requests that filter by email will return deactivated users.
query Parameters
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:

  • emails (NOT email)
  • username
  • name.familyname
  • name.givenname
  • externalid
  • or

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:

  • emails
  • username
  • name.familyname
  • name.givenname
  • name.formatted
sortOrder
string
Example: sortOrder=ascending

Indicates the direction of sorting. May be "ascending" or "descending"; if not present, the sort will be ascending.

Responses

Response samples

Content type
application/json
{
  • "Resources": [
    ],
  • "itemsPerPage": 1,
  • "schemas": [
    ]
}

Create User v2

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.

Email Collisions

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.

Request Body schema: application/json
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