Mavenlink

Account Memberships

Account membership represent the relation between your account and its users.

Account membership objects have the following readable attributes:

  • user_id - the internal user ID
  • default_role_id - the internal default role ID of the user for the account
  • bill_rate_in_cents - the default billing rate in cents used for the user in a workspace on this account when the workspace does not use rate card. This attribute is only accessible if the current user is a project lead.
  • cost_rate_in_cents - the default cost rate used in cents for the user in a workspace on this account. This attribute is only accessible if the current user is an administrator on the account.
  • disabled_at - null is the membership is active or the timestamp when it was disabled
  • permission - the user's permission level on the account
  • is_administrator - whether the user is an administrator
  • is_project_lead - whether the user is a project lead
  • is_punch_clock_user - whether the user is a punch clock user
  • can_create_workspace - whether the user can create workspaces
  • can_view_reports - whether the user can view reports
  • created_at - the date the membership was created
  • updated_at - the date the membership was last updated

Fetching Account Memberships

You can access all of the account membership on your account through the API as follows:

curl "https://api.mavenlink.com/api/v1/account_memberships.json"

The resulting JSON will be an array of objects. The entries will be sorted by the created_at field in descending order by default.

Associated Objects

You can include account memberships' associations with the include param. For example, to include the users on the account you would do the following:

curl "https://api.mavenlink.com/api/v1/account_memberships.json?include=user"

In this example, our API will ensure that the returned JSON contains top-level keys called users where you can find associated data by inspecting account memberships' user_id field. See Object Associations to learn more. The following association can be requested through the API:

  • user - an array of users associated with the account memberships, associated to your account.
  • default_role - an array of roles associated with the account memberships, associated to your account.

Filtering Account Memberships

The Mavenlink API allows you to pass in filter conditions to allow the retrieval of only certain account memberships.

  • only_active - (boolean) only includes users with an active membership (disabled_at is null)

  • only_inactive - (boolean) only includes users with an inactive membership (disabled_at is not null)

You can include archived workspaces in the returned JSON as follows:

curl "https://api.mavenlink.com/api/v1/account_memberships.json?only_active=true"

Ordering Account Memberships

Valid orders are:

  • created_at - by the creation date
  • full_name - by the full name of the users associated to the account membership
  • role - by the name of the roles associated to the accounts
  • permission - by the level of privileges as follows: administrator, reports viewers, project lead, project creator and regular user
  • cost_rate - by the cost rate
  • bill_rate - by the bill rate

The default order is created_at:desc.

Getting a Single Account Membership

As with all resources, you can request either GET /api/v1/account_memberships.json?only=5 or GET /api/v1/account_memberships/5.json. In both cases, default filters will be applied. Therefore, you won't receive account membership for inactive users (and will receive a 404 status on the "show" route) unless you provide the is_active:false filter.

Updating an existing Account Membership

You can edit an account membership as follows

curl -X PUT -d "account_membership[bill_rate_in_cents]=4000" "https://api.mavenlink.com/api/v1/account_memberships/2.json"

When updating an account membership you can modify the following attributes:

  • bill_rate_in_cents - (integer) the default billing rate in cents used for the user in a workspace
  • cost_rate_in_cents - (integer) the default cost rate in cents used for the user in a workspace
  • default_role_id - (integer) the internal ID of the default role of the user for the account
  • permission - the user's permission level; Valid values are: 'administrator', 'reports_viewer', 'project_lead', 'project_creator' or 'punch_clock'

The response will contain the JSON representation of the updated account membership or an error message indicating which arguments are missing or erroneous.

Make a user inactive

You can disable a user on an account by updating its account_membership as follows

curl -X PUT -d "https://api.mavenlink.com/api/v1/account_memberships/2/disable.json"

Make a user active

You can re-enable a user on an account by updating its account_membership as follows

curl -X PUT -d "https://api.mavenlink.com/api/v1/account_memberships/2/enable.json"

Remove a user from an account

You can remove a user from an account by deleting its account_membership as follows

curl -X DELETE "https://api.mavenlink.com/api/v1/account_memberships/2.json"

The response will have no content and HTTP 204 status code if the account membership has been successfully deleted, or a JSON error message indicating why the account membership could not be deleted.

The user associated with the deleted account membership will be moved on its own free account.