Mavenlink

Workspaces (Projects)

Workspaces (also know as Projects) are Mavenlink's primary space for communication and collaboration.

Workspace objects have the following readable attributes:

  • access_level - Determines whether or not this project is open and who its open to, can be 'invitation', 'open', or 'admin'
  • archived - Whether the project is archived
  • budget_used - The amount of the project budget already burned, only included if the current user has financial access in the workspace
  • budgeted - Whether the project is budgeted
  • can_create_line_items - Whether you can create line items in this workspace
  • can_invite - Whether you can invite others to the workspace
  • change_orders_enabled - Whether change orders are enabled in the project
  • client_role_name - The name of the customer role for the project
  • consultant_role_name - The name of the provider role for the project
  • created_at - The date the project was created
  • currency_base_unit - The currency base unit of the currency of this project (i.e. USD is 100)
  • currency_symbol - The currency symbol of the currency of this project
  • currency - The currency of the project, only included if the current user has financial access in the workspace
  • default_rate - The default billing rate for this project
  • description - The description of the project
  • due_date - The due date of the project
  • has_budget_access - Whether you have budget access in this project
  • id - The internal expense ID
  • over_budget - Whether the project is over budget, only included if the current user has financial access in the workspace
  • percentage_complete - The completion percentage of the project, calculated from the completion percentage of its stories
  • permissions - Actions that the current user is allowed to perform, see below
  • posts_require_privacy_decision - Posts are either private or shared with all participants
  • price_in_cents - The project budget in cents, only included if the current user has financial access in the workspace
  • price - The budget for this project, only included if the current user has financial access in the workspace
  • require_expense_approvals - Whether expense approvals are required in the project
  • require_time_approvals - Whether time approvals are required in the project
  • start_date - The start date of the project
  • title - The title of the project
  • updated_at - The date the project was last updated

Permissions

Certain attributes can only be modified by certain users or under specific circumstances, the permissions object of the workspace provides information on what can be changed

  • can_upload_files - File upload permission.
  • can_private_message - Private messaging permission.
  • can_join - Joinable permission.
  • is_participant - Whether or not the user is a participant in the workspace.
  • access_level - The user access integer.
  • user_is_client - Whether the user is a client.

Some permissions of the currently logged in user are less common and have their information in a separate endpoint.

https://api.mavenlink.com/api/v1/workspaces/2/permissions
  • can_change_budgetability - Whether or not the user has permission to change the workspace budget settings.
  • can_change_currency - Whether or not the workspace is in a state where the currency can be changed.
  • can_change_time_approvals - Whether or not the user has permission to change the time approval settings and if the workspace is in a state that would allow changing the time approval setting.
  • can_change_expense_approvals - Whether or not the user has permission to change the expense approval settings and if the workspace is in a state that would allow changing the expense approval setting.
  • can_edit_change_orders - Whether or not the workspace is in a state where change_orders could be disabled.
  • can_edit_project_settings - Whether or not the user has permission to edit settings in the workspace.
  • can_edit_team_names - Whether or not the user has permission to edit team names in the workspace.
  • can_manage_invoice_preferences - Whether or not the user has permission to edit invoice preferences in the workspace.
  • can_manage_finance - Whether or not the user has permission and the account has access to workspace finance settings.

Fetching Workspaces

You can access all of the workspaces you are participating in through the API as follows:

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

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

Associated Objects

You can include workspaces' associations with the include param. For example, to include returned workspaces' participants and you would do the following:

curl "https://api.mavenlink.com/api/v1/workspaces.json?include=participants"

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 workspaces' participant_ids field. See Object Associations to learn more. The following associations can be requested through the API:

  • primary_counterpart - The User ID called primary_counterpart_id which is the lead of the opposite team of the current user
  • participants - An array of User IDs called participant_ids that contains the users participating in this workspace, returned in the users top-level key
  • creator - The User who created this workspace, referenced by creator_id. Please note that this User may have subsequently left the workspace. primary_counterpart may actually be what you want.
  • workspace_groups - An array of Workspace Group IDs associated with the workspace visible to the current user.
  • timesheet_submissions - An array of TimesheetSubmissions

Filtering Workspaces

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

Name Type Filters for workspaces…
include_archived boolean All, including archived workspaces
can_create_line_items boolean The current user has permission to log time to
has_participant user_id The specified user is an active participant in
has_maven_participant user_id The specified user is participating as a maven in
user_not_participating user_id The specified user is not participating in
budgeted boolean That are budgeted
matching string With a title that matches a search string

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

curl "https://api.mavenlink.com/api/v1/workspaces.json?include_archived=true"

Searching Workspaces

You can search among the workspaces that you have access to by passing a search param and query string:

curl "https://api.mavenlink.com/api/v1/workspaces.json?search=my%20amazing%20project"

Workspaces are searched across the following fields:

  • title
  • description
  • team lead names

The following filters can be applied in conjunction with search:

  • include_archived

When using workspace search, most filters are not available, ordering is always by relevancy, and only requests do not apply. Pagination and includes continue to work as usual.

Ordering Workspaces

Valid orders are:

  • updated_at

The default order is updated_at:desc.

Getting a Single Workspace

