Account management API

Overview

The account management API for Meta Admin Center is a REST-based API that is compliant with the open standard SCIM 2.0, and which can be used for creating, updating and deactivating accounts within Admin Center.

In this section you'll find documentation for the SCIM schemas supported by Admin Center, as well as example requests and guides for how to use the API.

Using the API

The account management API is available to organizations using Admin Center via custom integrations.

In order to use the API, you need to have the correct permissions to create and manage custom integrations for your organization on Admin Center.

Follow the steps below to use the API:

Within Admin Center, navigate to the People panel, then open the Identity providers tab.
Click the Connect button, then choose Custom setup to create a new integration for your organization. Add the name and description as required, and provide a list of IP addresses from which the API calls will be made.
On the Permissions tab for your custom integration, add the permission Manage accounts.
Get an access token for your custom integration by following the steps in the Permissions and access tokens guide.
Make API requests to the API endpoints with the required parameters.

Custom integrations are scoped to the Admin Center where they were created.

API Endpoint

Base URL

The account management API is served from the base URL shown below:

https://scim.workplace.com

Supported paths

Users

The Users endpoint path is used to provision and manage accounts for your organization in Admin Center.

https://scim.workplace.com/Users

This is currently the only accessible endpoint for Work Accounts. All schema and extension properties outlined herein can be used with this endpoint.

Making API requests

All API requests must include Authorization and User-Agent headers. Authorization requires a valid access token.

To learn more about generating access tokens, see Permissions & access tokens.

GET /Users/ HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}
User-Agent: {your user agent}

Core User schema

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

The core user schema provides the base properties to interface with the SCIM API. The root schema may be further expanded with the schema extensions found in the subsequent sections of this document.

Field	Type	Description
`userName`	String	An organization-defined unique identifier for the account
`name`	Object Expand this row to view the data structure of this object.	The properties of the account's name.
`formatted`	String	The account holder's complete name, formatted for display including all prefixes, suffixes and middle names as required.
`familyName`	String	The family name, last name or surname of the account holder.
`givenName`	String	The given name or first name of the account holder.
`middleName`	String	The middle name(s) of the account holder.
`honorificPrefix`	String	The honorific prefix(es) or title(s) of the account holder.
`honorificSuffix`	String	The honorific suffix(es) or title(s) of the account holder.
`active`	Boolean	Identifies an account as active or inactive. Active accounts are able to access Meta tools and receive notifications.
`displayName`	String	The account's publicly displayed name. This will be the name displayed in Admin Center and other Meta tools and products.
`title`	String	The title of the account holder.
`nickName`	String	The preferred or nickname name of the account holder.
`profileUrl`	URL	Any fully qualified URL to the user's online profile.
`preferredLanguage`	String	The preferred language for the account holder. The value must be a language tag in accordance with ISO 639-1 and ISO 3166-1. For further details, see W3 language tags.
`locale`	String	Identifies the account holder's default location for the purposes of localization. The value must be a language tag in accordance with ISO 639-1 and ISO 3166-1. For further details, see W3 language tags.
`timezone`	String	The timezone of the account. The value must be in accordance with the Olson timezone database format.
`userType`	String	Identifies the account holder's relationship with their organization. Values should be in accordance with the organization's employee structure.
`photos`	Object Array	The properties for the account's reference image(s)
`value`	URL	Any fully qualified URL to the account's reference image.
`type`	String	Identifies the type of reference image, e.g. "Profile", "Badge".
`primary`	Boolean	Indicates that this is the primary photo for the account. Only one photo can be designated as the primary photo.
`emails`	Object Array	The properties of the account holder's email address(es).
`value`	String	The complete email address of the account.
`display`	String	READ ONLY The standardized representation of the account's email address. This will be the email address displayed in Meta tools.
`primary`	Boolean	Indicates that this is the primary email address for the account. Only one email address can be designated as the account's primary email address.
`type`	String	Identifies the email type in accordance with the organization's contacts structure, e.g. "Work", "Personal".
`phoneNumbers`	String Array	The phone number(s) on the account. Include country code for valid canonicalization.
`ims`	String Array	The instant messaging address(es) on the account.
`roles`	String Array	The role(s) of the account.
`entitlements`	String Array	The account's entitlements in accordance with the organization's entitlements structure.
`addresses`	Object Array	Addresses for the account.
`primary`	Boolean	Indicates that this is the account's primary address. Only one address can be designated as the account's primary address.
`type`	String	Identifies the address type in accordance with the organization's contacts structure, e.g. "Work", "Personal".
`streetAddress`	String	The full street address including house/apt number, street name, P.O. box, etc as required. This field can accept multi-line extended street address information by allowing newlines ( `\n` .)
`locality`	String	The city or locality of the address.
`region`	String	The state or region.
`postalCode`	String	The zip code or postal code.
`country`	String	The country name in accordance with the ISO 3166-1 alpha-2 short code format.
`formatted`	String	The full mailing address formatted for display or use with a mailing label. This field can accept multi-line extended street address information by allowing newlines ( `\n` ).
`x509Certificates`	String Array	One or more x509certificate values that each contain an X509 certificate issued to the account holder.
`schemas`	String Array	The URN(s) for the schema.
`id`	String	READ ONLY. The unique identifier for the account, as generated in Admin Center.
`externalId`	String	A customer-defined identifier for the User.

