Users API

Our fully SCIM 2.0 compliant API to create, search, retrieve, update and remove user information.

All described API calls below require a valid token. See here how to obtain a token.
Working examples can be found in our Postman collection in the “Getting Started” section.

User data model
Full JSON user representation
Search users
Get a user
Create user
Update user (PATCH)
Update user (PUT)
Delete user
Bulk user updates

User data model

A schema is a collection of attribute definitions that describe the contents and or attributes. The user resource in Federated Directory consists out of 3 schema’s:

urn:ietf:params:scim:schemas:core:2.0:User
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
urn:ietf:params:scim:schemas:extension:fd:2.0:User

The below table describes the attributes and their meta data in each schema. The mutability, type and other pattern constraints can be found in our SCIM Schema endpoint: https://api.federated.directory/v2/Schemas.

You can see how these schema’s and attributes form a user JSON object in the next chapter.

urn:ietf:params:scim:schemas:core:2.0:User

Attribute	Sub attribute	Min	Max	Comment
id		36	36	UUID format
externalId		0	70
userName		1	150	Unique in a directory
name {}
	givenName	0	150
	familyName	0	150
displayName		1	200
nickName		0	45
profileUrl		0	200	“Valid URL, starting with ‘http(s)://’”
title		0	150
userType		0	150
emails []				Max 2 email addresses
	value	0	150	Valid email address
	type	4	4	“work” or “home”
	primary
phoneNumbers []				Max 3 phone numbers
	value	0	45	Any number and these: _ . / ( ) # + -
	type	4	5	“work”, “home” or “mobile”
	primary			Boolean
addresses []				Max 2 addresses
	streetAddress	0	150
	locality	0	150
	region	0	150
	postalCode	0	45
	country	0	150
	type	4	4	“work” or “home”
	primary			Boolean
photos []				Max 2 photo’s
	type	4	4	“photo” or “thumbnail”
	value	0	200	Valid URL, starting with ‘http(s)://’
preferredLanguage		0	45
locale		0	45
timezone		0	45
active				Only available for the admin of a user.
groups []				Will only contain the groups the requester is a member of as well
	value	36	36	UUID format “admin”
	display	1	200	Group name
	logos []			Array with 2 objects: Logo & Thumbnail. ‘Value’ attribute contains path to image
	owner			Boolean
	assignedByFilter			Boolean. If true, the user can not be removed from the group manually
roles []				Max 1 role
	type	4	5	“user” or “admin”
	value	4	5	“user” or “admin”
password		8	30
meta {}				Only available for the admin of a user. Not available in list response
	created	20	20	ISO 8601 in UTC timezone
	lastModified	20	20	ISO 8601 in UTC timezone
	location	77	77	https://api.federated.directory/v2/Users/{id}
	resourceType	4	4	“User”

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Attribute	Sub attribute	Min	Max	Comment
organization		1	100	Company Name
employeeNumber		0	150
costCenter		0	150
division		0	150
department		0	150
manager {}
	value	36	36	Id of user in the same company
	displayName	0	200
	$ref	77	77	../v2/Users/{id}

urn:ietf:params:scim:schemas:extension:fd:2.0:User

Attribute	Sub attribute	Min	Max	Comment
description		0	250
companyId		36	36	UUID format
companyLogos []		36	36	UUID format
	type	4	9	“logo” or “thumbnail”
	value	0	200	Valid URL, starting with ‘http(s)://’
directoryId		36	36	UUID format
custom01		0	150	Custom attribute 1
custom02		0	150	Custom attribute 2
custom03		0	150	Custom attribute 3

Full JSON user representation

