# Users

## Get organization members

> Get a list of members for an organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization users.","name":"organization_user"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"limit":{"name":"limit","description":"Limits the number of results to return","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"cursor":{"name":"pageToken","description":"Pagination token that keeps of track of the current position in the list","in":"query","schema":{"type":"string"}},"direction":{"name":"reverse","description":"Order in which to retrieve the results","in":"query","schema":{"type":"boolean","default":false}},"queryPreview":{"in":"query","name":"preview","schema":{"type":"boolean"}},"querySearchTermString":{"description":"Search term used to filter organizations by name","in":"query","name":"searchTerm","schema":{"type":"string"}},"queryUserIDs":{"description":"List of user IDs.","in":"query","name":"userIds","schema":{"items":{"format":"uuid","type":"string"},"type":"array"}}},"schemas":{"UserMembershipList":{"type":"object","title":"UserMembershipList","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/UserMembership"}}},"required":["results"]},"UserMembership":{"type":"object","title":"UserMembership","additionalProperties":false,"properties":{"user":{"oneOf":[{"$ref":"#/components/schemas/user"},{"$ref":"#/components/schemas/UserPreview"}]},"status":{"$ref":"#/components/schemas/MembershipStatus"},"createdAt":{"type":"string","format":"date-time","description":"When the membership was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the membership was last updated."},"attributes":{"type":"object","additionalProperties":true,"description":"Authorization context for the membership.","nullable":true},"roleIds":{"type":"array","nullable":true,"uniqueItems":true,"items":{"type":"string","format":"uuid"},"deprecated":true,"description":"IDs of IAM roles assigned to the user."},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"items":{"$ref":"#/components/schemas/iam_role_ref"},"description":"The list of roles to assign to the membership"}},"required":["user","status","createdAt","updatedAt"]},"user":{"type":"object","title":"User","description":"A user on the platform.","properties":{"id":{"type":"string","description":"ID of the user","format":"uuid"},"status":{"type":"string","enum":["pending","active","deleted","invited","banned"],"default":"pending","description":"The status of the user"},"name":{"type":"string","description":"The display name for the user"},"bio":{"type":"string","description":"The user's description"},"activeSessions":{"type":"integer","minimum":0,"description":"The number of logged in session for the user."},"createdAt":{"type":"string","format":"date-time","description":"When the user was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the user was last updated."},"emails":{"type":"array","description":"Email addresses associated with user.","items":{"$ref":"#/components/schemas/user_email"}},"defaultEmail":{"type":"string","description":"The default email of the user in the list of emails."},"identities":{"type":"array","description":"Third-party identities associated with user.","items":{"$ref":"#/components/schemas/user_identity"}},"avatarUrl":{"type":"string","description":"URL to the user's profile picture."},"phoneNumber":{"oneOf":[{"type":"string","format":"phone-number"},{"type":"string","enum":["**hidden**"]}]},"phoneNumbers":{"type":"array","description":"The phone numbers associated with the user.","items":{"$ref":"#/components/schemas/user_phone_number"}},"locale":{"$ref":"#/components/schemas/locale"},"timezone":{"type":"string","format":"timezone","description":"The default timezone for the user."},"badges":{"type":"array","items":{"type":"string","enum":["messagebird:cx"]}},"userFraudInformation":{"$ref":"#/components/schemas/user_fraud_info"}},"required":["id","status","name","activeSessions","emails","phoneNumbers","createdAt","updatedAt"]},"user_email":{"type":"object","title":"UserEmail","description":"An email address for a user.","additionalProperties":false,"properties":{"id":{"type":"string","description":"ID of the email record.","format":"uuid"},"userId":{"type":"string","description":"ID of the user this record is associated with.","format":"uuid"},"email":{"type":"string","format":"email","description":"The email address."},"verified":{"type":"boolean","description":"Whether the email address is verified."},"passwordSet":{"type":"boolean","description":"Whether there is a password set for this email address."},"tokenSet":{"type":"boolean","description":"Whether there is a token set for this email address."},"createdAt":{"type":"string","format":"date-time","description":"When this record was created."},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated."}},"required":["id","userId","email","verified","passwordSet","tokenSet","createdAt"]},"user_identity":{"type":"object","title":"UserIdentity","additionalProperties":false,"properties":{"id":{"type":"string","description":"The ID of the user on the third-party provider."},"name":{"type":"string","description":"The name of the user on the third-party provider."},"email":{"type":"string","description":"The email of the user on the third-party provider."},"avatarUrl":{"type":"string","description":"The avatar URL of the user on the third-party provider."},"provider":{"type":"string","description":"The name of the provider"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the identity was created."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the identity was last updated."}}},"user_phone_number":{"type":"object","title":"UserPhoneNumber","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string","format":"phone-number"},"verified":{"type":"boolean"},"primary":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","userId","phoneNumber","verified","primary","createdAt","updatedAt"]},"locale":{"type":"string","format":"locale-bcp47"},"user_fraud_info":{"type":"object","title":"UserFraudInformation","additionalProperties":false,"properties":{"score":{"type":"number","description":"Fraud score"},"userId":{"type":"string","description":"Fraud user id"}}},"UserPreview":{"type":"object","title":"UserPreview","description":"Simplified view of the User object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/properties-id"},"name":{"$ref":"#/components/schemas/properties-name"},"bio":{"$ref":"#/components/schemas/bio"},"avatarUrl":{"$ref":"#/components/schemas/avatarUrl"},"locale":{"$ref":"#/components/schemas/locale"},"timezone":{"$ref":"#/components/schemas/timezone"},"attributes":{"type":"object","additionalProperties":true,"nullable":true},"badges":{"$ref":"#/components/schemas/badges"},"activeSessions":{"$ref":"#/components/schemas/activeSessions"},"status":{"$ref":"#/components/schemas/status"},"createdAt":{"$ref":"#/components/schemas/createdAt"},"updatedAt":{"$ref":"#/components/schemas/updatedAt"},"defaultEmail":{"$ref":"#/components/schemas/defaultEmail"}},"required":["id","name","createdAt"]},"properties-id":{"type":"string","description":"ID of the user","format":"uuid"},"properties-name":{"type":"string","description":"The display name for the user"},"bio":{"type":"string","description":"The user's description"},"avatarUrl":{"type":"string","description":"URL to the user's profile picture."},"timezone":{"type":"string","format":"timezone","description":"The default timezone for the user."},"badges":{"type":"array","items":{"type":"string","enum":["messagebird:cx"]}},"activeSessions":{"type":"integer","minimum":0,"description":"The number of logged in session for the user."},"status":{"type":"string","enum":["pending","active","deleted","invited","banned"],"default":"pending","description":"The status of the user"},"createdAt":{"type":"string","format":"date-time","description":"When the user was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the user was last updated."},"defaultEmail":{"type":"string","description":"The default email of the user in the list of emails."},"MembershipStatus":{"type":"string","description":"The status of user's membership on the organization.","enum":["banned","invited","active"]},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"responseBody":{"type":"object","title":"PaginatedList","description":"A list of results that supports pagination.","properties":{"nextPageToken":{"type":"string","description":"The token to fetch the next page of results. If empty, there are no more results to fetch."}}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/users":{"get":{"description":"Get a list of members for an organization.","operationId":"listOrganizationUsers","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/direction"},{"$ref":"#/components/parameters/queryPreview"},{"$ref":"#/components/parameters/querySearchTermString"},{"$ref":"#/components/parameters/queryUserIDs"},{"description":"If set, returns the user that is registered with this email address. Only does exact matching.","in":"query","name":"email","required":false,"schema":{"format":"email","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UserMembershipList"},{"$ref":"#/components/schemas/responseBody"}]}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Get organization members","tags":["organization_user"]}}}}
```

## Create organization member

> Add a user to an organization. This can either be an existing user, or a new user that is invited to the platform.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization users.","name":"organization_user"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateMembership":{"oneOf":[{"$ref":"#/components/schemas/AddUser"},{"$ref":"#/components/schemas/InviteUser"}]},"AddUser":{"type":"object","title":"AddUser","description":"Add an existing user to the organization","additionalProperties":false,"properties":{"userId":{"type":"string","description":"The user ID","format":"uuid"},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of roles to assign to the membership","items":{"$ref":"#/components/schemas/iam_role_ref"}},"roleIds":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of Role IDs to assign to the user","deprecated":true,"items":{"type":"string","format":"uuid"},"maxItems":5},"attributes":{"type":"object","description":"Structured attributes for organization user membership (preferred method)","properties":{"roles":{"type":"array","description":"List of role slugs (consistent with workspace users)","items":{"type":"string","pattern":"^[a-z]+:[a-zA-Z0-9_-]+$","description":"Role slug format (e.g., 'managed:organization_admin')"}}}}},"required":["userId"]},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"InviteUser":{"type":"object","title":"InviteUser","description":"Invite a new user to the organization","additionalProperties":false,"properties":{"name":{"type":"string","description":"The name of the person to invite","minLength":1,"maxLength":256},"email":{"type":"string","format":"email","description":"The email address of the person to invite"},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"items":{"$ref":"#/components/schemas/iam_role_ref"},"maxItems":5,"description":"The list of roles to assign to the membership (legacy, use attributes instead)","deprecated":true},"roleIds":{"type":"array","nullable":true,"items":{"type":"string","format":"uuid"},"description":"The list of Role IDs to assign to the user (legacy, use attributes instead)","deprecated":true},"attributes":{"type":"object","description":"Structured attributes for organization user membership (preferred method)","properties":{"roles":{"type":"array","description":"List of role slugs (consistent with workspace users)","items":{"type":"string","pattern":"^[a-z]+:[a-zA-Z0-9_-]+$","description":"Role slug format (e.g., 'managed:organization_admin')"}}}}},"required":["name","email"]},"UserMembershipOnInvite":{"type":"object","title":"UserMembershipOnInvite","additionalProperties":true},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"domainNotAllowed":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"The e-mail domain not allowed to register with"},"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"alreadyExists":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The resource already exists"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/users":{"post":{"description":"Add a user to an organization. This can either be an existing user, or a new user that is invited to the platform.","operationId":"createOrganizationUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMembership"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserMembershipOnInvite"}}},"description":"Created"},"403":{"$ref":"#/components/responses/domainNotAllowed"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/alreadyExists"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Create organization member","tags":["organization_user"]}}}}
```

## Get organization user

> Get a single organization membership record.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization users.","name":"organization_user"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"UserMembershipEnriched":{"type":"object","title":"UserMembershipEnriched","additionalProperties":false,"properties":{"user":{"oneOf":[{"$ref":"#/components/schemas/user"},{"$ref":"#/components/schemas/UserPreview"}]},"status":{"$ref":"#/components/schemas/MembershipStatus"},"createdAt":{"type":"string","format":"date-time","description":"When the membership was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the membership was last updated."},"roleIds":{"type":"array","nullable":true,"uniqueItems":true,"items":{"type":"string","format":"uuid"},"deprecated":true,"description":"IDs of IAM roles assigned to the user."},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"items":{"$ref":"#/components/schemas/iam_role_ref"},"description":"The list of roles to assign to the membership"},"teamRoles":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of roles inherited from teams","items":{"$ref":"#/components/schemas/TeamRole"}},"attributes":{"type":"object","nullable":true,"description":"Additional attributes for the membership","additionalProperties":true}},"required":["user","status","createdAt","updatedAt"]},"user":{"type":"object","title":"User","description":"A user on the platform.","properties":{"id":{"type":"string","description":"ID of the user","format":"uuid"},"status":{"type":"string","enum":["pending","active","deleted","invited","banned"],"default":"pending","description":"The status of the user"},"name":{"type":"string","description":"The display name for the user"},"bio":{"type":"string","description":"The user's description"},"activeSessions":{"type":"integer","minimum":0,"description":"The number of logged in session for the user."},"createdAt":{"type":"string","format":"date-time","description":"When the user was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the user was last updated."},"emails":{"type":"array","description":"Email addresses associated with user.","items":{"$ref":"#/components/schemas/user_email"}},"defaultEmail":{"type":"string","description":"The default email of the user in the list of emails."},"identities":{"type":"array","description":"Third-party identities associated with user.","items":{"$ref":"#/components/schemas/user_identity"}},"avatarUrl":{"type":"string","description":"URL to the user's profile picture."},"phoneNumber":{"oneOf":[{"type":"string","format":"phone-number"},{"type":"string","enum":["**hidden**"]}]},"phoneNumbers":{"type":"array","description":"The phone numbers associated with the user.","items":{"$ref":"#/components/schemas/user_phone_number"}},"locale":{"$ref":"#/components/schemas/locale"},"timezone":{"type":"string","format":"timezone","description":"The default timezone for the user."},"badges":{"type":"array","items":{"type":"string","enum":["messagebird:cx"]}},"userFraudInformation":{"$ref":"#/components/schemas/user_fraud_info"}},"required":["id","status","name","activeSessions","emails","phoneNumbers","createdAt","updatedAt"]},"user_email":{"type":"object","title":"UserEmail","description":"An email address for a user.","additionalProperties":false,"properties":{"id":{"type":"string","description":"ID of the email record.","format":"uuid"},"userId":{"type":"string","description":"ID of the user this record is associated with.","format":"uuid"},"email":{"type":"string","format":"email","description":"The email address."},"verified":{"type":"boolean","description":"Whether the email address is verified."},"passwordSet":{"type":"boolean","description":"Whether there is a password set for this email address."},"tokenSet":{"type":"boolean","description":"Whether there is a token set for this email address."},"createdAt":{"type":"string","format":"date-time","description":"When this record was created."},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated."}},"required":["id","userId","email","verified","passwordSet","tokenSet","createdAt"]},"user_identity":{"type":"object","title":"UserIdentity","additionalProperties":false,"properties":{"id":{"type":"string","description":"The ID of the user on the third-party provider."},"name":{"type":"string","description":"The name of the user on the third-party provider."},"email":{"type":"string","description":"The email of the user on the third-party provider."},"avatarUrl":{"type":"string","description":"The avatar URL of the user on the third-party provider."},"provider":{"type":"string","description":"The name of the provider"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the identity was created."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the identity was last updated."}}},"user_phone_number":{"type":"object","title":"UserPhoneNumber","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string","format":"phone-number"},"verified":{"type":"boolean"},"primary":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","userId","phoneNumber","verified","primary","createdAt","updatedAt"]},"locale":{"type":"string","format":"locale-bcp47"},"user_fraud_info":{"type":"object","title":"UserFraudInformation","additionalProperties":false,"properties":{"score":{"type":"number","description":"Fraud score"},"userId":{"type":"string","description":"Fraud user id"}}},"UserPreview":{"type":"object","title":"UserPreview","description":"Simplified view of the User object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/properties-id"},"name":{"$ref":"#/components/schemas/properties-name"},"bio":{"$ref":"#/components/schemas/bio"},"avatarUrl":{"$ref":"#/components/schemas/avatarUrl"},"locale":{"$ref":"#/components/schemas/locale"},"timezone":{"$ref":"#/components/schemas/timezone"},"attributes":{"type":"object","additionalProperties":true,"nullable":true},"badges":{"$ref":"#/components/schemas/badges"},"activeSessions":{"$ref":"#/components/schemas/activeSessions"},"status":{"$ref":"#/components/schemas/status"},"createdAt":{"$ref":"#/components/schemas/createdAt"},"updatedAt":{"$ref":"#/components/schemas/updatedAt"},"defaultEmail":{"$ref":"#/components/schemas/defaultEmail"}},"required":["id","name","createdAt"]},"properties-id":{"type":"string","description":"ID of the user","format":"uuid"},"properties-name":{"type":"string","description":"The display name for the user"},"bio":{"type":"string","description":"The user's description"},"avatarUrl":{"type":"string","description":"URL to the user's profile picture."},"timezone":{"type":"string","format":"timezone","description":"The default timezone for the user."},"badges":{"type":"array","items":{"type":"string","enum":["messagebird:cx"]}},"activeSessions":{"type":"integer","minimum":0,"description":"The number of logged in session for the user."},"status":{"type":"string","enum":["pending","active","deleted","invited","banned"],"default":"pending","description":"The status of the user"},"createdAt":{"type":"string","format":"date-time","description":"When the user was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the user was last updated."},"defaultEmail":{"type":"string","description":"The default email of the user in the list of emails."},"MembershipStatus":{"type":"string","description":"The status of user's membership on the organization.","enum":["banned","invited","active"]},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"TeamRole":{"type":"object","title":"TeamRole","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"description":"The list of roles assigned to the team","items":{"$ref":"#/components/schemas/iam_role_ref"}}},"required":["id","name"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}}},"paths":{"/organizations/{organizationId}/users/{userId}":{"get":{"description":"Get a single organization membership record.","operationId":"getOrganizationUser","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserMembershipEnriched"}}},"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Get organization user","tags":["organization_user"]}}}}
```

## Delete organization user

> Remove a user from the organization

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization users.","name":"organization_user"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"}},"schemas":{"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}}}},"paths":{"/organizations/{organizationId}/users/{userId}":{"delete":{"description":"Remove a user from the organization","operationId":"deleteOrganizationUser","responses":{"204":{"description":"OK"},"404":{"$ref":"#/components/responses/notFound"}},"summary":"Delete organization user","tags":["organization_user"]}}}}
```

## Update organization user

> Update the properties of the organization membership for the user.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization users.","name":"organization_user"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"UpdateMembership":{"type":"object","title":"UpdateMembership","additionalProperties":false,"properties":{"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"items":{"$ref":"#/components/schemas/iam_role_ref"},"description":"The list of roles to assign to the membership (legacy, use attributes instead)","deprecated":true},"roleIds":{"type":"array","nullable":true,"uniqueItems":true,"items":{"type":"string","format":"uuid"},"maxItems":5,"description":"Roles to assign to the user (legacy, use attributes instead)","deprecated":true},"attributes":{"type":"object","description":"Structured attributes for organization user membership (preferred method)","properties":{"roles":{"type":"array","description":"List of role slugs (consistent with workspace users)","items":{"type":"string","pattern":"^[a-z]+:[a-zA-Z0-9_-]+$","description":"Role slug format (e.g., 'managed:organization_admin')"}}}},"roleTreatment":{"type":"string","nullable":true,"description":"Used to allow removing the legacy roles for the user"}}},"iam_role_ref":{"type":"object","title":"RoleReference","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["organization","managed"]},"workspaces":{"nullable":true,"type":"array","items":{"type":"string","format":"uuid"}}},"required":["id","type"]},"UserMembership":{"type":"object","title":"UserMembership","additionalProperties":false,"properties":{"user":{"oneOf":[{"$ref":"#/components/schemas/user"},{"$ref":"#/components/schemas/UserPreview"}]},"status":{"$ref":"#/components/schemas/MembershipStatus"},"createdAt":{"type":"string","format":"date-time","description":"When the membership was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the membership was last updated."},"attributes":{"type":"object","additionalProperties":true,"description":"Authorization context for the membership.","nullable":true},"roleIds":{"type":"array","nullable":true,"uniqueItems":true,"items":{"type":"string","format":"uuid"},"deprecated":true,"description":"IDs of IAM roles assigned to the user."},"roleRefs":{"type":"array","nullable":true,"uniqueItems":true,"items":{"$ref":"#/components/schemas/iam_role_ref"},"description":"The list of roles to assign to the membership"}},"required":["user","status","createdAt","updatedAt"]},"user":{"type":"object","title":"User","description":"A user on the platform.","properties":{"id":{"type":"string","description":"ID of the user","format":"uuid"},"status":{"type":"string","enum":["pending","active","deleted","invited","banned"],"default":"pending","description":"The status of the user"},"name":{"type":"string","description":"The display name for the user"},"bio":{"type":"string","description":"The user's description"},"activeSessions":{"type":"integer","minimum":0,"description":"The number of logged in session for the user."},"createdAt":{"type":"string","format":"date-time","description":"When the user was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the user was last updated."},"emails":{"type":"array","description":"Email addresses associated with user.","items":{"$ref":"#/components/schemas/user_email"}},"defaultEmail":{"type":"string","description":"The default email of the user in the list of emails."},"identities":{"type":"array","description":"Third-party identities associated with user.","items":{"$ref":"#/components/schemas/user_identity"}},"avatarUrl":{"type":"string","description":"URL to the user's profile picture."},"phoneNumber":{"oneOf":[{"type":"string","format":"phone-number"},{"type":"string","enum":["**hidden**"]}]},"phoneNumbers":{"type":"array","description":"The phone numbers associated with the user.","items":{"$ref":"#/components/schemas/user_phone_number"}},"locale":{"$ref":"#/components/schemas/locale"},"timezone":{"type":"string","format":"timezone","description":"The default timezone for the user."},"badges":{"type":"array","items":{"type":"string","enum":["messagebird:cx"]}},"userFraudInformation":{"$ref":"#/components/schemas/user_fraud_info"}},"required":["id","status","name","activeSessions","emails","phoneNumbers","createdAt","updatedAt"]},"user_email":{"type":"object","title":"UserEmail","description":"An email address for a user.","additionalProperties":false,"properties":{"id":{"type":"string","description":"ID of the email record.","format":"uuid"},"userId":{"type":"string","description":"ID of the user this record is associated with.","format":"uuid"},"email":{"type":"string","format":"email","description":"The email address."},"verified":{"type":"boolean","description":"Whether the email address is verified."},"passwordSet":{"type":"boolean","description":"Whether there is a password set for this email address."},"tokenSet":{"type":"boolean","description":"Whether there is a token set for this email address."},"createdAt":{"type":"string","format":"date-time","description":"When this record was created."},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated."}},"required":["id","userId","email","verified","passwordSet","tokenSet","createdAt"]},"user_identity":{"type":"object","title":"UserIdentity","additionalProperties":false,"properties":{"id":{"type":"string","description":"The ID of the user on the third-party provider."},"name":{"type":"string","description":"The name of the user on the third-party provider."},"email":{"type":"string","description":"The email of the user on the third-party provider."},"avatarUrl":{"type":"string","description":"The avatar URL of the user on the third-party provider."},"provider":{"type":"string","description":"The name of the provider"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the identity was created."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the identity was last updated."}}},"user_phone_number":{"type":"object","title":"UserPhoneNumber","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string","format":"phone-number"},"verified":{"type":"boolean"},"primary":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","userId","phoneNumber","verified","primary","createdAt","updatedAt"]},"locale":{"type":"string","format":"locale-bcp47"},"user_fraud_info":{"type":"object","title":"UserFraudInformation","additionalProperties":false,"properties":{"score":{"type":"number","description":"Fraud score"},"userId":{"type":"string","description":"Fraud user id"}}},"UserPreview":{"type":"object","title":"UserPreview","description":"Simplified view of the User object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/properties-id"},"name":{"$ref":"#/components/schemas/properties-name"},"bio":{"$ref":"#/components/schemas/bio"},"avatarUrl":{"$ref":"#/components/schemas/avatarUrl"},"locale":{"$ref":"#/components/schemas/locale"},"timezone":{"$ref":"#/components/schemas/timezone"},"attributes":{"type":"object","additionalProperties":true,"nullable":true},"badges":{"$ref":"#/components/schemas/badges"},"activeSessions":{"$ref":"#/components/schemas/activeSessions"},"status":{"$ref":"#/components/schemas/status"},"createdAt":{"$ref":"#/components/schemas/createdAt"},"updatedAt":{"$ref":"#/components/schemas/updatedAt"},"defaultEmail":{"$ref":"#/components/schemas/defaultEmail"}},"required":["id","name","createdAt"]},"properties-id":{"type":"string","description":"ID of the user","format":"uuid"},"properties-name":{"type":"string","description":"The display name for the user"},"bio":{"type":"string","description":"The user's description"},"avatarUrl":{"type":"string","description":"URL to the user's profile picture."},"timezone":{"type":"string","format":"timezone","description":"The default timezone for the user."},"badges":{"type":"array","items":{"type":"string","enum":["messagebird:cx"]}},"activeSessions":{"type":"integer","minimum":0,"description":"The number of logged in session for the user."},"status":{"type":"string","enum":["pending","active","deleted","invited","banned"],"default":"pending","description":"The status of the user"},"createdAt":{"type":"string","format":"date-time","description":"When the user was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the user was last updated."},"defaultEmail":{"type":"string","description":"The default email of the user in the list of emails."},"MembershipStatus":{"type":"string","description":"The status of user's membership on the organization.","enum":["banned","invited","active"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Forbidden operation"},"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/users/{userId}":{"patch":{"description":"Update the properties of the organization membership for the user.","operationId":"updateOrganizationUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMembership"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserMembership"}}},"description":"OK"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Update organization user","tags":["organization_user"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/accounts-api/api-reference/organizations/users.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.