Depot

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.

Headers authentication

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:

  1. Direct users of your application to: http://[subdomain].depothq.com/oauth/authorize
  2. The user will then be asked to login if they are not, and then to authorise your application to work on their behalf
  3. If permission is not granted, they will be returned to your callback URL with an URL parameter of error set
  4. If permission is granted, they will be returned to your callback URL with a temporary access code in the URL parameter code
  5. You must then make a request to http://[subdomain].depothq.com/oauth/token to convert your temporary code into a permanent access token
  6. Depot will then return the access token as part of a JSON formatted response (key: access_token)
  7. 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.

{
	"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 .

Wrappers & Kits

To help you get up and running with our API as quickly as possible, we are working on language specific kits which we will release here as soon as they are available.

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:

  1. Direct users of your application to: http://[subdomain].depothq.com/oauth/authorize
  2. The user will then be asked to login if they are not, and then to authorise your application to work on their behalf
  3. If permission is not granted, they will be returned to your callback URL with an URL parameter of error set
  4. If permission is granted, they will be returned to your callback URL with a temporary access code in the URL parameter code
  5. You must then make a request to http://[subdomain].depothq.com/oauth/token to convert your temporary code into a permanent access token
  6. Depot will then return the access token as part of a JSON formatted response (key: access_token)
  7. 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

{
	"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:

{
	"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

Activity

The activity resource lets you manage items that appear in the various journals across your Depot 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.

{
    "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>&lt;p&gt;Hello&lt;br /&gt;
&lt;br /&gt;
Please find an invoice attached for charges incurred on your account.&lt;br /&gt;
&lt;br /&gt;
Many thanks, Depot/p&gt;</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>&lt;p&gt;Hello&lt;br /&gt;
&lt;br /&gt;
Please find an invoice attached for charges incurred on your account.&lt;br /&gt;
&lt;br /&gt;
Many thanks, Depot&lt;/p&gt;</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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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)

Companies

The companies resource lets you manage companies in the connections area of your Depot account.

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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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>

Contacts

The contacts resource lets you manage individual people in the connections area of your Depot account.

List or search contacts

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.

{
    "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>

Get a specific contact

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

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.

{
	"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.

{
	"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 contact

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.

{
	"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.

{
	"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.

Delete a contact

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.

{
	"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.

Upload a contact image

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.

{
	"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.

{
	"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.

{
	"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>

Credit notes

The credit notes resource lets you manage credit notes (credit invoices) associated with your Depot account.

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.

{
{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Invoices

The invoices resource lets you manage invoices associated with your Depot account.

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.

{
    "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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Job actions

The jobactions resource lets you manage job actions associated with your Depot account.

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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Job items

The jobitems resource lets you manage job items associated with your Depot account.

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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Jobs

The jobs resource lets you manage jobs associated with your Depot 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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Notifications

The notifications resource lets you manage notifications associated with your Depot account.

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.

{
    "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.

{
	"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.

{
	"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.

Payments

The payments resource lets you manage payments associated with your Depot 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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

Periodicals

The periodic resource lets you manage periodicals associated with your Depot account.

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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Private Tasks

The privatetasks resource lets you manage private tasks associated with your Depot account.

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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Projects

The projects resource lets you manage projects associated with your Depot 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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Proposals

The proposals resource lets you manage proposals associated with your Depot 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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Reports

The reports resource lets you generate reports on different data from areas of your Depot 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.

{
    "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.

{
    "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.

{
    "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.

{
    "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.

{
    "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>

Settings

The settings resource lets you view and modify key account level settings.

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.

{
    "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.
{
    "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.

{
	"error": false
}
							
<?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.

{
	"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.

{
    "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.
{
[
    {
        "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.

{
	"error": false
}
							
<?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.

{
	"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.

{
    "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.
{
[
    {
        "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.

{
	"error": false
}
							
<?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.

{
	"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.

{
    "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.
{
[
    {
        "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.

{
	"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.

{
    "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.

{
	"error": false
}
							
<?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.

{
	"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.

{
    "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.

{
	"error": false
}
							
<?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.

{
	"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.

{
    "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.

{
	"error": false
}
							
<?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.

{
	"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.

{
    "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.

{
	"error": false
}
							
<?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.

{
	"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.

{
    "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.

{
	"error": false
}
							
<?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.

{
	"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>

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.

{
    "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.

{
	"error": false
}
							
<?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.

{
	"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.

{
	"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.

{
	"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.

{
	"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>

Timesheet

The timesheet resource lets you manage the time entries associated with a user.

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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

Users

The users resource lets you manage users and collaborators associated with your Depot account.

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.

{
    "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.

{
    "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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

{
	"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.

This site uses cookies for general analytics but not for advertising purposes. View our privacy policy to find out more. If you continue without changing your settings, we'll assume that you are happy to receive all cookies on our website. However, you can change your cookie settings at any time.