The following is a non-normative example of the fully populated SCIM representation in JSON format.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "9aa00-e97a-11e7-9faf-236ea7c81614",
  "externalId": "701984",
  "userName": "bjensen@example.com",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "displayName": "Babs Jensen",
  "nickName": "Fruit Loop",
  "profileUrl": "https://profile.example.com/bjensen",
  "emails": [
    {
      "value": "bjensen@example.com",
      "type": "work",
      "primary": true
    },
    {
      "value": "babs@jensen.org",
      "type": "home"
    }
  ],
  "addresses": [
    {
      "streetAddress": "100 Universal City Plaza",
      "locality": "Hollywood",
      "region": "CA",
      "postalCode": "91608",
      "country": "USA",
      "type": "work",
      "primary": true
    },
    {
      "type": "home",
      "streetAddress": "7632 cherry st",
      "postalCode": "coral springs",
      "locality": "nevada",
      "region": "85702",
      "country": "Spain"
    }
  ],
  "phoneNumbers": [
    {
      "type": "work",
      "primary": true,
      "value": "0061 3 9297 1600"
    },
    {
      "type": "home",
      "value": "(345)-767-6101"
    },
    {
      "type": "mobile",
      "value": "(068)-597-6483"
    }
  ],
  "photos": [
    {
      "value": "https://cdn.federated.directory/images/users/demo/w1.jpg",
      "type": "photo"
    },
    {
      "value": "https://cdn.federated.directory/images/users/demo/thumb/thumb_w1.jpg",
      "type": "thumbnail"
    }
  ],
  "userType": "Employee",
  "title": "Tour Guide",
  "active": true,
  "groups": [
    {
      "value": "7e9f14a0-fe8d-11ea-b3f4-d179f9eb8415",
      "display": "Tour Guides",
      "logos": [
        {
          "value": "https://cdn.federated.directory/images/groups/defaultgroup_icon_dskgidIYUDFYGUIKJugkj.svg",
          "type": "logo"
        },
        {
          "value": "https://cdn.federated.directory/images/groups/thumb/defaultgroup_icon_dskgidIYUDFYGUIKJugkj.svg",
          "type": "thumbnail"
        }
      ],
      "owner": true,
      "assignedByFilter": false
    }
  ],
  "roles": [
    {
      "value": "user",
      "display": "user"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "organization": "Cafe Expresso",
    "employeeNumber": "701984",
    "costCenter": "Hub04387",
    "division": "Getting Started",
    "department": "Bulk",
    "manager": {
      "displayName": "Paul Adam",
      "value": "d09420a0-e97a-11e7-9faf-236ea7c81614",
      "$ref": "../v2/Users/d09420a0-e97a-11e7-9faf-236ea7c81614"
    }
  },
  "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
    "description": "Potest manducare glacies crepito formidolose",
    "companyId": "8dc57fd0-d2af-11e7-9840-e757c2c4aa66",
    "companyLogos": [
      {
        "value": "https://dev.federated.directory/uploads/8dc57fd0-d2af-11e7-9840-e757c2c4aa66/8dc57fd0-d2af-11e7-9840-e757c2c4aa66_ow8fl.png",
        "type": "logo"
      },
      {
        "value": "https://dev.federated.directory/uploads/8dc57fd0-d2af-11e7-9840-e757c2c4aa66/thumb/8dc57fd0-d2af-11e7-9840-e757c2c4aa66_ow8fl.png",
        "type": "thumbnail"
      }
    ],
    "directoryId": "8dc57fd4-d2af-11e7-9840-e757c2c4aa66"
  },
  "meta": {
    "resourceType": "User",
    "location": "https://api.federated.directory/v2/Users/d0b9aa00-e97a-11e7-9faf-236ea7c81614",
    "created": "2017-12-25T13:52:15.000Z",
    "lastModified": "2018-03-25T11:28:24.000Z"
  }
}

Search users

Search through all the users in your Federated Directory. Over all companies, divisions and departments.

Key	Value
method	GET
url	https://api.federated.directory/v2/Users/?filter={filter}&attributes={attributes}&sortBy={sortBy}&sortOrder={sortOrder}&count={count}&startIndex={startindex}
headers	Content-Type: application/json Authorization: Bearer {token}

Parameters

The response can be controlled by the below parameters. Remember that the actual user data in the response, depends on the permissions and scope of the token, the groups memberships of this user and the shared attributes in each of these groups.

All attribute names, operators and parameters are case sensitive.

attributes

The attributes, filter and sortBy parameters can be configured by the below list of attributes.

Attribute	Filter operator
id	eq
externalId	eq co (admin only)
userName	eq co (admin only)
name.givenName
name.familyName
displayName	co
nickName
profileUrl
title	co
userType
emails
phoneNumbers
addresses
preferredLanguage
locale
timezone
active
groups	eq (group members only)
roles
meta
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division	co
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department	co
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager	eq (use manager.value)
urn:ietf:params:scim:schemas:extension:fd:2.0:User:description
urn:ietf:params:scim:schemas:extension:fd:2.0:User:directoryId	eq
urn:ietf:params:scim:schemas:extension:fd:2.0:User:companyId	eq
urn:ietf:params:scim:schemas:extension:fd:2.0:User:companyLogos

When no attributes are specified as a parameter in the query, it will default to the bold printed attributes above.

filter

Filter supports the following operators:

co → (contains)
eq → (equals)
and → (to combine multiple search operators)

Every filter attribute has a default filter operator which will be used, no matter which filter operator you use in the query. This default filter operator query can be found in the above attribute table. You can only filter on those attributes that have a default filter operator value.

Retrieve all the users with the same manager by settings a filter on urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value.

An administrator can only filter on directoryId within his own company. If directoryId is provided in the filter, any optional companyId in the filter is ignored.

sortBy

All of the attributes in the above table can be used in the ‘sortBy’ query parameter.

sortOrder

The sort order determines the sorting direction:

ascending
descending

If not specified. defaults to ascending.

count

Specifies the maximum number of results. Minimum 1 and maximum 50. If not specified it defaults back to 50.

startIndex

The 1-based index of the first result in the current set of list results. Minimum 1. If not specified it defaults back to 1.

Example Request

curl -X GET \
  'https://api.federated.directory/v2/Users?filter=urn:ietf:params:scim:schemas:extension:fd:2.0:User:companyId co %228dc57fd0-d2af-11e7-9840-e757c2c4aa66%22 and urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division co%22Getting Started%22 and urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department co %22Bulk%22&attributes=displayName,photos,title,urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division,urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department,urn:ietf:params:scim:schemas:extension:fd:2.0:User:companyId&sortBy=displayName&sortOrder=ascending&count=4&startIndex=1' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json'

Example Response

http status code: 200

{
  "totalResults": 4,
  "itemsPerPage": 4,
  "startIndex": 1,
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
      ],
      "id": "0fbc35e0-4d2d-11e8-a9c6-fbdcd95513af",
      "displayName": "Armando Pearson",
      "photos": [
        {
          "type": "photo",
          "primary": true,
          "value": "https://cdn.federated.directory/images/users/demo/m26.jpg"
        },
        {
          "type": "thumbnail",
          "value": "https://cdn.federated.directory/images/users/demo/thumb/thumb_m26.jpg"
        }
      ],
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "division": "Getting Started",
        "department": "Bulk"
      },
      "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
        "companyId": "8dc57fd0-d2af-11e7-9840-e757c2c4aa66"
      }
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
      ],
      "id": "0fbbe7c0-4d2d-11e8-a9c6-fbdcd95513af",
      "displayName": "Deborah Watson",
      "photos": [
        {
          "type": "photo",
          "primary": true,
          "value": "https://cdn.federated.directory/images/users/demo/w18.jpg"
        },
        {
          "type": "thumbnail",
          "value": "https://cdn.federated.directory/images/users/demo/thumb/thumb_w18.jpg"
        }
      ],
      "title": "Project Manager",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "division": "Getting Started",
        "department": "Bulk"
      },
      "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
        "companyId": "8dc57fd0-d2af-11e7-9840-e757c2c4aa66"
      }
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
      ],
      "id": "0fbbc0b0-4d2d-11e8-a9c6-fbdcd95513af",
      "displayName": "Mae Thomas",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "division": "Getting Started",
        "department": "Bulk"
      },
      "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
        "companyId": "8dc57fd0-d2af-11e7-9840-e757c2c4aa66"
      }
    },
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
      ],
      "id": "0fbc5cf0-4d2d-11e8-a9c6-fbdcd95513af",
      "displayName": "Rói Da Rosa",
      "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "division": "Getting Started",
        "department": "Bulk"
      },
      "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
        "companyId": "8dc57fd0-d2af-11e7-9840-e757c2c4aa66"
      }
    }
  ]
}

Get a user

Get the data of one specific user.

Key	Value
method	GET
url	https://api.federated.directory/v2/Users/{id}?attributes={attributes}
headers	Content-Type: application/json Authorization: Bearer {token}

Parameters

The response can only be controlled by the ‘attributes’ parameters. Remember that the actual user data in the response, depends on the permissions and scope of the token (from a user or key) and the data federated with your company.

All attribute names are case sensitive.

attributes

Use the same attributes as during the ‘search users’ queries above.

When no ‘attributes’ parameter is specified, all user attributes with a value will be returned. Including the ‘meta’ object for administrators.

Example Request

curl -X GET \
  'https://api.federated.directory/v2/Users/0dc48490-4d2d-11e8-a9c6-fbdcd95513af?attributes=displayName,userName,phoneNumbers,name.givenName,urn:ietf:params:scim:schemas:extension:fd:2.0:User:description,active,roles' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json'

Example Response

http status code: 200

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
  ],
  "id": "0dc48490-4d2d-11e8-a9c6-fbdcd95513af",
  "userName": "bjensen@example.com",
  "displayName": "Babs Jensen",
  "roles": [
    {
      "value": "user",
      "display": "user"
    }
  ],
  "active": true,
  "name": {
    "givenName": "Barbara"
  },
  "phoneNumbers": [
    {
      "type": "work",
      "primary": true,
      "value": "0061 3 9297 1600"
    },
    {
      "type": "home",
      "value": "(345)-767-6101"
    },
    {
      "type": "mobile",
      "value": "(068)-597-6483"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
    "description": "Potest manducare glacies crepito formidolose"
  },
}

Create user

Create a new user in a directory in your company.

Key	Value
method	POST
url	https://api.federated.directory/v2/Users
headers	Content-Type: application/json Authorization: Bearer {token} directoryId: {directoryId}
body	See below

