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.

  • permissions array

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

  • 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": {
    "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.",
    }
  ],
  "permissions": [
    "accounts.create",
    "accounts.update",
    "accounts.delete"
    {...}
  ],
  "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": {
      "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.",
      }
    ],
    "permissions": [
      "accounts.create",
      "accounts.update",
      "accounts.delete"
      {...}
    ],
    "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

    The roles associated with the user's membership.

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": {
      "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.",
      }
    ],
    "permissions": [
      "accounts.create",
      "accounts.update",
      "accounts.delete"
      {...}
    ],
    "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.",
        }
      ],
      "permissions": [
        "accounts.create",
        "accounts.update",
        "accounts.delete"
        {...}
      ],
      "created_at": "2019-04-24T01:27:22+00:00",
      "updated_at": "2019-04-24T01:27:22+00:00"
    },
    {...}
  ]
}