Users | Bird API Docs

Get organization members

get

Get a list of members for an organization.

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

Query parameters

limitinteger · min: 1 · max: 100Optional

Limits the number of results to return

Default: 10

pageTokenstringOptional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false

previewbooleanOptional

searchTermstringOptional

Search term used to filter organizations by name

userIdsstring · uuid[]Optional

List of user IDs.

emailstring · emailOptional

If set, returns the user that is registered with this email address. Only does exact matching.

Responses

200

OK

application/json

Responseall of

and

404

Resource not found

application/json

get

GET /organizations/{organizationId}/users HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*

{
  "results": [
    {
      "user": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "pending",
        "name": "text",
        "bio": "text",
        "activeSessions": 1,
        "createdAt": "2025-07-26T10:52:44.026Z",
        "updatedAt": "2025-07-26T10:52:44.026Z",
        "emails": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "userId": "123e4567-e89b-12d3-a456-426614174000",
            "email": "[email protected]",
            "verified": true,
            "passwordSet": true,
            "tokenSet": true,
            "createdAt": "2025-07-26T10:52:44.026Z",
            "updatedAt": "2025-07-26T10:52:44.026Z"
          }
        ],
        "defaultEmail": "text",
        "identities": [
          {
            "id": "text",
            "name": "text",
            "email": "text",
            "avatarUrl": "text",
            "provider": "text",
            "createdAt": "2025-07-26T10:52:44.026Z",
            "updatedAt": "2025-07-26T10:52:44.026Z"
          }
        ],
        "avatarUrl": "text",
        "phoneNumber": "text",
        "phoneNumbers": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "userId": "123e4567-e89b-12d3-a456-426614174000",
            "phoneNumber": "text",
            "verified": true,
            "primary": true,
            "createdAt": "2025-07-26T10:52:44.026Z",
            "updatedAt": "2025-07-26T10:52:44.026Z"
          }
        ],
        "locale": "text",
        "timezone": "text",
        "badges": [
          "messagebird:cx"
        ],
        "userFraudInformation": {
          "score": 1,
          "userId": "text"
        }
      },
      "status": "banned",
      "createdAt": "2025-07-26T10:52:44.026Z",
      "updatedAt": "2025-07-26T10:52:44.026Z",
      "attributes": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "roleRefs": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "organization",
          "workspaces": [
            "123e4567-e89b-12d3-a456-426614174000"
          ]
        }
      ]
    }
  ],
  "nextPageToken": "text"
}

Create organization member

post

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

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

Body

one ofOptional

or

Responses

201

Created

application/json

403

The e-mail domain not allowed to register with

application/json

404

Resource not found

application/json

409

The resource already exists

application/json

422

Request validation failed

application/json

post

POST /organizations/{organizationId}/users HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 184

{
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "roleRefs": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "organization",
      "workspaces": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ]
}

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get organization user

get

Get a single organization membership record.

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

userIdstringRequired

The user ID

Query parameters

previewbooleanOptional

Responses

200

OK

application/json

404

Resource not found

application/json

get

GET /organizations/{organizationId}/users/{userId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "name": "text",
    "bio": "text",
    "activeSessions": 1,
    "createdAt": "2025-07-26T10:52:44.026Z",
    "updatedAt": "2025-07-26T10:52:44.026Z",
    "emails": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[email protected]",
        "verified": true,
        "passwordSet": true,
        "tokenSet": true,
        "createdAt": "2025-07-26T10:52:44.026Z",
        "updatedAt": "2025-07-26T10:52:44.026Z"
      }
    ],
    "defaultEmail": "text",
    "identities": [
      {
        "id": "text",
        "name": "text",
        "email": "text",
        "avatarUrl": "text",
        "provider": "text",
        "createdAt": "2025-07-26T10:52:44.026Z",
        "updatedAt": "2025-07-26T10:52:44.026Z"
      }
    ],
    "avatarUrl": "text",
    "phoneNumber": "text",
    "phoneNumbers": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "123e4567-e89b-12d3-a456-426614174000",
        "phoneNumber": "text",
        "verified": true,
        "primary": true,
        "createdAt": "2025-07-26T10:52:44.026Z",
        "updatedAt": "2025-07-26T10:52:44.026Z"
      }
    ],
    "locale": "text",
    "timezone": "text",
    "badges": [
      "messagebird:cx"
    ],
    "userFraudInformation": {
      "score": 1,
      "userId": "text"
    }
  },
  "status": "banned",
  "createdAt": "2025-07-26T10:52:44.026Z",
  "updatedAt": "2025-07-26T10:52:44.026Z",
  "roleRefs": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "organization",
      "workspaces": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "teamRoles": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "roleRefs": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "organization",
          "workspaces": [
            "123e4567-e89b-12d3-a456-426614174000"
          ]
        }
      ]
    }
  ]
}

Delete organization user

delete

Remove a user from the organization

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

userIdstringRequired

The user ID

Query parameters

previewbooleanOptional

Responses

204

OK

404

Resource not found

application/json

delete

DELETE /organizations/{organizationId}/users/{userId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*

No content

Update organization user

patch

Update the properties of the organization membership for the user.

Authorizations

Path parameters

organizationIdstringRequired

The organization ID

userIdstringRequired

The user ID

Query parameters

previewbooleanOptional

Body

roleIdsstring · uuid[] · min: 1 · max: 5OptionalDeprecated

Roles to assign to the user.

Responses

200

OK

application/json

403

Forbidden operation

application/json

404

Resource not found

application/json

422

Request validation failed

application/json

patch

PATCH /organizations/{organizationId}/users/{userId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 168

{
  "roleRefs": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "organization",
      "workspaces": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "attributes": {
    "roles": [
      "text"
    ]
  }
}

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "name": "text",
    "bio": "text",
    "activeSessions": 1,
    "createdAt": "2025-07-26T10:52:44.026Z",
    "updatedAt": "2025-07-26T10:52:44.026Z",
    "emails": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[email protected]",
        "verified": true,
        "passwordSet": true,
        "tokenSet": true,
        "createdAt": "2025-07-26T10:52:44.026Z",
        "updatedAt": "2025-07-26T10:52:44.026Z"
      }
    ],
    "defaultEmail": "text",
    "identities": [
      {
        "id": "text",
        "name": "text",
        "email": "text",
        "avatarUrl": "text",
        "provider": "text",
        "createdAt": "2025-07-26T10:52:44.026Z",
        "updatedAt": "2025-07-26T10:52:44.026Z"
      }
    ],
    "avatarUrl": "text",
    "phoneNumber": "text",
    "phoneNumbers": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "userId": "123e4567-e89b-12d3-a456-426614174000",
        "phoneNumber": "text",
        "verified": true,
        "primary": true,
        "createdAt": "2025-07-26T10:52:44.026Z",
        "updatedAt": "2025-07-26T10:52:44.026Z"
      }
    ],
    "locale": "text",
    "timezone": "text",
    "badges": [
      "messagebird:cx"
    ],
    "userFraudInformation": {
      "score": 1,
      "userId": "text"
    }
  },
  "status": "banned",
  "createdAt": "2025-07-26T10:52:44.026Z",
  "updatedAt": "2025-07-26T10:52:44.026Z",
  "attributes": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "roleRefs": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "organization",
      "workspaces": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ]
}