As with all resources, you can request either GET /api/v1/workspaces.json?only=5 or GET /api/v1/workspaces/5.json. In both cases, default filters will be applied. Therefore, you won't receive archived Workspace (and will receive a 404 status on the "show" route) unless you provide the include_archived:true filter.

Creating a Single Workspace

You can create a workspace with the follow parameters:

  • title - (required) The title of the new workspace
  • creator_role - (required) Your role in the new workspace, either maven (consultant role) or buyer (client role)
  • budgeted - (optional) Whether or not the new workspace should have budget features; defaults to true for Mavenlink Pro users and false for Free users
  • description - (optional) Workspace description
  • currency - (optional) The currency code for the new workspace; it defaults to USD
  • price - (optional) The starting budget of the new workspace, in the workspace's base currency, e.g. dollars, if the workspace is budgeted
  • start_date - (optional) The start date for the new workspace; format is YYYY-MM-DD
  • due_date - (optional) The due date for the new workspace; format is YYYY-MM-DD
  • change_orders - (optional) It determines if change orders can be made in the new workspace
  • consultant_role_name - (optional) It determines what the consultant team will be labeled as in the workspace
  • client_role_name - (optional) It determines what the client team will be labeled as in the workspace
  • access_level - (optional) It determines whether or not this project is open and who its open to. the options are 'invitation', 'open', or 'admins' and can only be set by workspace administrators
  • project_tracker_template_id - (optional) The ID of any project template you have created or is being shared with you
  • expenses_in_burn_rate - (optional) Any expenses (and additional items in invoices) created in the project will count against the budget used in the project's burn rate calculation.

You can create workspaces through the API as follows:

curl  -d "workspace[title]=New WS" -d "workspace[creator_role]=maven" "https://api.mavenlink.com/api/v1/workspaces.json"

The response will contain a JSON representation of the newly created workspace or an error message indicating which arguments are missing or erroneous.

Creating Multiple Workspaces

You can create multiple workspaces in a single request if you send a workspaces array. An example would be to send a request with the following parameters encoded as application/json:

{"workspaces": [{"title": "WS 1", "creator_role": "maven"}, {"title": "WS 2", "creator_role": "buyer"}]}

Using curl, that request could be sent as:

curl -H "Content-Type: application/json" -d '{"workspaces": [{"title": "WS 1", "creator_role": "maven"}, {"title": "WS 2", "creator_role": "buyer"}]}' "https://api.mavenlink.com/api/v1/workspaces.json"

Updating an Existing Workspace

You can edit a Workspace as follows

curl -X PUT -d "workspace[title]=new title" "https://api.mavenlink.com/api/v1/workspaces/2.json"

When updating a workspace you can modify the following attributes:

  • archived
  • budgeted
  • currency
  • description
  • due_date - only updatable if change orders are not required
  • start_date
  • title
  • access_level - (optional) It determines who has access to the project. the options are 'invitation', 'open', or 'admins' - only workspace administrators can update this field (non-admins will receive a 404)
  • client_role_name - (optional) It determines what the client team will be labeled as in the workspace
  • consultant_role_name - (optional) It determines what the consultant team will be labeled as in the workspace
  • stories_are_fixed_fee_by_default - (optional) It determines the form of billing.
  • price - it is the budget in cents.
  • change_orders_enabled - (optional) It toggles if the project requires change orders for some fields.
  • currency - (optional) The currency that is used for finanicals.
  • posts_require_privacy_decision - (optional) It determines who can see communications.
  • tasks_default_non_billable - (optional) It toggles if tasks are billable by default
  • expenses_in_burn_rate - (optional) Any expenses (and additional items in invoices) created in the project will count against the budget used in the project's burn rate calculation.

Toggling time or expense approvals

Toggling time or expense approvals require calls to a separate PUT endpoint. requires_expense_approvals - https://api.mavenlink.com/api/v1/workspaces/2/toggle_expense_approvals requires_time_approvals - https://api.mavenlink.com/api/v1/workspaces/2/toggle_time_approvals

Both endpoints take two parameters:

  • backfill_date - (optional) The date to approve past time / expenses until. If no backfill_date is provided the feature is only toggled.
  • enable - (required) True or false to enable the feature.

Example: Turning time approvals on and backfilling all time entries until 10/12/1986 for workspace id=2.

curl -X PUT -d "backfill_date=10/12/1986" -d "enable=true" "https://api.mavenlink.com/api/v1/workspaces/2/toggle_time_approvals"	

Creating a Workspace Invitation

To add participants to a workspace they must first be invited. Users that already exist in Mavenlink will automatically accept the invitation and be added to the workspace, while users that don't already exist will be presented with the option of creating an account. When creating an invitation the following parameters are allowed:

  • full_name - (required) the full name of the person being invited
  • email_address - (required) the email address of the person being invited
  • invitee_role - (required) the role for the invited user, either maven (consultant role) or buyer (client role)
  • subject - (optional) the subject message of the invitation email
  • message - (optional) the text content of the invitation email; if you don't provide this, your default will be used

Given one of your workspaces, you can invite people to it through the API as follows:

curl -d "invitation[full_name]=John Smith" -d "invitation[email_address]=jsmith@example.com" -d "invitation[invitee_role]=maven" "https://api.mavenlink.com/api/v1/workspaces/2/invite.json"

The response will contain a JSON representation of the newly created invitation or an error message indicating which arguments are missing or erroneous.