Estimates
List all estimates
Returns a paginated list of all estimates in the administration.
The filter
argument allows you to filter on the list of estimates. Filters are a combination of keys and values,
separated by a comma: period:this_year,state:all
. The available options for filtering are:
Filter | Type | Default | Description |
state | String |
all |
all , draft , open , late , accepted , rejected , billed or archived |
period | String |
this_year |
This can either be the description of a period (this_month , prev_month , next_month , this_quarter , prev_quarter , next_quarter , this_year , prev_year , next_year ) or a custom period (201301..201302 , 20130101..20130131 ) |
contact_id | Integer |
Filters estimates by a single contact | |
workflow_id | Integer |
Filters estimates by a single workflow |
You can filter by multiple states at the same time as well. To do this, separate the state values by a pipe: state:draft|scheduled
.
Parameters
Parameter | Type | Description |
---|---|---|
filter |
String |
See table above for detailed options. |
per_page |
Integer |
Example: returns all estimates of an administration
Request
Response
Example: returns all estimates filtered on period
Request
Response
Example: returns all estimates filtered on state
Request
Response
Example: returns paginated estimates on page 1
Request
Response
Example: returns paginated estimates on page 2
Request
Response
Example: returns an error when too many estimates are requested
Request
Response
List all ids and versions
Returns all estimates in the administration. The list contains the id and version of the estimate.
If the version of the estimate is newer than the version you have stored locally, use the POST
variant to fetch estimates with the given ids.
Parameters
Parameter | Type | Description |
---|---|---|
filter |
String |
Example: retrieves the ids for synchronization
Request
Response
Example: retrieves the ids for synchronization filtered on state
Request
Response
Fetch estimates with given ids
Given a list of estimate ids, returns the estimate information belonging to the estimates. Returns a maximum of 100 estimates, even if more ids are provided.
Parameters
Parameter | Type | Description |
---|---|---|
ids |
Array[integer] |
Required |
Example: retrieves estimates by given ids
Request
Response
Get an estimate by id
Returns all information about an estimate.
Parameters
Parameter | Type | Description |
---|---|---|
includes |
Array |
Example: returns estimate by given id
Request
Response
Example: responds with a 404 code when estimate does not exist
Request
Response
Get an estimate by estimate_id
Returns all information about an estimate with the given estimate id
Parameters
Parameter | Type | Description |
---|---|---|
estimate_id |
String |
Required Should be a valid estimate id. Should be unique for the administration. |
Example: returns estimate by given estimate_id
Request
Response
Example: responds with a 404 code when estimate does not exist
Request
Response
Download estimate PDF by id
Redirects to the download URL of the estimate as PDF. The link is valid for 30 seconds.
Parameters
Parameter | Type | Description |
---|---|---|
media |
String |
In case you want to hide sender address and logo you can set this to ‘stationery’. |
Example: returns estimate by given id as PDF
Request
Response
Example: returns 404 when estimate does not exist
Request
Response
Creates a new estimate
Parameters
Parameter | Type | Description |
---|---|---|
estimate[contact_id] |
Integer |
Should be a valid contact id. |
estimate[contact_person_id] |
Integer |
Should be a valid contact person id. |
estimate[document_style_id] |
Integer |
Default document style is used when value is not provided. Should be a valid document style id. |
estimate[workflow_id] |
Integer |
If value is not provided, the workflow saved in the contact is used. If the contact doesn’t have a default workflow, the administration’s default workflow is used. Should be a valid workflow id. |
estimate[reference] |
String |
|
estimate[estimate_date] |
String |
|
estimate[estimate_sequence_id] |
String |
|
estimate[remove_estimate_sequence_id] |
Boolean |
|
estimate[language] |
String |
Can be |
estimate[currency] |
String |
ISO three-character currency code, e.g. EUR or USD. |
estimate[prices_are_incl_tax] |
Boolean |
|
estimate[show_tax] |
Boolean |
|
estimate[first_due_interval] |
Integer |
|
estimate[pre_text] |
String |
|
estimate[post_text] |
String |
|
estimate[discount] |
Decimal |
Discount percentage, e.g. 10,0%. Should be a number 0 <= n <= 100. |
estimate[original_sales_invoice_id] |
Integer |
|
estimate[details_attributes][id] |
Integer |
|
estimate[details_attributes][description] |
String |
|
estimate[details_attributes][period] |
String |
String with a date range: |
estimate[details_attributes][price] |
Decimal |
Both a decimal and a string ‘10,95’ are accepted. |
estimate[details_attributes][amount] |
String |
|
estimate[details_attributes][tax_rate_id] |
Integer |
Should be a valid tax rate id. |
estimate[details_attributes][ledger_account_id] |
Integer |
Should be a valid ledger account id. |
estimate[details_attributes][project_id] |
Integer |
Should be a valid project id. |
estimate[details_attributes][product_id] |
Integer |
Should be a valid product id. |
estimate[details_attributes][row_order] |
Integer |
|
estimate[details_attributes][is_optional] |
Boolean |
|
estimate[details_attributes][is_selected] |
Boolean |
|
estimate[details_attributes][_destroy] |
Boolean |
|
estimate[custom_fields_attributes][id] |
Integer |
Required |
estimate[custom_fields_attributes][value] |
String |
Required |
Example: creates a new estimate
Request
Response
Updates an estimate
When updating an estimate, provide only the attributes you want to update. The other attributes will not be changed.
Parameters
Parameter | Type | Description |
---|---|---|
estimate[contact_id] |
Integer |
Should be a valid contact id. |
estimate[contact_person_id] |
Integer |
Should be a valid contact person id. |
estimate[update_contact] |
Boolean |
|
estimate[document_style_id] |
Integer |
Default document style is used when value is not provided. Should be a valid document style id. |
estimate[workflow_id] |
Integer |
If value is not provided, the workflow saved in the contact is used. If the contact doesn’t have a default workflow, the administration’s default workflow is used. Should be a valid workflow id. |
estimate[reference] |
String |
|
estimate[estimate_date] |
String |
|
estimate[estimate_sequence_id] |
String |
|
estimate[remove_estimate_sequence_id] |
Boolean |
|
estimate[language] |
String |
Can be |
estimate[currency] |
String |
ISO three-character currency code, e.g. EUR or USD. |
estimate[prices_are_incl_tax] |
Boolean |
|
estimate[show_tax] |
Boolean |
|
estimate[first_due_interval] |
Integer |
|
estimate[pre_text] |
String |
|
estimate[post_text] |
String |
|
estimate[discount] |
Decimal |
Discount percentage, e.g. 10,0%. Should be a number 0 <= n <= 100. |
estimate[original_sales_invoice_id] |
Integer |
|
estimate[details_attributes][id] |
Integer |
|
estimate[details_attributes][description] |
String |
|
estimate[details_attributes][period] |
String |
String with a date range: |
estimate[details_attributes][price] |
Decimal |
Both a decimal and a string ‘10,95’ are accepted. |
estimate[details_attributes][amount] |
String |
|
estimate[details_attributes][tax_rate_id] |
Integer |
Should be a valid tax rate id. |
estimate[details_attributes][ledger_account_id] |
Integer |
Should be a valid ledger account id. |
estimate[details_attributes][project_id] |
Integer |
Should be a valid project id. |
estimate[details_attributes][product_id] |
Integer |
Should be a valid product id. |
estimate[details_attributes][row_order] |
Integer |
|
estimate[details_attributes][is_optional] |
Boolean |
|
estimate[details_attributes][is_selected] |
Boolean |
|
estimate[details_attributes][_destroy] |
Boolean |
|
estimate[custom_fields_attributes][id] |
Integer |
Required |
estimate[custom_fields_attributes][value] |
String |
Required |
Example: updates the discount
Request
Response
Example: updates estimate details
Request
Response
Example: responds with a 404 code when estimate does not exist
Request
Response
Changes the state of an estimate
Not every state change is allowed. e.g. open to billed is accepted, draft to open is not. Note: this only changes the state and does not perform other actions like sending or billing the estimate.
Parameters
Parameter | Type | Description |
---|---|---|
state |
String |
Required Can be accepted, rejected, open, late, billed or archived. |
Example: changes from open to accepted
Request
Response
Example: returns an error if estimate cannot be marked from draft to open
Request
Response
Bills an estimate
An invoice is created based on the accepted estimate.
Example: bills an accepted estimate
Request
Response
Example: bills an open estimate
Request
Response
Example: can not bill an open estimate
Request
Response
Deletes an estimate
Example: deletes estimate by given id
Request
Response
Adds note to entity
Parameters
Parameter | Type | Description |
---|---|---|
note[note] |
String |
Required. Text for the note or to-do. |
note[todo] |
Boolean |
If |
note[assignee_id] |
Integer |
Assign to-do to user. Should be a valid user id. If assignee_id is provided the note will be a to-do. |
Example: creates a note
Request
Response
Destroys note from entity
Example: deletes a note
Request
Response
Download attachment
Download the attachment. The response will be a redirect to a temporarily available URL
where the attachment can be downloaded. Use the Location
header in the response
to download the attachment.
Delete an attachment
Deletes an attachment of an attachable.
Sends an estimate
You can provide a send method, email address and message. If you don’t provide any arguments, the defaults from the contact and workflow will be used.
Parameters
Parameter | Type | Description |
---|---|---|
estimate_sending[delivery_method] |
String |
Can be |
estimate_sending[email_address] |
String |
|
estimate_sending[email_message] |
String |
|
estimate_sending[sign_online] |
Boolean |
|
sender |
Boolean |
|
signature_output |
String |
|
audit_trail |
String |
|
ip_address |
String |