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.

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" or with no version string use version 1.1.

Authentication

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.

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.

v1.1

Operations for SCIM v1.1. For reference, general SCIM v1.1 specifications can be found here:

Get Users v1.1

GET https://scim.quip.com/Users

Description

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".)

Filter Support

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

Sorting

The following sortBy values are supported:

  • emails (NOT email)
  • username
  • name.familyname
  • name.givenname
  • name.formatted

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 Params

filter Optional

Returned users will be limited to those that match the specified filter. For further details, see above.

count Optional

Limits the number of results returned.

startIndex Optional

1-based index used with "count" to fetch results in a paged fashion.

sortBy Optional

Indicates the field used to sort results.

sortOrder Optional

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

Simple Example

GET https://scim.quip.com/Users?count=1

Response

{
    "Resources": [
        {
            "active": true,
            "emails": [
                "test@hello.com"
            ],
            "id": "AtESTuSERiD",
            "name": {
                  "familyName": "User",
                  "formatted": "Test User",
                  "givenName": "Test"
            },
            "roles": ["Super Admin"],
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "userName": "AtESTuSERiD"
        }
    ],
    "itemsPerPage": 1,
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "startIndex": 1,
    "totalResults": 22
}

Create User v1.1

POST https://scim.quip.com/Users

Description

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.

Body Specification:

The body of this POST request much be a valid JSON document. Valid parameters here are:

  • name: Specifies the user 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.
  • emails: JSON list of all valid email addresses for the user to be created. This parameter must be present and non-empty.
  • externalId: a ID value that will be stored with the user and returned when the user is queried. Optional.
  • active: whether a user is enabled / disabled. Note this MUST be a JSON boolean, not a string. Optional.

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.

Headers

Content-Type:application/json

Request Body

{

    "name": "Test User",

    "emails": ["test@scimpizzaplanet.com"],

    "schemas": ["urn:scim:schemas:core:1.0"]

}

Simple Example

POST https://scim.quip.com/Users

Request


                            {
    "name": "Test User",
    "emails": ["test@scimpizzaplanet.com"],
    "schemas": ["urn:scim:schemas:core:1.0"]
}

Response

{
    "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"
}

Update User v1.1

PUT https://scim.quip.com/Users/:userId

Description

Update all fields on an existing user. Fields available for update are:

  • name
  • emails - note that an account must have at least one email address at all times
  • externalId - optional
  • active - whether a user is enabled / disabled. Note this MUST be a JSON boolean, not a string.
  • roles - a list with only one item which is the Admin Role name. The Admin Role name can be found in Settings/Site Settings/Admin Roles section of Admin Console. Not specifying this field, or an empty list [] removes the Admin Role. Optional.

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.

Headers

Content-Type:application/json

Path Variables

userId

ID of the user to update

Simple Example

PUT https://scim.quip.com/Users/AtESTuSERiD

Request


                            {
    "active": true,
    "emails": [
        "test@testpizzaplanet.com",
        "test@personalpizzaplanet.com"
    ],
    "name": {
        "formatted":"Test User"
    },
    "roles": ["Super Admin"],
    "schemas": ["urn:scim:schemas:core:1.0"]
}

Response

{
    "active": true,
    "emails": [
        "test@testpizzaplanet.com",
        "test@personalpizzaplanet.com"
    ],
    "id": "AtESTuSERiD",
    "name": {
        "familyName": "User",
        "formatted": "Test User",
        "givenName": "Test"
    },
    "roles": ["Super Admin"],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "userName": "AtESTuSERiD"
}

Disable User v1.1

DELETE https://scim.quip.com/Users/:userId

Description

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.

Responses

Sucessful response from this operation has HTTP status code 200 and the following response body:

{}

Path Variables

userId

Unique ID of the user account to disable.

Get Single User v1.1

GET https://scim.quip.com/Users/:userId

Description

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 Variables

userId

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

Simple Example

GET https://scim.quip.com/Users/AtESTuSERtiD

Response

{
    "active": true,
    "emails": [
        "testuser@testpizzaplanet.com"
    ],
    "id": "AtESTuSERtiD",
    "name": {
        "familyName": "User",
        "formatted": "Test User",
        "givenName": "Test"
    },
    "roles": ["Super Admin"],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "userName": "AtESTuSERtiD"
}

Get Group Folders v1.1

GET https://scim.quip.com/GroupFolders