The ‘directoryId’ in the header indicates the directory in which the user should be created. This could also be part of the user JSON in the body. If the bearer token comes from a directory key, a reference to a directoryId is not needed, since the directory key is bound to one single directory.

Body

User JSON object. See chapter “User data model” and “Full JSON user representation”.

Always include the mandatory attributes userName & displayName when creating a user. However a contact does not contain a userName. Do not include an id attribute or the meta object.

Example Request

curl -X POST \
  https://api.federated.directory/v2/Users \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'directoryId: 8dc57fd4-d2af-11e7-9840-e757c2c4aa66' \
  -d '{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
  ],
  "externalId": "701984",
  "userName": "bjensen@example.com",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "displayName": "Babs Jensen",
  "nickName": "Fruit Loop",
  "profileUrl": "https://profile.example.com/bjensen",
  "emails": [
    {
      "value": "bjensen@example.com",
      "type": "work",
      "primary": true
    },
    {
      "value": "babs@jensen.org",
      "type": "home"
    }
  ],
  "addresses": [
    {
      "streetAddress": "100 Universal City Plaza",
      "locality": "Hollywood",
      "region": "CA",
      "postalCode": "91608",
      "country": "USA",
      "type": "work",
      "primary": true
    },
    {
      "type": "home",
      "streetAddress": "7632 cherry st",
      "postalCode": "coral springs",
      "locality": "nevada",
      "region": "85702",
      "country": "Spain"
    }
  ],
  "phoneNumbers": [
    {
      "type": "work",
      "primary": true,
      "value": "0061 3 9297 1600"
    },
    {
      "type": "home",
      "value": "(345)-767-6101"
    },
    {
      "type": "mobile",
      "value": "(068)-597-6483"
    }
  ],
  "photos": [
    {
      "value": "https://cdn.federated.directory/images/users/demo/w1.jpg",
      "type": "photo"
    },
    {
      "value": "https://cdn.federated.directory/images/users/demo/thumb/thumb_w1.jpg",
      "type": "thumbnail"
    }
  ],
  "userType": "Employee",
  "title": "Tour Guide",
  "active": true,
  "roles": [
    {
      "value": "user",
      "display": "user"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "701984",
    "costCenter": "Hub04387",
    "division": "Getting Started"
  },
  "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
    "description": "Potest manducare glacies crepito formidolose"
  }
}'

Example Response

http status code: 201

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
  ],
  "id": "dfc73700-586b-11e8-8519-2b3682bb456c",
  "externalId": "701984",
  "userName": "bjensen@example.com",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "displayName": "Babs Jensen",
  "nickName": "Fruit Loop",
  "profileUrl": "https://profile.example.com/bjensen",
  "addresses": [
    {
      "type": "work",
      "primary": true,
      "streetAddress": "100 Universal City Plaza",
      "postalCode": "91608",
      "locality": "Hollywood",
      "region": "CA",
      "country": "USA"
    },
    {
      "type": "home",
      "streetAddress": "7632 cherry st",
      "postalCode": "coral springs",
      "locality": "nevada",
      "region": "85702",
      "country": "Spain"
    }
  ],
  "emails": [
    {
      "type": "work",
      "primary": true,
      "value": "bjensen@example.com"
    },
    {
      "type": "home",
      "value": "babs@jensen.org"
    }
  ],
  "phoneNumbers": [
    {
      "type": "work",
      "primary": true,
      "value": "0061 3 9297 1600"
    },
    {
      "type": "home",
      "value": "(345)-767-6101"
    },
    {
      "type": "mobile",
      "value": "(068)-597-6483"
    }
  ],
  "photos": [
    {
      "type": "photo",
      "primary": true,
      "value": "https://cdn.federated.directory/images/users/demo/w1.jpg"
    },
    {
      "type": "thumbnail",
      "value": "https://cdn.federated.directory/images/users/demo/thumb/thumb_w1.jpg"
    }
  ],
  "userType": "Employee",
  "title": "Tour Guide",
  "groups": [
    {
      "value": "7e9f14a0-fe8d-11ea-b3f4-d179f9eb8415",
      "display": "All users",
      "logos": [
        {
          "value": "https://cdn.federated.directory/images/groups/defaultgroup_icon_dskgidIYUDFYGUIKJugkj.svg",
          "type": "logo"
        },
        {
          "value": "https://cdn.federated.directory/images/groups/thumb/defaultgroup_icon_dskgidIYUDFYGUIKJugkj.svg",
          "type": "thumbnail"
        }
      ],
      "owner": false,
      "assignedByFilter": true
    }
  ],
  "active": true,
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "organization": "Cafe Expresso",
    "employeeNumber": "701984",
    "costCenter": "Hub04387",
    "division": "Getting Started"
  },
  "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
    "companyId": "8dc57fd0-d2af-11e7-9840-e757c2c4aa66",
    "companyLogos": [
      {
        "value": "https://dev.federated.directory/uploads/8dc57fd0-d2af-11e7-9840-e757c2c4aa66/8dc57fd0-d2af-11e7-9840-e757c2c4aa66_ow8fl.png",
        "type": "logo"
      },
      {
        "value": "https://dev.federated.directory/uploads/8dc57fd0-d2af-11e7-9840-e757c2c4aa66/thumb/8dc57fd0-d2af-11e7-9840-e757c2c4aa66_ow8fl.png",
        "type": "thumbnail"
      }
    ],
    "directoryId": "5b0afcc1-3262-11e7-9579-1d8db7d7ec6a",
    "description": "Potest manducare glacies crepito formidolose"
  },
  "roles": [
    {
      "value": "user",
      "display": "user"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "https://api.federated.directory/v2/Users/dfc73700-586b-11e8-8519-2b3682bb456c",
    "created": "2018-05-15T18:14:57.392Z"
  }
}

