Mavenlink

Account Invitations

Account invitation is used to invite users to your account.

An account invitation has the following readable attributes:

  • inviter_id - the internal user ID of the inviting user.
  • invitee_id - the internal user ID of the invited user.
  • default_role_id- the default internal role ID for the invited user.
  • full_name - the full name of the invited user
  • email_address - the email address of the user invited; an email will be sent to this address with a link to accept the invitation
  • pending - the status of the invitation
  • permission - the permission level of the invited user; see account_memberships for more details; Valid values are: 'administrator', 'reports_viewer', 'project_lead', 'project_creator', 'punch_clock' or 'collaborator'
  • 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 available if the current user is either an administrator or a project lead on the account
  • cost_rate_in_cents - the default cost rate used in cents for the user in a workspace on this account; this attribute is only available if the current user is an administrator on the account

Fetching Account Invitations

You can access the pending account invitations on your account through the API as follows:

curl "https://api.mavenlink.com/api/v1/account_invitations.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 invitation' associations with the include param. For example, to include returned invitations' inviters and you would do the following:

curl "https://api.mavenlink.com/api/v1/account_invitations.json?include=inviters"

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

  • inviter - the User who sent the invitation, referenced by inviter_id.
  • invitee - the User who was invited, referenced by invitee_id; This will only be available if the invitee was not an existing user on the system or has accepted the invitation.
  • default_role - the default Role for the user invited to your account.

Filtering Account Invitations

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

  • full_name - (string) only includes invitations with the attribute full_name including the provided string

You can request only pending account invitations in the returned JSON as follows:

curl "https://api.mavenlink.com/api/v1/account_invitations.json?full_name=john"

Ordering Account Invitations

Valid orders are:

  • created_at - by the creation date
  • full_name - by the full name of the invited users
  • permission - by the permission level on the account; following this order: 'administrator', 'reports_viewer', 'project_lead', 'project_creator', 'punch_clock' and finally 'collaborator'

The default order is created_at:desc.

Getting a Single Account Invitation

As with all resources, you can request either GET /api/v1/account_invitations.json?only=5 or GET /api/v1/account_invitations/5.json to request pending account invitation.

Creating an Account Invitation

You can create an account invitation to a user, as follows

curl -d "account_invitation[full_name]=John Doe" "account_invitation[email_address]=john.doe@example.com" "https://api.mavenlink.com/api/v1/account_invitations"

When creating an account you can use the following attributes:

  • full_name - (required, string) the full name of the invited user
  • email_address - (required, string) the email address of the user invited; an email will be sent to this address with a link to accept the invitation
  • bill_rate_in_cents - (optional, integer) 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 can only be set if the current user is either an administrator or a project lead on the account
  • cost_rate_in_cents - (optional, integer) the default cost rate used in cents for the user in a workspace on this account; this attribute can only be set if the current user is an administrator on the account
  • default_role_id - (optional, integer) the internal id of the default role to use for the invited user
  • permission - (optional, defaulted to collaborator) the permission level of the invited user; see account_memberships for more details; Valid values are: _administrator_, _reports_viewer_, _project_lead_, _project_creator_, _punch_clock_ or _collaborator_

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

Following the creation

If the email address belongs to a user that already exists, he or she will need to accept the invitation by following the link in the sent email. Acceptance will cancel the recipient's account and transfer them, along with their projects, to the inviter's account.

Delete an Account Invitation

You can cancel a pending invitation made to a user to your account by deleting its account invitation, as follows

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

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

Resend an Account Invitation

You can resend a pending account invitation via email, as follows

curl -X PUT "https://api.mavenlink.com/api/v1/account_invitations/2/resend.json"

The response will contain the JSON representation of the account invitation.