Menu
Developers welcome! The mite.api is looking forward to your precious hacking. Have a look at the detailed documentation to kick-start your coding.

Please note: Customers can not be edited by time trackers. Time trackers can only read customers of projects they were granted access to.

List all active customers

List all active customers, sorted by name:

GET /customers.xml
GET /customers.json

Parameters

name Filters the list by name. The given string will match partly and is treated as case-insensitive.
limit Limits the list to the given number of entries.
Default: indefinite
page Allows to access follow-up pages when combined with limit.
Default: 1

Response

Status: 200 OK
[
   {
      "customer": {...}
   },
   {
      "customer": {...}
   }
]
Status: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<customers type="array">
   <customer>
      ...
   </customer>
   <customer>
      ...
   </customer>
</customers>

List all archived customers

List all archived customers, sorted by name:

GET /customers/archived.xml
GET /customers/archived.json

You can use the same parameters as for the active customers.

Get a single customer

Get a single customer by his id:

GET /customers/:id.xml
GET /customers/:id.json

Response

Status: 200 OK
{
   "customer": {
      "id": 643,
      "name": "Acme",
      "note": "Difficult.",
      "active_hourly_rate": "hourly_rate",
      "hourly_rate": 6000,
      "archived": false,
      "hourly_rates_per_service": [
         {
            "service_id": 31272,
            "hourly_rate": 4500
         },
         {
            "service_id": 149228,
            "hourly_rate": 5500
         }
      ],
      "created_at": "2011-08-17T12:06:57+02:00",
      "updated_at": "2015-02-19T10:53:10+01:00"
   }
}
Status: 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<customer>
   <id type="integer">643</id>
   <name>Acme</name>
   <note>Difficult.</note>
   <archived type="boolean">false</archived>
   <hourly-rate type="integer">6000</hourly-rate>
   <active-hourly-rate>hourly_rate</active-hourly-rate>
   <hourly-rates-per-service type="array">
      <hourly-rate-per-service>
         <service-id type="integer">31272</service-id>
         <hourly-rate type="integer">4500</hourly-rate>
      </hourly-rate-per-service>
      <hourly-rate-per-service>
         <service-id type="integer">149228</service-id>
         <hourly-rate type="integer">5500</hourly-rate>
      </hourly-rate-per-service>
   </hourly-rates-per-service>
   <updated-at type="datetime">2011-08-17T12:06:57+02:00</updated-at>
   <created-at type="datetime">2015-02-19T10:53:10+01:00</created-at>
</customer>

Create a customer

Create a new customer. All attributes are optional, except the name.

POST /customers.xml
POST /customers.json

Attributes

name Is required!
note Default: "" (empty string)
active_hourly_rate null (Default), "hourly_rate" or "hourly_rates_per_service"
hourly_rate In cent (a hundredth of the base unit, irrespective of the currency). Is used if active_hourly_rate is set to "hourly_rate".
Default: null
hourly_rates_per_service List of rates per service. Is used if active_hourly_rate is set to "hourly_rate".
Default: [] (empty array)
archived true or false
Default: false

Request

Content-Type: application/json
{
   "customer": {
      "name": "Big Inc."
   }
}
Content-Type: application/xml
<customer>
   <name>Big Inc.</name>
</customer>

Response

Status: 201 Created
Location: https://demo.mite.de/customers/544.json
{
   "customer": {
      "id": 544,
      "name": "Big Inc.",
      "note": "",
      "hourly_rate": null,
      "archived": false,
      "active_hourly_rate": null,
      "hourly_rates_per_service": [],
      "created_at": "2015-10-15T11:40:49+02:00",
      "updated_at": "2015-10-15T11:40:49+02:00"
   }
}
Status: 201 Created
Location: https://demo.mite.de/customers/544.xml
<?xml version="1.0" encoding="UTF-8"?>
<customer>
   <id type="integer">544</id>
   <name>Big Inc.</name>
   <note></note>
   <archived type="boolean">false</archived>
   <hourly-rate type="integer" nil="true"/>
   <active-hourly-rate nil="true"/>
   <hourly-rates-per-service type="array"/>
   <updated-at type="datetime">2015-10-15T11:40:49+02:00</updated-at>
   <created-at type="datetime">2015-10-15T11:40:49+02:00</created-at>
</customer>

Edit a customer

Update the customer with the given attributes:

PATCH /customers/:id.xml
PATCH /customers/:id.json

Request

Content-Type: application/json
{
   "customer": {
      "archived": true
   }
}
Content-Type: application/xml
<customer>
   <archived>true</archived>
</customer>

Response

Status: 200 OK
{empty}

If you change any attributes regarding the hourly rate (active_hourly_rate, hourly_rate and/or hourly_rates_per_service), it will by default only apply the changed rate to time entries created from now on. If you want it to apply to all existing time entries, set the additional attribute update_hourly_rate_on_time_entries to true:

Content-Type: application/json
{
   "customer": {
      "hourly_rate": 12000,
      "update_hourly_rate_on_time_entries": true
   }
}
Content-Type: application/xml
<customer>
   <hourly-rate>12000</hourly-rate>
   <update-hourly-rate-on-time-entries>12000</update-hourly-rate-on-time-entries>
</customer>

Delete a customer

Delete a customer:

DELETE /customers/:id.xml
DELETE /customers/:id.json

Response

Status: 200 OK
{empty}

You can only delete customers without any associated projects. If there are, you will get back the following error:

Status: 422 Unprocessable Entity
{
   "error": "This customer cannot be deleted: There are \
associated projects. Please archive instead."
}
Status: 422 Unprocessable Entity
<?xml version="1.0" encoding="UTF-8"?>
<errors>
   <error>This customer cannot be deleted: There are associated \
projects. Please archive instead.</error>
</errors>