Update user (PATCH)

Update a user with a PATCH call to update one or more attributes.

Key	Value
method	PATCH
url	https://api.federated.directory/v2/Users/{id}
headers	Content-Type: application/json Authorization: Bearer {token}
body	See below

The body of a patch call includes an Operations array. Every object in this array contains a specific operation (add, remove, replace) on one or more attributes of this user.

There are two types of Operation objects:

1. With a path key
One user attribute per operation can be changed. The path indicates the user attribute that needs to be changed. In case of an ‘add’ or ‘replace’ operation, will the new value be present in the ‘value’ key.

2. Without a path key
Every operation can change multiple user attributes. Every operation can basically contain part .

Body with a path key

This operation consists out of the following attributes.

Key	Value
op	‘add’, ‘replace’ or ‘remove’
path	The user attribute.
value	The new value of the attribute.

Every operation modifies one attribute. Since every attribute should be defined explicitly (even in a multi valued attribute like emails), an ‘add’ operation is the same as a ‘replace’ operation.

An attribute is defined in the path and MAY be uniquely identified by prefixing the attribute name with its schema URN separated by a colon (“:”) character; e.g., the core User resource attribute ‘userName’ is identified as “urn:ietf:params:scim:schemas:core:2.0:User:userName” or just as “userName”.

Complex attributes’ sub-attributes are referenced via nested dot (‘.’) notation, i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For example, the fully qualified path for a User’s givenName is “urn:ietf:params:scim:schemas:core:2.0:User:name.givenName” (or just ‘name.givenName’). All facets (URN, attribute, and sub-attribute name) of the fully encoded attribute name are case insensitive.

Multi value attributes like ‘emails’,’phoneNumbers’ & ‘addresses’ include the ‘type’ in the ‘path’:

emails[type eq "work"].value
phoneNumbers[type eq "home"].value
addresses[type eq "work"].streetAddress
photos[type eq "thumbnail"].value

The ‘manager’ and ‘roles’ attributes are not multi valued but rather complex. Their ‘path’ is actually pretty easy:

manager
roles

The value is defined as a string or as an array with one object.
Usually, this object contains one value attribute, except for the ‘manager’. In that case it could also contain a displayName. If they are both defined, the value of the manager | takes precedence.

Body without a path key

This operation consists out of the following attributes.

Attribute	Value
op	‘add’ or ‘replace’
value	The new value of the attribute. Only in case of an ‘add’ or a ‘replace’

Every operation modifies one or more attribute. Since every attribute should be defined explicitly (even in a multi valued attribute like emails), an ‘add’ operation is the same as a ‘replace’ operation.

The attributes in the value object have the exact same format as the user attributes in a POST or PUT call. But in this case it can contain parts of user and only the attributes mentioned in this object will be replaced on the user.

Example Request

The below example contains the three patch operation methods:

with path attribute and value as an array with one object
with path attribute and value as a string
without a path attribute