Description

This API call is used to fetch information about current Quip Group Folders.
By default, all group folders will be returned from this call. The number of results returned with a single request can be chosen using the "count" parameter - this is a good idea if you have a lot of group folders or if your group folders are large.

Headers

Content-Type:application/json

Query Params

count Optional

Limits the number of results returned.

startIndex Optional

1-based index used with "count" to fetch results in a paged fashion.

Simple Example

GET https://scim.quip.com/GroupFolders?count=1&startIndex=2

Response

{
    "totalResults": 2,
    "itemsPerPage": 1,
    "startIndex": 2,
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "Resources": [
        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "ATESTGROUPFOLDERID",
            "displayName": "A Group Folder",
            "members": [
                {
                    "value": "AtESTuSERiD"
                },
                {
                    "value": "ANOTHErUSErId"
                }
            ]
        }
    ]
}

Create Group Folder v1.1

POST https://scim.quip.com/GroupFolders

Description

This operation allows a caller to create a new group folder for the company. A group folder must have at least one member at all times, including when it is created. The group folder will be created as a top level folder for your company and can be further managed using the Admin Console, under Group Folders.

Note: at present, this API returns response messages that contain the incorrect schema value.

Headers

Content-Type:application/json

Simple Example

POST https://scim.quip.com/GroupFolders

Request


                            {
    "displayName": "My Group Folder",
    "members": [
        "AtESTuSERiD",
        "ANOTHErUSErId"
    ],
    "schemas":["urn:scim:schemas:core:1.0"]
}

Response

