Get Started
The quickest and easiest way to start using the API is to download one of our API wrappers, plug in your details and start pulling down resources.
Keep reading for more information on authentication, working out your endpoint, request methods and response formats we support.
Our API supports two authentication methods - headers and OAuth.
This gives you access to a complete Depot account, so should be used with caution.
Authentication is in the form of a Token-Secret pair, both of which can be found in the account settings of your Depot account.
In order to authenticate, you need to pass both parameters as custom headers with every request:
Arguments
X-DEPOT-TOKEN
your-token-goes-here
X-DEPOT-SECRET
your-secret-goes-here
If you update your Token or Secret in the account settings, all your consuming applications need to be updated with these new keys.
If the Token and Secret do not authenticate, you will receive a HTTP code 403 Forbidden
OAuth authentication
To authenticate using OAuth you need to first register your OAuth application with us, details of how to do this can be found on the OAuth authentication page .
The authentication flow then works as follows:
Direct users of your application to: http://[subdomain].depothq.com/oauth/authorize
The user will then be asked to login if they are not, and then to authorise your application to work on their behalf
If permission is not granted, they will be returned to your callback URL with an URL parameter of error set
If permission is granted, they will be returned to your callback URL with a temporary access code in the URL parameter code
You must then make a request to http://[subdomain].depothq.com/oauth/token to convert your temporary code into a permanent access token
Depot will then return the access token as part of a JSON formatted response (key: access_token)
You should use this access token for all future calls to the API using the HTTP Authorisation Bearer header
More detailed explanations of all of these steps, including the parameters you should pass at each step is provided on the OAuth authentication page .
Access tokens do not currently expire, but we may change this in a future API version.
If the Bearer token does not authenticate, you will receive a HTTP code 403 Forbidden
If accessing a resource the user has no permission to access, you will receive a HTTP code 401 Unauthorised
End point
Your Depot end point is https://[subdomain].depothq.com/api/v[version]/
You then append the resource to the end of that url, e.g. if you wanted to get a list of contacts in JSON format it would be https://[subdomain].depothq.com/api/v[version]/contacts.json
The current API version is 1
All calls to the API must be made using SSL. Non-SSL traffic will be rejected.
Request methods
Our API supports 4 request methods, GET, POST, PATCH and DELETE
GET
GET is used to request information about resources that already exist, and can either be a list of many, or a list of 1.
e.g. GET contacts.json, GET contacts/1.json
POST
POST is used to create a resource, and is therefore only supported on non-ID URLs.
e.g. POST contacts.json is valid, POST contacts/1.json is NOT valid
Parameters to insert should be standard form data
PATCH
PATCH is used to update an existing resource, and is therefore only supported on ID URLs.
e.g. PATCH contacts.json is NOT valid, PATCH contacts/1.json is valid
Parameters to update should be standard form data
DELETE
DELETE is used to delete an existing resource, and is therefore only supported on ID URLs.
e.g. DELETE contacts.json is NOT valid, DELETE contacts/1.json is valid
Response formats
Depots responses can be formatted as either JSON or XML, depending on your requirements. The format is determined by the URL you
target, i.e. contacts.json will return JSON, contacts.xml will return XML.
Responses always return an error flag (error) which is a boolean true/false. You should further inspect the HTTP status code to
ensure the response worked as intended. Human readable error messages are provided, but should not be relied on for parsing.
More detailed information on responses can be found on each resources’ page
Valid responses
Response rows are found within an rows array, which will contain a number of items.
If you aren't querying a specific item (i.e. a non-ID URL), then you will also receive the total number of rows that match your query.
Xml Json
{
"error":false,
"rows":[
{
"id":99,
"name":"Users time sheets",
"status":"C",
"project":"12",
"job":"13",
"client":{
"type":"C",
"id":"488",
"name":"Depot"
},
"added":"1366187493",
"deadline":"1366187493"
}
]
}
{
{
"error":false,
"rows":[
{
"id":99,
"name":"Users time sheets",
"status":"C",
"project":"12",
"job":"13",
"client":{
"type":"C",
"id":"488",
"name":"Depot"
},
"added":"1366187493",
"deadline":"1366187493"
}
]
}
Invalid responses
Invalid responses will return an HTTP status code greater than 201, along with a human readable error message.
Reasons for invalid responses include validation errors 400 Bad Request , authentication errors 401 Unauthorised, 403 Forbidden , and potential system errors 500 System Error .
If you have written an API kit that you would like to see listed here, drop us an email at api@depothq.com
Official PHP Kit v1.0
https://github.com/DepotHQ/Depot-PHP
OAuth Authentication
To authenticate using OAuth you need to first register your OAuth application with us. To do this, send an email to
oauth@depothq.com telling us what your application is intended to do, and if approved we will send you
back an Application ID and Secret.
The process
The authentication flow then works as follows:
Direct users of your application to: http://[subdomain].depothq.com/oauth/authorize
The user will then be asked to login if they are not, and then to authorise your application to work on their behalf
If permission is not granted, they will be returned to your callback URL with an URL parameter of error set
If permission is granted, they will be returned to your callback URL with a temporary access code in the URL parameter code
You must then make a request to http://[subdomain].depothq.com/oauth/token to convert your temporary code into a permanent access token
Depot will then return the access token as part of a JSON formatted response (key: access_token)
You should use this access token for all future calls to the API using the HTTP Authorisation Bearer header
Access tokens do not currently expire, but we may change this in a future API version.
Authorise URL
To build an authorize url, substitute the following with your application parameters
http://[subdomain].depothq.com/oauth/authorize?response_type=code&client_id=[application-id]&redirect_uri=[callback-url]
Subdomain
The Depot account subdomain you are authenticating against.
Application id
Your Application ID supplied to you by us
Callback URL
The callback URL which you want users to be redirected to after authentication
Gaining an access token
To gain access to the system you need to turn your temporary access code into a permanent access token (step 5)
You should make a POST request to http://[subdomain].depothq.com/oauth/token with the following form data.
client_id
The Application ID supplied to you by us
client_secret
The Application Secret supplied to you by us
code
The temporary access code you were returned
grant_type
Should always be authorization_code
redirect_uri
The callback URI you passed to grant the access token
If successful, you will receive a JSON response of the format
Json
{
"access_token":"token-you-should-save-and-use",
"expires_in":12345678,
"scope":"string"
}
Although expires_in and scope are currently meaningless, we include them to honour the OAuth2 spec, and may choose to use them in a future API version.
If something went wrong, or you made an invalid call you will receive a response in the format:
Json
{
"error":"error code or name",
"description":"a description of this error"
}
Making requests
Once you have an access token, you can make a request to the Depot API.
We ONLY support requests using Bearer in an HTTP Authorisation header, i.e. all your requests should have a header in the form:
Authorization: Bearer [access-token]
Where access token is the token returned to you in Step 6.
If the Bearer token does not authenticate, you will receive a HTTP code 403 Forbidden
If accessing a resource the user has no permission to access, you will receive a HTTP code 401 Unauthorised
Note
This is a permissions determined resource, therefore the results returned to an authenticated are determined by the permissions granted to their login account.
List or search activity
Retrieve a list or filtered list of all activity associated with your Depot account.
This can be performed by a GET operation on [endpoint]/activity.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
type
A comma separated list of the type of activity you want to return. Refer to the types list for a full list of activity types.
for
The item the activity is associated with. Refer to the items list for a full list of activity items.
by
The email address of the user whose activity you want to view
Response format
Below is an example of the response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": 12,
"title": "Sent Invoice 10",
"type": "B",
"content": "<p>Hello<br />\r\n<br />\r\nPlease find an invoice attached for charges incurred on your account.<br />\r\n<br />\r\nMany thanks, Depot/p>",
"for": {
"type": "C",
"id": "140",
"name": ""
},
"by": {
"email": "hello@depothq.com",
"name": "Depot",
"image": "http://path/to/image.jpeg"
},
"added": "1392076878",
"extra": {
"recipients": [
{
"id": "11",
"name": "Joe Bloggs"
}
],
"file": "http://path/to/file.pdf"
},
"replyto": null,
"replies": []
},
{
"id": 11,
"title": "Sent Invoice 9",
"type": "B",
"content": "<p>Hello<br />\r\n<br />\r\nPlease find an invoice attached for charges incurred on your account.<br />\r\n<br />\r\nMany thanks, Depot</p>",
"for": {
"type": "C",
"id": "91",
"name": ""
},
"by": {
"email": "hello@depothq.com",
"name": "Depot",
"image": "http://path/to/image.jpeg"
},
"added": "1392076873",
"extra": {
"recipients": [
{
"id": "10",
"name": "Walt Disney"
}
],
"file": "http://path/to/file.pdf"
},
"replyto": null,
"replies": []
}
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<added>1392076878</added>
<by>
<email>hello@depothq.com</email>
<image>http://path/to/image.jpeg</image>
<name>Depot</name>
</by>
<content><p>Hello<br />
<br />
Please find an invoice attached for charges incurred on your account.<br />
<br />
Many thanks, Depot/p></content>
<extra>
<file>http://path/to/file.pdf</file>
<recipients>
<item>
<id>11</id>
<name>Joe Bloggs</name>
</item>
</recipients>
</extra>
<for>
<id>140</id>
<name />
<type>C</type>
</for>
<id>12</id>
<replies />
<replyto null="true" />
<title>Sent Invoice 10</title>
<type>B</type>
</item>
<item>
<added>1392076873</added>
<by>
<email>hello@depothq.com</email>
<image>http://path/to/image.jpeg</image>
<name>Depot</name>
</by>
<content><p>Hello<br />
<br />
Please find an invoice attached for charges incurred on your account.<br />
<br />
Many thanks, Depot</p></content>
<extra>
<file>http://path/to/file.pdf</file>
<recipients>
<item>
<id>10</id>
<name>Walt Disney</name>
</item>
</recipients>
</extra>
<for>
<id>91</id>
<name />
<type>C</type>
</for>
<id>11</id>
<replies />
<replyto null="true" />
<title>Sent Invoice 9</title>
<type>B</type>
</item>
</rows>
<total>10</total>
</response>
Get a specific item of activity
Retrieve an individual activity item associated with your Depot account.
This can be performed by a GET operation on [endpoint]/activity/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this contact
Add a new activity item
Add a new activity item to your Depot account.
This can be performed by a POST operation on [endpoint]/activity.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
title
The subject of the activity
type
The type of the activity (Refer to the types list for a full list of activity types)
addedby
The email address of the user adding the activity
for
The item the activity is associated with (Refer to the items list for a full list of activity items)
Optional parameters
date
default: now
The date associated with the activity
content
Text content / message body for the activity item (HTML will be stripped)
replyto
The ID of the original activity item this new activity is replying to
subtype
If the activity type is a comment (C), then you can associate a subtype with it. Possible values are 'email', 'callin', or 'callout'.
Success response
If the activity is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-activity
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-activity</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating an activity
To update an existing activity on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/activity/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this activity
Parameters
The parameters that can be updated are the same as those when adding a new activity, however you only need to pass the parameters you want to update.
Success response
If the activity is update with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-activity
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-activity</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a activity that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete an activity
To delete an existing activity on your Depot account, you should perform a DELETE operation on [endpoint]/activity/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this activity
Parameters
No parameters should be passed.
Success response
If the activity is deleted with no errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-activity
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-activity</id>
</response>
Not found response
If you delete a activity that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Upload an activity file/image
You can associate an image with an existing activity by sending POST data to [endpoint]/activity/[id]/upload.[xml|json]
The uploader supports both standard and chunked upload methods.
Standard upload
The data should be multipart/form-data and the file should be in a field named _tbxFile1 .
Success response
On successful upload you will receive a response in the format.
XML JSON
{
"error": false,
"finish": true,
"upload_name": "upload_file_uri"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>true</finish>
<upload_name>upload_file_uri</upload_name>
</response>
Chunked upload
The request body should contain the file data chunk you want to upload, along with the following required parameters.
X-File-Id
A unique id for the file you are uploading (e.g. 1)
X-File-Name
The filename
X-File-Size
The final size of the completed file
X-File-Resume
Boolean, is the upload being resumed or not
Progress response
On upload progress you will receive a response in the format.
XML JSON
{
"error": false,
"id": "id_you_supply",
"finish": false
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>false</finish>
<id>id_you_supply</id>
</response>
Success response
On successful upload you will receive a response in the format.
XML JSON
{
"error": false,
"finish": true,
"upload_name": "upload_file_uri"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>true</finish>
<upload_name>upload_file_uri</upload_name>
</response>
Activity items
Activities can be associated with different resource types on Depot. They are identified by a single character followed by the ID of the item (e.g. P1 for project with ID 1).
A - Job action
B - Invoice (Bill)
C - Company
I - Person (individual)
J - Job
K - Credit note (Kredit)
M - Payment (Money)
N - Activity Type
P - Project
Q - Proposal (Quote)
R - Periodical (Repeat)
T - Job item (Task)
U - User
Activity types
Activities are assigned a type to help identify what type of action they are to be associated with. Each type is an uppercase single character as follows.
A - Announcement
B - Invoice (Bill)
C - Comment
K - Credit note (Kredit)
Q - Proposal (Quote)
List or search companies
Retrieve a list or filtered list of all companies associated with your Depot account.
This can be performed by a GET operation on [endpoint]/companies.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
search
A text field on which to match to the fullname field
tag
Filter contacts with a specific tag
lastupdated
Return results updated more recently than this epoch timestamp
hidenotes
Default: true
Hide the notes details (if present) from the response (true) or show them (false)
hidetags
Default: true
Hide the tags from the response (true) or show them (false)
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id":501,
"name":"Company name",
"website":"",
"telephone":"",
"added":1326186529,
"image":null,
"lastupdated":"1369312358",
"accountsdata":{
},
"customfields":[
{"title":"value"}
],
"tags":[""],
"address":{
"id":"4f0c0021c7405",
"line1":"Address line 1",
"line2":"Address line 2",
"line3":"",
"city":"City",
"district":"County",
"country":"Country",
"postcode":""
}
}
,
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<accountsdata />
<added>1326186529</added>
<address>
<city>City</city>
<country>Country</country>
<district>County</district>
<id>4f0c0021c7405</id>
<line1>Address line 1</line1>
<line2>Address line 2</line2>
<line3 />
<postcode />
</address>
<customfields>
<item>
<title>value</title>
</item>
</customfields>
<id>501</id>
<image null="true" />
<lastupdated>1369312358</lastupdated>
<name>Company name</name>
<tags>
<item />
</tags>
<telephone />
<website />
</item>
</rows>
<total>10</total>
</response>
Get a specific company
Retrieve an individual company associated with your Depot account.
This can be performed by a GET operation on [endpoint]/companies/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this contact
Parameters
hidenotes
Default: true
Hide the notes details (if present) from the response (true) or show them (false)
hidetags
Default: true
Hide the tags from the response (true) or show them (false)
Add a new company
Add a new company to your Depot account.
This can be performed by a POST operation on [endpoint]/companies.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
name
The name of the company
Optional parameters
website
The website associated with this company
notes
Notes associated with this company
telephone
The phone number of this company
tags
A comma separated list of tags to associate with this company
line1
Line 1 of their address
line2
Line 2 of their address
line3
Line 3 of their address
city
City of their address
district
District of their address
country
Country of their address
postcode
Postcode/Zipcode of their address
customfields
A JSON encoded array of key/value pairs corresponding to the custom contact information you want to store
creditlimit
An integer for the amount of outstanding credit they are allowed at any point in time.
Success response
If the company is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-company
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-company</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a company
To update an existing company on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/companies/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this company
Parameters
The parameters that can be updated are the same as those when adding a new company, however you only need to pass the parameters you want to update.
Success response
If the company is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-company
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-company</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a company that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a company
To delete an existing company on your Depot account, you should perform a DELETE operation on [endpoint]/companies/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this company
Parameters
No parameters should be passed.
Success response
If the company is deleted with no errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-company
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-company</id>
</response>
Not found response
If you delete a company that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Upload a company image
You can associate an image with an existing company by sending POST data to [endpoint]/companies/[id]/upload.[xml|json]
The uploader supports both standard and chunked upload methods.
Standard upload
The data should be multipart/form-data and the file should be in a field named _tbxFile1 .
Success response
On successful upload you will receive a response in the format.
XML JSON
{
"error": false,
"finish": true,
"upload_name": "upload_file_uri"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>true</finish>
<upload_name>upload_file_uri</upload_name>
</response>
Chunked upload
The request body should contain the file data chunk you want to upload, along with the following required parameters.
X-File-Id
A unique id for the file you are uploading (e.g. 1)
X-File-Name
The filename
X-File-Size
The final size of the completed file
X-File-Resume
Boolean, is the upload being resumed or not
Progress response
On upload progress you will receive a response in the format.
XML JSON
{
"error": false,
"id": "id_you_supply",
"finish": false
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>false</finish>
<id>id_you_supply</id>
</response>
Success response
On successful upload you will receive a response in the format.
XML JSON
{
"error": false,
"finish": true,
"upload_name": "upload_file_uri"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>true</finish>
<upload_name>upload_file_uri</upload_name>
</response>
Retrieve a list or filtered list of all contacts associated with your Depot account.
This can be performed by a GET operation on [endpoint]/contacts.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: fullname
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
search
A text field on which to match to the fullname field
tag
Filter contacts with a specific tag
company
Only return contacts in this company (note, this is an ID field)
isincompany
Only return contacts that are part of a company (true), or only result contacts that aren’t part of a company (false)
email
Filter contacts whose email matches the value you pass
lastupdated
Return results updated more recently than this epoch timestamp
hideaddress
Default: false
Hide the address details from the response (true) or show them (false)
hidecompany
Default: false
Hide the company details (if present) from the response (true) or show them (false)
hidenotes
Default: true
Hide the notes details (if present) from the response (true) or show them (false)
hidetags
Default: true
Hide the tags from the response (true) or show them (false)
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": 536,
"title": "",
"firstname": "Sherlock",
"lastname": "Holmes",
"othernames": "",
"fullname": "Sherlock Holmes",
"email": "hello@sherlockinvestigates.com",
"telephone": "",
"added": 1345545662,
"image": "",
"lastupdated": "1369904831",
"accountsdata": {
},
"customfields":[
{"title":"value"}
],
"tags": ["detective", "violin"],
"company": {
"id": 598,
"name": "Sherlock Investigates Inc",
"position": ""
},
"address": {
"id": "4ff6925fc0231",
"line1": "221B Baker Street",
"line2": "",
"line3": "",
"city": "London",
"district": "Greater London",
"country": "United Kingdom",
"postcode": "NW1 6XE"
}
},
...
{
"id": 591,
"title": "",
"firstname": "John",
"lastname": "Moriarty",
"othernames": "",
"fullname": "John Moriarty",
"email": "john@moriarty.com",
"telephone": "",
"added": 1345645662,
"image": "",
"lastupdated": "1362904831",
"accountsdata": {
},
"customfields":[
{"title":"value"}
],
"tags": ["evil"],
"address": {
"id": "4ff6925fc0231",
"line1": "The Shadows",
"line2": "",
"line3": "",
"city": "London",
"district": "Greater London",
"country": "United Kingdom",
"postcode": ""
}
}
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<accountsdata />
<added>1345545662</added>
<address>
<city>London</city>
<country>United Kingdom</country>
<district>Greater London</district>
<id>4ff6925fc0231</id>
<line1>221B Baker Street</line1>
<line2 />
<line3 />
<postcode>NW1 6XE</postcode>
</address>
<company>
<id>598</id>
<name>Sherlock Investigates Inc</name>
<position />
</company>
<customfields>
<item>
<title>value</title>
</item>
</customfields>
<email>hello@sherlockinvestigates.com</email>
<firstname>Sherlock</firstname>
<fullname>Sherlock Holmes</fullname>
<id>536</id>
<image />
<lastname>Holmes</lastname>
<lastupdated>1369904831</lastupdated>
<othernames />
<tags>
<item>detective</item>
<item>violin</item>
</tags>
<telephone />
<title />
</item>
<item>
<accountsdata />
<added>1345645662</added>
<address>
<city>London</city>
<country>United Kingdom</country>
<district>Greater London</district>
<id>4ff6925fc0231</id>
<line1>The Shadows</line1>
<line2 />
<line3 />
<postcode />
</address>
<customfields>
<item>
<title>value</title>
</item>
</customfields>
<email>john@moriarty.com</email>
<firstname>John</firstname>
<fullname>John Moriarty</fullname>
<id>591</id>
<image />
<lastname>Moriarty</lastname>
<lastupdated>1362904831</lastupdated>
<othernames />
<tags>
<item>evil</item>
</tags>
<telephone />
<title />
</item>
</rows>
<total>10</total>
</response>
Retrieve an individual contact associated with your Depot account.
This can be performed by a GET operation on [endpoint]/contacts/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id The auto-assigned ID of this contact
Optional parameters
hideaddress
Default: false
Hide the address details from the response (true) or show them (false)
hidecompany
Default: false
Hide the company details (if present) from the response (true) or show them (false)
hidenotes
Default: true
Hide the notes details (if present) from the response (true) or show them (false)
hidetags
Default: true
Hide the tags from the response (true) or show them (false)
Add a new contact to your Depot account.
This can be performed by a POST operation on [endpoint]/contacts.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
name
The full name of the contact
Optional parameters
email
The email address associated with this contact
notes
Notes associated with this contact
telephone
The phone number of this contact
tags
A comma separated list of tags to associate with this contact
companyid
The ID of the company to add them to
companyname
The name of a company to add them to, or create if no company with this name exists
line1
Line 1 of their address
line2
Line 2 of their address
line3
Line 3 of their address
city
City of their address
district
District of their address
country
Country of their address
postcode
Postcode/Zipcode of their address
customfields
A JSON encoded array of key/value pairs corresponding to the custom contact information you want to store
creditlimit
An integer for the amount of outstanding credit they are allowed at any point in time.
Success response
If the contact is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-contact
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-contact</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
To update an existing contact on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/contacts/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this contact
Parameters
The parameters that can be updated are the same as those when adding a new contact, however you only need to pass the parameters you want to update.
Success response
If the contact is update with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-contact
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-contact</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a contact that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
To delete an existing contact on your Depot account, you should perform a DELETE operation on [endpoint]/contacts/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this contact
Parameters
No parameters should be passed.
Success response
If the contact is deleted with no errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-contact
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-contact</id>
</response>
Not found response
If you delete a contact that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
You can associate an image with an existing contact by sending POST data to [endpoint]/contacts/[id]/upload.[xml|json]
The uploader supports both standard and chunked upload methods.
Standard upload
The data should be multipart/form-data and the file should be in a field named _tbxFile1 .
Success response
On successful upload you will receive a response in the format.
XML JSON
{
"error": false,
"finish": true,
"upload_name": "upload_file_uri"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>true</finish>
<upload_name>upload_file_uri</upload_name>
</response>
Chunked upload
The request body should contain the file data chunk you want to upload, along with the following required parameters.
X-File-Id
A unique id for the file you are uploading (e.g. 1)
X-File-Name
The filename
X-File-Size
The final size of the completed file
X-File-Resume
Boolean, is the upload being resumed or not
Progress response
On upload progress you will receive a response in the format.
XML JSON
{
"error": false,
"id": "id_you_supply",
"finish": false
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>false</finish>
<id>id_you_supply</id>
</response>
Success response
On successful upload you will receive a response in the format.
XML JSON
{
"error": false,
"finish": true,
"upload_name": "upload_file_uri"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>true</finish>
<upload_name>upload_file_uri</upload_name>
</response>
List or search credit notes
Retrieve a list or filtered list of all credit notes associated with your Depot account.
This can be performed by a GET operation on [endpoint]/creditnotes.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
issuehistory
Return the history of when credit notes were issued
client
Filter items associated with a specific contact or company (format is C for company, I for contact followed by the ID e.g. C1)
clientname
Free text search for items associated with a company or contact with a matching name
for
Default: true
Show items associated with a job or project (format is P for project, J for job followed by the ID e.g. P1)
reference
Items matching a specific reference string
issued
True for items that have been issued, or false for those that have not.
invoiceid
Items marked against a specific invoice id (e.g. 1)
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
{
"error": false,
"rows": [
{
"id": 10,
"ready": true,
"issued": true,
"reference": "101",
"invoiceid": "42",
"invoicereference": "102",
"client": {
"type": "C",
"id": "42",
"name": "Joe Bloggs",
"accountsdata": {
}
},
"sendemail": true,
"email": {
"to": [
"5"
],
"bcc": [],
"message": "Hello\n\nPlease find attached a credit note against invoice 102.\n\nThanks\nDepot"
},
"for": null,
"items": [
{
"title": "Void of invoice",
"items": [
{
"type": "fixed",
"title": "Fixed charge",
"description": "",
"quantity": 1,
"unitprice": 50,
"take": 100,
"taxcode": "002",
"markup": 0,
"category": "-"
}
]
}
],
"total": 50,
"tax": 0,
"grandtotal": 50,
"date": 1391680975,
"pdf": "http://path/to/file.pdf",
"addedby": [
{
"email": "hello@depothq.com",
"name": "Depot"
}
]
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<addedby>
<item>
<email>hello@depothq.com</email>
<name>Depot</name>
</item>
</addedby>
<client>
<accountsdata />
<id>42</id>
<name>Joe Bloggs</name>
<type>C</type>
</client>
<date>1391680975</date>
<email>
<bcc />
<message>Hello
Please find attached a credit note against invoice 102.
Thanks
Depot</message>
<to>
<item>5</item>
</to>
</email>
<for null="true" />
<grandtotal>50</grandtotal>
<id>10</id>
<invoiceid>42</invoiceid>
<invoicereference>102</invoicereference>
<issued>true</issued>
<items>
<item>
<items>
<item>
<category>-</category>
<description />
<markup>0</markup>
<quantity>1</quantity>
<take>100</take>
<taxcode>002</taxcode>
<title>Fixed charge</title>
<type>fixed</type>
<unitprice>50</unitprice>
</item>
</items>
<title>Void of invoice</title>
</item>
</items>
<pdf>http://path/to/file.pdf</pdf>
<ready>true</ready>
<reference>101</reference>
<sendemail>true</sendemail>
<tax>0</tax>
<total>50</total>
</item>
</rows>
<total>10</total>
</response>
Get a specific credit note
Retrieve an individual credit note associated with your Depot account.
This can be performed by a GET operation on [endpoint]/creditnotes/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this creditnote
Optional parameters
issuehistory
Return the history of when this credit note has been issued
Add a new credit note
Add a new credit note to your Depot account.
This can be performed by a POST operation on [endpoint]/creditnotes.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
invoiceid
The the ID of the invoice to mark this credit note against
items
A JSON encoded string of line items to add to this credit note
total
The total value of the credit note (this is used to validate items)
addedby
The email address of the user adding the credit note
Optional parameters
date
Default: now
The date to issue the credit note
sendemail
True for yes, False for no
emailto
A comma-seperated list of contact IDs to send the invoice to
emailbcc
A comma-seperated list of user emails to bcc the invoice to
emailmessage
The message body you want to send by email
ready
True for ready to send (email), False for not ready
Success response
If the credit note is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-credit-note
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-credit-note</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a credit note
To update an existing credit note on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/creditnotes/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this credit note
Parameters
The parameters that can be updated are the same as those when adding a new credit note, however you only need to pass the parameters you want to update.
Success response
If the credit note is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-credit-note
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-credit-note</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a credit note that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a credit note
To delete an existing credit note on your Depot account, you should perform a DELETE operation on [endpoint]/creditnotes/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this credit note
Parameters
No parameters should be passed.
Success response
If the credit note is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-credit-note
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-credit-note</id>
</response>
Not found response
If you delete a credit note that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
List or search invoices
Retrieve a list or filtered list of all invoices associated with your Depot account.
This can be performed by a GET operation on [endpoint]/invoices.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: date
The key of the field you want to use for ordering the response
orderasc
Default: false
Order ascending (true), or descending (false)
issuehistory
Return the history of when invoices were issued
client
Filter items associated with a specific contact or company (format is C for company, I for contact followed by the ID e.g. C1)
clientname
Free text search for items associated with a company or contact with a matching name
for
Show items associated with a job or project (format is P for project, J for job followed by the ID e.g. P1)
reference
Items matching a specific reference string
issued
True for items that have been issued, or false for those that have not.
paid
True for items that have been paid, or false for those that have not.
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
overduefrom
Epoch time of start datetime to return results that are overdue from
overdueto
Epoch time of end datetime to return results that are overdue to
payments
True to return payments associated with invoices
creditnotes
True to return creditnotes associated with invoices
group
True to group invoices by client. This affects the response format you receive.
Response format (no grouping)
Below is an example of the JSON response you should expect when group is false.
XML JSON
{
"error": false,
"rows": [
{
"id": 11,
"issued": true,
"ready": true,
"reference": "171",
"purchaseorder": "",
"terms": {
"timestamp": 1393286473,
"days": 14
},
"client": {
"type": "C",
"id": "41",
"name": "Joe Bloggs Inc",
"accountsdata": {
}
},
"sendemail": true,
"email": {
"to": [
"11"
],
"bcc": [],
"message": "Hello\r\n\r\nPlease find an invoice attached for charges incurred on your account.\r\n\r\nMany thanks, Depot"
},
"for": [],
"items": [
{
"title": "Section 1",
"items": [
{
"type": "hourly",
"title": "Item 1",
"description": "",
"quantity": 1,
"unitprice": 100,
"take": 100,
"taxcode": "001",
"markup": 0
},
{
"type": "hourly",
"title": "Item 2",
"description": "",
"quantity": 1,
"unitprice": 150,
"take": 100,
"taxcode": "001",
"markup": 0
}
]
}
],
"discount": 0,
"total": 250,
"tax": 50,
"grandtotal": 300,
"date": 1392076851,
"pdf": "http://path/to/file.pdf",
"amountpaid": 0,
"paid": false,
"addedby": {
"email": "hello@depothq.com",
"name": "Depot"
},
"balance": 300
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<addedby>
<email>hello@depothq.com</email>
<name>Depot</name>
</addedby>
<amountpaid>0</amountpaid>
<balance>300</balance>
<client>
<accountsdata />
<id>41</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<date>1392076851</date>
<discount>0</discount>
<email>
<bcc />
<message>Hello
Please find an invoice attached for charges incurred on your account.
Many thanks, Depot</message>
<to>
<item>11</item>
</to>
</email>
<for />
<grandtotal>300</grandtotal>
<id>11</id>
<issued>true</issued>
<items>
<item>
<items>
<item>
<description />
<markup>0</markup>
<quantity>1</quantity>
<take>100</take>
<taxcode>001</taxcode>
<title>Item 1</title>
<type>hourly</type>
<unitprice>100</unitprice>
</item>
<item>
<description />
<markup>0</markup>
<quantity>1</quantity>
<take>100</take>
<taxcode>001</taxcode>
<title>Item 2</title>
<type>hourly</type>
<unitprice>150</unitprice>
</item>
</items>
<title>Section 1</title>
</item>
</items>
<paid>false</paid>
<pdf>http://path/to/file.pdf</pdf>
<purchaseorder />
<ready>true</ready>
<reference>171</reference>
<sendemail>true</sendemail>
<tax>50</tax>
<terms>
<days>14</days>
<timestamp>1393286473</timestamp>
</terms>
<total>250</total>
</item>
</rows>
<total>10</total>
</response>
Response format (grouping)
Below is an example of the JSON response you should expect when group is true.
XML JSON
{
"error": false,
"rows": [
{
"client": {
"type": "C",
"id": "1",
"name": "Apple Inc"
},
"invoices": [
"196"
],
"total": 110,
"grandtotal": 132,
"count": 1
},
{
"client": {
"type": "C",
"id": "42",
"name": "Joe Bloggs Inc"
},
"invoices": [
"197",
"200",
"201"
],
"total": 2030,
"grandtotal": 2436,
"count": 3
}
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<client>
<id>1</id>
<name>Apple Inc</name>
<type>C</type>
</client>
<count>1</count>
<grandtotal>132</grandtotal>
<invoices>
<item>196</item>
</invoices>
<total>110</total>
</item>
<item>
<client>
<id>42</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<count>3</count>
<grandtotal>2436</grandtotal>
<invoices>
<item>197</item>
<item>200</item>
<item>201</item>
</invoices>
<total>2030</total>
</item>
</rows>
<total>10</total>
</response>
Get a specific invoice
Retrieve an individual invoice associated with your Depot account.
This can be performed by a GET operation on [endpoint]/invoices/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this invoice
Optional parameters
issuehistory
Return the history of when this invoice has been issued
payments
True to return payments associated with invoices
creditnotes
True to return creditnotes associated with invoices
Add a new invoice
Add a new invoice to your Depot account.
This can be performed by a POST operation on [endpoint]/invoices.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
items
A JSON encoded string of line items to add to this invoice
total
The total value of the invoice (this is used to validate items)
addedby
The email address of the user adding the invoice
Optional parameters
discount
Float: A percentage of the total to be applied as a discount
for
The ID of a job or project the invoice is to be associated with (format is P for project, J for job followed by the ID e.g. P1)
purchaseorder
A purchase order string to associated with the invoice
date
Default: now
The date to issue the invoice
terms
Required if date passed
The number of days within which payment is required
sendemail
True for yes, False for no
emailto
A comma-seperated list of contact IDs to send the invoice to
emailbcc
A comma-seperated list of user emails to bcc the invoice to
emailmessage
The message body you want to send by email
ready
True for ready to send (email), False for not ready
Success response
If the invoice is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-invoice
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-invoice</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating an invoice
To update an existing invoice on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/invoices/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this invoice
Parameters
The parameters that can be updated are the same as those when adding a new invoice, however you only need to pass the parameters you want to update.
Success response
If the invoice is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-invoice
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-invoice</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update an invoice that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete an invoice
To delete an existing invoice on your Depot account, you should perform a DELETE operation on [endpoint]/invoices/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this invoice
Parameters
No parameters should be passed.
Success response
If the invoice is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-invoice
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-invoice</id>
</response>
Not found response
If you delete an invoice that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
List or search job actions
Retrieve a list or filtered list of all jobactions associated with your Depot account.
This can be performed by a GET operation on [endpoint]/jobactions.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
search
Return items whose title match the search string
item
Filter items associated with a specific job item ID
job
Filter items associated with a specific job ID
project
Filter items associated with a specific project ID
for
Show items associated with a company or contact (format is C for company, I for contact followed by the ID e.g. C1)
status
C for completed actions, U for unfinished items
assigned
Email address of user actions are assigned to.
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": 5,
"name": "Title of action",
"status": "C",
"project": "2",
"job": "3",
"client": {
"type": "C",
"id": "42",
"name": "Joe Bloggs Inc"
},
"added": "1362730398",
"deadline": "1362730398",
"assignedto": [
{
"email": "hello@depothq.com",
"name": "Depot"
}
],
"addedby": {
"email": "hello@depothq.com",
"name": "Depot"
}
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<added>1362730398</added>
<addedby>
<email>hello@depothq.com</email>
<name>Depot</name>
</addedby>
<assignedto>
<item>
<email>hello@depothq.com</email>
<name>Depot</name>
</item>
</assignedto>
<client>
<id>42</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<deadline>1362730398</deadline>
<id>5</id>
<job>3</job>
<name>Title of action</name>
<project>2</project>
<status>C</status>
</item>
</rows>
<total>10</total>
</response>
Get a specific jobaction
Retrieve an individual job action associated with your Depot account.
This can be performed by a GET operation on [endpoint]/jobactions/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this jobaction
Add a new jobaction
Add a new job action to your Depot account.
This can be performed by a POST operation on [endpoint]/jobactions.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
title
A string for the title/text of this item
status
C for completed, U for unfinished
item
The ID of the jobitem to associate this action with
addedby
The email address of the user adding the action
Optional parameters
assignedto
The email address of the user to assign to the action
deadline
Default: +7 days
An epoch time value for the deadline of when the action should be completed by
Success response
If the jobaction is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-jobaction
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-jobaction</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a jobaction
To update an existing jobaction on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/jobactions/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this jobaction
Parameters
The parameters that can be updated are the same as those when adding a new jobaction, however you only need to pass the parameters you want to update.
Success response
If the jobaction is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-jobaction
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-jobaction</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a jobaction that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a job action
To delete an existing jobaction on your Depot account, you should perform a DELETE operation on [endpoint]/jobactions/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this jobaction
Parameters
No parameters should be passed.
Success response
If the jobaction is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-jobaction
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-jobaction</id>
</response>
Not found response
If you delete a response that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
List or search job items
Retrieve a list or filtered list of all jobitems associated with your Depot account.
This can be performed by a GET operation on [endpoint]/jobitems.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
search
Return items whose title match the search string
job
Filter items associated with a specific job ID
project
Filter items associated with a specific project ID
for
Show items associated with a company or contact (format is C for company, I for contact followed by the ID e.g. C1)
status
O for open, H for held, P for pending, C for cancelled, F for finished
actionassignedto
Default: all
Email address of user actions are assigned to
hasactions
If true only items with actions will be returned
Response format
Below is an example of the JSON response you should expect.
XML
{
"error": false,
"rows": [
{
"id": 22,
"name": "Quoted Work",
"description": "",
"status": "F",
"project": "20",
"job": "28",
"hours": {
"allocated": 21,
"logged": 0,
"remaining": 21
},
"client": {
"type": "C",
"id": "41",
"name": "Joe Bloggs Inc"
},
"added": "1326982898",
"start": "1327587698",
"deadline": "1327587698",
"team": [],
"type": "hourly",
"actions": [],
"hasactions": false,
"order": "1",
"category": null,
"rate": 50,
"taxcode": null,
"actioncount": 0
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<actioncount>0</actioncount>
<actions />
<added>1326982898</added>
<category null="true" />
<client>
<id>41</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<deadline>1327587698</deadline>
<description />
<hasactions>false</hasactions>
<hours>
<allocated>21</allocated>
<logged>0</logged>
<remaining>21</remaining>
</hours>
<id>22</id>
<job>28</job>
<name>Quoted Work</name>
<order>1</order>
<project>20</project>
<rate>50</rate>
<start>1327587698</start>
<status>F</status>
<taxcode null="true" />
<team />
<type>hourly</type>
</item>
</rows>
<total>10</total>
</response>
Get a specific jobitem
Retrieve an individual job item associated with your Depot account.
This can be performed by a GET operation on [endpoint]/jobitems/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this jobitem
Add a new jobitem
Add a new job item to your Depot account.
This can be performed by a POST operation on [endpoint]/jobitems.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
title
A string for the title/text of this item
status
O for open, H for held, P for pending, C for cancelled, F for finished
job
The ID of the job to associate this item with
type
The type of item it is (hourly, fixed or external)
hours
A float of the hours/quantity allocated to this item
rate
A float of the unit rate/price of this item (markup for external costs)
addedby
The email address of the user adding the action
Optional parameters
description
A string for the description of this item
team
A comma-seperated list of the email addresses of the users to assign to the item
start
Default: now
An epoch time value for the date of when the action should be started by
deadline
default: +7 days
An epoch time value for the deadline of when the action should be completed by
taxcode
The code for the tax bracket for this item
ledger
The code of the ledger category for this item
order
An ascending integer indicating the order this item should appear in relation to other items in the same job
Success response
If the jobitem is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-jobitem
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-jobitem</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a jobitem
To update an existing jobitem on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/jobitems/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this jobitem
Parameters
The parameters that can be updated are the same as those when adding a new jobitem, however you only need to pass the parameters you want to update.
Success response
If the jobitem is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-jobitem
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-jobitem</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a jobitem that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a jobitem
To delete an existing jobitem on your Depot account, you should perform a DELETE operation on [endpoint]/jobitems/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this jobitem
Parameters
No parameters should be passed.
Success response
If the jobitem is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-jobitem
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-jobitem</id>
</response>
Not found response
If you delete a jobitem that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Note
This is a permissions determined resource, therefore the results returned to an authenticated are determined by the permissions granted to their login account.
List or search jobs
Retrieve a list or filtered list of all jobs associated with your Depot account.
This can be performed by a GET operation on [endpoint]/jobs.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
search
Return jobs whose title match the search string
itemsearch
Return jobs contains items whose title match the search string
project
Filter items associated with a specific project ID
for
Show items associated with a company or contact (format is C for company, I for contact followed by the ID e.g. C1)
status
O for open, H for held, P for pending, C for cancelled, F for finished
itemstatus
Return items in jobs whose status matches O for open, H for held, P for pending, C for cancelled, F for finished
brief
Default: false
Set to true to return job brief
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": 412,
"idinproject": 1,
"name": "Job name",
"status": "F",
"project": "4",
"projecttitle": "Project name",
"hours": {
"allocated": 0.5,
"logged": 0,
"remaining": 0.5
},
"client": {
"type": "C",
"id": "41",
"name": "Joe Bloggs Inc"
},
"start": "1391180046",
"deadline": "1391133600",
"items": [
{
"id": "8",
"name": "Line item",
"start": "1391126400",
"deadline": "1391133600",
"hours": {
"allocated": 5,
"logged": 2
},
"brief": "Line item description",
"type": "hourly",
"actions": [],
"team": [
{
"email": "hello@depothq.com",
"name": "Depot"
}
],
"category": "4030",
"timecategory": "",
"rate": "50.00000",
"taxcode": "001"
}
],
"team": [
{
"email": "hello@depothq.com",
"name": "Depot"
}
],
"contacts": [],
"order": "1",
"discount": 0,
"addedby": {
"email": "hello@depothq.com",
"name": "Depot"
}
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<addedby>
<email>hello@depothq.com</email>
<name>Depot</name>
</addedby>
<client>
<id>41</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<contacts />
<deadline>1391133600</deadline>
<discount>0</discount>
<hours>
<allocated>0.5</allocated>
<logged>0</logged>
<remaining>0.5</remaining>
</hours>
<id>412</id>
<idinproject>1</idinproject>
<items>
<item>
<actions />
<brief>Line item description</brief>
<category>4030</category>
<deadline>1391133600</deadline>
<hours>
<allocated>5</allocated>
<logged>2</logged>
</hours>
<id>8</id>
<name>Line item</name>
<rate>50.00000</rate>
<start>1391126400</start>
<taxcode>001</taxcode>
<team>
<item>
<email>hello@depothq.com</email>
<name>Depot</name>
</item>
</team>
<timecategory />
<type>hourly</type>
</item>
</items>
<name>Job name</name>
<order>1</order>
<project>4</project>
<projecttitle>Project name</projecttitle>
<start>1391180046</start>
<status>F</status>
<team>
<item>
<email>hello@depothq.com</email>
<name>Depot</name>
</item>
</team>
</item>
</rows>
<total>10</total>
</response>
Get a specific job
Retrieve an individual job associated with your Depot account.
This can be performed by a GET operation on [endpoint]/jobs/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this jobitem
Add a new job
Add a new job to your Depot account.
This can be performed by a POST operation on [endpoint]/jobs.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
title
A string for the title of this job
status
O for open, H for held, P for pending, C for cancelled, F for finished
project
The ID of the project to associate this job with
addedby
The email address of the user adding the job
Optional parameters
brief
A string for the brief of this item
team
A comma-seperated list of the email addresses of the users to assign to the job
deadline
Default: +7 days
An epoch time value for the deadline of when the action should be completed by
contacts
A comma-seperated list of the contact IDs associated with the job
order
An ascending integer indicating the order this item should appear in relation to other jobs in the same project
discount
Float: A percentage of the job total to be applied as a discount
Success response
If the job is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-job
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-job</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a job
To update an existing job on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/jobs/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this job
Parameters
The parameters that can be updated are the same as those when adding a new job, however you only need to pass the parameters you want to update.
Success response
If the job is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-job
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-job</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a job that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a job
To delete an existing job on your Depot account, you should perform a DELETE operation on [endpoint]/jobs/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this job
Parameters
No parameters should be passed.
Success response
If the job is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-job
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-job</id>
</response>
Not found response
If you delete a job that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
List or search notifications
Retrieve a list or filtered list of all notifications associated with your Depot account.
This can be performed by a GET operation on [endpoint]/notifications.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: date
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
user
The email address of the user for whom you want to see notifications
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
Response format
Below is an example of the JSON response you should expect.
Xml Json
{
"error": false,
"rows": [
{
"id": 1020,
"type": "teamadd",
"date": "1384170422",
"title": "Notification title",
"link": "job/3",
"content": "Notification content",
"readby": [
{
"id": "hello@depothq.com",
"name": "Depot"
}
],
"deletedby": [
{
"id": "hello@depothq.com",
"name": "Depot"
}
],
"users": [
{
"id": "hello@depothq.com",
"name": "Depot"
}
]
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<content>Notification content</content>
<date>1384170422</date>
<deletedby>
<item>
<id>hello@depothq.com</id>
<name>Depot</name>
</item>
</deletedby>
<id>1020</id>
<link>job/3</link>
<readby>
<item>
<id>hello@depothq.com</id>
<name>Depot</name>
</item>
</readby>
<title>Notification title</title>
<type>teamadd</type>
<users>
<item>
<id>hello@depothq.com</id>
<name>Depot</name>
</item>
</users>
</item>
</rows>
<total>10</total>
</response>
Get a specific notification
Retrieve an individual notification associated with your Depot account.
This can be performed by a GET operation on [endpoint]/notifications/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this notification
Updating a notification
To update an existing notification on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/notifications/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this notification
Optional parameters
readby
The email address of the user who has read the notification
deletedby
The email address of the user who has deleted the notification
Success response
If the notification is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-notification
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-notification</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a notification that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a notification
Notifications are automatically deleted after 3 months, so the API does not support deleting notifications.
Note
This is a permissions determined resource, therefore the results returned to an authenticated are determined by the permissions granted to their login account.
List or search payments
Retrieve a list or filtered list of all payment associated with your Depot account.
This can be performed by a GET operation on [endpoint]/payments.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: date
The key of the field you want to use for ordering the response
orderasc
Default: false
Order ascending (true), or descending (false)
invoice
Return payments associated with the invoice id passed
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": 2,
"invoice": "41",
"invoicereference": "141",
"amount": 43.2,
"date": 1416614400,
"method": "BACS",
"note": ""
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<amount>43.2</amount>
<date>1416614400</date>
<id>2</id>
<invoice>41</invoice>
<invoicereference>141</invoicereference>
<method>BACS</method>
<note />
</item>
<item>...</item>
</rows>
<total>10</total>
</response>
Get a specific payment
Retrieve an individual payment associated with your Depot account.
This can be performed by a GET operation on [endpoint]/payments/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this payment
Add a new payment
Add a new payment to your Depot account.
This can be performed by a POST operation on [endpoint]/payments.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
invoice
The ID of the invoice to mark this payment against
amount
A float indicating the amount paid
date
An epoch time integer indicating the date the payment was received
method
The payment method used (BACS, Card, Cheque, Cash)
Optional parameters
note
A string for a note associated with this payment
Success response
If the payment is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-payment
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-payment</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a payment
Updating payments is not supported, and so will return a 400 Bad Request status code.
Delete a payment
To delete an existing payment on your Depot account, you should perform a DELETE operation on [endpoint]/payments/[id].[xml|json]
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this payment
Parameters
No parameters should be passed.
Success response
If the payment is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-payment
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-payment</id>
</response>
Not found response
If you delete a payment that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
List or search periodicals
Retrieve a list or filtered list of all periodicals associated with your Depot account.
This can be performed by a GET operation on [endpoint]/periodic.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: desc
The key of the field you want to use for ordering the response
orderasc
Default: false
Order ascending (true), or descending (false)
client
Filter items associated with a specific contact or company (format is C for company, I for contact followed by the ID e.g. C1)
clientname
Free text search for items associated with a company or contact with a matching name
repeat
Show items with a repeat interval of D for Day, W for Week, M for Month, Y for Year
hasrun
True to return periodicals that have been sent, false for those that have not
Response format
Below is an example of the JSON response you should expect when group is false.
XML JSON
{
"error": false,
"rows": [
{
"id": 5,
"title": "Title of Periodic item",
"terms": {
"days": 14
},
"client": {
"type": "C",
"id": "41",
"name": "Joe Bloggs Inc"
},
"sendemail": true,
"email": {
"to": [
"14"
],
"bcc": [],
"message": "Hello\n\nPlease find attached our invoice for ongoing charges on your account.\n\Thank you,\nDepot"
},
"items": [
{
"title": "Section title",
"items": [
{
"type": "hourly",
"title": "Line item title",
"description": "",
"quantity": 1,
"unitprice": 50,
"take": 100,
"taxcode": "001",
"markup": 0,
"category": "-"
}
]
}
],
"discount": 0,
"total": 50,
"grandtotal": 50,
"repeat": "Y",
"repeatinterval": 1,
"purchaseorder": null,
"first": 1391212800,
"last": null,
"addedby": [
{
"email": "hello@depothq.com",
"name": "Depot"
}
]
}
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<addedby>
<item>
<email>hello@depothq.com</email>
<name>Depot</name>
</item>
</addedby>
<client>
<id>41</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<discount>0</discount>
<email>
<bcc />
<message>Hello
Please find attached our invoice for ongoing charges on your account.
Thank you,
Depot</message>
<to>
<item>14</item>
</to>
</email>
<first>1391212800</first>
<grandtotal>50</grandtotal>
<id>5</id>
<items>
<item>
<items>
<item>
<category>-</category>
<description />
<markup>0</markup>
<quantity>1</quantity>
<take>100</take>
<taxcode>001</taxcode>
<title>Line item title</title>
<type>hourly</type>
<unitprice>50</unitprice>
</item>
</items>
<title>Section title</title>
</item>
</items>
<last null="true" />
<purchaseorder null="true" />
<repeat>Y</repeat>
<repeatinterval>1</repeatinterval>
<sendemail>true</sendemail>
<terms>
<days>14</days>
</terms>
<title>Title of Periodic item</title>
<total>50</total>
</item>
</rows>
<total>10</total>
</response>
Get a specific periodical
Retrieve an individual periodical associated with your Depot account.
This can be performed by a GET operation on [endpoint]/periodic/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this periodical
Add a new periodical
Add a new periodical to your Depot account.
This can be performed by a POST operation on [endpoint]/periodic.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
terms
An integer indicating the number of days within which payment is required
client
A specific contact or company (format is C for company, I for contact followed by the ID e.g. C1)
items
A JSON encoded string of line items to add to this periodical
total
The total value of the periodical (this is used to validate items)
addedby
The email address of the user adding the periodical
Optional parameters
repeat
Default: Y
Repeat interval of D for Day, W for Week, M for Month, Y for Year
repeatinterval
Default: 1
Integer of amount of repeat interval to repeat at (e.g. 2 with a repeat of W would be 2 weeks)
discount
Float: A percentage of the total to be applied as a discount
purchaseorder
A purchase order string to associated with the invoice
title
A title string to associated with the invoice
first
Default: now
The date to first send the periodic
last
Default: none
The date to last send the periodic, or null for never ending
terms
Required if date passed
The number of days within which payment is required
sendemail
True for yes, False for no
emailto
A comma-seperated list of contact IDs to send the invoice to
emailbcc
A comma-seperated list of user emails to bcc the invoice to
emailmessage
The message body you want to send by email
Success response
If the periodical is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-periodical
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-periodical</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a periodical
To update an existing periodical on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/periodic/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this periodical
Parameters
The parameters that can be updated are the same as those when adding a new periodical, however you only need to pass the parameters you want to update.
Success response
If the invoice is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-periodical
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-periodical</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update an periodical that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a periodical
To delete an existing periodical on your Depot account, you should perform a DELETE operation on [endpoint]/periodic/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this periodical
Parameters
No parameters should be passed.
Success response
If the periodical is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-periodical
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-periodical</id>
</response>
Not found response
If you delete a periodical that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
List or search private tasks
Retrieve a list or filtered list of all private tasks associated with your Depot account.
This can be performed by a GET operation on [endpoint]/privatetasks.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: date
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
user
The email address of the user for whom you want to see private tasks
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": 1,
"date": 1373932800,
"text": "Call doctor",
"user": {
"email": "hello@depothq.com",
"name": "Depot"
}
}
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<date>1373932800</date>
<id>1</id>
<text>Call doctor</text>
<user>
<email>hello@depothq.com</email>
<name>Depot</name>
</user>
</item>
</rows>
<total>10</total>
</response>
Get a specific task
Retrieve an individual private task associated with your Depot account.
This can be performed by a GET operation on [endpoint]/privatetasks/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this task
Add a new task
Add a new task to your Depot account.
This can be performed by a POST operation on [endpoint]/privatetasks.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
text
The text of the task
date
An epoch date value for the day the private task should be shown against
user
The email address of the user adding the task
Success response
If the task is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-task
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-task</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a task
To update a existing task on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/privatetasks/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this task
Parameters
The parameters that can be updated are the same as those when adding a new task, however you only need to pass the parameters you want to update.
Success response
If the task is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-task
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-task</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a task that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a task
To delete an existing task on your Depot account, you should perform a DELETE operation on [endpoint]/privatetasks/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this task
Parameters
No parameters should be passed.
Success response
If the task is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-task
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-task</id>
</response>
Not found response
If you delete a task that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Note
This is a permissions determined resource, therefore the results returned to an authenticated are determined by the permissions granted to their login account.
List or search projects
Retrieve a list or filtered list of all projects associated with your Depot account.
This can be performed by a GET operation on [endpoint]/projects.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
search
Return jobs whose title match the search string
for
Show items associated with a company or contact (format is C for company, I for contact followed by the ID e.g. C1)
status
O for open, H for held, P for pending, C for cancelled, F for finished
jobs
Set to true to return jobs in this project
jobstatus
Return jobs whose status matches O for open, H for held, P for pending, C for cancelled, F for finished
items
Set to true to return items in jobs
itemstatus
Return items in jobs whose status matches O for open, H for held, P for pending, C for cancelled, F for finished
hasitems
Set to true to only return jobs that have items, false to return those that don't
hasactions
Set to true to only return items that have actions, false to return those that don't
actionassignedto
Set to the email address of the user you want to return actions for
team
Enter the email address of the user you want to see projects they are on the team of
contacts
Enter the id of a contact you want to see the projects they are associated with
brief
Default: false
Set to true to return job brief
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": 158,
"name": "Project title",
"status": "F",
"client": {
"type": "C",
"id": "41",
"name": "Joe Bloggs Inc"
},
"hours": {
"allocated": 10,
"logged": 4.75,
"remaining": 5.25
},
"added": "1368630883",
"deadline": "1369270800",
"hasactions": 0,
"hasitems": 0,
"discount": "0.00",
"addedby": {
"email": "hello@depothq.com",
"name": "Depot"
},
"team": [
{
"email": "hello@depothq.com",
"name": "Depot"
}
]
}
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<added>1368630883</added>
<addedby>
<email>hello@depothq.com</email>
<name>Depot</name>
</addedby>
<client>
<id>41</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<deadline>1369270800</deadline>
<discount>0.00</discount>
<hasactions>0</hasactions>
<hasitems>0</hasitems>
<hours>
<allocated>10</allocated>
<logged>4.75</logged>
<remaining>5.25</remaining>
</hours>
<id>158</id>
<name>Project title</name>
<status>F</status>
<team>
<item>
<email>hello@depothq.com</email>
<name>Depot</name>
</item>
</team>
</item>
</rows>
<total>10</total>
</response>
Get a specific project
Retrieve an individual project associated with your Depot account.
This can be performed by a GET operation on [endpoint]/projects/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this project
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
jobs
Set to true to return jobs in this project
items
Set to true to return items in jobs
itemstatus
Return items in jobs whose status matches O for open, H for held, P for pending, C for cancelled, F for finished
hasitems
Set to true to only return jobs that have items, false to return those that don't
hasactions
Set to true to only return items that have actions, false to return those that don't
actionassignedto
Set to the email address of the user you want to return actions for
brief
Default: false
Set to true to return job brief
Add a new project
Add a new project to your Depot account.
This can be performed by a POST operation on [endpoint]/projects.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
title
A string for the title of this job
status
O for open, H for held, P for pending, C for cancelled, F for finished
for
The ID of the company or contact to associate the project with (format is C for company, I for contact followed by the ID e.g. C1)
addedby
The email address of the user adding the project
Optional parameters
brief
A string for the brief of this item
expanded
A JSON array of key/value pairs indicating title and content of the expanded sections
conclusion
A JSON array of key/value pairs indicating title and content of the conclusion sections
deadline
Default: +7 days
An epoch time value for the deadline of when the project should be completed by
discount
Float: A percentage of the job total to be applied as a discount
Success response
If the project is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-project
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-project</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a project
To update an existing project on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/projects/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this project
Parameters
The parameters that can be updated are the same as those when adding a new project, however you only need to pass the parameters you want to update.
Success response
If the project is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-project
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-project</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a project that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a project
To delete an existing project on your Depot account, you should perform a DELETE operation on [endpoint]/projects/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this project
Parameters
No parameters should be passed.
Success response
If the project is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-project
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-project</id>
</response>
Not found response
If you delete a project that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Note
This is a permissions determined resource, therefore the results returned to an authenticated are determined by the permissions granted to their login account.
List or search proposals
Retrieve a list or filtered list of all proposals associated with your Depot account.
This can be performed by a GET operation on [endpoint]/proposals.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
title
Return jobs whose title match the search string
status
O for open, H for held, P for pending, C for cancelled, F for finished
issuehistory
Return the history of when invoices were issued
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": 4,
"client": {
"type": "C",
"id": "41",
"name": "Joe Bloggs Inc"
},
"status": "P",
"name": "Proposal title",
"overview": "An overview goes here...",
"expanded": [],
"conclusion": [],
"jobs": [
{
"name": "Job title goes here",
"brief": "",
"discount": 0,
"print": false,
"items": [
{
"hours": "315.00",
"name": "Line item 1",
"brief": "",
"rate": "50.00",
"taxcode": "001",
"actions": [],
"type": "hourly",
"start": "TBC",
"duration": 0,
"team": "",
"print": true,
"category": "-"
},
{
"hours": "196.00",
"name": "Line item 2",
"brief": "",
"rate": "50.00",
"taxcode": "001",
"actions": [],
"type": "hourly",
"start": "TBC",
"duration": 0,
"team": "",
"print": true,
"category": "-"
},
{
"hours": "238.00",
"name": "Line item 3",
"brief": "",
"rate": "50.00",
"taxcode": "001",
"actions": [],
"type": "hourly",
"start": "TBC",
"duration": 0,
"team": "",
"print": true,
"category": "-"
},
{
"hours": "196.00",
"name": "Line item 4",
"brief": "",
"rate": "50.00",
"taxcode": "001",
"actions": [],
"type": "hourly",
"start": "TBC",
"duration": 0,
"team": "",
"print": true,
"category": "-"
},
{
"hours": "0.00",
"name": "Line item 5",
"brief": "",
"rate": "50.00",
"taxcode": "001",
"actions": [],
"type": "fixed",
"start": "TBC",
"duration": 0,
"team": "",
"print": false,
"category": "-"
}
],
"team": ""
}
],
"discount": 0,
"total": 47250,
"tax": 9450,
"grandtotal": 56700,
"printtotal": true,
"pdf": "https://path/to/file.pdf",
"created": 1392020397,
"submitdate": 0,
"user": {
"email": "hello@depothq.com",
"name": "Depot"
}
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<client>
<id>41</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<conclusion />
<created>1392020397</created>
<discount>0</discount>
<expanded />
<grandtotal>56700</grandtotal>
<id>4</id>
<jobs>
<item>
<brief />
<discount>0</discount>
<items>
<item>
<actions />
<brief />
<category>-</category>
<duration>0</duration>
<hours>315.00</hours>
<name>Line item 1</name>
<print>true</print>
<rate>50.00</rate>
<start>TBC</start>
<taxcode>001</taxcode>
<team />
<type>hourly</type>
</item>
<item>
<actions />
<brief />
<category>-</category>
<duration>0</duration>
<hours>196.00</hours>
<name>Line item 2</name>
<print>true</print>
<rate>50.00</rate>
<start>TBC</start>
<taxcode>001</taxcode>
<team />
<type>hourly</type>
</item>
<item>
<actions />
<brief />
<category>-</category>
<duration>0</duration>
<hours>238.00</hours>
<name>Line item 3</name>
<print>true</print>
<rate>50.00</rate>
<start>TBC</start>
<taxcode>001</taxcode>
<team />
<type>hourly</type>
</item>
<item>
<actions />
<brief />
<category>-</category>
<duration>0</duration>
<hours>196.00</hours>
<name>Line item 4</name>
<print>true</print>
<rate>50.00</rate>
<start>TBC</start>
<taxcode>001</taxcode>
<team />
<type>hourly</type>
</item>
<item>
<actions />
<brief />
<category>-</category>
<duration>0</duration>
<hours>0.00</hours>
<name>Line item 5</name>
<print>false</print>
<rate>50.00</rate>
<start>TBC</start>
<taxcode>001</taxcode>
<team />
<type>fixed</type>
</item>
</items>
<name>Job title goes here</name>
<print>false</print>
<team />
</item>
</jobs>
<name>Proposal title</name>
<overview>An overview goes here...</overview>
<pdf>https://path/to/file.pdf</pdf>
<printtotal>true</printtotal>
<status>P</status>
<submitdate>0</submitdate>
<tax>9450</tax>
<total>47250</total>
<user>
<email>hello@depothq.com</email>
<name>Depot</name>
</user>
</item>
</rows>
<total>10</total>
</response>
Get a specific proposal
Retrieve an individual proposal associated with your Depot account.
This can be performed by a GET operation on [endpoint]/proposals/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this proposal
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
issuehistory
Return the history of when invoices were issued
Add a new proposal
Add a new proposal to your Depot account.
This can be performed by a POST operation on [endpoint]/proposals.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
title
A string for the title of this job
status
P for pending, A for accepted, X for rejected
client
The ID of the company or contact to associate the proposal with (format is C for company, I for contact followed by the ID e.g. C1)
user
The email address of the user adding the proposal
Optional parameters
overview
A string for the overview of this proposal
items
A JSON array of sections and items (see response format for expected structure)
expanded
A JSON array of key/value pairs indicating title and content of the expanded sections
conclusion
A JSON array of key/value pairs indicating title and content of the conclusion sections
submitdate
Default: none
An epoch time value for the deadline of when the proposal should be submitted by
discount
Float: A percentage of the total to be applied as a discount
printtotal
If true overall totals will be added to any outputs
Success response
If the proposal is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-proposal
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-proposal</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a proposal
To update an existing proposal on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/proposals/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this proposal
Parameters
The parameters that can be updated are the same as those when adding a new proposal, however you only need to pass the parameters you want to update.
Success response
If the proposal is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-proposal
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-proposal</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a proposal that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a proposal
To delete an existing proposal on your Depot account, you should perform a DELETE operation on [endpoint]/proposals/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this proposal
Parameters
No parameters should be passed.
Success response
If the proposal is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-proposal
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-proposal</id>
</response>
Not found response
If you delete a proposal that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Note
This is a permissions determined resource, therefore the results returned to an authenticated are determined by the permissions granted to their login account.
Invoices
Retrieve a grouped list of all invoices associated with your Depot account.
This can be performed by a GET operation on [endpoint]/reports/invoices.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
default: 0
The row you want the response to start at
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
groupby
Default: 'date'
Can be either of 'date' (group by invoice date), 'client' (group by client), 'category' (group by ledger category)
client
Filter items associated with a specific contact or company (format is C for company, I for contact followed by the ID e.g. C1)
project
Filter items associated with a specific project specified by ID
job
Filter items associated with a specific job specified by ID
paid
Set true for invoices that are paid, false for those than are not
assigned
Default: 'all'
Return invoices sent by a specific user by passing their email address
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": {
"2014-02": {
"total": 0,
"clients": []
},
"2014-03": {
"total": 1834,
"clients": {
"C66": {
"type": "C",
"id": "41",
"name": "Job Blogs Inc.",
"total": 18
},
...
}
}
...
},
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<2014-02>
<clients />
<total>0</total>
</2014-02>
<2014-03>
<clients>
<C66>
<id>41</id>
<name>Job Blogs Inc.</name>
<total>18</total>
<type>C</type>
</C66>
</clients>
<total>1834</total>
</2014-03>
</rows>
<total>10</total>
</response>
Payments
Retrieve a grouped list of all payments associated with your Depot account.
This can be performed by a GET operation on [endpoint]/reports/payments.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
groupby
Default: 'date'
Can be either of 'date' (group by invoice date), 'client' (group by client)
client
Filter items associated with a specific contact or company (format is C for company, I for contact followed by the ID e.g. C1)
project
Filter items associated with a specific project specified by ID
job
Filter items associated with a specific job specified by ID
assigned
Default: 'all'
Return payments relating to invoices sent by a specific user by passing their email address
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": {
"2014-02": {
"total": 0,
"clients": []
},
"2014-03": {
"total": 1834,
"clients": {
"C66": {
"type": "C",
"id": "41",
"name": "Job Blogs Inc.",
"total": 18
},
...
}
}
...
},
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<2014-02>
<clients />
<total>0</total>
</2014-02>
<2014-03>
<clients>
<C66>
<id>41</id>
<name>Job Blogs Inc.</name>
<total>18</total>
<type>C</type>
</C66>
</clients>
<total>1834</total>
</2014-03>
</rows>
<total>10</total>
</response>
Periodicals
Retrieve a grouped list of all periodicals associated with your Depot account.
This can be performed by a GET operation on [endpoint]/reports/periodicals.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
groupby
Default: 'date'
Can be either of 'date' (group by invoice date), 'client' (group by client)
client
Filter items associated with a specific contact or company (format is C for company, I for contact followed by the ID e.g. C1)
assigned
Default: 'all'
Return periodicals sent by a specific user by passing their email address
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": {
"1": {
"total": 5507,
"clients": {
"C73": {
"type": "C",
"id": "73",
"name": "Apple Inc",
"total": 495
},
}
...
}
...
},
"grouping": "week",
"stats": {
"billable": 288.55,
"unbillable": 57.5,
"total": 346.05,
"daily": 2.0598214285714
},
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<grouping>week</grouping>
<rows>
<1>
<clients>
<C73>
<id>73</id>
<name>Apple Inc</name>
<total>495</total>
<type>C</type>
</C73>
</clients>
<total>5507</total>
</1>
</rows>
<stats>
<billable>288.55</billable>
<daily>2.0598214</daily>
<total>346.05</total>
<unbillable>57.5</unbillable>
</stats>
<total>10</total>
</response>
Timesheets
Retrieve a grouped list of all timesheet entries associated with your Depot account.
This can be performed by a GET operation on [endpoint]/reports/timesheets.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
groupby
Default: 'date'
Can be either of 'date' (group by invoice date), 'client' (group by client)
client
Filter items associated with a specific contact or company (format is C for company, I for contact followed by the ID e.g. C1)
project
Filter items associated with a specific project specified by ID
job
Filter items associated with a specific job specified by ID
item
Filter items associated with a specific job item specified by ID
action
Filter items associated with a specific job action specified by ID
assigned
Default: 'all'
Return items added by a specific user by passing their email address
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": {
"2014-02": {
"total": 0,
"projects": []
},
"2014-03": {
"total": 76.5,
"projects": {
"P394": {
"id": "394",
"name": "Project name",
"type": "P",
"client": {
"type": "C",
"id": "41",
"name": "Joe Bloggs Inc"
}
},
...
}
}
...
},
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<2014-02>
<projects />
<total>0</total>
</2014-02>
<2014-03>
<projects>
<P394>
<client>
<id>41</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<id>394</id>
<name>Project name</name>
<type>P</type>
</P394>
</projects>
<total>76.5</total>
</2014-03>
</rows>
<total>10</total>
</response>
Profitability
Retrieve statistics on profitability (hours allocated vs hours logged) for given criteria.
This can be performed by a GET operation on [endpoint]/reports/profitability.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
client
Filter items associated with a specific contact or company (format is C for company, I for contact followed by the ID e.g. C1)
project
Filter items associated with a specific project specified by ID
job
Filter items associated with a specific job specified by ID
assigned
Default: 'all'
Return time added by a specific user by passing their email address
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": "438",
"name": "36 Bedford Row - Logo Addition",
"client": {
"type": "C",
"id": "140",
"name": "Sparks Studio"
},
"allocated": 0.5,
"logged": 0,
"jobs": [
{
"id": "412",
"name": "36 Bedford Row - Logo Addition",
"allocated": 0.5,
"logged": 0
}
]
},
... ,
],
"grouping": "project",
"stats": {
"projects": 21,
"logged": 503.3,
"allocated": 415.5
},
"total": 21
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<grouping>project</grouping>
<rows>
<item>
<allocated>0.5</allocated>
<client>
<id>140</id>
<name>Sparks Studio</name>
<type>C</type>
</client>
<id>438</id>
<jobs>
<item>
<allocated>0.5</allocated>
<id>412</id>
<logged>0</logged>
<name>36 Bedford Row - Logo Addition</name>
</item>
</jobs>
<logged>0</logged>
<name>36 Bedford Row - Logo Addition</name>
</item>
</rows>
<stats>
<allocated>415.5</allocated>
<logged>503.3</logged>
<projects>21</projects>
</stats>
<total>21</total>
</response>
Note
This is a permissions determined resource, therefore the results returned to an authenticated are determined by the permissions granted to their login account.
Companies and contacts
Search a combined list of all contacts and companies associated with your Depot account.
This can be performed by a GET operation on [endpoint]/search.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
name
Return items that match the search string passed
tag
Return items that have the tag passed
noindividualsincompanies
If true individuals in companies will be omitted from results
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": "C1",
"name": "Depot"
},
{
"id": "C41",
"name": "Joe Bloggs Inc"
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<id>C1</id>
<name>Depot</name>
</item>
<item>
<id>C41</id>
<name>Joe Bloggs Inc</name>
</item>
</rows>
<total>10</total>
</response>
Search a list of all tags that have been added to your Depot account.
This can be performed by a GET operation on [endpoint]/search/tags.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: Name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
search
Return items that match the search string passed
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"rows": [
{
"id": "Tag 1",
"name": "Tag 1"
},
{
"id": "Tag 2",
"name": "Tag 2"
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<id>C1</id>
<name>Depot</name>
</item>
<item>
<id>C41</id>
<name>Joe Bloggs Inc</name>
</item>
</rows>
<total>10</total>
</response>
Note
This is a permissions determined resource, therefore the results returned to an authenticated are determined by the permissions granted to their login account.
View activity types
Search a list of activity types assigned to your account.
This can be performed by a GET operation on [endpoint]/settings/activitytypes.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": "1",
"name": "Administration"
},
{
"id": "2",
"name": "Cleaning"
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<id>1</id>
<name>Administration</name>
</item>
<item>
<id>2</id>
<name>Cleaning</name>
</item>
</rows>
<total>10</total>
</response>
Update activity types
To update the activity types on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/activitytypes.[xml|json]
Parameters
The following parameters should be sent.
value
A JSON encoded object made up of an array of objects with an id and name referenced by the key tasks, along with another key called nextid specifying the next integer value for any activity types added through the system.
JSON
{
"nextid": 101
"tasks": [
{
"id": "1",
"name": "Administration"
},
{
"id": "2",
"name": "Cleaning"
},
...
],
"total": 10
}
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
View tax codes
Search a list of tax codes assigned to your account.
This can be performed by a GET operation on [endpoint]/settings/taxcodes.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"code": "001",
"name": "Standard VAT",
"rate": 0.2
},
{
"code": "002",
"name": "Zero VAT",
"rate": 0
},
{
"code": "003",
"name": "Reduced VAT",
"rate": 0.05
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<code>001</code>
<name>Standard VAT</name>
<rate>0.2</rate>
</item>
<item>
<code>002</code>
<name>Zero VAT</name>
<rate>0</rate>
</item>
<item>
<code>003</code>
<name>Reduced VAT</name>
<rate>0.05</rate>
</item>
</rows>
</response>
Update tax codes
To update the tax cods on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/taxcodes.[xml|json]
Parameters
The following parameters should be sent.
value
A JSON encoded object made up of an array of objects with an code, name and rate.
JSON
{
[
{
"code": "101",
"name": "Standard tax",
"rate": 0.2
},
{
"id": "102",
"name": "No tax",
"rate": 0
},
...
]}
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
View charge rates
Search a list of tax codes assigned to your account.
This can be performed by a GET operation on [endpoint]/settings/chargerates.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the JSON response you should expect.
Xml Json
{
"error": false,
"rows": [
{
"name": "Standard rate",
"rate": 100
},
{
"name": "Consultancy rate",
"rate": 150
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<name>Standard rate</name>
<rate>100</rate>
</item>
<item>
<name>Consultancy rate</name>
<rate>150</rate>
</item>
</rows>
</response>
Update charge rates
To update the charge rates on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/chargerates.[xml|json]
Parameters
The following parameters should be sent.
value
A JSON encoded object made up of an array of objects with an code, name and rate.
JSON
{
[
{
"code": "101",
"name": "Standard tax",
"rate": 0.2
},
{
"code": "102",
"name": "No tax",
"rate": 0
},
...
],
}
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
View ledger categories
Search a list of ledger categories assigned to your account.
This can be performed by a GET operation on [endpoint]/settings/ledgers.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"code": "4000",
"name": "Consultancy & Strategy"
},
{
"code": "4001",
"name": "Research"
},
...
]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<code>4000</code>
<name>Consultancy & Strategy</name>
</item>
<item>
<code>4001</code>
<name>Research</name>
</item>
</rows>
</response>
Update ledger categories
To update the ledgers on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/ledgers.[xml|json]
Parameters
The following parameters should be sent.
value
A JSON encoded object made up of an array of objects with an code and name.
JSON
{
[
{
"code": "4000",
"name": "Consultancy & Strategy"
},
{
"code": "4001",
"name": "Research"
},
...
],
}
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<code>4000</code>
<name>Consultancy & Strategy</name>
</item>
<item>
<code>4001</code>
<name>Research</name>
</item>
</rows>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
View breakeven point
Return the value of the breakeven amount.
This can be performed by a GET operation on [endpoint]/settings/breakeven.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"value": "24000"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<value>24000</value>
</response>
Update breakeven point
To update the breakeven point on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/breakeven.[xml|json]
Parameters
The following parameters should be sent.
value
An integer for the new breakeven value
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
View time rounding
Return the value of the timerounding interval in minutes.
This can be performed by a GET operation on [endpoint]/settings/timeround.[xml|json]
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"value": "15"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<value>15</value>
</response>
Update time rounding
To update the time rounding on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/timeround.[xml|json]
Parameters
The following parameters should be sent.
value
An integer for the new timeround value in minutes
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
View next proposal/project ID
Return the id of the next proposal.
This can be performed by a GET operation on [endpoint]/settings/nextproposalid.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"value": 456
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<value>456</value>
</response>
Update next proposal/project ID
To update the next id on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/nextproposalid.[xml|json]
Parameters
The following parameters should be sent.
value
An integer for the next id
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
View next invoice ID
Return the id of the next invoice.
This can be performed by a GET operation on [endpoint]/settings/nextinvoiceid.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"value": 456
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<value>456</value>
</response>
Update next invoice ID
To update the next id on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/nextinvoiceid.[xml|json]
Parameters
The following parameters should be sent.
value
An integer for the next id
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
View next credit ID
Return the id of the next credit note.
This can be performed by a GET operation on [endpoint]/settings/nextcreditid.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"value": 456
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<value>456</value>
</response>
Update next credit ID
To update the next id on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/nextcreditid.[xml|json]
Parameters
The following parameters should be sent.
value
An integer for the next id
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
View logo
Return the url of the logo associated with your account.
This can be performed by a GET operation on [endpoint]/settings/logo.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Response format
Below is an example of the response you should expect.
XML JSON
{
"error": false,
"value": "https://path/to/file"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<https://path/to/file>
</response>
Remove logo
To remove the logo on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/settings/logo.[xml|json]
Parameters
The following parameters should be sent.
removelogo
Enter a value of 1
Success response
If the update is performed with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Upload a logo
You can upload a logo by sending POST data to [endpoint]/settings/logo.[xml|json]
The uploader supports both standard and chunked upload methods.
Standard upload
The data should be multipart/form-data and the file should be in a field named _tbxFile1 .
Success response
On successful upload you will receive a response in the format.
XML JSON
{
"error": false,
"finish": true,
"upload_name": "upload_file_uri"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>true</finish>
<upload_name>upload_file_uri</upload_name>
</response>
Chunked upload
The request body should contain the file data chunk you want to upload, along with the following required parameters.
X-File-Id
A unique id for the file you are uploading (e.g. 1)
X-File-Name
The filename
X-File-Size
The final size of the completed file
X-File-Resume
Boolean, is the upload being resumed or not
Progress response
On upload progress you will receive a response in the format.
XML JSON
{
"error": false,
"id": "id_you_supply",
"finish": false
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>false</finish>
<id>id_you_supply</id>
</response>
Success response
On successful upload you will receive a response in the format.
XML JSON
{
"error": false,
"finish": true,
"upload_name": "upload_file_uri"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<finish>true</finish>
<upload_name>upload_file_uri</upload_name>
</response>
Note
This is a permissions determined resource, therefore the results returned to an authenticated are determined by the permissions granted to their login account.
List or search timesheets
Retrieve a list or filtered list of all timesheet entries associated with your Depot account.
This can be performed by a GET operation on [endpoint]/timesheet.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
rows
Default: 10
The number of rows you want to return (max 1000)
start
Default: 0
The row you want the response to start at
order
Default: name
The key of the field you want to use for ordering the response
orderasc
Default: true
Order ascending (true), or descending (false)
project
The ID of a project to show timesheet entries for
job
The ID of a job to show timesheet entries for
item
The ID of an item to show timesheet entries for
user
The email address of the user whose time entries you want to view
from
Epoch time of start datetime to return results from
to
Epoch time of end datetime to return results to
type
Filter entries by an activity type
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": 1931,
"notes": "",
"user": {
"email": "hello@depothq.com",
"name": "Depot"
},
"date": 1392210439,
"hours": 2.5,
"isinternal": false,
"activitytype": "",
"activitytitle": "",
"added": 1392195553,
"jobitem": {
"id": "836",
"title": "Job item title"
},
"job": {
"id": "362",
"title": "Job title"
},
"project": {
"id": "372",
"title": "Project Title"
},
"client": {
"type": "C",
"id": "41",
"name": "Joe Bloggs Inc"
}
},
...
],
"total": 1843
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<activitytitle />
<activitytype />
<added>1392195553</added>
<client>
<id>41</id>
<name>Joe Bloggs Inc</name>
<type>C</type>
</client>
<date>1392210439</date>
<hours>2.5</hours>
<id>1931</id>
<isinternal>false</isinternal>
<job>
<id>362</id>
<title>Job title</title>
</job>
<jobitem>
<id>836</id>
<title>Job item title</title>
</jobitem>
<notes />
<project>
<id>372</id>
<title>Project Title</title>
</project>
<user>
<email>hello@depothq.com</email>
<name>Depot</name>
</user>
</item>
</rows>
<total>1843</total>
</response>
Get a specific time entry
Retrieve an individual time entry associated with your Depot account.
This can be performed by a GET operation on [endpoint]/timesheet/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this time entry
Add a new time entry
Add a new timesheet entry to your Depot account.
This can be performed by a POST operation on [endpoint]/timesheet.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
date
An epoch representation of the datetime the entry is for
hours
A float value of the hours spent on the entry
userid
The email address of the user adding the entry
job
The ID of the item the enter is associated with preceded by a character (J for job, p for project, A for action, T for item)
Optional parameters
notes
Any notes to associate with the entry
type
The ID of a valid activity type that represents the type of work that has been done
Success response
If the entry is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-entry
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-entry</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a entry
To update an existing entry on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/timesheet/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this entry
Parameters
The parameters that can be updated are the same as those when adding a new entry, however you only need to pass the parameters you want to update.
Success response
If the activity is update with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-entry
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-entry</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a activity that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete an entry
To delete an existing entry on your Depot account, you should perform a DELETE operation on [endpoint]/timesheet/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The auto-assigned ID of this entry
Parameters
No parameters should be passed.
Success response
If the activity is deleted with no errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-entry
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-entry</id>
</response>
Not found response
If you delete an entry that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
List or search users
Retrieve a list or filtered list of all users and collaborators associated with your Depot account.
This can be performed by a GET operation on [endpoint]/users.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Optional Parameters
The following URL parameters can be sent to filter or amend the rows returned.
type
Can be collaborator or standard
Response format
Below is an example of the JSON response you should expect.
XML JSON
{
"error": false,
"rows": [
{
"id": "hello@depothq.com",
"name": "Depot",
"active": 1,
"restricted": 1,
"type": "standard",
"image": "https://path/to/file.jpg",
"jobtitle": ""
},
...
],
"total": 10
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<active>1</active>
<id>hello@depothq.com</id>
<image>https://path/to/file.jpg</image>
<jobtitle />
<name>Depot</name>
<restricted>1</restricted>
<type>standard</type>
</item>
</rows>
<total>10</total>
</response>
Get a specific user
Retrieve an individual user associated with your Depot account.
This can be performed by a GET operation on [endpoint]/users/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The email address of the user
Response format
Below is an example of teh JSON response you should expect to receive.
XML JSON
{
"error": false,
"rows": [
{
"id": "hello@depothq.com",
"name": "Depot",
"active": 1,
"restricted": 0,
"type": "standard",
"image": "https://path/to/file.jpeg",
"jobtitle": "",
"address": {
"line1": "Unit B1.10 Portview",
"line2": "",
"line3": "",
"city": "Belfast",
"district": "Antrim",
"country": "Northern Ireland",
"postcode": "BT4 1HE"
},
"telephone": "",
"notes": [
{
"title": "Birthday",
"content": "28th February 2014"
}
],
"permissions": []
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<rows>
<item>
<active>1</active>
<address>
<city>Belfast</city>
<country>Northern Ireland</country>
<district>Antrim</district>
<line1>Unit B1.10 Portview</line1>
<line2 />
<line3 />
<postcode>BT4 1HE</postcode>
</address>
<id>hello@depothq.com</id>
<image>https://path/to/file.jpeg</image>
<jobtitle />
<name>Depot</name>
<notes>
<item>
<content>28th February 2014</content>
<title>Birthday</title>
</item>
</notes>
<permissions />
<restricted>0</restricted>
<telephone />
<type>standard</type>
</item>
</rows>
</response>
Add a new standard user
Add a new user to your Depot account.
This can be performed by a POST operation on [endpoint]/users.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
email
The email address of the user you want to add
name
The full name of the user you want to add
restrictions
A JSON encoded object indicating the permissions the user should have (NEEDS FLESHED OUT)
Success response
If the user is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-user
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-user</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Add a new collaborator
Add a new collaborator to your Depot account.
This can be performed by a POST operation on [endpoint]/users.[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
Required parameters
email
The email address of the user you want to add
name
The full name of the user you want to add
collaborator
Should have a value of 1
jobs
A comma delimited list of the jobs which this user can collaborate on
Success response
If the user is added with no validation errors, you will be returned a 201 Created status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-user
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-user</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Updating a user
To update an existing user on your Depot account, you should perform a PATCH operation along with parameters sent as form data on [endpoint]/users/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The email address of this user
Parameters
The parameters that can be updated are the same as those when adding a new user, however you only need to pass the parameters you want to update.
Success response
If the invoice is updated with no validation errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-user
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-user</id>
</response>
Error response
If there are validation errors, you will be returned a 400 Bad Request status code, and the following response.
XML JSON
{
"error": true,
"msg": "Validation errors",
"errors": ["Error 1", "Error 2"]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>true</error>
<errors>
<item>Error 1</item>
<item>Error 2</item>
</errors>
<msg>Validation errors</msg>
</response>
Not found response
If you update a user that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.
Delete a user
To delete an existing user on your Depot account, you should perform a DELETE operation on [endpoint]/users/[id].[xml|json]
Variables
endpoint Your Depot endpoint as explained here
xml | json Your response format as explained here
id
The email address of this user
Parameters
No parameters should be passed.
Success response
If the invoice is deleted with errors, you will be returned a 200 OK status code, and the following response.
XML JSON
{
"error": false,
"id": id-of-this-user
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<id>id-of-this-user</id>
</response>
Not found response
If you try to delete a user that doesn’t exist, you will be returned a 404 Not Found status code, and no response body.