curl -X PATCH \
  https://api.federated.directory/v2/Users/dfc73700-586b-11e8-8519-2b3682bb456c \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  -d '{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "Replace",
            "path": "userName",
            "value": [
                {
                    "value": "babs@example.net"
                }
            ]
        },
        {
            "op": "Replace",
            "path": "name.familyName",
            "value": [
                {
                    "value": "Gibson"
                }
            ]
        },
        {
            "op": "Replace",
            "path": "password",
            "value": [
                {
                    "value": "Mndsjgdh!d1265@4JH#FJGDH"
                }
            ]
        },
        {
            "op": "Add",
            "path": "manager",
            "value": [
                {
                    "value": "dfc73700-586b-11e8-8519-2b3682bb456c",
                    "display": "Babs"
                }
            ]
        },
        {
            "op": "Add",
            "path": "emails[type eq \"home\"].value",
            "value": "babs@example.net"
        },
        {
            "op": "Add",
            "path": "urn:ietf:params:scim:schemas:extension:fd:2.0:User:description",
            "value": "Company Chess Champion of 2012"
        },
        {
            "op": "Replace",
            "path": "roles",
            "value": "admin"
        },
        {
            "op": "Add",
            "value": {
                "userType": "Patched UserType",
                "addresses": [
                    {
                        "country": "DE",
                        "type": "work",
                        "primary": "true",
                        "locality": "Berlin"
                    }
                ]
            }
        },
        {
            "op": "Replace",
            "value": {
                "phoneNumbers": [
                    {
                        "value": "03012345678",
                        "type": "home",
                        "primary": "false"
                    },
                    {
                        "value": "02012345678",
                        "type": "work",
                        "primary": "true"
                    }
                ]
            }
        }
    ]
}'

Example Response

http status code: 200

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
  ],
  "id": "dfc73700-586b-11e8-8519-2b3682bb456c",
  "externalId": "701984",
  "userName": "babs@example.net",
  "name": {
    "familyName": "Gibson",
    "givenName": "Barbara"
  },
  "displayName": "Ms. Barbara J Jensen, III",
  "nickName": "Fruit Loop",
  "profileUrl": "https://profile.example.com/bjensen",
  "addresses": [
    {
      "type": "work",
      "primary": true,
      "streetAddress": "100 Universal City Plaza",
      "postalCode": "91608",
      "locality": "Berlin",
      "region": "CA",
      "country": "DE"
    },
    {
      "type": "home",
      "streetAddress": "7632 cherry st",
      "postalCode": "coral springs",
      "locality": "nevada",
      "region": "85702",
      "country": "Spain"
    }
  ],
  "emails": [
    {
      "type": "work",
      "primary": true,
      "value": "bjensen@example.com"
    },
    {
      "type": "home",
      "value": "babs@example.net"
    }
  ],
  "phoneNumbers": [
    {
      "type": "work",
      "primary": true,
      "value": "02012345678"
    },
    {
      "type": "home",
      "value": "03012345678"
    },
    {
      "type": "mobile",
      "value": "(068)-597-6483"
    }
  ],
  "photos": [
    {
      "type": "photo",
      "primary": true,
      "value": "https://cdn.federated.directory/images/users/demo/w1.jpg"
    },
    {
      "type": "thumbnail",
      "value": "https://cdn.federated.directory/images/users/demo/thumb/thumb_w1.jpg"
    }
  ],
  "userType": "Patched UserType",
  "title": "Tour Guide",
  "active": true,
  "groups": [
    {
      "value": "7e9f14a0-fe8d-11ea-b3f4-d179f9eb8415",
      "display": "All users",
      "logos": [
        {
          "value": "https://cdn.federated.directory/images/groups/defaultgroup_icon_dskgidIYUDFYGUIKJugkj.svg",
          "type": "logo"
        },
        {
          "value": "https://cdn.federated.directory/images/groups/thumb/defaultgroup_icon_dskgidIYUDFYGUIKJugkj.svg",
          "type": "thumbnail"
        }
      ],
      "owner": false,
      "assignedByFilter": true
    },
    {
      "value": "5e9f14a0-fe8d-11ea-b3f4-d179f9eb8422",
      "display": "Project Muffin",
      "logos": [
        {
          "value": "https://cdn.federated.directory/uploads/groups/5e9f14a0-fe8d-11ea-b3f4-d179f9eb8422/5e9f14a0-fe8d-11ea-b3f4-d179f9eb8422_IKJuk.svg",
          "type": "logo"
        },
        {
          "value": "https://cdn.federated.directory/uploads/groups/5e9f14a0-fe8d-11ea-b3f4-d179f9eb8422/thumb/5e9f14a0-fe8d-11ea-b3f4-d179f9eb8422_IKJuk.svg",
          "type": "thumbnail"
        }
      ],
      "owner": true,
      "assignedByFilter": false
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "organization": "Cafe Expresso",
    "employeeNumber": "701984",
    "costCenter": "Hub04387",
    "manager": {
      "value": "dfc73700-586b-11e8-8519-2b3682bb456c",
      "$ref": "../v2/Users/dfc73700-586b-11e8-8519-2b3682bb456c",
      "displayName": "Babs Jensen"
    }
  },
  "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
    "companyId": "8dc57fd0-d2af-11e7-9840-e757c2c4aa66",
    "companyLogos": [
      {
        "value": "https://dev.federated.directory/uploads/8dc57fd0-d2af-11e7-9840-e757c2c4aa66/8dc57fd0-d2af-11e7-9840-e757c2c4aa66_ow8fl.png",
        "type": "logo"
      },
      {
        "value": "https://dev.federated.directory/uploads/8dc57fd0-d2af-11e7-9840-e757c2c4aa66/thumb/8dc57fd0-d2af-11e7-9840-e757c2c4aa66_ow8fl.png",
        "type": "thumbnail"
      }
    ],
    "directoryId": "5b0afcc1-3262-11e7-9579-1d8db7d7ec6a",
    "description": "Company Chess Champion of 2012"
  },
  "roles": [
    {
      "value": "admin",
      "display": "admin"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "https://api.federated.directory/v2/Users/dfc73700-586b-11e8-8519-2b3682bb456c",
    "created": "2018-05-15T18:14:57.000Z",
    "lastModified": "2018-05-15T18:41:35.736Z"
  }
}

