Web API

Press shift + S to search API reference.

Users

Manage user membership

posthttps://api.airtable.com/v0/meta/enterpriseAccounts/{enterpriseAccountId}/users/claim

Batch manage organizations enterprise account users. This endpoint allows you to change a user's membership status from being unmanaged to being an organization member, and vice versa. To use this endpoint, provide either the user's id or email in the request body. If both are supplied, the email will be ignored.

This endpoint can only be used if your enterprise is not domain capturing.

In the example request provided, the first two users are successfully processed while all of the remaining users are not processed and are returned in the errors array with the reason why they were not able to be processed.

Note that the domain of the user you are trying to claim must be verified in your organization's Admin Panel. If the domain is not verified, the user will not be claimed and will be returned in the errors array.

For more information on managing users and the different types of users in organizations, please see our support article.

Requirements

AuthenticationPersonal access token, OAuth integration
Scopeenterprise.user:write
User role

Enterprise admin

Billing plansEnterprise (pre-2023.08 legacy plan), Enterprise Scale

Path parameters

enterpriseAccountId
string

Request body

users
array of the below object
id
optional<string>

A user ID

state
"managed" | "unmanaged"
email
optional<string>

Response format

errors
array of the below object
id
optional<string>
type
string
message
string
email
optional<string>

Error responses

ID or email not specified (422)
Either id or email must be supplied in the request body, or there were no valid users in your request.
{
"error": {
"message": "Invalid request: either ID or email must be specified. Check your request data.",
"type": "INVALID_REQUEST_UNKNOWN"
}
}
Request (example)
Copy
$
curl -X POST "https://api.airtable.com/v0/meta/enterpriseAccounts/{enterpriseAccountId}/users/claim" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"users": [
{
"id": "usrL2PNC5o3H4lBEi",
"state": "managed"
},
{
"email": "foo@bar.com",
"state": "unmanaged"
},
{
"email": "bam@bam.com",
"state": "managed"
},
{
"id": "usrsOEchC9xuwRgKk",
"state": "unmanaged"
},
{
"id": "usrL2PNC5o3H4lBEi",
"state": "managed"
},
{
"email": "user@unverifiedDomain.com",
"state": "managed"
},
{
"email": "user@externalDomain.com",
"state": "managed"
},
{
"id": "usrGcrteE5fUMqq0R",
"state": "managed"
},
{
"id": "usrqccqnMB2eHylqB",
"state": "managed"
},
{
"id": "usrogvSbotRtzdtZW",
"state": "unmanaged"
},
{
"email": "foo@bam.com",
"state": "unmanaged"
},
{
"id": "usrcQYqV90vkqUDXv",
"state": "unmanaged"
}
]
}'
200 – Response (example)
{
"errors": [
{
"email": "bam@bam.com",
"message": "User not found",
"type": "NOT_FOUND"
},
{
"id": "usrsOEchC9xuwRgKk",
"message": "User not found",
"type": "MODEL_ID_NOT_FOUND"
},
{
"id": "usrL2PNC5o3H4lBEi",
"message": "Duplicate user",
"type": "DUPLICATE"
},
{
"email": "user@unverifiedDomain.com",
"message": "Domain is unverified, please verify your domain or request to manage user instead",
"type": "DOMAIN_IS_UNVERIFIED"
},
{
"email": "user@externalDomain.com",
"message": "User email domain is not part of this enterprise",
"type": "NOT_FOUND"
},
{
"id": "usrGcrteE5fUMqq0R",
"message": "User is already claimed by enterprise account entUBq2RGdihxl3vU",
"type": "ALREADY_CLAIMED"
},
{
"id": "usrqccqnMB2eHylqB",
"message": "User is already claimed by this enterprise account",
"type": "ALREADY_CLAIMED"
},
{
"id": "usrogvSbotRtzdtZW",
"message": "User is not claimed by this enterprise account",
"type": "NOT_CLAIMED"
},
{
"id": "foo@bam.com",
"message": "Service accounts cannot be unmanaged",
"type": "SERVICE_ACCOUNT"
},
{
"id": "usrcQYqV90vkqUDXv",
"message": "Deactivated users cannot be unmanaged",
"type": "DEACTIVATED_USER"
}
]
}