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"
    },
    {...}
  ]
}