Update user (PUT)

Update a user with a PUT call to replace all the users attributes.

Key	Value
method	PUT
url	https://api.federated.directory/v2/Users/{id}
headers	Content-Type: application/json Authorization: Bearer {token}
body	See below

The body of a PUT call is comparable with that of the POST call, but can include all the attributes retrieved of the user in a GET call. Like the id or meta object. Those are not mutable but can be included.

Mutable attributes not included in the body of the PUT will be emptied or reset to its default value. Group memberships can be included in the PUT but will be ignored. Group memberships can only be changed in a PATCH.

Example Request

curl -X PUT \
  https://api.federated.directory/v2/Users/0fbc35e0-4d2d-11e8-a9c6-fbdcd95513af \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  -d '{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
  ],
  "userName": "armando.pearson@example.com",
  "name": {
    "familyName": "Pearson",
    "givenName": "Armando Lawrence"
  },
  "displayName": "Armando Pearson",
  "emails": [
    {
      "type": "work",
      "primary": true,
      "value": "armando.pearson@example.com"
    }
  ],
  "photos": [
    {
      "type": "photo",
      "value": "https://cdn.federated.directory/images/users/demo/m26.jpg"
    },
    {
      "type": "thumbnail",
      "value": "https://cdn.federated.directory/images/users/demo/thumb/thumb_m26.jpg"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "manager": {
      "value": "0fbbe7c0-4d2d-11e8-a9c6-fbdcd95513af"
    }
  }
}'

Example Response

http status code: 200

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
  ],
  "id": "0fbc35e0-4d2d-11e8-a9c6-fbdcd95513af",
  "userName": "armando.pearson@example.com",
  "name": {
    "familyName": "Pearson",
    "givenName": "Armando Lawrence"
  },
  "displayName": "Armando Pearson",
  "emails": [
    {
      "type": "work",
      "primary": true,
      "value": "armando.pearson@example.com"
    }
  ],
  "photos": [
    {
      "type": "photo",
      "primary": true,
      "value": "https://cdn.federated.directory/images/users/demo/m26.jpg"
    },
    {
      "type": "thumbnail",
      "value": "https://cdn.federated.directory/images/users/demo/thumb/thumb_m26.jpg"
    }
  ],
  "active": false,
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "organization": "Cafe Expresso",
    "manager": {
      "value": "0fbbe7c0-4d2d-11e8-a9c6-fbdcd95513af",
      "$ref": "../v2/Users/0fbbe7c0-4d2d-11e8-a9c6-fbdcd95513af",
      "displayName": "Deborah Watson"
    }
  },
  "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
    "companyId": "8dc57fd0-d2af-11e7-9840-e757c2c4aa66",
    "companyLogos": [
      {
        "value": "https://dev.federated.directory/uploads/8dc57fd0-d2af-11e7-9840-e757c2c4aa66/8dc57fd0-d2af-11e7-9840-e757c2c4aa66_ow8fl.png",
        "type": "logo"
      },
      {
        "value": "https://dev.federated.directory/uploads/8dc57fd0-d2af-11e7-9840-e757c2c4aa66/thumb/8dc57fd0-d2af-11e7-9840-e757c2c4aa66_ow8fl.png",
        "type": "thumbnail"
      }
    ],
    "directoryId": "5b0afcc1-3262-11e7-9579-1d8db7d7ec6a"
  },
  "roles": [
    {
      "value": "user",
      "display": "user"
    }
  ],
  "meta": {
    "resourceType": "User",
    "location": "https://api.federated.directory/v2/Users/0fbc35e0-4d2d-11e8-a9c6-fbdcd95513af",
    "created": "2018-05-01T10:47:36.000Z",
    "lastModified": "2018-05-15T18:55:54.102Z"
  }
}

Delete user

Delete a user. Will remove the user and it’s data completely. Can not be restored. This will also remove the user from all its groups.

Key	Value
method	DELETE
url	https://api.federated.directory/v2/Users/{id}
headers	Content-Type: application/json Authorization: Bearer {token}