Extensions

Enterprise Extension

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

This extension allows organizational properties to be attributed to an account.

Fixed Fields

Field	Type	Description
`employeeNumber`	String	A customer-defined employee identifier for the user.
`costCenter`	String	Identifies the name of the user's cost center.
`organization`	String	Identifies the name of the user's organization.
`division`	String	Identifies the name of the user's division.
`department`	String	Identifies the name of the user's department.
`manager`	Object	The properties of the user's manager. When removing a user's manager, the full object must be removed. It cannot contain an empty value.
`value`	String	The Admin Center generated unique identifier (`id`) for the manager's account.
`$ref`	String	READ ONLY. The URI of the SCIM resource representing the User's manager.
`displayName`	String	READ ONLY. The display name of the manager.

Start/Term Date Extension

URN: urn:ietf:params:scim:schemas:extension:facebook:starttermdates:2.0:User

The Start/Termination Date Extension is used to store the start and termination dates of a user.

Fixed Fields

Field	Type	Description
`startDate`	String	The organization's hire date for the employee. Date format `xsd:dateTime (YYYY-MM-DDThh:mm:ssZ)`
`termDate`	String	The organization's termination date for the employee. Date format `xsd:dateTime (YYYY-MM-DDThh:mm:ssZ)`

Account Status Details Extension

URN: urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User

The Account Status Details Extension is used to identify specific states for a user account.

Fixed Fields

Field	Type	Description
`accessCode`	String	READ ONLY. An access code generated by Admin Center for initial account login.
`accessCodeExpirationDate`	Date/Time	READ ONLY. The expiration date for the access code.
`canDelete`	Boolean	READ ONLY. Identifies whether the account can be deleted.
`claimed`	Boolean	Identifies if the account holder has claimed the account or not.
`claimDate`	Date/Time	Identifies the date (displayed as a Unix timestamp) when the user claimed the account.
`claimLink`	URL	The URL that allows a user to claim the account.
`invited`	Boolean	Identifies if a user is invited to Work Accounts or not.
`invitedDate`	Date/Time	Identifies the date (displayed as a Unix timestamp) when the invitation was sent.

When executing GET user requests, responses will vary depending on the state of the account.

Example Responses

Unclaimed and deactivated account

{
  "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User":{
    "claimed": false,
    "invited": false,
    "inviteDate": "2021-05-19T13:14:29+00:00"
  }
}

Invited and unclaimed account

{
  "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
    "claimed": false,
    "invited": false,
    "inviteDate": "2021-05-19T13:14:29+00:00"
  }
}

Claimed (by claim link) account

{
  "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
    "claimed": true,
    "claimDate": "2021-05-22T10:34:35+00:00",
    "invited": true,
    "inviteDate": "2021-05-19T13:14:29+00:00"
  }
}

Not invited and unclaimed account

{
  "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
    "claimed": false,
    "invited": false
  }
}

Authentication Method Extension

URN: urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User

This extension defines which authentication method users must use to log into their account.

Fixed Fields

Field	Type	Description
`authMethod`	String	The authentication method for the user. The value can only be set to `sso` or `password`

PATCH Operations

PATCH operations allow updates to specific fields. This reduces the overall payload size and mitigates accidental overwriting of existing values. PATCH requests can perform multiple field updates in a single request. Each field being updated is defined as an additional value in the Operations object.

URN: urn:ietf:params:scim:api:messages:2.0:PatchOp

Fixed Fields

Field	Type	Description
`Operations`	Object Array	The properties of the patch operation.
`op`	String	Identifies the operation key: add, replace, remove.
`path`	String	Identifies the path for the field that will be updated.
`value`	String	The updated value for the field. Not required for remove operations.

Request

Request Path

PATCH /Users HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token} 
User-Agent: {your user agent}

Request Body

{
  "schemas":[
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[{
    "op": "{ADD/REMOVE/REPLACE}",
    "path": "{URN:FIELD}",
    "value": ["{STRING/OBJECT/BOOLEAN}"]
  },
  ... + additional operations...
  ]
}

Examples

Create a new account

This request creates a new user account. Newly created user accounts will immediately begin receiving invitation and other notification emails from Work Accounts.

Not all objects in the request body are required when creating a new account. The request body lists all available fields associated with the Users endpoint. Only the userName field is required to create a new user account.

Request:

POST /Users
      
{
    "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:facebook:authmethod:2.0:User"
    ],
    "userName":"anne@example.com",
    "name":{
      	"givenName":"Anne",
    },
    "active":true,
    "displayName":"Anne",
    "emails":[
     	{
      	"value":"anne@example.com",
      	"primary":true,
      }
   	],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    	"employeeNumber":"007",
      }
    },
    "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": {
    	"authMethod": "sso"
    }
}

