
The Beta release of our documentation is available at:
http://developer.mavenlink.com/beta/
Expenses in Mavenlink allow users to track non-timed items of work or expense. Once created, they can be included in invoices generated subsequently.
Expense objects have seventeen readable attributes. They are:
id
the unique identifier for this expense objectcreated_at
the date the expense was recorded in Mavenlinkupdated_at
the date the expense was last updateddate
the date the expense was incurrednotes
any notes added to the expensecategory
the category of the expense, which can be any string. Built-in categories are: "Travel", "Mileage", "Lodging", "Food", "Entertainment", "Other"amount_in_cents
the amount of the expense, in centscurrency
the currency of the expensecurrency_symbol
the symbol that represents the currency of the expensecurrency_base_unit
the number of the units in the amount_as_cents
attribute that are required to make up a single unit of the currency
user_can_edit
can the viewing user edit this expense?is_invoiced
has this expense been included on an invoice?is_billable
is this a billable expense?taxable
was this expense marked as taxable when invoiced?workspace_id
the id of the project Workspace
this expense is associated withuser_id
the id of the user who created this expensereceipt_id
the id of an attached Receipt Attachmentstory_id
the id of the story Story (Task)
this expense is associated withThe expenses endpoint provides a list of every expense that the user making the request is allowed to see, across all workspaces that the user belongs to.
The response will contain an array of expense objects, sorted by the date
attribute in descending order, available under the key named expenses
.
As with all API listing actions, you can provide per_page
and page
to paginate your response. You may also limit the response to one or more specific expenses using the only
parameter.
To list all a user's expenses using curl, run:
curl "https://api.mavenlink.com/api/v1/expenses.json"
You can include expenses' associations with the include
param. For example, to include returned expenses' workspaces and stories, you would do the following:
curl "https://api.mavenlink.com/api/v1/expenses.json?include=workspace,story"
In this example, our API will ensure that the returned JSON contains top-level keys called workspaces
and stories
where you can find associated data by inspecting expenses' workspace_id
and story_id
fields. See Object Associations to learn more. The following associations can be requested through the API:
workspace
- the workspace (project) that owns this expense, returned in the workspaces
top-level keyuser
- the user object of the expense creator, returned in the users
top-level keystory
- linked story (task), returned in the stories
top-level keyreceipt
- information about any receipt associated with this expense, returned in the attachments
top-level keyexpense_category
- the expense category that this expense is associated withThe expenses list provides filters to allow you to limit the expenses that will be returned.
workspace_id
limits the returned expenses to only the expenses that belong to the workspace whose ID was givenfrom_archived_workspaces
(default: false
) can be set to true
to request that expenses from archived workspaces be included in the responsedate_expensed_between
- Requires a colon separated pair of dates in YYYY-MM-DD format. If a date is not passed in, it is interpreted as negative or positive infinitycreated_before
- include expenses created before the given timestamp (in ISO 8601 format)created_after
- include expenses created after the given timestamp (in ISO 8601 format)updated_before
- include expenses updated before the given timestamp (in ISO 8601 format)updated_after
- include expenses updated after the given timestamp (in ISO 8601 format)For example, to retrieve expenses filtered by workspace:
curl "https://api.mavenlink.com/api/v1/expenses.json?workspace_id=1"
To request expenses including those from archived workspaces:
curl "https://api.mavenlink.com/api/v1/expenses.json?from_archived_workspaces=true"
Valid orders are:
date
As with all resources, you can request either GET /api/v1/expenses.json?only=5
or GET /api/v1/expenses/5.json
. In both cases, default filters will be applied. Therefore, you won't receive Expenses from archived workspaces (and will receive a 404 status on the "show" route) unless you provide the from_archived_workspaces:true
filter.
The expense
parameter has four required attributes:
workspace_id
the ID of the Workspace in which the expense will be createddate
the date of the expense in ISO8601 formatcategory
the category of the expense as a stringamount_in_cents
the amount of the expense, expressed in centsThere are four optional attributes:
notes
freeform text related to the expensebillable
is a boolean that indicates whether or not this expense is billablereceipt_id
is the optional id of a Receipt Attachment for this expensestory_id
is the optional id of a Story in the Workspace to link to this new Expenseuser_id
- the internal ID of the user the expense is associated with. This parameter is ignored unless the authorizing user has financial access in the workspace and is on the consultants team (or if the authorizing user is an account administrator and has proxy permissions via an account member with those permissions).For example, to create a new expense using curl in the "Food" category, incurred on February 19th, 2013, at 5:13:23 PM PST, for an amount of $30, run:
curl -H "Content-Type: application/json" --data-binary '{"expense": {"workspace_id": 1, "date": "2013-02-19T17:13:23-08:00", "category": "Food", "amount_in_cents": 3000}}' "https://api.mavenlink.com/api/v1/expenses.json"
You can create multiple expenses in a single request if you send a expenses
array. An example would be to send a request with the following parameters encoded as application/json
:
{"expenses": [{"workspace_id": 1, "date": "2013-02-19T17:13:23-08:00", "category": "Food", "amount_in_cents": 5000},{"workspace_id": 1, "date": "2015-02-19T17:13:23-08:00", "category": "Travel", "amount_in_cents": 10000} ]}
Using curl, that request could be sent as:
curl -H "Content-Type: application/json" -d '{"expenses": [{"workspace_id": 1, "date": "2013-02-19T17:13:23-08:00", "category": "Food", "amount_in_cents": 5000},{"workspace_id": 1, "date": "2015-02-19T17:13:23-08:00", "category": "Travel", "amount_in_cents": 10000} ]}' "https://api.mavenlink.com/api/v1/expenses.json"
An expense that has already been created can be updated with an HTTP PUT request. Any required or optional attribute, with the exception of workspace_id
, can be changed in an update.
For example, to update the expense with ID 5 to a cost of $100 using curl, run:
curl -X PUT -H "Content-Type: application/json" --data-binary '{"expense": {"amount_in_cents": 10000}}' "https://api.mavenlink.com/api/v1/expenses/5.json"
The response will contain the JSON representation of the updated expense or an error message indicating which arguments are missing or erroneous.
An expense that has already been created can be deleted with an HTTP DELETE request.
For example, to delete the expense with ID 5 run:
curl -X DELETE "https://api.mavenlink.com/api/v1/expenses/5.json"
The response will have no content and HTTP 204 status code if the expense has been successfully deleted, or a JSON error message indicating why the expense could not be deleted.