# Memberships

These are the memberships of users who have access to the account. For example, when you invite a user to join your account, and the user accepts the invitation, a membership is created for that user.

# The membership object

  • id integer

    The system-generated ID of the membership.

  • user_id string

    The user id who owns the membership.

  • account_id string

    The account id where the membership belongs to.

  • user object expandable

    The user who owns the membership.

  • account object expandable

    The account where the membership belongs to.

  • roles array of roles expandable

    The roles assigned to this user membership.

  • mailboxes array of mailboxes expandable

    The mailboxes the user has access to. Permissions to each mailbox depends on the roles selected. User has access to all mailboxes in the account (as per the roles selected) when there are no mailboxes attached.

  • permissions array

    The list of permissions associated with the membership. The array contains permissions of all the associated roles.

  • is_online boolean

    Whether the user is considered online based on the availability preferences.

  • last_activity string

    The timestamp when the user was last seen in the account.

  • created_at string

    The timestamp when the membership was created.

  • updated_at string

    The timestamp when the membership was last updated.

# The membership object

{
  "id": 1,
  "user_id": 1,
  "account_id": 1,
  "user": {...},
  "account": {...},
  "roles": [...],
  "mailboxes": [...],
  "permissions": [
    "accounts.create",
    "accounts.update",
    "accounts.delete"
    {...}
  ],
  "is_online": false,
  "last_activity": "2019-04-24T01:27:22+00:00",
  "created_at": "2019-04-24T01:27:22+00:00",
  "updated_at": "2019-04-24T01:27:22+00:00"
}

# Retrieve a membership

TIP

To quickly retrieve your own membership object, send a GET request to /api/v1/accounts/1/membership.

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/memberships/1 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

# Sample successful response

{
  "data": {
    "id": 1,
    "user_id": 1,
    "account_id": 1,
    "user": {...},
    "account": {...},
    "roles": [...],
    "mailboxes": [...],
    "permissions": [
      "accounts.create",
      "accounts.update",
      "accounts.delete"
      {...}
    ],
    "is_online": false,
    "last_activity": "2019-04-24T01:27:22+00:00",
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Update a membership

  • roles array of role ids required

    The roles associated with the user's membership.

  • mailboxes array of mailboxes ids optional

    The mailboxes the user has access to. Permissions to each mailbox depends on the roles selected. User has access to all mailboxes in the account (as per the roles selected) when there are no mailboxes attached.

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/memberships/1 \
  --request PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d roles[]=1

# Sample successful response

{
  "data": {
    "id": 1,
    "user_id": 1,
    "account_id": 1,
    "user": {...},
    "account": {...},
    "roles": [...],
    "mailboxes": [...],
    "permissions": [
      "accounts.create",
      "accounts.update",
      "accounts.delete"
      {...}
    ],
    "is_online": false,
    "last_activity": "2019-04-24T01:27:22+00:00",
    "created_at": "2019-04-24T01:27:22+00:00",
    "updated_at": "2019-04-24T01:27:22+00:00"
  }
}

# Delete a membership

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/memberships/1 \
  --request DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" 

If successful, the above request will return an empty response with 204 HTTP status code.

# List all memberships

# Sample request

curl https://www.yourdomain.com/api/v1/accounts/1/memberships \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -G

# Sample successful response

{
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "account_id": 1,
      "user": {
        "id": 1,
        "name": "Jane Doe",
        "initials": "JD",
        "email": "jane@example.org",
        "email_verified_at": null,
        "created_at": "2019-04-24T01:27:22+00:00",
        "updated_at": "2019-04-24T01:27:22+00:00"
      },
      "account": {
        "id": 1,
        "name": "ACME, LLC",
        "realtime_channel": "account.1",
        "next_conversation_number": 1,
        "default_sites_domain": "example.org",
        "default_locale": "en-US",
        "languages": [
          {
            "id": 1,
            "name": "English",
            "code": "en-US",
          }
        ]
      },
      "roles": [
        {
          "id": 1,
          "name": "Account owner",
          "description": "Has full access to the account.",
        }
      ],
      "mailboxes": [...],
      "permissions": [
        "accounts.create",
        "accounts.update",
        "accounts.delete"
        {...}
      ],
      "last_activity": "2019-04-24T01:27:22+00:00",
      "created_at": "2019-04-24T01:27:22+00:00",
      "updated_at": "2019-04-24T01:27:22+00:00"
    },
    {...}
  ]
}