Response:

201: Created
  
{
    "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:facebook:authmethod:2.0:User"
    ],
    "userName":"anne@example.com",
    "name":{
      	"givenName":"Anne",
    },
    "active":true,
    "displayName":"Anne",
    "emails":[
     	{
      	"value":"anne@example.com",
      	"primary":true,
      }
   	],
    "id":"1987", 
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    	"employeeNumber":"007",
      }
    },
    "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": {
    	"authMethod": "sso"
    }
}

Failing to create a new account when an existing account uses the same username

When there is a pre-existing user account with the same username as the one being used for creation, a HTTP failure status is returned.

Reponse:

409: Conflict

This can typically be resolved by performing a PATCH operation on the existing user account and updating the relevant fields.

Get user by `id`

Fetching an account by using the id field set for it in Admin Center.

Request:

GET /Users/2567
Host: scim.workplace.com

Response:

200: Success
      
{
    "userName":"joe@example.com",
    "active":true,
    "id":"2567"
}

Get user by `userName`

This request finds an account by the value of the customer-defined userName. The username is added to the request as a filter parameter.

Request:

GET /Users?filter=userName%20eq%20%22ednash%22
Host: scim.workplace.com

Response:

200: Success
      
{
    "userName":"ednash",
    "id":"2341"
}

Get all user accounts

This request returns a JSON representation of all user accounts. The default request will return results in pages of 1,000 users. You can configure the request to specify the number of users per page and the page offset by adding count and startIndex parameters to the request.

Request:

GET /Users
Host: scim.workplace.com

Response:

200: Success
      
(1000)[{...}, {...}, {...}, ...]
0: {...}
1: {...}
2: {...}
3: {...}
4: {...}
5: {...}
  "userName":"james@example.com",
  "id":"6"
...
999:{...}
  "userName":"jane@example.com",
  "active":true
  "id":"1000"

Update a User's Title

Request:

PATCH /Users/201

{
  "schemas":[
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[{
    "op": "replace",
    "path": "urn:ietf:params:scim:schemas:core:2.0:User:title",
    "value": "Director"
  }]
}

Response:

200: Success
      
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User"
    ],
    "userName":"anne@example.com",
    "active":true,
    "title":"Director",
    "id":"201",
    "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": {
      "authMethod": "sso"
    }
}

Update account's `invited` state

This request updates an account from a `not invited` state to an `invited` state.

Invited users cannot be uninvited. The request will silently fail and return a response with unchanged values.

Request:

PATCH /Users/7065
Host: scim.workplace.com
      
{
  "schemas":[
  	"urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[{
  	"op": "replace",
  	"path": "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User:invited",
  	"value":true
  }]
}

Response:

200: Success
      
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User" 
    ],
    "userName":"d.grayson",
    "id":"7065", 
    "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": {
    	"invited":true
    }
}

Assign a manager to an account

Identify the manager's account ID

Identify the manager's account ID. If the ID is unknown, perform a GET request to the User endpoint using the manager's username or externalId to retrieve the id field.

GET /Users?filter=userName%20eq%20%22`b.wayne`%22

200: Success
      
{
    "userName":"b.wayne",
    "id":"2567" 
}

Assign a manager to a new account

Perform a Create User request and set the manager's id in the manager field.

Request:

POST https://scim.workplace.com/Users
      
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0/User",
      	"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    ],
    "userName":"d.grayson",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      	"manager":{
      		"value":"2567",
      	}
    }
}

Response:

201: Created
      
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0/User",
      	"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    ],
    "userName":"d.grayson",
    "id":"4215",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      	"manager":{
      		"value":"2567",
      	}
    }
}

Assign Manager to an Existing User

Identify the ID of the account being updated. If the ID is unknown, perform a GET request to the User endpoint using the user's username or externalId to retrieve the id field.

Perform a Patch Request to update the User's manager field.

Request:

PATCH /Users/616

{
  "schemas":[
  	"urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[{
  	"op": "replace",
  	"path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager",
  	"value":{
   		"value":"2567"
   	}
  }]
}

Response:

200: Success
  
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0/User",
      	"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    ],
    "userName":"m.morales",
    "id":"616",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
      	"manager":{
      		"value":"2567",
      	}
    }
}

Account management API

Overview

Using the API

API Endpoint

Base URL

Supported paths

Users

Making API requests

Core User schema

Extensions

Enterprise Extension

Fixed Fields

Start/Term Date Extension

Fixed Fields

Account Status Details Extension

Fixed Fields

Example Responses

Authentication Method Extension

Fixed Fields

PATCH Operations

Fixed Fields

Request

Request Path

Request Body

Examples

Create a new account

Failing to create a new account when an existing account uses the same username

Get user by id

Get user by userName

Get all user accounts

Update a User's Title

Update account's invited state

Assign a manager to an account

Identify the manager's account ID

Assign a manager to a new account

Assign Manager to an Existing User

Get user by `id`

Get user by `userName`

Update account's `invited` state