Account Management API

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:

1. Within Admin Center, navigate to the People panel, then open the Identity providers tab.
2. 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.
3. On the Permissions tab for your custom integration, add the permission Manage accounts.
4. Get an access token for your custom integration by following the steps in the Permissions and access tokens guide.
5. Make API requests to the API endpoints with the required parameters.

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

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.

Extensions

Enterprise Extension

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

Fixed Fields

Start/Term Date Extension

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

Fixed Fields

Account Status Details Extension

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

Fixed Fields

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

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

Fixed Fields

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.

Fixed Fields

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.

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.

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