Example Request

curl -X DELETE \
  https://api.federated.directory/v2/Users/dfc73700-586b-11e8-8519-2b3682bb456c \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \

Example Response

http status code: 204

Bulk user updates

Perform multiple (max 1000) user CRUD (Create, Update, Delete) actions in one API call.

Key	Value
method	POST
url	https://api.federated.directory/v2/Bulk
headers	Content-Type: application/json Authorization: Bearer {token} directoryId: {directoryId}
body	See below

The ‘directoryId’ in the header indicates the directory in which the users should be created. All users in a bulk action should be located in the same directory.

Body

The body of a bulk call includes an Operations array. Every object in this array contains a user CRUD action.

An operation object consists out of the following attributes.

Attribute	Comment
data	The same JSON you would use in the body of a normal POST or PUT call
method	‘POST’, ‘PUT’ or ‘DELETE’. ‘PATCH’ is not supported
bulkId	Temporary id, used in the response. Can not be used to assign a user as manager to other users
path	Optional. Path to user endpoint

Example Request

curl -X POST \
  https://api.federated.directory/v2/Bulk \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -H 'directoryid: 8dc57fd4-d2af-11e7-9840-e757c2c4aa66' \
  -d '{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
  ],
  "Operations": [
    {
      "data": {
        "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "externalId": "701984",
        "userName": "bjensen@example.com",
        "name": {
          "familyName": "Jensen",
          "givenName": "Barbara"
        },
        "displayName": "Babs Jensen",
        "emails": [
          {
            "value": "bjensen@example.com",
            "type": "work",
            "primary": true
          }
        ],
        "addresses": [
          {
            "streetAddress": "100 Universal City Plaza",
            "locality": "Hollywood",
            "region": "CA",
            "postalCode": "91608",
            "country": "USA",
            "type": "work",
            "primary": true
          }
        ],
        "phoneNumbers": [
          {
            "type": "mobile",
            "value": "(068)-597-6483"
          }
        ]
      },
      "method": "POST",
      "bulkId": "bjensen@example.com",
      "path": "/Users"
    },
    {
      "data": {
        "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User",
          "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
          "urn:ietf:params:scim:schemas:extension:fd:2.0:User"
        ],
        "id": "d6b52060-4d7f-11e8-8b44-3d5adce8c545",
        "userName": "armando.pearson@example.com",
        "name": {
          "familyName": "Pearson",
          "givenName": "Armando Lawrence"
        },
        "displayName": "Armando Pearson",
        "emails": [
          {
            "type": "work",
            "primary": true,
            "value": "armando.pearson@example.com"
          }
        ],
        "photos": [
          {
            "type": "photo",
            "value": "https://cdn.federated.directory/images/users/demo/m26.jpg"
          },
          {
            "type": "thumbnail",
            "value": "https://cdn.federated.directory/images/users/demo/thumb/thumb_m26.jpg"
          }
        ],
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
          "manager": {
            "value": "c6d02640-593c-11e8-a0b7-ed7a977b183b"
          },
          "division": "Getting Started",
          "department": "Bulk"
        },
        "urn:ietf:params:scim:schemas:extension:fd:2.0:User": {
          "description": "Never watched Game of Thrones"
        }
      },
      "method": "PUT",
      "bulkId": "d6b52060-4d7f-11e8-8b44-3d5adce8c545",
      "path": "/Users/d6b52060-4d7f-11e8-8b44-3d5adce8c545"
    },
    {
      "data": {
        "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "id": "d6b52060-4d7f-11e8-8b44-3d5adce8c545"
      },
      "method": "DELETE",
      "bulkId": "d6b52060-4d7f-11e8-8b44-3d5adce8c545",
      "path": "/Users/d6b52060-4d7f-11e8-8b44-3d5adce8c545"
    }
  ]
}

Example Response

http status code: 200

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
  "Operations": [
    {
      "bulkId": "bjensen@example.com",
      "method": "POST",
      "location": "https://api.federated.directory/v2/Users/a9460fa0-eb0e-11e7-b1e2-6f788593d827",
      "status": {
        "code": 201
      }
    },
    {
      "bulkId": "d6b52060-4d7f-11e8-8b44-3d5adce8c545",
      "method": "PUT",
      "location": "https://api.federated.directory/v2/Users/d6b52060-4d7f-11e8-8b44-3d5adce8c545",
      "status": {
        "code": 200
      }
    },
    {
      "bulkId": "d6b52060-4d7f-11e8-8b44-3d5adce8c545",
      "method": "DELETE",
      "location": "https://api.federated.directory/v2/Users/d6b52060-4d7f-11e8-8b44-3d5adce8c545",
      "status": {
        "code": 204
      }
    }
  ]
}