{
    "displayName": "My Group Folder",
    "id": "cREATEDgROUPFOLDeriD",
    "members": [
        {
            "value": "AtESTuSERiD"
        },
        {
            "value": "ANOTHErUSErId"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Get Single Group Folder v1.1

GET https://scim.quip.com/GroupFolders/:groupFolderId

Description

This API call can be used to fetch the information on a single group folder, given the group ID.
Note: at present, this API returns response messages that contain the incorrect schema value.

Path Variables

groupFolderId

Simple Example

GET https://scim.quip.com/GroupFolders/

Response

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "id": "ATESTGROUPFOLDERID",
    "displayName": "My Group Folder",
    "members": [
        {
            "value": "AtESTuSERiD"
        },
        {
            "value": "ANOTHErUSErId"
        }
    ]
}

Patch Group Folder v1.1

PATCH https://scim.quip.com/GroupFolders/:groupFolderId

Description

This API call can be used to modify a group, i.e. add and/or remove members, without replacing the entire group. More than one change can be made in a single request. This can be useful for groups with many members.

Headers

Content-Type:application/json

Path Variables

groupFolderId

Unique ID of the group folder that will be modified.

Add One User, Remove Another

PATCH https://scim.quip.com/GroupFolders/ATESTGROUPFOLDERID

Request


                            {
    "schemas": ["urn:scim:schemas:core:1.0"],
    "members": [
        {
            "value": "HAPPYNEWUSERID"
        },
        {
            "value": "BADOLDUSERID",
            "operation": "delete"
        }
    ]
}

Response

{
    "displayName": "My Group Folder",
    "id": "ATESTGROUPFOLDERID",
    "members": [
        {
            "value": "AnOTHERUsERId"
        },
        {
            "value": "HAPPYNEWUSERID"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Get Groups v1.1

GET https://scim.quip.com/Groups

Description

This API call is used to fetch information about current Quip User Groups.
By default, all user groups will be returned from this call. The number of results returned with a single request can be chosen using the "count" parameter - this is a good idea if you have a lot of user groups or if your user groups are large.

Filter Support

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:

  • displayName
  • 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".

Headers

Content-Type:application/json

Query Params

filter Optional

Returned groups will be limited to those that match the specified filter. For further details, see above.

count Optional

Limits the number of results returned.

startIndex Optional

1-based index used with "count" to fetch results in a paged fashion.

Simple Example

GET https://scim.quip.com/Groups?count=1&startIndex=2

Response

{
    "totalResults": 2,
    "itemsPerPage": 1,
    "startIndex": 2,
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "Resources": [
        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "ATESTGROUPID",
            "displayName": "A Group",
            "members": [
                {
                    "value": "AtESTuSERiD"
                },
                {
                    "value": "ANOTHErUSErId"
                }
            ]
        }
    ]
}

Create Group v1.1

POST https://scim.quip.com/Groups

Description

This operation allows a caller to create a new user group for the company.Use groups can be used to assign users to group folders by synchronizing the folder on the Quip UI.

Headers

Content-Type:application/json

Simple Example

POST https://scim.quip.com/Groups

Request


                            {
    "displayName": "My Group",
    "members": [
        {"value": "AtESTuSERiD"},
        {"value": "ANOTHErUSErId"}
    ],
    "schemas":["urn:scim:schemas:core:1.0"]
}

Response

{
    "displayName": "My Group",
    "id": "cREATEDgROUPiD",
    "members": [
        {
            "value": "AtESTuSERiD"
        },
        {
            "value": "ANOTHErUSErId"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Get Single Group v1.1

GET https://scim.quip.com/Groups/:groupId

Description

This API call can be used to fetch the information on a single user group, given the group ID.

Path Variables

groupId

Unique ID of the group whose information will be fetched.

Simple Example

GET https://scim.quip.com/Groups/ATESTGROUPID

Response

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "id": "ATESTGROUPID",
    "displayName": "My Group",
    "members": [
        {
            "value": "AtESTuSERiD"
        },
        {
            "value": "ANOTHErUSErId"
        }
    ]
}

Patch Group v1.1

PATCH https://scim.quip.com/Groups/:groupId

Description

This API call can be used to update a user group — including adding and removing members, and updating user group name. More than one change can be made in a single request. After user group membership is updated, the changes will be reflected in any corresponding group folders.

Headers

Content-Type:application/json

Path Variables

groupId

Unique ID of the group that will be modified.

Add One User, Remove Another

PATCH https://scim.quip.com/Groups/ATESTGROUPID

Request


                            {
    "schemas": ["urn:scim:schemas:core:1.0"],
    "displayName": "Group Name Updated",
    "members": [
        {
            "value": "HAPPYNEWUSERID"
        },
        {
            "value": "BADOLDUSERID",
            "operation": "delete"
        }
    ]
}

Response

{
    "displayName": "Group Name Updated",
    "id": "ATESTGROUPID",
    "members": [
        {
            "value": "AnOTHERUsERId"
        },
        {
            "value": "HAPPYNEWUSERID"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Delete Group v1.1

DELETE https://scim.quip.com/Groups/:groupId

Description

Deletes all members of a group folder. Deleting a group removes the members’ access to their corresponding group folder. You can use this API method to fulfill your compliance and user-management service-level agreements (SLAs).

See Also: Folders

Path Variables

groupId

The ID of the group that you want to delete. To find the groupId, call the Get Groups v1.1 API method.

Simple Example

DELETE https://scim.quip.com/Groups/ATESTGROUPID

v2.0

Operations for SCIM v2.0. For reference, general SCIM v2.0 specifications can be found here:

Get Users v2

GET https://scim.quip.com/2/Users

Description

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".)

Filter Support

The service supports a subset of the behavior described http://www.simplecloud.info/specs/draft-scim-api-01.html#query-resources 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 [http://www.simplecloud.info/specs/draft-scim-api-01.html#query-resources](SCIM v1.1 specification) is supported, with the exception of the "is present" operator "pr".

Sorting

The following sortBy values are supported:

  • emails (NOT email)
  • username
  • name.familyname
  • name.givenname
  • name.formatted

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 Params

filter Optional

Returned users will be limited to those that match the specified filter. For further details, see above.

count Optional

Limits the number of results returned.

startIndex Optional

1-based index used with "count" to fetch results in a paged fashion.

sortBy Optional

Indicates the field used to sort results.

sortOrder Optional

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

Simple Example

GET https://scim.quip.com/2/Users?count=1

Response

{
    "Resources": [
        {
            "active": true,
            "emails": [
                {
                    "primary": true,
                    "type": "work",
                    "value": "test@hello.com"
                }
            ],
            "id": "AtESTuSERiD",
            "name": {
                  "familyName": "User",
                  "formatted": "Test User",
                  "givenName": "Test"
            },
            "roles": ["Super Admin"],
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "userName": "AtESTuSERiD"
        }
    ],
    "itemsPerPage": 1,
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "startIndex": 1,
    "totalResults": 22
}

Create User v2

POST https://scim.quip.com/2/Users

Description

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.

Body Specification:

The body of this POST request much be a valid JSON document. Valid parameters here are:

  • name: Specifies the user 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.
  • emails: JSON list of all valid email addresses for the user to be created. This parameter must be present and non-empty.
  • externalId: a ID value that will be stored with the user and returned when the user is queried. Optional.
  • active - whether a user is enabled / disabled. Note this MUST be a JSON boolean, not a string. Optional.

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.

Headers

Content-Type:application/json

Simple Example

POST https://scim.quip.com/2/Users

Request


                            {
    "name": {
        "formatted": "Test User"
    },
    "emails": [
        {
            "value": "test@scimpizzaplanet.com"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ]
}

Response

{
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "test@scimpizzaplanet.com"
        }
    ],
    "id": "AtESTuSERiD",
    "name": {
        "familyName": "User",
        "formatted": "Test User",
        "givenName": "Test"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "AtESTuSERiD"
}

Update User v2

PUT https://scim.quip.com/2/Users/:userId

Description

Update all fields on an existing user. Fields available for update are:

  • name
  • emails - note that an account must have at least one email address at all times
  • externalId - optional
  • active - whether a user is enabled / disabled. Note this MUST be a JSON boolean, not a string.
  • roles - a list with only one item which is the Admin Role name. The Admin Role name can be found in Settings/Site Settings/Admin Roles section of Admin Console. Not specifying this field, or an empty list [] removes the Admin Role. Optional.

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.

Headers

Content-Type:application/json

Path Variables

userId

ID of the user to update

Simple Example

PUT https://scim.quip.com/2/Users/AtESTuSERiD

Request


                            {
    "active": true,
    "emails": [
        {
            "value":"test@testpizzaplanet.com"
        }
    ],
    "name": {
        "formatted": "Test User"
    },
    "roles": ["Super Admin"],
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]
}

Response

{
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "test@scimpizzaplanet.com"
        }
    ],
    "id": "AtESTuSERiD",
    "name": {
        "familyName": "User",
        "formatted": "Test User",
        "givenName": "Test"
    },
    "roles": ["Super Admin"],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "AtESTuSERiD"
}

Patch User v2

PATCH https://scim.quip.com/2/Users/:userId

Description

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.

Supported path values are:

  • active
  • emails (not email)
  • externalId
  • name.familyName
  • name.formatted
  • name.givenName
  • roles (See description details in Update User)

Note that if "path" is active, "value" must be true or false, not "true" or "false" - i.e. a boolean, not a string.

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 "Replace With No Path".

Path Variables

userId

Unique ID of the user that will be updated

Multiple Operations

PATCH https://scim.quip.com/2/Users/AtESTuSERiD

Request


                            {
    "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:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}

Response

{
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "new_email@testing.org"
        }
    ],
    "id": "AtESTuSERiD",
    "name": {
        "familyName": "Name",
        "formatted": "New Name",
        "givenName": "New"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "AtESTuSERiD"
}

Replace With No Path

PATCH https://scim.quip.com/2/Users/AtESTuSERiD

Request


                            {
    "Operations": [
        {
            "op": "replace",
            "value": {
                "active": false,
                "externalId": "an-external-id"
            }
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}

Response

{
    "active": false,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "email@testing.org"
        }
    ],
    "externalId": "an-external-id",
    "id": "AtESTuSERiD",
    "name": {
        "familyName": "User",
        "formatted": "Test User",
        "givenName": "Test"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "AtESTuSERiD"
}

Change Primary Email

PATCH https://scim.quip.com/2/Users/AtESTuSERiD

Request


                            {
    "Operations": [
        {
            "op": "add",
            "path": "emails",
            "value": [
                {
                    "value": "new_primary_email@testing.org",
                    "primary": true
                }
            ]
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}

Response

{
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "new_primary_email@testing.org"
        },
        {
            "type": "work",
            "value": "old_primary_email@testing.org"
        }
    ],
    "id": "AtESTuSERiD",
    "name": {
        "familyName": "User",
        "formatted": "Test User",
        "givenName": "Test"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "AtESTuSERiD"
}

Replace Name

PATCH https://scim.quip.com/2/Users/AtESTuSERiD

Request


                            {
	"Operations": [
		{
			"op": "replace",
			"path": "name.formatted",
			"value": "New Username"
		}
	],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}

Response

{
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "test@scimpizzaplanet.com"
        }
    ],
    "id": "AtESTuSERiD",
    "name": {
        "familyName": "Username",
        "formatted": "New Username",
        "givenName": "New"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "AtESTuSERiD"
}

Disable User v2

DELETE https://scim.quip.com/2/Users/:userId

Description

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.

Responses

Sucessful response from this operation has HTTP status code 200 and the following response body:

{}

Path Variables

userId

Unique ID of the user account to disable.

Get Single User v2

GET https://scim.quip.com/2/Users/:userId

Description

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 Variables

userId

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

Simple Example

GET https://scim.quip.com/2/Users/AtESTuSERtiD

Response

{
    "active": true,
    "emails": [
        {
            "primary": true,
            "type": "work",
            "value": "testuser@testpizzaplanet.com"
        }
    ],
    "id": "AtESTuSERtiD",
    "name": {
        "familyName": "User",
        "formatted": "Test User",
        "givenName": "Test"
    },
    "roles": ["Super Admin"],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "AtESTuSERtiD"
}

Get Group Folders v2

GET https://scim.quip.com/2/GroupFolders

Description

This API call is used to fetch information about current Quip Group Folders.
By default, all group folders will be returned from this call. The number of results returned with a single request can be chosen using the "count" parameter - this is a good idea if you have a lot of group folders or if your group folders are large.

Note: currently the schema returned from this operation is incorrect.

Headers

Content-Type:application/json

Query Params

count Optional

Limits the number of results returned.

startIndex Optional

1-based index used with "count" to fetch results in a paged fashion.

Simple Example

GET https://scim.quip.com/2/GroupFolders?count=1&startIndex=2

Response

{
    "Resources": [
        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "ATESTGROUPID",
            "displayName": "A Group Folder",
            "members": [
                {
                    "value": "AtESTuSERiD"
                },
                {
                    "value": "ANOTHErUSErId"
                }
            ]
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "itemsPerPage": 1,
    "startIndex": 2,
    "totalResults": 2
}

Create Group Folder v2

POST https://scim.quip.com/2/GroupFolders

Description

This operation allows a caller to create a new group folder for the company. A group folder must have at least one member at all times, including when it is created. The group folder will be created as a top level folder for your company and can be further managed using the Admin Console, under Group Folders.

Note: at present, this API returns response messages that contain the incorrect schema value.

Headers

Content-Type:application/json

Request Body

{

    "displayName": "My Group 3",

    "members": [

         "ULPAEA71azn",

         "bERAEAjHidQ",

         "eJHAEATIfS7"

    ],

    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]

}

Simple Example

POST https://scim.quip.com/2/GroupFolders

Request


                            {
    "displayName": "My Group",
    "members": [
        "AtESTuSERiD",
        "ANOTHErUSErId"
    ],
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]
}

Response

{
    "displayName": "My Group",
    "id": "ATESTGROUPID",
    "members": [
        {
            "value": "AtESTuSERiD"
        },
        {
            "value": "ANOTHErUSErId"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Get Single Group Folder v2

GET https://scim.quip.com/2/GroupFolders/:groupFolderId

Description

This API call can be used to fetch the information on a single group folder, given the group ID.

Note: at present, this API returns response messages that contain the incorrect schema value.

Path Variables

groupFolderId

Unique ID of the group folder whose information will be fetched.

Simple Example

GET https://scim.quip.com/2/GroupFolders/ATESTGROUPID

Response

{
    "displayName": "My Group Folder",
    "id": "ATESTGROUPID",
    "members": [
        {
            "value": "AtESTuSERiD"
        },
        {
            "value": "ANOTHErUSErId"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Patch Group Folder v2

PATCH https://scim.quip.com/2/GroupFolders/:groupFolderId

Description

This API call can be used to update a user group — including adding and removing members, and updating user group name. More than one change can be made in a single request. After user group membership is updated, the changes will be reflected in any corresponding group folders.

Headers

Content-Type:application/json

Path Variables

groupFolderId

Unique ID of the group that will be modified.

Add One User, Remove Another

PATCH https://scim.quip.com/GroupFolders/"ATESTGROUPFOLDERID"

Request


                            {
    "schemas": ["urn:scim:schemas:core:1.0"],
    "displayName": "Group Folder Updated",
    "members": [
        {
            "value": "HAPPYNEWUSERID"
        },
        {
            "value": "BADOLDUSERID",
            "operation": "delete"
        }
    ]
}

Response

{
    "displayName": "Group Folder Updated",
    "id": "ATESTGROUPFOLDERID",
    "members": [
        {
            "value": "AnOTHERUsERId"
        },
        {
            "value": "HAPPYNEWUSERID"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Get Groups v2

GET https://scim.quip.com/2/Groups

Description

This API call is used to fetch information about current Quip User Groups.
By default, all user groups will be returned from this call. The number of results returned with a single request can be chosen using the "count" parameter - this is a good idea if you have a lot of user groups or if your user groups are large.

Note: currently the schema returned from this operation is incorrect.

Filter Support

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:

  • displayName
  • 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".

Headers

Content-Type:application/json

Query Params

filter Optional

Returned groups will be limited to those that match the specified filter. For further details, see above.

count Optional

Limits the number of results returned.

startIndex Optional

1-based index used with "count" to fetch results in a paged fashion.

Simple Example

GET https://scim.quip.com/2/Groups?count=1&startIndex=2

Response

{
    "Resources": [
        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "ATESTGROUPID",
            "displayName": "A Group",
            "members": [
                {
                    "value": "AtESTuSERiD"
                },
                {
                    "value": "ANOTHErUSErId"
                }
            ]
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "itemsPerPage": 1,
    "startIndex": 2,
    "totalResults": 2
}

Create Group v2

POST https://scim.quip.com/2/Groups

Description

This operation allows a caller to create a new user group for the company.Use groups can be used to assign users to group folders by synchronizing the folder on the Quip UI.

Note: at present, this API returns response messages that contain the incorrect schema value.

Headers

Content-Type:application/json

Request Body

{

    "displayName": "My Group 3",

    "members": [

        {"value": "ULPAEA71azn"},

        {"value": "bERAEAjHidQ"},

        {"value": "eJHAEATIfS7"}

    ],

    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"]

}

Simple Example

POST https://scim.quip.com/2/Groups

Request


                            {
    "displayName": "My Group",
    "members": [
        {"value": "AtESTuSERiD"},
        {"value": "ANOTHErUSErId"}
    ],
    "schemas":["urn:scim:schemas:core:1.0"]
}

Response

{
    "displayName": "My Group",
    "id": "ATESTGROUPID",
    "members": [
        {
            "value": "AtESTuSERiD"
        },
        {
            "value": "ANOTHErUSErId"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Get Single Group v2

GET https://scim.quip.com/2/Groups/:groupId

Description

This API call can be used to fetch the information on a single user group, given the group ID.

Note: at present, this API returns response messages that contain the incorrect schema value.

Path Variables

groupId

Unique ID of the group whose information will be fetched.

Simple Example

GET https://scim.quip.com/2/Groups/ATESTGROUPID

Response

{
    "displayName": "My Group",
    "id": "ATESTGROUPID",
    "members": [
        {
            "value": "AtESTuSERiD"
        },
        {
            "value": "ANOTHErUSErId"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Patch Group v2

PATCH https://scim.quip.com/2/Groups/:groupId

Description

This API call can be used to update a user group — including adding and removing members, and updating user group name. More than one change can be made in a single request. After user group membership is updated, the changes will be reflected in any corresponding group folders.

Headers

Content-Type:application/json

Path Variables

groupId

Unique ID of the group that will be modified.

Add One User, Remove Another

PATCH https://scim.quip.com/Groups/ATESTGROUPID

Request


                            {
    "schemas": ["urn:scim:schemas:core:1.0"],
    "displayName": "Group Name Updated",
    "members": [
        {
            "value": "HAPPYNEWUSERID"
        },
        {
            "value": "BADOLDUSERID",
            "operation": "delete"
        }
    ]
}

Response

{
    "displayName": "Group Name Updated",
    "id": "ATESTGROUPID",
    "members": [
        {
            "value": "AnOTHERUsERId"
        },
        {
            "value": "HAPPYNEWUSERID"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ]
}

Delete Group v2

DELETE https://scim.quip.com/Groups/:groupId

Description

Deletes all members of a group folder. Deleting a group removes the members’ access to their corresponding group folder. You can use this API method to fulfill your compliance and user-management service-level agreements (SLAs).

See Also: Folders

Path Variables

groupId

The ID of the group that you want to delete. To find the groupId, call the Get Groups v2 API method.

Simple Example

DELETE https://scim.quip.com/Groups/ATESTGROUPID