apiary.apib

FORMAT: 1A
HOST: https://api.focus.teamleader.eu

# Teamleader API

This is the documentation of the Teamleader Focus API. If you have any feedback, or are you missing functionality to support your use case? Let us know via [api@teamleader.eu](mailto:api@teamleader.eu).

## AP-What?

An API is an Application Programming Interface. It is used to programmatically interact with Teamleader, integrate with other software tools or add custom functionalities to Teamleader.

Before creating a new integration, make sure to check our existing integrations built by our community in our [Teamleader Marketplace](https://marketplace.focus.teamleader.eu).

## General principles

### Endpoints

Our API consists of HTTP RPC-style methods, in the form of `https://api.focus.teamleader.eu/resource.action`.

We chose this action based approach over the more popular REST, because it enables us to have domain related actions on resources such as `invoices.book`, `timetracking.start` and `timetracking.stop`.

### Transport Security

We expect all network clients to make use of TLS 1.2 or higher when connecting to our infrastructure.

### Requests

All methods must be called using HTTPS. Data is passed as JSON data in a POST request.

```
POST https://api.focus.teamleader.eu/invoices.list

{
    "filter": {
        "department_id": "9d4096c3-813f-4bd5-b3c4-4091807b5b74"
    },
    "page": {
        "size": 50,
        "number": 3
    }
}
```

### Responses

Both single objects and collections are returned as JSON objects, keyed by `data` in the top level of a JSON object:

```json
{
    "data": {
        "id": "f1dfb84c-3c29-4548-9b9b-9090a080742a",
        "first_name": "Erlich",
        "last_name": "Bachman",
        "salutation": "Mr",
        "email": "info@piedpiper.eu"
    }
}
```

Responses may also contain meta data for pagination.

Sample response with pagination:
```json
{
    "data": [
        {
            "id": "f1dfb84c-3c29-4548-9b9b-9090a080742a",
            "first_name": "Erlich",
            "last_name": "Bachman",
            "salutation": "Mr",
            "email": "info@piedpiper.eu"
        },
        {
            "id": "f1dfb84c-3c29-4548-9b9b-9090a080742b",
            "first_name": "John",
            "last_name": "Doe",
            "salutation": "Mr",
            "email": "john@piedpiper.eu"
        }
    ],
    "meta": {
        "page": {
            "size": 20,
            "number": 2
        },
        "matches": 200
    }
}
```

### Errors

Errors are always returned as an array of error objects, keyed by `errors` in the top level of a JSON object:

```json
{
  "errors": [
    {
      "title": "Company name must not be empty"
    }
  ]
}
```

### Rate limiting

To ensure a fast and predictable experience for everyone, we limit the number of calls your integration (or client id) can make to a specific Teamleader account.  
To calculate this, we use the **sliding window** principle: before allowing requests, we check how many requests your integration made in the **last minute**. 
If you would cross your limit, we deny the request by replying with a specific HTTP error.

`HTTP 429 Too Many Requests`

You will be able to make a request again, if the oldest request we took into account falls outside the last minute window.  
To help you predict this, you can find rate limiting specific headers on each response:

```
X-RateLimit-Limit: 200
# the number of requests we allow per sliding minute

X-RateLimit-Reset: 2021-06-15T10:51:23.035+0100 
# the exact time your oldest significant request will expire; 
# when over limit, this is the earliest time you'll be able to successfully make requests again

X-RateLimit-Remaining: 78                       
# the number of requests you have left before you will be denied access; 
# note that this number can go up if earlier requests expire (after one minute)
```

You can use these headers to
- programmatically check the `X-RateLimit-Remaining` _number_ to avoid making calls that will be denied anyways, if the number is 0
- postpone execution until `X-RateLimit-Reset` _time_ to avoid waiting not long enough or too long before trying a next request

If you consistently bump into rate limits
- check if you can use `.list` endpoints instead of `.info` endpoints (did you know you can filter `.list` endpoints with a list of entity `ids`?)
- check if you can limit the items you fetch by making use of specific filters, eg. `updated_since`
- check if you can replace periodical checks with [webhooks](#/reference/other/webhooks)
- check if you can [side-load](#sideloading) related entities instead of fetching them yourself
- ask us for help through [api@teamleader.eu](mailto:api@teamleader.eu)

### Status codes

When objects are created, we return a `201` response containing the `id` and `type` of the new resource:

```json
{
  "type": "contact",
  "id": "9d4096c3-813f-4bd5-b3c4-4091807b5b74"
}
```

When objects are updated or actions are performed, we often return an empty response with a `204` status code.

Common used status codes:

 - `200` - OK
 - `201` - Created, when resources are created
 - `204` - No Content, on resource updates or actions
 - `400` - Bad Request, the request contains invalid data or references non-existing resources
 - `401` - Unauthorized, invalid or missing access token
 - `403` - Forbidden, not allowed to access this resource
 - `404` - Not Found, resource not found
 - `429` - Too Many Requests, your client has reached the API rate limit
 - `500` - Internal Server Error, something went wrong on our end

### Collections

Collections are groups of items, represented as JSON arrays `[]`, such as:
* Line items for quotations, invoices
* Addresses for contacts, companies
* Customer tags
* Custom fields

#### Updating collections

Collections are replaced entirely during updates, so all the wanted values should be provided when updating entities.
Other existing values which are not provided will be removed.

```json
POST https://api.focus.teamleader.eu/contacts.update

{
  "id": "f79a44dc-ec94-0d3c-b63e-8dcf41bba54e",
  "tags": [
    "existing tag",
    "a new tag"
  ],
  "custom_fields": [
    {
      "id": "0da89a10-794d-021d-9b2c-1f71dcd22489",
      "value": "existing value"
    },
    {
      "id": "fe50d0c5-49ba-0c12-8a34-d63becc7049e",
      "value": "a new value"
    }
  ]
}
```

> **Note:**
>
> + There is an exception for custom field collections where partial updates are possible, by including the parameter `custom_fields_update_strategy` with the value `partial` in the request body.
>
> + This will allow updating only the values of specific custom fields and leaving the remaining ones unchanged.

## Authentication

### OAuth 2

OAuth 2 is an authorization framework that allows a user to grant limited access to data in a Teamleader account, without having to expose their credentials.

To get access to the protected resources using our API, OAuth 2 uses access tokens. An access token is a string representing the granted permissions. Access tokens can be obtained after a user has completed the OAuth 2 authorization flow.

Before starting, you will need to register your integration (an OAuth 2 client) on our [Marketplace](https://marketplace.focus.teamleader.eu/build). Each registered integration is assigned a unique `client_id` and `client_secret`, which is used in the OAuth 2 authorization flow. Note that the `client_secret` key should not be shared or embedded in client-side code.

When you register an integration on our [Marketplace](https://marketplace.focus.teamleader.eu), it is required to select all *scopes* your integration wants access to.

For more detailed information about OAuth 2, we recommend reading [this article](https://auth0.com/docs/protocols/oauth2).

### Authorization flow

To get access to a user's Teamleader data using the *authorization code grant type*, redirect users to the Teamleader authorization page:

`https://focus.teamleader.eu/oauth2/authorize`

The required GET parameters are:

 - `client_id` - issued when you create your integration
 - `response_type` - must be "code"
 - `state` - unique string to be passed back upon completion (optional)
 - `redirect_uri` - URL to redirect back to after authorization

> A list of allowed redirect URIs needs to be configured on your integration's [settings page](https://marketplace.focus.teamleader.eu/build). Only redirect URIs matching one of these whitelisted URIs will be accepted. This is a security measure to prevent malicious users to impersonate your integration.

After logging in, the user will be asked to authorize your integration to access the data in their account. You will only be granted access to certain Teamleader data, based on the scopes you have selected on your integration's [settings page](https://marketplace.focus.teamleader.eu/build).

If the user authorizes your integration, they will be redirected to the specified `redirect_uri` with a temporary authorization code and the original `state` parameter. If the `state` parameter does not match the original value, the response may have been created by a third party and should be ignored.

`https://YOUR_REDIRECT_URI?code=CODE&state=STATE`

If the user denies your integration, he will be redirected to the `redirect_uri`, with an `error` parameter:

`https://YOUR_REDIRECT_URI?error=access_denied`

### Obtaining access tokens

After receiving the authorization code from the previous step, an access token can be requested to make API calls. Note that authorization codes can only be exchanged for an access token once and expire 10 minutes after issuance. To exchange the code for an access token, send an HTTP POST request to the following endpoint:

`https://focus.teamleader.eu/oauth2/access_token`

The required POST parameters are:

 - `client_id` - issued when you register your integration
 - `client_secret` - issued when you register your integration
 - `code` - the authorization code
 - `grant_type` - must be "authorization_code"
 - `redirect_uri` - the original submitted redirect URL

It is recommended to add `content-type` header to this request. Supported content types are:

 - application/x-www-form-urlencoded
 - application/json

You will receive a JSON response containing an `access_token` and `refresh_token`:

```
{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "ACCESS_TOKEN",
    "refresh_token": "REFRESH_TOKEN"
}
```

These access tokens are also known as bearer tokens. You can use this token to call API endpoints on behalf of the user, by adding it to the API request as an `Authorization` header.

```
POST https://api.focus.teamleader.eu/contacts.list HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciO...
Accept: application/json
```

Access tokens expire shortly (usually 1 hour) after they are issued for security reasons. If your integration needs to communicate with our API beyond the access token's lifespan, you will need to request a new access token using the refresh token which was issued with the access token. Note that refresh tokens can only be used once to get a new access token and refresh token.

### Using refresh tokens

If an access token is expired, a new access token and refresh token pair can be obtained by sending an HTTP POST request to the following endpoint:

`https://focus.teamleader.eu/oauth2/access_token`

The required POST parameters are:

 - `client_id` - issued when you register your integration
 - `client_secret` - issued when you register your integration
 - `refresh_token` - the refresh token
 - `grant_type` - must be "refresh_token"

Refresh tokens will continue functioning until the user revokes them or uninstalls your integration.

### Client-side authorization (implicit grant)

Your client secret must remain private and can not be embedded within client side applications such as browser plugins. For these types of applications, we have an alternative authorization method called using the [implicit grant](https://tools.ietf.org/html/rfc6749#section-1.3.2).  
The implicit grant is a simplified authorization code flow optimized for clients implemented in a browser using a scripting language such as JavaScript. In the implicit flow, instead of issuing the client an authorization code, the client is issued an access token directly.

Similar to the regular flow, users are redirected to the Teamleader authorization page, but use `token` as the `response_type`:

`https://focus.teamleader.eu/oauth2/authorize`

The required GET parameters are:

 - `client_id` - issued when you create your integration
 - `response_type` - must be "token" (instead of "code")
 - `state` - unique string to be passed back upon completion (optional)
 - `redirect_uri` - URL to redirect back to after authorization

> A list of allowed redirect URIs needs to be configured on your integration's [settings page](https://marketplace.focus.teamleader.eu/build). Only redirect URIs matching one of these whitelisted URIs will be accepted. This is a security measure to prevent malicious users to impersonate your integration.

After authorization, the user is redirected to the `redirect_uri` with the following parameters in the **fragment part of the url**:

 - `token_type` - with the value "Bearer"
 - `expires_in` - the TTL for this access token in seconds
 - `access_token` - the access token
 - `state` - the state parameter sent in the original request

Example:

`https://YOUR_REDIRECT_URI#token_type=Bearer&expires_in=900&access_token=TOKEN&state=STATE`

Note that the implicit grant does not return refresh tokens and that our access tokens have a short TTL value. If you opt for this authorization method, you will have to go through the authorization flow every time you want to make API calls on behalf of the user. Keep this in mind while developing client-side applications.

### User Identity

To retrieve information about the user who authorized your application (the resource owner), call the `users.me` API endpoint:

`https://api.focus.teamleader.eu/users.me`

### PHP code example

You can find a (very) minimal PHP code example, showing how to start the OAuth 2 authentication flow and retrieve the user's identity using the obtained access token.

[https://github.com/teamleadercrm/api/blob/master/examples/oauth2.php](https://github.com/teamleadercrm/api/blob/master/examples/oauth2.php)

<a name="sideloading"></a>
## Sideloading

Sideloading (or compound documents) allows you to retrieve relevant related items as part of a single request. For example, a deal has a reference to a lead which can either be a contact or a company:

```
{
  "data": {
    "id": "f6871b06-6513-4750-b5e6-ff3503b5a029",
    "title": "Deal with ACME",
    "lead": {
      "customer": {
        "type": "company",
        "id": "2659dc4d-444b-4ced-b51c-b87591f604d7"
      }
    }
  }
}
```

Relationships are always represented by an object with a type/id combination. All of these relationships are candidates for sideloading.

To sideload relationships, use the dot-notation reference of the relationship's property and add it as an `include` parameter to your JSON body or your URL. In this case of our deal's customer, that would be `include=lead.customer`.

The sideloaded relationships are returned as part of an `included` property in the response body.

```
{
  "data": {
    "id": "f6871b06-6513-4750-b5e6-ff3503b5a029",
    "title": "Deal with ACME",
    "lead": {
      "customer": {
        "type": "company",
        "id": "2659dc4d-444b-4ced-b51c-b87591f604d7"
      }
    }
  },
  "included": {
    "company": [
      {
        "id": "2659dc4d-444b-4ced-b51c-b87591f604d7",
        "name": "ACME"
      }
    ]
  }
}
```

Note that the sideloaded relationships are indexed based on their object type. Use the `type` property from your original relationship object to search for the sideloaded relationship in the `included` section.

Multiple relationships can be sideloaded at the same time by passing them as a comma-separated value such as `include=lead.customer,responsible_user`.

Sideloading is supported on every endpoint which returns objects.

## Changes & upgrades

We want to keep this API backwards compatible as long as possible, but at the same time, we need to make changes to it to match our evolving product.

Therefore we assigned a dated version to your API client when it was created.
This version controls the API and webhooks behaviour for your API client.
When we change the API in a backwards-incompatible way, we release a new dated version.
To avoid breaking your code, you stay on your assigned version until you [upgrade your API version](#upgrading-your-api-version).

### Types of changes

We consider the following changes to be backwards-compatible:

- Adding new API endpoints.
- Adding new optional parameters to existing API requests.
- Adding new properties to existing API responses.
- Adding new webhook types.
- Making existing parameters optional.
- Changing the order of properties in existing API responses.
- Fixing (potential) bugs that made an endpoint unusable (HTTP 500 errors).
- (Currently, we also hold ourselves the right to return a different error format, as there is still room for improvement)

We consider the following changes to be backwards-incompatible:

- Renaming or removing an endpoint.
- Renaming or removing a parameter of API requests.
- Renaming or removing a property of API responses.
- Changing the format of a parameter of API responses (eg. integer to float)
- Making validation of a parameter more strict (eg. making it required)
- Returning a different HTTP status code.

<a name="additions"></a>
### Additions

We list all backwards-compatible additions here. These are currently available in all published versions.
(There is also a [list of backwards-incompatible upgrades](#changelog) available, but those only apply if you [upgrade your API version](#upgrading-your-api-version).)

#### December 2024
- We added `initial_time_tracked`, `initial_price`, `initial_cost`, `initial_amount_billed`, and `initial_amount_paid` to `projects-v2/projects.create`. "Initial" values can be used when importing project data.
- We added `project` as a note type. `project` is a legacy project. For new projects, use `nextgenProject`.

#### November 2024
- We added `name` to `quotations.info` and `quotations.list`.

#### October 2024
- We added `preferred_currency` to the `companies.add` and `companies.update` endpoints.
- We added `payment_method` property to `invoice_generation` object on `subscription.info`, `subscriptions.create` and `subscriptions.update` endpoints.

#### September 2024
- We added `currency` to the `deals.create` and `deals.update` endpoints.
- We added `currency_exchange_rate` to the `deals.info` and `deals.list` endpoints.
- We added `pipeline` to the `deals.info` endpoint.
- The property `pipeline` on `deals.list` has been documented as resource.
- We added `will_be_automatically_switched_on` to the `accounts.projects-v2-status` endpoint.

#### August 2024
- We added the `accounts/projects-v2-status` endpoint to check the Projects version of an account.
- We added the `legacy_project` optional include to `projects-v2/projects.list` and `projects-v2/projects.info`.
- The `tickets.list` endpoint can now filter tickets by project ids.
- We added `billing_info` to `timeTracking.list` endpoint.
- We added the `users.getWeekSchedule` endpoint.
- We added `milestone_id` to the `tickets.create` and `tickets.update` endpoints.
- We added `milestone` and `project` to the `tickets.info` and `tickets.list` endpoints.
- We added `reference` to the `tickets.info` and `tickets.list` endpoints.
- We added `workOrder` to the `meetings.info` endpoint.
- We added `project_id` to the `tasks.update` endpoint.
- We added `work_order_id` to the `meetings.schedule` endpoint.
- We added `hourly_rate` to the `timeTracking.list` and `timeTracking.info` endpoints.
- We added `suppliers` as an optional include to the `products.info` endpoint.

#### July 2024
- We added `ticket` to the `tickets.getMessage` endpoint.
- We added `attachments` to the `emailTracking.list` endpoint.
- We added `attachments` to the `emailTracking.create` endpoint.
- We added `ticket.created`, `ticket.updated`, `ticket.closed`, `ticket.reopened` and `ticket.deleted` to supported Webhook types.
- We added `ticketMessage.added` to supported Webhook types.
- We added `custom_fields` as an optional include to `contacts.list`, `companies.list` and `deals.list` endpoints.
- We added `custom_fields` as an optional include to `projects-v2/projects.list` endpoint.

#### June 2024
- We added `tax` to the `products.info` endpoint.
- We added the `daysOff.import` and `daysOff.bulkDelete` endpoints.
- We added the `dayOffTypes.create`, `dayOffTypes.update` and `dayOffTypes.delete` endpoints.
- We added the `closingDays.add` and `closingDays.delete` endpoints.

#### May 2024
- We added `purchase_order_number` to `projects-v2/projects.info`, `projects-v2/projects.create` and `projects-v2/projects.update`.
- We added `product.updated` and `product.deleted` to supported Webhook types.

#### April 2024
- The meeting property `project` returned in `meetings.list` and `meetings.info` can now be an id of a `nextgenProject` as well.

#### February 2024
- We added the `tickets.importMessage`, `tickets.addReply` and `tickets.addInternalMessage` endpoints.
- We now support `ticket` as a valid `type` on the `cloudPlatforms.url` endpoint.
- We added the `initial_reply` to `tickets.create` endpoint.
- We added the `emailTracking.list` endpoint.
- We added `deal_id` to `calls.add` and `calls.update`.
- We added `deal` to `calls.list` and `calls.info`.
- We added `task.created`, `task.updated`, `task.completed`, `task.deleted` types to supported Webhook types.
- We added `contact.updatedLinkToCompany` to supported Webhook types.
- We added `includes` to the `companies.info` endpoint.
- We added `includes` to the `users.info` endpoint.
- We added `includes` to the `timeTracking.list` and `timeTracking.info` endpoints.

#### January 2024
- We renamed `task_type` and `task_type_id` to `work_type` and `work_type_id` in `projects-v2/tasks.list`, `projects-v2/tasks.info`, `projects-v2/tasks.create` and `projects-v2/tasks.update`. The old names are still supported, but deprecated.
- We replaced `task_type_rate` with `work_type_rate` in `projects-v2/tasks.list`, `projects-v2/tasks.info`, `projects-v2/tasks.create` and `projects-v2/tasks.update`. `task_type_rate` was never used.
- We added `project_id` to the `tasks.create` endpoint.
- We added the `users.listDaysOff` and `dayOffTypes.list` endpoints.
- We added `ticket` as a supported file subject on `files.list` and `files.upload`.
- We added `email_verification_status` to `users.me`.
- We added ticket endpoints `tickets.list`, `tickets.info`, `tickets.create` and `tickets.update`.
- We added endpoints for ticket messages `tickets.listMessages` and `tickets.getMessage`.
- We added the `ticketStatus.list` endpoint.
- We added `ticket_id` to `tasks.create`,`tasks.update`, `tasks.list` and `tasks.info`.

#### December 2023
- The `dealPhases.list` endpoint can now filter phases by pipeline id.
- We added `actions`, `requires_attention_after` and `probability` to `dealPhases.list`.
- We added the `dealPhases.create` endpoint.
- We added the `dealPhases.update` endpoint.
- We added the `dealPhases.duplicate` endpoint.
- We added the `dealPhases.move` endpoint.
- We added the `dealPhases.delete` endpoint.
- We added the `dealPipelines.list` endpoint.
- We added the `dealPipelines.create` endpoint.
- We added the `dealPipelines.update` endpoint.
- We added the `dealPipelines.markAsDefault` endpoint.
- We added the `dealPipelines.duplicate` endpoint.
- We added the `dealPipelines.delete` endpoint.
- The `deals.list` endpoint can now filter deals by pipeline ids.
- We added `pipeline` to `deals.list`.
- We now return the `default` payment term id in `paymentTerms.list` meta information.
- We added the `meetings.createReport` endpoint.
- We now return the user's team(s) in `users.info` and `users.list` endpoints.
- We added `nextgenProject` as a subject type to `files.upload`, `files.list` and `files.info`.
- The `/customFieldDefinitions.list` endpoint can now filter custom field definitions by context and ids.
- We added `nextgenProject` as a subject type to `emailTracking.create`.
- We added `nextgenProject` as a subject type to `notes.create` and `notes.list`.
- We added `nextgenProject` types to supported Webhook types.
- We added the `closingDays.list` endpoint.

#### November 2023
- We added the `calls.add`, `calls.list`, `calls.info` and `calls.complete` endpoints.
- We added the `callOutcomes.list` endpoint.
- We added `call.added`, `call.updated` and `call.deleted` types to supported Webhook types.
- We added the `meetings.schedule`, `meetings.update`, `meetings.complete` and `meetings.delete` endpoints.
- We added `meeting.created`, `meeting.updated` and `meeting.deleted` types to supported Webhook types.
- The `meetings.info` and `meetings.list` endpoints now return the meeting recurrence id for recurring meetings.
- The `meetings.list` endpoint can now filter meetings by recurrence id.
- We added `custom_fields` to `projects-v2/projects.info`, `projects-v2/projects.create` and `projects-v2/projects.update`
- We added `call.completed` and `meeting.completed` types to supported Webhook types.
- We added the `notes.list`, `notes.create` and `notes.update` endpoints.
- We added the `emailTracking.create` endpoint.

#### October 2023
- We added `late_fees` to `invoices.info` and `invoices.list`.
- We added the `invoices.updateBooked` endpoint.

#### September 2023
- We added the `meetings.list` and `meetings.info` endpoints.
- We added `time_estimated` and `amount_unbilled` to `projects-v2/projects.list`.
- We added sorting on `amount_billed`, `amount_paid`, `amount_unbilled`, `external_budget_spent`, `external_budget`, `internal_budget` and `time_estimated` to `projects-v2/projects.list`.

#### August 2023
- We added `quotation` as a type for `cloudPlatforms.url`.
- We added `currency` to `invoices.info`, `subscriptions.info`, `quotations.info` and `creditNotes.info`.
- We added `product_category` to `products.info`.
- We added the `invoices.creditPartially` endpoint.
- We added a `paymentMethods.list` endpoint.
- We added `payment_method_id` to `invoices.registerPayment`.
- We added the `cloudPlatforms.url` endpoint.
- We added `expiry` to `quotations.create`, `quotations.update`, `quotations.info` and `quotations.list`.
- We added `expired` as possible value for a quotation status.
- We added `subscription.add`, `subscription.updated`, `subscription.deleted`, `subscription.deactivated` types to supported Webhook types

#### July 2023
- We added `status` to the filters on `contacts.list`.
- We added `status` to the filters on `companies.list`.
- We added a `mailTemplates.list` endpoint.
- We added a `unitsOfMeasure.list` endpoint.
- We added `unit` on `grouped_lines` to `invoices.info`, `subscriptions.info`, `quotations.info` and `creditNotes.info`
- We added `unit_of_measure_id` on `grouped_lines` to `invoices.draft`, `invoices.update`, `subscriptions.create`, `subscriptions.update`, `quotations.create` and `quotations.update`.
- We added the `invoices.send` endpoint.
- 🎉 We added all endpoints for the _New Projects_ module: `projects-v2/projects`, `projects-v2/projectLines`, `projects-v2/projectGroups`, `projects-v2/tasks`, and `projects-v2/materials`. 🎉
- We added `billing_info` on `timetrackings.info`.
- We added `invoice_number` to the filters on `invoices.list`.
- We added the `priceLists.list` endpoint.
- We added `price_list_prices` to `products.info` and `products.add`.
- We added `stock` and `configuration` to `products.list`, `products.info` and `products.add`.
- We added `department_id`, `product_category_id` and `tax_rate_id` to `products.add`.
- We added the `products.update` endpoint.
- We added the `products.delete` endpoint.
- We added `added_at` to `products.info`.
- We added `updated_at` to `products.info` and `products.list`.
- We added `custom_fields` to `products.add` and `products.update`.
- We added `selling_price` to `products.update`.
- We added `unit_of_measure_id` to `products.add` and `products.update`.
- We added `unit` to `products.info` and `products.list`.
- We added the `currencies.exchangeRates` endpoint.
- We added `document_template` to `subscriptions.info`.
- We added `document_template_id` to `subscriptions.create` and `subscriptions.update`.
- We added `deal` as a link type to `events.create` and `events.update`.

#### June 2023

- We enhanced the existing filter on `term` in `users.list`.
  In addition to returning the users who have the term in their first name, last name or email address, we now also return those users who have the term in their function.
- We added the `commercialDiscounts.list` endpoint.
- We added the `documentTemplates.list` endpoint.

#### May 2023

- We added `team_lead_id` to the filters on `teams.list`.
- We added sorting on `first_name`, `last_name`, `email` and `function` to `users.list`.
- We added `creditNote.updated`, `creditNote.deleted`, `creditNote.sent` types to supported Webhook types.

#### April 2023

- We added `ids` to the filters on `teams.list`.

#### March 2023

- We added `customField`,`timeTracking` and `department` as allowed types on `migrate.id`.
- We added `credit_note_date_before` and `credit_note_date_after` to the filters on `creditNotes.list`.
- We added `ids` to the filters on `timeTrackings.list`.
- We added `term` to the filters on `teams.list`.
- The property `gender` has been expanded with additional values on:
  - `contacts.create`
  - `contacts.info`
  - `contacts.list`
  - `contacts.update`

#### February 2023

- Product custom fields are now included as `custom_fields` on `products.info`.

#### January 2023

- We added `user_id` to `timeTracking.add`.
- We updated the HTTP verb for all endpoints to `POST`. Using `GET ` for `.list`, `.info` and `migrate` endpoints is still possible, but deprecated.

#### December 2022

- We added `secondary_position` and `division` to the related company data on `contacts.info`.

#### November 2022

- We added `invoice_date` as a sort field on `invoices.list`.

#### October 2022

- We added `default_department` and `created_at` to the sorting options on `departments.list`.

#### September 2022

- We added `project_id` to `invoices.draft` and `invoices.update`.
- We added `payment_term`, `grouped_lines` and `invoice_generation` to `subscriptions.info`.
- We added `starts_on` and `ends_on` to `subscriptions.list` and `subscriptions.info`.
- We added `subscriptions.create` and `subscriptions.update`.
- We added the `quotations.send` endpoint.
- We clarified how the optional `folder` argument for the `files.upload` endpoint works.

#### August 2022

- We added `invoices.removePayments`.
- We added `department_id` to the filters on `subscriptions.list`.
- We added `tags` to `companies.update`.

#### July 2022

- We added `product` and `project` as subject type for `files.list`.
- We added `priority` to `tasks.list` and `tasks.info`.
- We added `vat_number` to the filters on `companies.list`.

#### June 2022

- We added `files.list`, `files.info`, `files.download`, `files.upload` and `files.delete`.

#### May 2022

- We added `status` as a sort field on `subscriptions.list`.

#### April 2022

- We added the `contacts.updateCompanyLink` endpoint.
- We added the `subscriptions.deactivate` endpoint.

#### March 2022

- We added the `subscriptions.info` and `subscriptions.list` endpoints.

#### February 2022

- We added `customer` to the filters on `invoices.list`.
- We added a `subscription` filter to `invoices.list`.
- We added `project` to `invoices.list` and `invoices.info`.

#### December 2021

- We added `on_hold_since` to `invoices.info`.
- We added `deal_id` to the filters on `invoices.list`.
- We added `project_id` to the filters on `invoices.list`.
- We added `invoice_date_before` and `invoice_date_after` to the filters on `invoices.list`.
- We added an `updated_since` filter to `projects.list`.

#### November 2021

- We added `status` on `companies.list` and `companies.info`.
- We added `status` on `contacts.list` and `contacts.info`.
- We added `ids` to the filters on `creditNotes.list`.
- We added `invoice_id` and `project_id` to the filters on `creditNotes.list`.
- We added `discounts` to `creditNotes.info`.
- We added `added_at` on `products.list`, and `tasks.list`.
- We added `created_at` on `projects.list`.

#### September 2021

- We added `sort` to `timeTracking.list`.
- We added `teams.list`.

#### June 2021

- We added `description` on `products.add`.
- We added `title` on `tasks.info` and `tasks.list`.
- We added `term` to the filters on `workTypes.list`.
- We added `started_on` to `timeTracking.update` and `timeTracking.add`.
- We added the `quotations.delete` endpoint.
- We changed the behaviour of the started_before, started_after, ended_before, and ended_after filters on timeTracking.list to be inclusive. So "started after midnight" will include time tracking that started exactly on midnight.
- We added `status` to `quotations.info` and `quotations.list`.

#### March 2021

- Updated the `migrate.id` endpoint for type `quotation` to return the first or accepted quotation uuid for given deal id.

#### January 2021

- We added `deal` on `invoices.list` and `invoices.info`.

#### October 2020

- We added `title` as a sort field on `projects.list`.
- We added `area_level_two` to the .list and .info responses for `company`, `contact` and `department` addresses.
- We added `area_level_two_id` to the .add and .update calls for `companies` and `contacts`.
- We added `starts_on` to `milestones.create`, `milestones.update`, `milestones.list`, `milestones.info`, and `projects.create` (in the milestone context).
- We added `budget` on `projects.update`.
- We added `customer` on `projects.update`.
- We added `starts_on` and `desc` to the sort options on `milestones.list`.
- We added `file` to `invoices.list` and `invoices.info`.
- We added `quotations.accept` endpoint.

#### September 2020

- We added the `milestones.close` and `milestones.open` endpoints.
- We added the `created_at` and `updated_at` fields to `quotations.list` and `quotations.info`. Please note that these fields are nullable and will only be filled in for future quotations.
- We added the `discounts` field to `quotations.info`.
- We added the `purchase_price` field to `quotations.list`, `quotations.info`, `quotations.create` and `quotations.update`.
- We added `projects.close` and `projects.reopen` endpoints.

#### August 2020

- We added a filter `done` to `events.list`.
- We added the `currency_exchange_rate` to `invoices.list`.
- We added the `product_id` property to `quotations.create`, `quotations.update`, `invoices.draft` and `invoices.update`.

#### July 2020

- We added `quotations.list`, `quotations.create` and `quotations.update`.

#### June 2020

- We added the `emails` property to `departments.list`.
- We added the `status` property to `departments.info` and `departments.list`, this property is also available as a filter on `departments.list`.

- We added a filter `scheduled` to `tasks.list`.

- We added the `total` field to `quotations.info`.

#### May 2020

- We no longer require all fields in `projects.update`, only the id remains required.
- We added the `purchase_order_number` field to `projects.info`, `projects.create`, and `projects.update`.

#### April 2020

- We added the `description` field to `milestones.info`, `milestones.create`, and `milestones.update`.

- We added the `propagate_date_changes` property to `milestones.update`. This allows propagating the new due date difference to the due date of all open tasks of that milestone, and recursively to all depending milestones.

- We added the `vat_number` property to `contacts.info`.

- Project custom fields are now included as `custom_fields` on `projects.info`. They can also be added and updated through the `projects.create` / `projects.update` endpoints.

#### March 2020

- We added actuals and budget to `projects.list`, `projects.info`, `milestones.list`, and `milestones.info`.

- We added `depends_on` to the `milestones.info` and `milestones.list` endpoints.

- We added `dependency_for` to the `milestones.info` and `milestones.list` endpoints. This indicates all the milestones for which the current milestone is a dependency.

- We added `depends_on` to the `milestones.create` and `milestones.update` endpoints. It allows setting a dependency on another milestone of the same project.

#### February 2020

- We added an `ids` filter to `lostReasons.list`.

- As events can be linked to deals, we added the `deal` link type to `events.list` and `events.info`, and allow filtering on deals in `events.list`.

- We added `lost_reason` to the response of `deals.info`.

- We added `lost_reason` to the response of `deals.list`. This is composed of a `lostReason` object along with a more elaborate `remark`.

- We added a filter `term` to `invoices.list`.

- We added the `purchase_order_number` to the response of both `deals.list` and `deals.info` request.

- We added the `summary` to the response of both the `deals.list` and `deals.info` request. The `summary` can also be added and updated through the `deals.create` / `deals.update` endpoints.

#### January 2020

- We added the time tracking `locked` and `updatable` properties to `timeTracking.info`.

- We exposed the "Freeze time tracking after a number of days" preference in `users.me`.

- We added format `ubl/e-fff` to `invoices.download`.

- We added filters `estimated_closing_date_from` and `estimated_closing_date_until` to `deals.list`.

- We added a new sorting option `weighted_value` to `deals.list` and will allow ascending as well as descending orders on sorts.
  The default remains created_at and descending as before if nothing is passed.

- We added the `weighted_value` to the response of both `deals.list` and `deals.info` requests.

- We added the `extra_option_allowed` information (for single select custom fields) to `customFieldDefinitions.list` and `customFieldDefinitions.info` endpoints.

- We added format `ubl/e-fff` to `creditNotes.download`.

#### October 2019

- We added `milestones.delete`.

- We added a `estimated_closing_date` filter to `deals.list`.

- We added a filter `created_before` to `deal.list`.

- We modified filter `responsible_user_id` in `deal.list` to also accept an array of responsible_user_ids.

- Task custom fields are now included as `custom_fields` on `tasks.info`. They can also be added and updated through the `tasks.create` / `tasks.update` endpoints.

- Milestone custom fields are now included as `custom_fields` on `milestones.info`. They can also be added and updated through the `milestones.create` / `milestones.update` endpoints.

#### July 2019

- We added an `updated_since` filter to `products.list`.

- We added `project` to `tasks.info` and `tasks.list`.

- We added a filter by `subject` to `timeTracking.list`.

- A `task_id` filter has been added to `/events.list`.

- We added a `term` filter to `milestone.list`.

#### June 2019

- We added a `term` filter to `tasks.list`.

- We added `tasks.complete` and `tasks.reopen` endpoints.

- We added `due_by` and `due_from` to `tasks.list` filters.

- We added a `tasks.schedule` endpoint.

- We added the ability to sort `tasks.list` based on a descending `due_at`.

- `tasks.info` and `tasks.list` now return information about the customer.

- We added `customer` parameter to `tasks.create` and `tasks.update`.

- In order to link milestones and deals to a task, we added `milestone_id` and `deal_id` as optional parameters to `tasks.create` and `tasks.update`.

- `tasks.list` and `tasks.info` now return the milestone and deal objects.

#### May 2019

- We added a `started_at` property to `timers.update` in order to be able to update the start time of a running timer.

- We added `sent` as a boolean to `invoices.info` and `invoices.list`.

- We added an optional filter on `ids` to `invoices.list`.

- We added `creditNote.booked` and `product.added` to the available webhooks list.

#### April 2019

- In `users.info`, we added the `status` property to the response since it is now possible to retrieve deactivated users.

- In `users.list`, you can now also request deactivated users, by using a new filter on `status`.
  By default, the endpoint keeps returning active users only. The status is also returned in the response data.

- We've added a `products.add` endpoint.
  Because you can provide the selling price of a product in this endpoint, we also return it in `products.info` from now on.

- We now also return the `payment_reference` of an invoice in the `invoices.list`.
  We also made it filterable through the `payment_reference` filter.

- We added the `purchase_order_number` to all relevant endpoints (`invoices.draft`, `invoices.update`, `invoices.info` and `invoices.list`).
  The property is also filterable through the `purchase_order_number` filter.

- We added `currency_exchange_rate` to `quotations.info`.

- The `events.list` endpoint now has an optional filter property `ids`.

- The `tasks.list` endpoint now has an optional filter property `ids`.

- We added an `invoices.credit` endpoint.

#### March 2019

- On `invoices.draft` and `invoices.update` you can now also provide (a) global discount(s) through the `discounts` property.

- We've published a bunch of `tasks` endpoints (`tasks.list`, `tasks.info`, `tasks.create`, `tasks.update`, `tasks.delete`).

- We now also return a `currency_exchange_rate` on all `.info` endpoints where we support multi-currency.
  That is `quotations.info`, `invoices.info` and `creditNotes.info`.

#### February 2019

- We now also return the `invoicing_method` of a milestone. Both in `milestones.list` and `milestones.info`.

- We now expose the invoiceability of time trackings and running timers. You can now use the `invoiceable` property on the following endpoints:
  - `timeTracking.list`
  - `timeTracking.info`
  - `timeTracking.add`
  - `timeTracking.update`
  - `timers.current`
  - `timers.start`
  - `timers.update`

  We also return an `invoiceable` preference in the `users.me` endpoint that exposes whether a user prefers to track time by default as invoiceable or not.

- We've added a `national_identification_number` property on contacts.
  You can read it from `contacts.list` and `contacts.info`.
  It's also writeable through `contacts.add` and `contacts.update`.

- Invoicing custom fields included as `custom_fields`.
  They are returned in `invoices.info`.
  They can be added or updated through `invoices.draft` and `invoices.update`.

- Deal can now be filtered with a `term` in `deals.list`.
  We will return deals of which the term is part of the title, reference or customer's name.

- We have created a way to fetch more data about related resources: sideloading.
  More information can be found [here](#sideloading).

- We didn't provide you with a way to find the uuid of a quotation.
  Based on a v1 deal id, you can now retrieve the uuid of a quotation with `migrate.id`.

#### January 2019

- The `projects.list` endpoint has an optional filter to filter on `term` now.
  We return projects for which the term appears in the title or description.

- During `invoices.draft` and `invoices.update`, we now allow you to provide a `withholding_tax_rate_id`.
  Don't worry if you don't know what this is. Withholding taxes only apply in certain countries, eg Spain or Italy.

- We added a filter on `term` in `users.list`.
  We return those users who have the term in their first name, last name or email address.

- We already had a part of the products APIs for our own usage, but since it might be useful to you, we are making it public.
  So `products.list` and `products.info` are now available for usage.

<a name="upgrading-your-api-version"></a>
### Upgrading your API version

This documentation only reflects the latest version of the API.
If you need to make changes to your client or you want to make use of the latest feature, you might need to upgrade your API version.

You can find your current API version, in the `X-Api-Version` header on any API response.
The current latest version is **2023-09-26**.

After checking the API [changelog](#changelog) to see which endpoints work differently, you can upgrade your API version:

Send an `X-Api-Version` header containing the identifier of a version (newer than your current version) with your requests.

_This will only affect the version for those API calls and won't affect any other calls done by your client._

<a name="changelog"></a>
### Changelog

We list all backwards-incompatible changes here. As described above, new additions and forwards-compatible changes don’t need a new API version and can be found [here](#additions).

#### 2023-10-01

As of October 1st 2023, we expect all network clients to make use of TLS 1.2 or higher when connecting to our infrastructure.

#### 2023-09-26

 - When updating events through `events.update`, links to deals must also be provided otherwise existing deal link(s) will be removed.

 - `unit_price.currency` is no longer returned for line items on the response of `invoices.info`, `subscriptions.info`, `quotations.info` and `creditNotes.info`.
 - `unit_price.currency` is no longer supported or validated on line items for invoices, quotations, subscriptions & credit notes endpoints. Instead, it will be supported on the document level for
  - `invoices.draft`
  - `invoices.update`
  - `quotations.create`
  - `quotations.update`

 - `customFieldDefinitions.list` and `customFieldDefinitions.info` will now return configuration options (for single and multiple select custom fields) as an array of objects.

 - We updated the `location` format of returned by `/meetings.info` endpoint
 - Both `/meetings.list`  and `/meetings.info` will now return a meeting `title` instead of `name`

#### 2022-09-15

- The property `remark` has been renamed to `note` on:
  - `subscriptions.info`
  - `subscriptions.list`

- The property `periodicity` has been replaced by `billing_cycle` on:
  - `subscriptions.info`
  - `subscriptions.list`

- The property `tags` will no longer be converted to lowercase on:
  - `companies.list`
  - `companies.info`
  - `contacts.list`
  - `contacts.info`

- The property `tag` will no longer be converted to lowercase on:
  - `tags.list`

#### 2021-09-01

- The property `description` is now returned in Markdown instead of HTML on:
  - `products.info`
  - `products.list`

#### 2020-05-01

- The property `title` is added to the response of:
  - `tasks.list`
  - `tasks.info`

- The property `title` is added and required on:
  - `tasks.create`
  - `tasks.update`

- The property `description` is no longer required on:
  - `tasks.create`
  - `tasks.update`

#### 2020-01-01

- The property `assignee` is now returned as null instead of `assignee.id` being returned as null on:
  - `tasks.list`
  - `tasks.info`

- The property `assignee` is now accepting null instead of `assignee.id` on:
  - `tasks.create`
  - `tasks.update`

#### 2019-10-09

- We added `billing_method` and `budget`, and `billing_method` and `price` to `milestones.create`.
  - When choosing `time_and_materials` or `non_invoiceable` as the billing method, you can provide a `budget`.
  - When choosing `fixed_price` as the billing method, you need to provide the `price`.

#### 2019-07-03

- The property `todo` has been renamed to `task` on the following endpoints:
  - `events.list`
  - `events.info`

- We renamed the `context` field for work orders on customFieldDefinitions from `werkbonnen` to `work_orders`

- The property `due_at` was removed in favour of `due_on`. Additionally, `due_on` is a date with format `YYYY-MM-DD`, instead of a ISO8601 datetime. These changes affect the following endpoints:
  - `tasks.info`
  - `tasks.list`
  - `tasks.create`
  - `tasks.update`

- We won't accept `project` as a `subject` anymore in `timeTracking.add`, `timeTracking.update`, `timers.start` and `timers.update`.
  We wrongly accepted this in the past, but time tracking always needs to be coupled to a milestone. Please use the `milestone` subject instead.
  For older versions, we will link the time tracked to the oldest `open` milestone. If there is no `open` milestone, it's linked to the most recent `closed` or `done` milestone.

#### 2019-03-13

- The property `tax` has been changed. Instead of giving you the `rate` of the tax it now shows the `id` and the `type` of the tax. This has been changed on the following endpoints:
  - `invoices.info`
  - `creditNote.info`
  - `quotations.info`

- We simplified the `products.info` and `products.list` endpoints:
  - `name` and `description` are no longer wrapped in a `translations` object.
  - `external_id` was renamed to `code`
  - `prices` are temporarily no longer returned, to avoid confusion, as they didn't take into account price lists

#### 2019-01-24

- Previously, the `invoices.info` endpoint returned an _non-existing_ or _empty_ `extended_description` as an empty string, while `invoices.draft` and `invoices.update` didn't allow an empty string as `extended_description`.
  From now on, `invoices.info` will return an _non-existing_ or _empty_ `extended_description` as `null`, to make this more consistent and interchangeable.

- Invoices can now have three statuses (`draft`, `outstanding` or `matched`) instead of two (`draft` or `booked`).
  Therefore the `status` property in `invoices.list` and `invoices.info` will either return `outstanding` or `matched` for invoices that were previously just `booked`.
  This is also reflected in the `status` filter on `invoices.list`: to allow you to still query all `outstanding` and `matched` invoices (previously all `booked`) , it now *only* accepts an array of filter values (eg. `["outstanding", "matched"]` or `["draft"]`).

- The property `local_business_number` was renamed to `national_identification_number` on the following endpoints:
  - `companies.info`
  - `companies.list`
  - `companies.add`
  - `companies.update`
  - `invoices.info`
  - `creditNotes.info`

- An invoice number actually contains the bookyear, so from now on, you will see eg. `2018 / 27` instead of `27`.
  This is reflected in the `invoice_number` property in the `invoices.list` and `invoices.info` endpoints.

#### 2018-10-30

- The top-level property `customer` was removed on all deal endpoints.
  Earlier, this property could already be found under the `lead.customer` property.
  If you were still using the `customer` property, just wrap it in an object under a `lead` key.

- The `contacts.list` & `companies.list` endpoints used to give back an object under the `address` key.
  This object is now returned under the `primary_address` key.

### Stay informed

You can follow our API progress and ongoing proposals via our [API Blueprint GitHub repository](https://github.com/teamleadercrm/api).

# Group General

## Departments [/departments]

Departments are used to split quotations and invoices for different legal entities or within one organisation.

*Required scopes: `departments`*

### departments.list [POST /departments.list]

Get a list of departments.

+ Request (application/json)

    + Attributes (object)
        + filter (object)
            + ids: `92296ad0-2d61-4179-b174-9f354ca2157f`,`53635682-c382-4fbf-9fd9-9506ca4fbcdd` (array[string], optional)
            + status (array[enum], optional) - Filters on status
                + Members
                    + active - Filters on active departments
                    + archived - Filters on archived departments
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + `default_department` - When sorting ascending, default departments are listed first
                        + `name`
                        + `created_at`
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (array)
                    + (object)
                        + field: `default_department`
                        + order: `asc`
                    + (object)
                        + field: `created_at`
                        + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `67c576e7-7e6f-465d-b6ab-a864f6e5e95b` (string)
                + name: `Human Resources` (string)
                + vat_number: `BE0899623035` (string)
                + currency: `EUR` (string)
                + emails (array)
                    + (object)
                        + type: `primary` (enum)
                            + Members
                                + primary
                                + invoicing
                        + email: `info@piedpiper.eu` (string)
                + status: `active` (enum)
                    + Members
                        + active
                        + archived

### departments.info [POST /departments.info]

Get details for a single department.

+ Request (application/json)

    + Attributes (object)
        + id: `92296ad0-2d61-4179-b174-9f354ca2157f` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data  (object)
            + id: `67c576e7-7e6f-465d-b6ab-a864f6e5e95b` (string)
            + name: `Human Resources` (string)
            + vat_number: `BE0899623035` (string)
            + address (AddressResponse)
            + emails (array)
                + (object)
                    + type: `primary` (enum)
                        + Members
                            + primary
                            + invoicing
                    + email: `info@piedpiper.eu` (string)
            + telephones (array[object])
                + type: `phone` (enum, required)
                    + Members
                        + phone
                        + fax
                + number: `092980615` (string, required)
            + website: `https://piedpiper.com` (string)
            + currency: `EUR` (string)
            + iban: `BE12123412341234` (string)
            + bic: `BICBANK` (string)
            + fiscal_regime: `RF01` (string, nullable)
            + status: `active` (enum)
                + Members
                    + active
                    + archived

## Users [/users]

Users are co-workers in a Teamleader account.

*Required scopes: `users`*

### users.me [POST /users.me]

Get the current authenticated user.

+ Response 200 (application/json)

    + Attributes
        + data (object)
            + id: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5` (string)
            + account (object)
                + type: `account` (string)
                + id: `0fc55513-7f68-4865-aba0-de5da9e4e43d` (string)
            + first_name: `John` (string)
            + last_name: `Smith` (string)
            + email: `john@teamleader.eu` (string)
            + email_verification_status: `confirmed` (enum)
                + Members
                    + pending
                    + confirmed
            + telephones (array[Telephone])
            + language: `nl-BE` (enum)
                + Members
                    + da-DK
                    + de-DE
                    + en-GB
                    + es-ES
                    + fi-FI
                    + fr-FR
                    + it-IT
                    + nb-NO
                    + nl-BE
                    + nl-NL
                    + pl-PL
                    + pt-PT
                    + sv-SE
                    + tr-TR
            + function: `Sales` (string)
            + time_zone: `Europe/Brussels` (string)
            + preferences (object)
                + invoiceable: true (boolean)
                + historic_time_tracking_limit (object, nullable)
                    + unit (enum)
                        + Members
                            + hour - Hours
                    + value: 24 (number)
                + whitelabeling: true (boolean)

### users.list [POST /users.list]

Get a list of all users.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5`,`f8a57a6f-dd1e-41a3-b8d3-428663f1d09e` (array[string], optional)
            + term: `John` (string, optional) - Filters on first name, last name, email and function
            + status (array[enum], optional) - Filters on status
                + Members
                    + active - Filters on active users
                    + deactivated - Filters on deactivated users
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + first_name
                        + last_name
                        + email
                        + function
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (array)
                    + (object)
                        + field: `first_name`
                        + order: `asc`
                    + (object)
                        + field: `last_name`
                        + order: `asc`
        + page (Page, optional)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5` (string)
                + account (object)
                    + type: `account` (string)
                    + id: `0fc55513-7f68-4865-aba0-de5da9e4e43d` (string)
                + first_name: `John` (string)
                + last_name: `Smith` (string)
                + email: `john@teamleader.eu` (string)
                + telephones (array[Telephone])
                + language: `nl` (string)
                + function: `Sales` (string)
                + status: `active` (enum)
                    + Members
                        + active
                        + deactivated
                + teams (array)
                    + (object)
                        + type: `team` (string)
                        + id: `6dd0069e-45da-0ec4-911a-afb351d968cd`


### users.info [POST /users.info]

Get details for a single user.

+ Request (application/json)

    + Attributes (object)
        + id: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5` (string, required)
        + includes: `external_rate` (string, optional) - when used, the response will include `external_rate`

+ Response 200 (application/json)

    + Attributes
        + data (object)
            + id: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5` (string)
            + account (object)
                + type: `account` (string)
                + id: `0fc55513-7f68-4865-aba0-de5da9e4e43d` (string)
            + first_name: `John` (string)
            + last_name: `Smith` (string)
            + email: `john@teamleader.eu` (string)
            + telephones (array[Telephone])
            + language: `nl-BE` (enum)
                + Members
                    + da-DK
                    + de-DE
                    + en-GB
                    + es-ES
                    + fi-FI
                    + fr-FR
                    + it-IT
                    + nb-NO
                    + nl-BE
                    + nl-NL
                    + pl-PL
                    + pt-PT
                    + sv-SE
                    + tr-TR
            + function: `Sales` (string)
            + time_zone: `Europe/Brussels` (string)
            + status: `active` (enum)
                + Members
                    + active
                    + deactivated
            + teams (array)
                + (object)
                    + type: `team` (string)
                    + id: `6dd0069e-45da-0ec4-911a-afb351d968cd`
            + `external_rate` (Money, nullable) - Only included with request parameter `includes=external_rate`


### users.listDaysOff [POST /users.listDaysOff]

Returns information about days off of a given user.

+ Request (application/json)
    + Attributes (object)
        + id: `87982c96-f2fe-4b05-838c-ff42c0525758` (string, required)
        + filter (object, optional)
            + `starts_after`: `2023-10-01` (string, optional) - Start of the period for which to return days off.
            + `ends_before`: `2023-10-30` (string, optional) - End of the period for which to return days off.
        + page (Page, optional)

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + `id`: `f611da79-90c2-02b1-b819-a810e0c77291` (string)
                + `starts_at`: `2023-10-01T09:00:00+01:00` (string)
                + `ends_at`: `2023-10-20T18:00:00+01:00` (string)
                + user (object)
                    + `type`: `user` (enum[string])
                        + Members
                            + `user`
                    + `id`: `b5094b3f-bb7a-0391-b01b-e709773f3509` (string)
                + leave_type (object)
                    + `type`: `dayOffType` (enum[string])
                        + Members
                            + `dayOffType`
                    + `id`: `f68b123c-4c36-0f5c-ac16-11f498e5dc01` (string)
                + `status`: `approved` (enum)
                    + Members
                        + `approved`
                        + `not_approved`
                        + `pending`
        + meta (object) - Only included with request parameter `includes=pagination`
            + page (Pagination)
            + matches: `12` (number)

### users.getWeekSchedule [POST /users.getWeekSchedule]

Returns information about week schedule of a user. Only available with the *Weekly working schedule* feature.

+ Request (application/json)
    + Attributes (object)
        + id: `87982c96-f2fe-4b05-838c-ff42c0525758` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (object)
            + periods (array)
                + (object)
                    + `type`: `working_hours` (enum[string])
                        + Members
                            + `working_hours`
                            + `lunch_break`
                    + `start` (object)
                        + `day`:  `monday` (Weekday)
                        + `time`: `09:00` (string) - The time of day in 24-hour hh:mm format. The time will be reported in the user's time zone.
                    + `end` (object)
                        + `day`:  `monday` (Weekday)
                        + `time`: `17:00` (string) - The time of day in 24-hour hh:mm format. The time will be reported in the user's time zone.

## Teams [/teams]

*Required scopes: `users`*

### teams.list [POST /teams.list]

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `92296ad0-2d61-4179-b174-9f354ca2157f`,`53635682-c382-4fbf-9fd9-9506ca4fbcdd` (array[string], optional)
            + term: `Designers` (string, optional) - Filters on name
            + team_lead_id: `6a9106c3-ed2a-46a2-a919-eb3d41165dd2` (string) - Filters on teams for which a user is team lead for
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + name
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `name`
                    + order: `asc`

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + id: `4b5291aa-2d78-09d2-882c-6c1483f00d88` (string)
                + name: `Designers` (string)
                + `team_lead` (User, nullable) - If the team lead is deactivated or deleted, null is returned
                + members (array[User])

## Custom Fields [/customFieldDefinitions]

Custom fields are used to add additional data/properties to entities within Teamleader.

### customFieldDefinitions.list [POST /customFieldDefinitions.list]

Get a list of all the definitions of custom fields.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `9c64570b-4ec1-4e03-9662-af904f78f7fa`,`aa6d2560-63f9-4b2f-bf96-823dc7c34df7` (array[string], optional)
            + context (enum, optional) - Filters on context
                + Members
                    + contact
                    + company
                    + deal
                    + project
                    + milestone
                    + product
                    + invoice
                    + subscription
                    + ticket
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + label
                        + context
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `label`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `74855f4a-2b61-429c-81d8-c79ad3675a76` (string)
                + context: `contact` (enum)
                    + Members
                        + contact
                        + company
                        + deal
                        + project
                        + milestone
                        + product
                        + invoice
                        + subscription
                        + ticket
                + type (enum)
                    + Members
                        + single_line - Single line text
                        + multi_line - Multiline text
                        + single_select - Single selection - has configuration
                        + multi_select - Multiple selection - has configuration
                        + date - Date
                        + money - Money
                        + auto_increment - Automatically incrementing field
                        + integer - Integer
                        + number - Number
                        + boolean - Yes/No
                        + email - Email address
                        + telephone - Phone number
                        + url - URL
                        + company - Company
                        + contact - Contact
                        + product - Product
                        + user - User
                + label (string)
                + group (string)
                + required: false (boolean)
                + configuration (object, optional)
                    + options (array, optional) - Only returned for `single_select` and `multi_select` types
                        + (object)
                            + id: `179e1564-493b-4305-8c54-a34fc80920fc` (string)
                            + value: `foo` (string)
                    + extra_option_allowed: true (boolean)

### customFieldDefinitions.info [POST /customFieldDefinitions.info]

Get info about a specific custom field definition.

+ Request (application/json)

    + Attributes (object)
        + id: `9c64570b-4ec1-4e03-9662-af904f78f7fa` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `57e851e2-3d3b-4523-82f8-fe77df5a5d6c` (string)
            + context: `contact` (enum)
                + Members
                    + contact
                    + company
                    + deal
                    + project
                    + milestone
                    + product
                    + invoice
                    + subscription
                    + ticket
            + type (enum)
                + Members
                    + single_line - Single line text
                    + multi_line - Multiline text
                    + single_select - Single selection - has configuration
                    + multi_select - Multiple selection - has configuration
                    + date - Date
                    + money - Money
                    + auto_increment - Automatically incrementing field
                    + integer - Integer
                    + number - Number
                    + boolean - Yes/No
                    + email - Email address
                    + telephone - Phone number
                    + url - URL
                    + company - Company
                    + contact - Contact
                    + product - Product
                    + user - User
            + label (string)
            + group (string)
            + required: false (boolean)
            + configuration (object, optional)
                + options (array, optional) - Only returned for `single_select` and `multi_select` types
                    + (object)
                        + id: `179e1564-493b-4305-8c54-a34fc80920fc` (string)
                        + value: `foo` (string)
                + extra_option_allowed: true (boolean)

## Work Types [/workTypes]

Work types define the type of work for events or time tracking. Hourly rates can be added to work types, so that the work can be billed to a customer.

### workTypes.list [POST /workTypes.list]

Get a list of all work types, sorted alphabetically (on their name).

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `6e342192-76d4-4b26-b1d7-e24df46bf603`,`1652ab6f-ad24-4f5c-a2fc-c6a30693a930` (array[string], optional)
            + term: `design` (string, optional) - Searches in the work type name only
        + page (Page, optional)
        + sort (array, optional)
            + Default
                + (object)
                    + field: `name`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `811a5825-96f4-4318-83c3-2840935c6003` (string)
                + name: `Planning` (string)

## Document Templates [/documentTemplates]

### documentTemplates.list [POST /documentTemplates.list]

Get a list of all document templates.

+ Request (application/json;charset=utf-8)

    + Attributes (object)
        + filter (object, required)
            + department_id: `a344c251-2494-0013-b433-ccee8e8435e5` (string, required)
            + document_type: `invoice` (enum[string], required)
                + Members
                    + delivery_note
                    + invoice
                    + order
                    + order_confirmation
                    + quotation
                    + timetracking_report
                    + workorder
            + status (array[enum], optional) - Filters on status
                + Members
                    + active - Filters on active
                    + archived - Filters on archived

+ Response 200 (application/json;charset=utf-8)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `a344c251-2494-0013-b433-ccee8e8435e5` (string)
                + department (object)
                    + type: `department` (string)
                    + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string)
                + document_type: `invoice` (enum[string])
                    + Members
                        + delivery_note
                        + invoice
                        + order
                        + order_confirmation
                        + quotation
                        + timetracking_report
                        + workorder
                + is_default: true (boolean)
                + name: `new logo` (string)
                + status: `active` (enum[string])
                    + Members
                        + active
                        + archived

## Currencies [/currencies]

### currencies.exchangeRates [POST /currencies.exchangeRates]

Get a list of exchange rates for a provided currency.

+ Request (application/json)

    + Attributes (object)
        + base: `EUR` (Currency, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + code: `USD` (Currency)
                + symbol: `$` (string)
                + name: `US Dollar` (string)
                + exchange_rate: `1.1238` (number) - The exchange rate from the provided base currency to the listed currency

## Notes [/notes]

### notes.list [POST /notes.list]

Get a list of all notes.

+ Request (application/json;charset=utf-8)

    + Attributes (object)
        + filter (object, required)
            + subject (object, required)
                + type: `contact` (enum[string], required)
                    + Members
                        + `company`
                        + `contact`
                        + `creditNote`
                        + `deal`
                        + `invoice`
                        + `nextgenProject`
                        + `product`
                        + `project`
                        + `quotation`
                        + `subscription`
                + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string, required)
        + page (Page, optional)

+ Response 200 (application/json;charset=utf-8)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `a344c251-2494-0013-b433-ccee8e8435e5` (string)
                + content: `new note content` (string)
                + subject (object)
                    + type: `contact` (enum[string])
                        + Members
                            + `company`
                            + `contact`
                            + `creditNote`
                            + `deal`
                            + `invoice`
                            + `nextgenProject`
                            + `product`
                            + `project`
                            + `quotation`
                            + `subscription`
                    + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string)
                + added_at: `2016-01-01T00:00:00+00:00` (string)

### notes.create [POST /notes.create]

Create a new note.

+ Request (application/json)
    + Attributes (object)
        + subject (object, required)
            + type: `contact` (NoteSubjectTypes, required)
            + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string, required)
        + content: `new note content` (string, required)
        + notify (array, optional)
            + (object)
                + type: `user` (enum, required)
                    + Members
                        + `user`
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `note` (string)
            + id: `ee94b4c0-5786-0517-9d26-8dd1e6406f20` (string)

### notes.update [POST /notes.update]

Update an existing note.

+ Request (application/json)
    + Attributes (object)
        + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string, required)
        + content: `new note content` (string, optional)

+ Response 204

## Email Tracking [/emailTracking]

### emailTracking.list [POST /emailTracking.list]

Get a list of all email tracking.

+ Request (application/json;charset=utf-8)

    + Attributes (object)
        + filter (object, required)
            + subject (object, required)
                + type: `contact` (EmailTrackingSubjectTypes, required)
                + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string, required)
        + page (Page, optional)

+ Response 200 (application/json;charset=utf-8)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `a344c251-2494-0013-b433-ccee8e8435e5` (string)
                + title: `an email subject` (string)
                + content: `<p>the contents of the received email</p>` (string)
                + subject (object)
                    + type: `contact` (EmailTrackingSubjectTypes)
                    + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string)
                + added_at: `2016-01-01T00:00:00+00:00` (string)
                + attachments (array)
                    + (object)
                        + `type`: `file` (string)
                        + `id`: `0686d0da-1797-475b-ae94-27191b2eca4d` (string)

### emailTracking.create [POST /emailTracking.create]

Create a new email tracking.

+ Request (application/json)
    + Attributes (object)
        + subject (object, required)
            + type: `contact` (EmailTrackingSubjectTypes, required)
            + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string, required)
        + title: `an email subject` (string, optional)
        + content: `<p>the contents of the received email</p>` (string, required)
        + `attachments`: `4f4288b2-c21b-4dac-87f6-a97511309079` (array[string], optional) - All files must have the same subject as the email tracking subject

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `emailTracking` (string)
            + id: `91e99ae3-16f9-01d7-9046-9a501cb2155f` (string)

## Closing Days [/closingDays]

### closingDays.list [POST /closingDays.list]

Returns information about closing days of the account

+ Request (application/json)
    + Attributes (object)
        + filter (object, optional)
            + date_before: `2023-12-31` (string, optional) - Start of the period for which to return closing days. This includes closing days starting on the date provided.
            + date_after: `2023-12-01` (string, optional) - End of the period for which to return closing days. This includes closing days ending on the date provided.
        + page (Page, optional)

+ Response 200 (application/json)
    + Attributes (object)
        + `data` (array)
            + (object)
                + `id`: `05676ac4-c61d-42bf-a3ea-a420fc1ec017` (string)
                + `date`: `2023-12-21` (string)
        + meta (object) - Only included with request parameter `includes=pagination`
            + page (Pagination)
            + matches: `12` (number)

### closingDays.add [POST /closingDays.add]

Adds a closing day for the account.

+ Request (application/json)
    + Attributes (object)
        + `day`: `2024-02-01` (string, required)

+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
            + type: `closingDay` (string)
            + id: `eb264fd0-0e5c-0dbf-ae1e-49e7d6a8e6b8` (string, required)

### closingDays.delete [POST /closingDays.delete]

Removes a closing day for the account.

+ Request (application/json)
    + Attributes (object)
        + id: `eb264fd0-0e5c-0dbf-ae1e-49e7d6a8e6b8` (string, required)

+ Response 204

## Day Off Types [/dayOffTypes]

### dayOffTypes.list [POST /dayOffTypes.list]

Returns a list of day off types for the account

+ Request (application/json)

+ Response 200 (application/json)
    + Attributes (object)
        + `data` (array)
            + (object)
                + `id`: `39263c14-9c16-022d-8513-60cf722ab088` (string)
                + `name`: `Sick leave` (string)

### dayOffTypes.create [POST /dayOffTypes.create]

Create a new day off type.

+ Request (application/json)
    + Attributes (object)
        + name: `day off type` (string, required)
        + color: `#00B2B2` (string, nullable, optional)
        + date_validity (object, nullable, optional)
            + from: `2024-04-04` (string, required)
            + unit: `2025-05-05` (string, required)


+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
            + type: `dayOffType` (string)
            + id: `cf307a90-d778-003c-b820-ab8415d1a524` (string)

### dayOffTypes.update [POST /dayOffTypes.update]

Update a day off type.

+ Request (application/json)
    + Attributes (object)
        + `id`: `1b7cece0-288c-0bbe-b916-5a315fbe9fe2` (string, required)
        + name: `day off type` (string, optional)
        + color: `#00B2B2` (string, optional)
        + date_validity (object, nullable, optional)
            + from: `2024-04-04` (string, required)
            + unit: `2025-05-05` (string, required)

+ Response 204 (application/json)

### dayOffTypes.delete [POST /dayOffTypes.delete]

Delete a day off type.

+ Request (application/json)
    + Attributes (object)
        + `id`: `1b7cece0-288c-0bbe-b916-5a315fbe9fe2` (string, required)

+ Response 204

## Days Off [/daysOff]

### daysOff.import [POST /daysOff.import]

Imports a list of days off for the given user.

+ Request (application/json)
    + Attributes (object)
        + `user_id`: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required) - The id of the user that the days off belong to.
        + `leave_type_id`: `0f517e20-2e76-4684-8d6c-3334f6d7148c` (string, required) - The id of the leave type that is associated with the given days off.
        + `days` (array, required) - At least one day must be present
            + (object)
                + `starts_at`: `2024-02-01T08:00:00+00:00` (string, required)
                + `ends_at`: `2024-02-01T18:00:00+00:00` (string, required)

+ Response 201 (application/json)

### daysOff.bulkDelete [POST /daysOff.bulkDelete]

Deletes a list of days off for the given user.

+ Request (application/json)
    + Attributes (object)
        + `user_id`: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required) - The id of the user that the days off belong to.
        + `ids`: `0a481ce9-0d2a-0913-9439-0fd8b469b566`, `5050789e-4385-02f6-bd3c-d051cc12f5cf`  (array[string]) - At least one day off id must be present.

+ Response 204 (application/json)

# Group CRM

## Contacts [/contacts]

Contacts are physical entities who are added to your CRM database. Contacts might be linked to one or more companies.

*Required scopes: `contacts`*

### contacts.list [POST /contacts.list]

Get a list of contacts.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + email (object, optional)
                + type: `primary` (enum, required)
                    + Members
                         + primary
                + email: `info@piedpiper.eu` (string, required)
            + ids: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5`,`f8a57a6f-dd1e-41a3-b8d3-428663f1d09e` (array[string], optional)
            + company_id: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5` (string, optional)
            + term: `James` (string, optional) - Filters on first_name, last_name, email and telephone
            + updated_since: `2016-02-04T16:44:33+00:00` (string, optional)
            + tags: `expo`,`prospect` (array[string], optional) - Filters on contacts coupled to all given tags
            + status: `active` (enum, optional)
                + Members
                    + active
                    + deactivated
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + added_at - Sorts on added_at
                        + name - Sorts alphabetically on last_name and first_name
                        + updated_at - Sorts on updated_at
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `name`
                    + order: `asc`
        + includes: `custom_fields` (string, optional) - Comma-separated list of optional includes

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `2a39e420-3ba3-4384-8024-fa702ef99c9f` (string)
                + first_name: `Erlich` (string)
                + last_name: `Bachman` (string)
                + status: `active` (enum[string])
                    + Members
                        + `active`
                        + `deactivated`
                + salutation: `Mr` (string)
                + emails (array)
                    + (object)
                        + type: `primary` (enum)
                            + Members
                                + primary
                        + email: `info@piedpiper.eu` (string)
                + telephones (array[Telephone])
                + website: `https://piedpiper.com` (string)
                + primary_address (AddressResponse)
                + gender: `unknown` (enum, nullable)
                    + Members
                        + female
                        + male
                        + non_binary
                        + prefers_not_to_say
                        + unknown
                + birthdate: `1987-04-25` (string)
                + iban: `BE12123412341234` (string)
                + bic: `BICBANK` (string)
                + national_identification_number: `86792345-L` (string)
                + language: `en` (string)
                + payment_term (PaymentTerm, nullable)
                + invoicing_preferences (object)
                    + electronic_invoicing_address (string, nullable)
                + tags: prospect, expo (array[string])
                + added_at: `2016-02-04T16:44:33+00:00` (string)
                + updated_at: `2016-02-05T16:44:33+00:00` (string)
                + `web_url`: `https://focus.teamleader.eu/contact_detail.php?id=2a39e420-3ba3-4384-8024-fa702ef99c9f` (string)
                + `custom_fields` (array[CustomField]) - Only included with request parameter `includes=custom_fields`

### contacts.info [POST /contacts.info]

Get details for a single contact.

+ Request (application/json)

    + Attributes (object)
        + id: `cde0bc5f-8602-4e12-b5d3-f03436b54c0d` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `cde0bc5f-8602-4e12-b5d3-f03436b54c0d` (string)
            + first_name: `Erlich` (string)
            + last_name: `Bachman` (string)
            + status: `active` (enum[string])
                    + Members
                        + `active`
                        + `deactivated`
            + salutation: `Mr` (string)
            + vat_number: `BE0899623034` (string, nullable)
            + emails (array)
                + (object)
                    + type: `primary` (enum)
                        + Members
                            + primary
                    + email: `info@piedpiper.eu` (string)
            + telephones (array[Telephone])
            + website: `https://piedpiper.com` (string)
            + addresses (array)
                + (object)
                    + type: `invoicing` (enum)
                        + Members
                            + primary
                            + invoicing
                            + delivery
                            + visiting
                    + address (AddressWithAddresseeResponse) - Primary addresses can not contain an addressee
            + gender: `unknown` (enum, nullable)
                + Members
                    + female
                    + male
                    + non_binary
                    + prefers_not_to_say
                    + unknown
            + birthdate: `1987-04-25` (string)
            + iban: `BE12123412341234` (string)
            + bic: `BICBANK` (string)
            + national_identification_number: `00051730-A` (string)
            + companies (array)
                + (object)
                    + position: `Developer` (string)
                    + secondary_position: `Technical lead` (string)
                    + division: 'Engineering' (string)
                    + decision_maker: true (boolean)
                    + company (object)
                        + type: `company` (string)
                        + id: `40157f9d-1322-4f2e-b245-188efdc52cc2` (string)
            + language: `en` (string)
            + payment_term (PaymentTerm, nullable)
            + invoicing_preferences (object)
                + electronic_invoicing_address (string, nullable)
            + remarks: `First contact at expo` (string) - Uses Markdown formatting
            + tags: prospect, expo (array[string])
            + custom_fields (array[CustomField])
            + marketing_mails_consent: false (boolean)
            + added_at: `2016-02-04T16:44:33+00:00` (string)
            + updated_at: `2016-02-05T16:44:33+00:00` (string)
            + `web_url`: `https://focus.teamleader.eu/contact_detail.php?id=cde0bc5f-8602-4e12-b5d3-f03436b54c0d` (string)

### contacts.add [POST /contacts.add]

Add a new contact.

+ Request (application/json)

    + Attributes (object)
        + first_name: `John` (string, optional)
        + last_name: `Smith` (string, required)
        + emails (array, optional)
            + (object)
                + type: `primary` (enum, required)
                    + Members
                        + primary
                + email: `info@piedpiper.eu` (string, required)
        + salutation: `Mr` (string, optional)
        + telephones (array[Telephone], optional)
        + website: `http://example.com` (string, optional)
        + addresses (array, optional)
            + (object)
                + type: `invoicing` (enum, required)
                    + Members
                        + primary
                        + invoicing
                        + delivery
                        + visiting
                + address (AddressWithAddresseeRequest, required) - Primary addresses can not contain an addressee
        + language: `en` (string, optional)
        + gender: `unknown` (enum, optional, nullable)
            + Members
                + female
                + male
                + non_binary
                + prefers_not_to_say
                + unknown
        + birthdate: `1989-08-19` (string, optional)
        + iban: `BE12123412341234` (string, optional)
        + bic: `BICBANK` (string, optional)
        + national_identification_number: `01234567-X` (string)
        + remarks: `Met at expo` (string, optional) - Uses Markdown formatting
        + tags: prospect, expo (array[string], optional)
        + custom_fields (array[CustomFieldValue], optional)
        + marketing_mails_consent: false (boolean, optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `contact` (string)
            + id: `7c1d8672-f502-4333-9ea4-7a45add15115` (string)

### contacts.update [POST /contacts.update]

Update a contact.

+ Request (application/json)

    + Attributes (object)
        + id: `76c9d03c-ec5c-4b21-9fc6-7ffee488b12d` (string, required)
        + first_name: `John` (string, optional, nullable)
        + last_name: `Smith` (string, optional)
        + salutation: `Mr` (string, optional, nullable)
        + emails (array, optional)
            + (object)
                + type: `primary` (enum, required)
                    + Members
                        + primary
                + email: `info@piedpiper.eu` (string, required, nullable)
        + telephones (array[Telephone], optional, nullable)
        + website: `http://example.com` (string, optional, nullable)
        + addresses (array, optional)
            + (object)
                + type: `invoicing` (enum, required)
                    + Members
                        + primary
                        + invoicing
                        + delivery
                        + visiting
                + address (AddressWithAddresseeRequest, required) - Primary addresses can not contain an addressee
        + language: `en` (string, optional)
        + gender: `unknown` (enum, optional, nullable)
            + Members
                + female
                + male
                + non_binary
                + prefers_not_to_say
                + unknown
        + birthdate: `1989-08-19` (string, optional, nullable)
        + iban: `BE12123412341234` (string, optional, nullable)
        + bic: `BICBANK` (string, optional, nullable)
        + national_identification_number: `19346758-T` (string)
        + remarks: `Met at expo` (string, optional, nullable) - Uses Markdown formatting
        + tags: prospect, expo (array[string], optional) - This will overwrite existing tags
        + custom_fields (array[CustomFieldValue], optional)
        + marketing_mails_consent: false (boolean, optional)

+ Response 204

### contacts.delete [POST /contacts.delete]

Delete a contact.

+ Request (application/json)

    + Attributes (object)
        + id: `4e235f27-0af0-40e5-82f3-d32d0aa9edb3` (string, required)

+ Response 204

### contacts.tag [POST /contacts.tag]

Add a new or existing tag to a contact.

+ Request (application/json)

    + Attributes (object)
        + id: `cadd94ba-a41e-4eb4-a46e-39a7f6f96070` (string, required)
        + tags: prospect, expo (array[string], required)

+ Response 204

### contacts.untag [POST /contacts.untag]

Remove a tag from a contact.

+ Request (application/json)

    + Attributes (object)
        + id: `518d2e5e-99bc-4c66-8509-78e6820a1418` (string, required)
        + tags: prospect, expo (array[string], required)

+ Response 204

### contacts.linkToCompany [POST /contacts.linkToCompany]

Link a contact to a company.

+ Request (application/json)

    + Attributes (object)
        + id: `75596038-b9c8-4a37-969d-61059e300a28` (string, required)
        + company_id: `4da20f00-0628-4336-b885-aa90e580dd85` (string, required)
        + position: `CEO` (string, optional)
        + decision_maker: true (boolean, optional)

+ Response 204

### contacts.unlinkFromCompany [POST /contacts.unlinkFromCompany]

Unlink a contact from a company.

+ Request (application/json)

    + Attributes (object)
        + id: `b4b3160a-b55e-4033-bdae-25b6d22949b4` (string, required)
        + company_id: `3f1c8650-4292-4187-bb02-4aa00bbe9632` (string, required)

+ Response 204

### contacts.updateCompanyLink [POST /contacts.updateCompanyLink]

Update contact to company link.

+ Request (application/json)

    + Attributes (object)
        + id: `75596038-b9c8-4a37-969d-61059e300a28` (string, required)
        + company_id: `4da20f00-0628-4336-b885-aa90e580dd85` (string, required)
        + position: `CEO` (string, optional)
        + decision_maker: true (boolean, optional)

+ Response 204

## Companies [/companies]

Companies are legal entities, usually linked to a VAT and/or local business number.

*Required scopes: `companies`*

### companies.list [POST /companies.list]

Get a list of companies.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + email (object, optional)
                + type: `primary` (enum, required)
                    + Members
                         + primary
                + email: `info@piedpiper.eu` (string, required)
            + ids: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5`,`f8a57a6f-dd1e-41a3-b8d3-428663f1d09e` (array[string], optional)
            + term: `Acme` (string, optional) - Filters on name, vat number, emails and telephones
            + updated_since: `2016-02-04T16:44:33+00:00` (string, optional)
            + tags: `expo`,`lead` (array[string], optional) - Filters on tag names
            + vat_number: `BE 0899.623.035` (string, optional)
            + status: `active` (enum, optional)
                + Members
                    + active
                    + deactivated
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + name
                        + added_at
                        + updated_at
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `name`
                    + order: `asc`
        + includes: `custom_fields` (string, optional) - Comma-separated list of optional includes

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `96a38bbf-24ed-4083-8a5c-20db92aa471e` (string)
                + name: `Pied Piper` (string)
                + status: `active` (enum[string])
                    + Members
                        + `active`
                        + `deactivated`
                + business_type (object)
                    + type: `businessType` (string)
                    + id: `fd48d4a3-b9dc-4eac-8071-5889c9f21e5d` (string)
                + vat_number: `BE0899623035` (string)
                + national_identification_number: `63326426` (string)
                + emails (array)
                    + (object)
                        + type: `primary` (enum)
                            + Members
                                + primary
                                + invoicing
                        + email: `info@piedpiper.eu` (string)
                + telephones (array[CompanyTelephone])
                + website: `https://piedpiper.com` (string)
                + primary_address (AddressResponse)
                + iban: `BE12123412341234` (string)
                + bic: `BICBANK` (string)
                + language: `nl` (string)
                + preferred_currency: `EUR` (string, nullable)
                + payment_term (PaymentTerm, nullable)
                + invoicing_preferences (object)
                    + electronic_invoicing_address (string, nullable)
                + responsible_user (object)
                    + type: `user` (string)
                    + id: `9b99d8f8-183b-4c7b-8354-9b98b47a192e` (string)
                + added_at: `2016-02-04T16:44:33+00:00` (string)
                + updated_at: `2016-02-05T16:44:33+00:00` (string)
                + `web_url`: `https://focus.teamleader.eu/company_detail.php?id=96a38bbf-24ed-4083-8a5c-20db92aa471e` (string)
                + tags: prospect, expo (array[string])
                + `custom_fields` (array[CustomField]) - Only included with request parameter `includes=custom_fields`

### companies.info [POST /companies.info]

Get details for a single company.

+ Request (application/json)

    + Attributes (object)
        + id: `e8d31ae7-8258-4fcd-9b2d-78f41b0aa5d5` (string, required)
        + includes: `related_companies,related_contacts` (string, optional) - when used, the response will include `related_companies` and/or `related_contacts`

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `e8d31ae7-8258-4fcd-9b2d-78f41b0aa5d5` (string)
            + name: `Pied Piper` (string)
            + status: `active` (enum[string])
                    + Members
                        + `active`
                        + `deactivated`
            + business_type (object)
                + type: `businessType` (string)
                + id: `fd48d4a3-b9dc-4eac-8071-5889c9f21e5d` (string)
            + vat_number: `BE0899623035` (string)
            + national_identification_number: `63326426` (string)
            + emails (array)
                + (object)
                    + type: `primary` (enum)
                        + Members
                            + primary
                            + invoicing
                    + email: `info@piedpiper.eu` (string)
            + telephones (array[CompanyTelephone])
            + website: `https://piedpiper.com` (string)
            + addresses (array)
                + (object)
                    + type: `invoicing` (enum)
                        + Members
                            + primary
                            + invoicing
                            + delivery
                            + visiting
                    + address (AddressWithAddresseeResponse) - Primary addresses can not contain an addressee
            + iban: `BE12123412341234` (string)
            + bic: `BICBANK` (string)
            + language: `nl` (string)
            + preferred_currency: `EUR` (string, nullable)
            + payment_term (PaymentTerm, nullable)
            + invoicing_preferences (object)
                + electronic_invoicing_address (string, nullable)
            + responsible_user (object)
                + type: `user`
                + id: `7ba98a20-5e2b-4b46-81b9-a3364432d4f0` (string)
            + remarks: `First contact at expo` (string) - Uses Markdown formatting
            + added_at: `2016-02-04T16:44:33+00:00` (string)
            + updated_at: `2016-02-05T16:44:33+00:00` (string)
            + `web_url`: `https://focus.teamleader.eu/company_detail.php?id=e8d31ae7-8258-4fcd-9b2d-78f41b0aa5d5` (string)
            + tags: prospect, expo (array[string])
            + custom_fields (array[CustomField])
            + marketing_mails_consent: false (boolean)
            + `related_companies` (array) - Only included with request parameter `includes=related_companies`
                + (object)
                    + type: `company` (string)
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
            + `related_contacts` (array) - Only included with request parameter `includes=related_contacts`
                + (object)
                    + type: `contact` (string)
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                    + position: `Developer` (string, nullable)
                    + secondary_position: `Technical lead` (string, nullable)
                    + division: `Engineering` (string, nullable)
                    + is_decision_maker: false (boolean)

### companies.add [POST /companies.add]

Add a new company.

+ Request (application/json)

    + Attributes (object)
        + name: `Pied Piper` (string, required)
        + business_type_id: `fd48d4a3-b9dc-4eac-8071-5889c9f21e5d` (string, optional)
        + vat_number: `BE0899623035` (string, optional)
        + national_identification_number: `63326426` (string, optional)
        + emails (array, optional)
            + (object)
                + type: `primary` (enum, required)
                    + Members
                        + primary
                        + invoicing
                + email: `info@piedpiper.eu` (string, required)
        + telephones (array[CompanyTelephone], optional)
        + website: `http://example.com` (string, optional)
        + addresses (array, optional)
            + (object)
                + type: `invoicing` (enum, required)
                    + Members
                        + primary
                        + invoicing
                        + delivery
                        + visiting
                + address (AddressWithAddresseeRequest, required) - Primary addresses can not contain an addressee
        + iban: `BE12123412341234` (string)
        + bic: `BICBANK` (string, optional)
        + language: `en` (string, optional)
        + responsible_user_id: `2b12bd5d-d2d9-43ac-8755-36a1e00bd67f` (string, optional)
        + remarks: `Met at expo` (string, optional) - Uses Markdown formatting
        + tags: prospect, expo (array[string], optional)
        + custom_fields (array[CustomFieldValue], optional)
        + marketing_mails_consent: false (boolean, optional)
        + preferred_currency: `EUR` (Currency, optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `company` (string)
            + id: `4784189d-610b-4488-b3a5-5f324f752417` (string)

### companies.update [POST /companies.update]

Update a company.

+ Request (application/json)

    + Attributes (object)
        + id: `4784189d-610b-4488-b3a5-5f324f752417` (string, required)
        + name: `Pied Piper` (string, optional)
        + business_type_id: `fd48d4a3-b9dc-4eac-8071-5889c9f21e5d` (string, optional, nullable)
        + vat_number: `BE0899623035` (string, optional, nullable)
        + national_identification_number: `63326426` (string, optional, nullable)
        + emails (array, optional)
            + (object)
                + type: `primary` (enum, required)
                    + Members
                        + primary
                        + invoicing
                + email: `info@piedpiper.eu` (string, required)
        + telephones (array[CompanyTelephone], optional)
        + website: `http://example.com` (string, optional)
        + addresses (array, optional)
            + (object)
                + type: `invoicing` (enum, required)
                    + Members
                        + primary
                        + invoicing
                        + delivery
                        + visiting
                + address (AddressWithAddresseeRequest, required) - Primary addresses can not contain an addressee
        + iban: `BE12123412341234` (string, optional, nullable)
        + bic: `BICBANK` (string, optional, nullable)
        + language: `en` (string, optional, nullable)
        + responsible_user_id: `0ea94804-401d-4dbd-a577-c2d60998f798` (string, optional, nullable)
        + remarks: `Met at expo` (string, optional, nullable) - Uses Markdown formatting
        + tags: prospect, expo (array[string], optional) - This will overwrite existing tags
        + custom_fields (array[CustomFieldValue], optional)
        + marketing_mails_consent: false (boolean, optional)
        + preferred_currency: `EUR` (Currency, optional, nullable)

+ Response 204

### companies.delete [POST /companies.delete]

Delete a company.

+ Request (application/json)

    + Attributes (object)
        + id: `f3d67f3e-b8a9-45e8-99b1-17a3b14de8a6` (string, required)

+ Response 204

### companies.tag [POST /companies.tag]

Add a new or existing tag to a company.

+ Request (application/json)

    + Attributes (object)
        + id: `cadd94ba-a41e-4eb4-a46e-39a7f6f96070` (string, required)
        + tags: prospect, expo (array[string], required)

+ Response 204

### companies.untag [POST /companies.untag]

Remove a tag from a company.

+ Request (application/json)

    + Attributes (object)
        + id: `518d2e5e-99bc-4c66-8509-78e6820a1418` (string, required)
        + tags: prospect, expo (array[string], required)

+ Response 204

## Business Types [/businessTypes]

Each country has a specific set of business types or range of legal entities. You can specify the business type when adding or updating a company.

### businessTypes.list [POST /businessTypes.list]

Get the names of business types (legal structures) a company can have within a certain country, sorted alphabetically.

+ Request (application/json)

    + Attributes (object)
        + country: `BE` (string, optional)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `fd48d4a3-b9dc-4eac-8071-5889c9f21e5d` (string)
                + name: `VZW/ASBL` (string)
                + country: `BE` (string)

## Tags [/tags]

Tags are used to label contacts or companies, so that they can easily be filtered or grouped into segments.

### tags.list [POST /tags.list]

Get a list of tags.

+ Request (application/json)

    + Attributes (object)
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + tag
                + order (enum, optional)
                    + Members
                        + asc
            + Default
                + (object)
                    + field: `tag`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + tag: `campaign` (string)

## Addresses [/levelTwoAreas]

We provide a set of data which can be used to build addresses.

### levelTwoAreas.list [POST /levelTwoAreas.list]

Get a list of level two areas (which correspond to provinces, departments or states in most countries).

+ Request (application/json)

    + Attributes (object)
        + country: `BE` (string, required)
        + language: `nl` (string, optional) - if not passed, the name is returned in the primary language of the country

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `fd48d4a3-b9dc-4eac-8071-5889c9f21e5d` (string)
                + name: `West-Vlaanderen` (string)
                + country: `BE` (string)

# Group Deals

## Deals [/deals]

Deals are sale opportunities, which need to be followed up by their responsible user. A deal can move through specific deal phases, and be marked as won or lost.

*Required scopes: `deals`*

### deals.list [POST /deals.list]

Get a list of deals.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `3f507137-e599-41d4-8625-0e2adba0be4c`,`ae97f6d3-0bb4-43d3-b13d-f06069d07e98` (array[string], optional)
            + term: `Interesting deal` (string, optional) - Filters on the title, reference and customer's name
            + customer (object, optional)
                + type (enum, required)
                    + Members
                        + company
                        + contact
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
            + phase_id: `1758e847-cc1f-04ce-bd17-5a852e8c01b4` (string, optional)
            + estimated_closing_date: `2018-02-11` (string, optional, nullable)
            + estimated_closing_date_from: `2020-01-01` (string, optional) - This date is inclusive
            + estimated_closing_date_until: `2020-01-31` (string, optional) - This date is inclusive
            + One Of
                + responsible_user_id: `98b2863e-7b01-4232-82f5-ede1f0b9db22` (string, optional)
                + responsible_user_id: `98b2863e-7b01-4232-82f5-ede1f0b9db22`, `98b2863e-7b01-4232-82f5-ede1f0b9db24` (array[string], optional)
            + updated_since: `2018-02-11T16:45:30+00:00` (string, optional) - This date is inclusive
            + created_before: `2018-02-11T16:45:30+00:00` (string, optional) - This date is inclusive
            + status: `open`, `won`, `lost` (array[string], optional)
            + pipeline_ids: `41ec2e1b-46e4-053b-b310-39322c273811` (array[string], optional) - an array of pipeline ids
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + created_at
                        + weighted_value
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `created_at`
                    + order: `desc`
        + includes: `custom_fields` (string, optional) - Comma-separated list of optional includes

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `6e7fe84d-d4b3-4723-abae-9bc082d8f65a` (string)
                + title: `Interesting deal` (string)
                + summary: `Additional information` (string, nullable)
                + reference: `2017/2` (string)
                + status: `won` (enum)
                    + Members
                        + new
                        + open
                        + won
                        + lost
                + lead (object)
                    + customer (object)
                        + type: `company` (enum)
                            + Members
                                + contact
                                + company
                        + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
                    + contact_person (object)
                        + type: `contact` (string)
                        + id: `74c6769e-815a-4774-87d7-dfab9b1a0abb` (string)
                + department (object)
                    + type: `department`
                    + id: `33121d39-44e2-426a-92ef-62178edeec8a` (string)
                + estimated_value (Money)
                + estimated_closing_date: `2017-05-09` (string)
                + estimated_probability: `0.5` (number)
                + weighted_value (Money)
                + purchase_order_number: `000023` (string, nullable)
                + current_phase (object)
                    + type: `dealPhase`
                    + id: `521a331d-60d1-4920-bde3-ccd01d09f9f1` (string)
                + responsible_user (object)
                    + type: `user`
                    + id: `bac1c91b-bc86-489b-8590-9be9478f62bb` (string)
                + closed_at: `2017-05-09T11:31:30+00:00` (string)
                + source (object)
                    + type: `dealSource` (string)
                    + id: `52a4bbb2-d196-48d7-8e43-9ec2f44d06f9` (string)
                + lost_reason (object, nullable)
                    + reason (object, nullable)
                        + type: lostReason (string)
                        + id: `4e81f3c4-7dca-44cb-b126-6158bec392a2` (string)
                    + remark: `Too expensive` (string, nullable)
                + created_at: `2017-05-09T11:25:11+00:00` (string)
                + updated_at: `2017-05-09T11:30:58+00:00` (string)
                + `web_url`: `https://focus.teamleader.eu/sale_detail.php?id=6e7fe84d-d4b3-4723-abae-9bc082d8f65a` (string)
                + `custom_fields` (array[CustomField]) - Only included with request parameter `includes=custom_fields`
                + `currency_exchange_rate` (object)
                    + `from`: `USD` (Currency)
                    + `to`: `EUR` (Currency)
                    + `rate`: 1.1234 (number)
                + pipeline (object)
                    + type: `dealPipeline` (string)
                    + id: `4e81f3c4-7dca-44cb-b126-6158bec392a2` (string)

### deals.info [POST /deals.info]

Get details for a single deal.

+ Request (application/json)

    + Attributes (object)
        + id: `f6871b06-6513-4750-b5e6-ff3503b5a029` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `f6871b06-6513-4750-b5e6-ff3503b5a029` (string)
            + title: `Interesting deal` (string)
            + summary: `Additional information` (string, nullable)
            + reference: `2017/2` (string)
            + status: `won` (enum)
                + Members
                    + open
                    + won
                    + lost
            + lead (object)
                + customer (object)
                    + type: `company` (enum)
                        + Members
                            + contact
                            + company
                    + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
                + contact_person (object)
                    + type: `contact` (string)
                    + id: `74c6769e-815a-4774-87d7-dfab9b1a0abb` (string)
            + department (object)
                + type: `department`
                + id: `92247818-643e-4f5a-bf87-25cd908e8ad9` (string)
            + estimated_value (Money)
            + estimated_closing_date: `2017-05-09` (string)
            + estimated_probability: `0.5` (number)
            + weighted_value (Money)
            + purchase_order_number: `000023` (string, nullable)
            + current_phase (object)
                + type: dealPhase (string)
                + id: `676a6070-f7d3-43a6-bc08-cda0d32c27ab` (string)
            + responsible_user (object)
                + type: user (string)
                + id: `4e81f3c4-7dca-44cb-b126-6158bec392a2` (string)
            + closed_at: `2017-05-09T11:31:30+00:00` (string)
            + source (object)
                + type: `dealSource` (string)
                + id: `aba0ad66-bf59-49fa-b546-45dcbc5e7e6e` (string)
            + phase_history (array)
                + (object)
                    + phase (object)
                        + type: dealPhase (string)
                        + id: `d5a629f2-7b58-4748-aaca-acf9b6d62404` (string)
                    + started_at: `2017-05-01 12:00:00` (string)
                    + started_by (object)
                        + type: user (string)
                        + id: `4ec55a8c-2d80-472a-a9c2-5ff5ee7eac6a` (string)
            + quotations (array)
                + (object)
                    + id: `e2314517-3cab-4aa9-8471-450e73449041` (string)
                    + type: `quotation` (string)
            + lost_reason (object, nullable)
                + reason (object, nullable)
                    + type: lostReason (string)
                    + id: `4e81f3c4-7dca-44cb-b126-6158bec392a2` (string)
                + remark: `Too expensive` (string, nullable)
            + created_at: `2017-05-09T11:25:11+00:00` (string)
            + updated_at: `2017-05-09T11:30:58+00:00` (string)
            + `web_url`: `https://focus.teamleader.eu/sale_detail.php?id=f6871b06-6513-4750-b5e6-ff3503b5a029` (string)
            + custom_fields (array[CustomField])
            + `currency_exchange_rate` (object)
                + `from`: `USD` (Currency)
                + `to`: `EUR` (Currency)
                + `rate`: 1.1234 (number)
            + pipeline (object)
                + type: `dealPipeline` (string)
                + id: `4e81f3c4-7dca-44cb-b126-6158bec392a2` (string)

### deals.create [POST /deals.create]

Create a new deal for a customer.

+ Request (application/json)

    + Attributes (object)
        + lead (object, required)
            + customer (object, required)
                + type: `company` (enum, required)
                    + Members
                        + contact
                        + company
                + id: `09e5d75f-f817-4872-9723-57fbb8ff710d` (string, required)
            + contact_person_id: `b38ebb9b-6e46-4bf4-a1e2-af747d6b64ae` (string, optional)
        + title: `Interesting business deal` (string, required)
        + summary: `Additional information` (string, optional)
        + source_id: `b38ebb9b-6e46-4bf4-a1e2-af747d6b64ae` (string, optional)
        + department_id: `6a6343fc-fdd8-4bc0-aa69-3a004c710e87` (string, optional)
        + responsible_user_id: `98b2863e-7b01-4232-82f5-ede1f0b9db22` (string, optional)
        + phase_id: `060687bb-a742-4882-a538-199a5e5feb60` (string, optional)
        + estimated_value (Money, optional)
        + estimated_probability: `0.75` (number, optional) - A number between 0 and 1 (inclusive)
        + estimated_closing_date: `2017-05-09` (string, optional)
        + custom_fields (array[CustomFieldValue], optional)
        + `currency` (object, optional)
            + `code`: `EUR` (Currency, required)
            + `exchange_rate`: 1.1238 (number, required)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `deal` (string)
            + id: `65a35860-dcca-4850-9fd6-47ff08469e0c` (string)

### deals.update [POST /deals.update]

Update a deal.

+ Request (application/json)

    + Attributes (object)
        + id: `65a35860-dcca-4850-9fd6-47ff08469e0c` (string, required)
        + lead (object, optional)
            + customer (object, required)
                + type (enum, required)
                    + Members
                        + contact
                        + company
                + id: `09e5d75f-f817-4872-9723-57fbb8ff710d` (string, required)
            + contact_person_id: `b38ebb9b-6e46-4bf4-a1e2-af747d6b64ae` (string, optional)
        + title: `Interesting business deal` (string, optional)
        + summary: `Additional information` (string, optional, nullable)
        + source_id: `b38ebb9b-6e46-4bf4-a1e2-af747d6b64ae` (string, optional, nullable)
        + department_id: `6a6343fc-fdd8-4bc0-aa69-3a004c710e87` (string, optional, nullable)
        + responsible_user_id: `98b2863e-7b01-4232-82f5-ede1f0b9db22` (string, optional, nullable)
        + estimated_value (Money, optional, nullable)
        + estimated_probability: `0.75` (number, optional, nullable) - A number between 0 and 1 (inclusive)
        + estimated_closing_date: `2017-05-09` (string, optional, nullable)
        + custom_fields (array[CustomFieldValue], optional)
        + `currency` (object, optional)
            + `code`: `EUR` (Currency, required)
            + `exchange_rate`: 1.1238 (number, required)

+ Response 204

### deals.move [POST /deals.move]

Move the deal to a different phase.

+ Request (application/json)

    + Attributes (object)
        + id: `e88131bf-50c4-49d3-8ae3-47e5d9626bf6` (string, required)
        + phase_id: `8776abee-d856-43c6-b98d-9ffc912e8b0b` (string, required)

+ Response 204

### deals.win [POST /deals.win]

Mark a deal as won.

+ Request (application/json)

    + Attributes (object)
        + id: `e88131bf-50c4-49d3-8ae3-47e5d9626bf6` (string, required)

+ Response 204

### deals.lose [POST /deals.lose]

Mark a deal as lost.

+ Request (application/json)

    + Attributes (object)
        + id: `460df7b2-fe82-4c6c-b215-6d0a1bd3c742` (string, required)
        + reason_id: `da4c902f-2ae5-4c1f-be6f-b50308aabc5c` (string, optional)
        + extra_info: `Not ready for a change, decision postponed` (string, optional)

+ Response 204

### deals.delete [POST /deals.delete]

Delete a deal.

+ Request (application/json)

    + Attributes (object)
        + id: `4e235f27-0af0-40e5-82f3-d32d0aa9edb3` (string, required)

+ Response 204

### lostReasons.list [POST /lostReasons.list]

Get a list of lost reasons for deals.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `6fe903a7-1bf7-0f82-b917-c8b60aafbb63`,`b298edc3-a0cf-0f42-8413-f3063c7dc364` (array[string], optional)
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + name
                + order (enum, optional)
                    + Members
                        + asc
            + Default
                + (object)
                    + field: `name`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `6e7fe84d-d4b3-4723-abae-9bc082d8f65a` (string)
                + name: `Deal declined` (string)

## Deal Pipelines [/dealPipelines]

Each deal belongs to a specific pipeline, in which it goes through the different deal phases.

*Required scopes: `deals`*

### dealPipelines.list [POST /dealPipelines.list]

Get a list of all deal pipelines.

+ Request (application/json)
    + Attributes (object)
        + filter (object, optional)
            + `ids`: `46156648-87c6-478d-8aa7-1dc3a00dacab`, `46156648-87c6-478d-8aa7-1dc3a00daca4` (array[string])
            + status (array, optional)
                + (enum)
                    + Members
                        + open
                        + pending_deletion
        + page (Page, optional)

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + id: `f350e48a-fbc3-0a79-e62a-53aa1ae86d44` (string)
                + name: `Main Pipeline` (string)
        + meta (object)
            + `default`: `f350e48a-fbc3-0a79-e62a-53aa1ae86d44` (string)
            + `page` (Pagination) - Only included with request parameter `includes=pagination`
            + `matches`: `12` (number) - Only included with request parameter `includes=pagination`

### dealPipelines.create [POST /dealPipelines.create]

Create a new deal pipeline.

+ Request (application/json)

    + Attributes (object)
        + name: `Primary Pipeline` (string, required)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `dealPipeline` (string)
            + id: `f350e48a-fbc3-0a79-e62a-53aa1ae86d44` (string)

### dealPipelines.update [POST /dealPipelines.update]

Update a single deal pipeline.

+ Request (application/json)

    + Attributes (object)
        + id: `254dc5ee-f8de-0791-9e31-a4f7817e64d2` (string, required)
        + name: `Main Pipeline` (string, required)

+ Response 204

### dealPipelines.markAsDefault [POST /dealPipelines.markAsDefault]

Mark a pipeline as default.

+ Request (application/json)

    + Attributes (object)
        + id: `f350e48a-fbc3-0a79-e62a-53aa1ae86d44` (string, required)

+ Response 202 (application/json)

### dealPipelines.duplicate [POST /dealPipelines.duplicate]

Create a new deal pipeline by duplicating an existing one.

+ Request (application/json)

    + Attributes (object)
        + id: `f350e48a-fbc3-0a79-e62a-53aa1ae86d44` (string, required) - Id from source pipeline

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `dealPipeline` (string)
            + id: `5876126e-11c2-4731-b9e3-6e2fecd01d80` (string, required)

### dealPipelines.delete [POST /dealPipelines.delete]

Delete a deal pipeline.

+ Request (application/json)

    + Attributes (object)
        + id: `f350e48a-fbc3-0a79-e62a-53aa1ae86d44` (string, required)
        + migrate_phases (array, optional) - Array of phase ids to migrate deals to
            + (object)
                + `old_phase_id`: `57785244-0d45-0f01-9c18-5ce1cb68e4c1` (string, required)
                + `new_phase_id`: `29648aea-52f9-09f7-8e1e-cc5c08b4c742` (string, required)

+ Response 204 (application/json)

## Deal Phases [/dealPhases]

Deal phases are the different phases a deal typically goes through. A deal can be moved to either a next or previous phase. A deal can be marked as won or lost independently from the deal phase.

*Required scopes: `deals`*

### dealPhases.list [POST /dealPhases.list]

Get a list of all phases a deal can go through, sorted by their order in the flow.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `53a7e592-a136-4bae-ae15-517befd3d75d`,`bb50af79-55cd-4be0-8306-e9626c70a90f` (array[string], optional)
            + deal_pipeline_id: `53a7e592-a136-4bae-ae15-517befd3d75d` (string, optional)
        + page (Page, optional)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `21efc56e-1ba8-469d-926a-e89502591b47` (string)
                + name: `New` (string)
                + actions (array) - Only returned when user has access to planning and deal automation
                    + (enum)
                        + Members
                            + create_event
                            + create_call
                            + create_task
                + requires_attention_after (object) - Time period in this phase after which a deal requires attention
                    + amount: 7 (number)
                    + unit: `days` (enum[string])
                        + Members
                            + days
                            + weeks
                + probability: 0.75 (number)

### dealPhases.create [POST /dealPhases.create]

Create a new deal phase.

+ Request (application/json)

    + Attributes (object)
        + name: `Investigation` (string, required)
        + deal_pipeline_id: `f350e48a-fbc3-0a79-e62a-53aa1ae86d44` (string, required)
        + requires_attention_after (object, required) - Time period after which a deal requires attention
            + amount: 7 (number, required)
            + unit: `days` (enum[string], required)
                + Members
                   + days
                   + weeks
        + estimated_probability: `0.5` (number, optional)
        + follow_up_actions (array, optional)
            + (enum)
                + Members
                    + create_event
                    + create_call
                    + create_task

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `dealPhase` (string)
            + id: `22364cbf-971e-022c-811b-a76c28000257` (string)

### dealPhases.update [POST /dealPhases.update]

Update a deal phase.

+ Request (application/json)

    + Attributes (object)
        + id: `22364cbf-971e-022c-811b-a76c28000257` (string, required)
        + name: `Preparation` (string, optional)
        + requires_attention_after (object, required) - Time period after which a deal requires attention
            + amount: 7 (number, required)
            + unit: `days` (enum[string], required)
                + Members
                    + days
                    + weeks
        + estimated_probability: `0.8` (number, optional)
        + follow_up_actions (array, optional)
            + (enum)
                + Members
                    + create_event
                    + create_call
                    + create_task

+ Response 204

### dealPhases.duplicate [POST /dealPhases.duplicate]

Create a new deal phase by duplicating an existing one.

+ Request (application/json)

    + Attributes (object)
        + id: `22364cbf-971e-022c-811b-a76c28000257` (string, required) - Id from source phase

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `dealPhase` (string)
            + id: `eb264fd0-0e5c-0dbf-ae1e-49e7d6a8e6b8` (string, required)

### dealPhases.move [POST /dealPhases.move]

Move a phase to a new position in the pipeline.

+ Request (application/json)

    + Attributes (object)
        + id: `f350e48a-fbc3-0a79-e62a-53aa1ae86d44` (string, required)
        + after_phase_id: `22364cbf-971e-022c-811b-a76c28000257` (string, required)

+ Response 204

### dealPhases.delete [POST /dealPhases.delete]

Delete a phase.

+ Request (application/json)

    + Attributes (object)
        + id: `f350e48a-fbc3-0a79-e62a-53aa1ae86d44` (string, required)
        + new_phase_id: `29648aea-52f9-09f7-8e1e-cc5c08b4c742` (string, optional) - Phase to migrate deals to

+ Response 204 (application/json)

## Deal Sources [/dealSources]

Deal sources are used to track the origin of a deal.

*Required scopes: `deals`*

### dealSources.list [POST /dealSources.list]

Get a list of all deal sources, sorted alphabetically (on name)

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `4bd112da-8a39-47b9-b1e2-8ce339c241a3`,`94bd8c65-72ce-4a43-9cdf-9b75f1966010` (array[string], optional)
        + page (Page, optional)
        + sort (array, optional)
            + Default
                + (object)
                    + field: `name`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `b18c298b-0e6f-495d-8fcd-31dfecaea741` (string)
                + name: `Referral` (string)

## Quotations [/quotations]

A quotation is a sales offer for a specific customer. It is always attached to a deal. Quotations can be signed online via Cloudsign.

*Required scopes: `quotations`*

### quotations.list [POST /quotations.list]

Get a list of quotations.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `5b16f6ee-e302-0079-901b-50c26c4a55b1`, `2700006a-b351-070b-b311-fb45ed99abe2` (array[string], optional)
        + page (Page, optional)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `5b16f6ee-e302-0079-901b-50c26c4a55b1` (string)
                + deal (object)
                    + type: `deal` (string)
                    + id: `53474a7a-f9b2-4dd4-88a8-40ce773c7a64` (string)
                + currency_exchange_rate (object)
                    + from: `USD` (string)
                    + to: `EUR` (string)
                    + rate: 1.1234 (number)
                + total (object)
                    + tax_exclusive (Money)
                    + tax_inclusive (Money)
                    + taxes (array)
                        + (object)
                            + rate: 0.21 (number)
                            + taxable (Money)
                            + tax (Money)
                    + purchase_price (Money, nullable)
                + created_at: `2017-05-09T11:25:11+00:00` (string, nullable)
                + updated_at: `2017-05-09T11:30:58+00:00` (string, nullable)
                + status: `open` (enum)
                    + Members
                        + open
                        + accepted
                        + expired
                        + rejected
                        + closed
                + name: `Webdevelopment` (string)
                + expiry (object) - returned if user has access to quotation expiry and `includes=expiry` is requested
                    + expires_after: `2023-04-05` (string)
                    + action_after_expiry (enum[string])
                        + Members
                            + lock
                            + none

### quotations.info [POST /quotations.info]

Get a quotation

+ Request (application/json)

    + Attributes (object)
        + id: `e7a3fe2b-2c75-480f-87b9-121816b5257b` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `e7a3fe2b-2c75-480f-87b9-121816b5257b` (string)
            + deal (object)
                + type: `deal` (string)
                + id: `53474a7a-f9b2-4dd4-88a8-40ce773c7a64` (string)
            + grouped_lines (array)
                + (object)
                    + section (object)
                        + title (string)
                    + line_items (array)
                        + (object)
                            + product (object, nullable)
                                + type: `product` (string)
                                + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)
                            + quantity: 3 (number)
                            + description: `An awesome product` (string)
                            + extended_description: `Some more information about this awesome product` (string) - Uses Markdown formatting
                            + unit (object, nullable)
                                + type: `unitOfMeasure` (string)
                                + id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string)
                            + unit_price (object)
                                + Include Money
                                + tax: `excluding` (enum)
                                    + Members
                                        + excluding
                            + tax (object)
                                + type: `taxRate` (string)
                                + id: `e2314517-3cab-4aa9-8471-450e73449042`
                            + discount (object, nullable)
                                + type: `percentage` (enum)
                                    + Members
                                        + percentage
                                + value: 15.00 (number)
                            + purchase_price (Money, nullable)
                            + total
                                + tax_exclusive (Money)
                                + tax_exclusive_before_discount (Money)
                                + tax_inclusive (Money)
                                + tax_inclusive_before_discount (Money)
            + currency: `USD` (string)
            + currency_exchange_rate (object)
                + from: `USD` (string)
                + to: `EUR` (string)
                + rate: 1.1234 (number)
            + total (object)
                + tax_exclusive (Money)
                + tax_inclusive (Money)
                + taxes (array)
                    + (object)
                        + rate: 0.21 (number)
                        + taxable (Money)
                        + tax (Money)
                + purchase_price (Money, nullable)
            + discounts (array[CommercialDiscount])
            + created_at: `2017-05-09T11:25:11+00:00` (string, nullable)
            + updated_at: `2017-05-09T11:30:58+00:00` (string, nullable)
            + status: `open` (enum)
                + Members
                    + open
                    + accepted
                    + expired
                    + rejected
                    + closed
            + name: `Webdevelopment` (string)
            + document_template (object)
                + type: `documentTemplate` (string)
                + id: `179e1564-493b-4305-8c54-a34fc80920fc` (string)
            + expiry (object) - returned if user has access to quotation expiry and `includes=expiry` is requested
                + expires_after: `2023-04-05` (string)
                + action_after_expiry (enum[string])
                    + Members
                        + lock
                        + none

### quotations.download [POST /quotations.download]

Download a quotation in a specific format.

+ Request (application/json)

    + Attributes (object)
        + id: `d885e5d5-bacb-4607-bde9-abc4a04a901b` (string, required)
        + format: `pdf` (enum, required)
            + Members
                + pdf

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + location: `https://cdn.teamleader.eu/file` (string) - A temporary url where the requested file can be downloaded
            + expires: `2018-02-05T16:44:33+00:00` (string) - Expiration time of the temporary download link

### quotations.create [POST /quotations.create]

Create a quotation.

+ Request (application/json)

    + Attributes (object)
        + deal_id: `cef01135-7e51-4f6f-a6eb-6e5e5a885ac8` (string, required)
        + currency (object)
            + code: `EUR` (Currency, required)
            + exchange_rate: `1.1238` (number)
        + `grouped_lines` (array, optional) - A quotation needs `grouped_lines` and/or `text` to be valid
            + (object)
                + section (object, optional)
                    + title (string, required)
                + line_items (array, required)
                    + (object)
                        + quantity: `3` (number, required)
                        + description: `An awesome product` (string, required)
                        + extended_description: `Some more information about this awesome product` (string, optional) - Uses Markdown formatting
                        + unit_of_measure_id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string, optional, nullable)
                        + unit_price (object, required)
                            + amount: `123.30` (number)
                            + tax: `excluding` (enum, required)
                                + Members
                                    + excluding
                        + tax_rate_id: `c0c03f1e-77e3-402c-a713-30ea1c585823` (string, required)
                        + discount (object, optional)
                            + value: 10 (number, required)
                            + type (enum, required)
                                + Members
                                    + percentage - Values between 0 and 100
                        + product_id: `d905ff57-e866-0f59-9d1e-1fd4538bfae1` (string, optional) - This is purely informational and does not affect the quotation besides adding a reference to the product
                        + purchase_price (Money, nullable, optional) - the currency must match the account currency
        + discounts (array[CommercialDiscount], optional)
        + text: `Quotation text` (string, optional) - Uses Markdown formatting. A quotation needs `grouped_lines` and/or `text` to be valid
        + document_template_id: `179e1564-493b-4305-8c54-a34fc80920fc` (string, optional)
        + expiry (object) - only available if user has access to quotation expiry
            + expires_after: `2023-04-05` (string, nullable)
            + action_after_expiry (enum[string], required)
                + Members
                    + lock
                    + none

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `quotation` (string)
            + id: `e4bf74ca-e900-471f-84b1-276e5d3afae4` (string)

### quotations.send [POST /quotations.send]

Send a quotation.

+ Request (application/json)

    + Attributes (object)
        + quotations: `023a4609-eda4-006c-8d2c-314539ec5d85`, `b42635b7-ccd3-0bfc-9628-e90940694845` (array[string], required) - list of quotation ids you wish to send. These quotations need to come from the same deal.
        + from (object, optional)
            + sender (object, required)
                + type (enum, required)
                    + Members
                        + user
                        + department
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
            + email_address: `info@teamleader.eu` (string, required)
        + recipients (object, required)
            + to (array, required)
                + (object)
                    + customer (object, optional, nullable)
                        + type (enum, required)
                            + Members
                                + company
                                + contact
                        + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
                    + email_address: `info@teamleader.eu` (string, required)
            + cc (array, optional)
                + (object)
                    + customer (object, optional, nullable)
                        + type (enum, required)
                            + Members
                                + company
                                + contact
                        + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
                    + email_address: `info@teamleader.eu` (string, required)
           + bcc (array, optional)
                + (object)
                   + customer (object, optional, nullable)
                       + type (enum, required)
                           + Members
                               + company
                               + contact
                       + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
                   + email_address: `info@teamleader.eu` (string, required)
        + subject: `An offer you cannot refuse` (string, required)
        + content: `Sign your offer here #LINK` (string, required) - the shortcode '#LINK' will be replaced with the cloudsign url
        + attachments: `e76d381a-f7ea-04d1-9a32-14aab27bc1e2` (array[string], optional) - an array of file ids
        + language (Language, required)

+ Response 204

### quotations.update [POST /quotations.update]

Update a quotation.

+ Request (application/json)

    + Attributes (object)
        + id: `5b16f6ee-e302-0079-901b-50c26c4a55b1` (string, required)
        + currency (object)
            + code: `EUR` (Currency, required)
            + exchange_rate: `1.1238` (number)
        + `grouped_lines` (array, optional) - A quotation needs `grouped_lines` and/or `text` to be valid
            + (object)
                + section (object, optional)
                    + title (string, required)
                + line_items (array, required)
                    + (object)
                        + quantity: `3` (number, required)
                        + description: `An awesome product` (string, required)
                        + extended_description: `Some more information about this awesome product` (string, optional) - Uses Markdown formatting
                        + unit_of_measure_id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string, optional, nullable)
                        + unit_price (object, required)
                            + amount: `123.30` (number)
                            + tax: `excluding` (enum, required)
                                + Members
                                    + excluding
                        + tax_rate_id: `c0c03f1e-77e3-402c-a713-30ea1c585823` (string, required)
                        + discount (object, optional)
                            + value: 10 (number, required)
                            + type (enum, required)
                                + Members
                                    + percentage - Values between 0 and 100
                        + product_id: `d905ff57-e866-0f59-9d1e-1fd4538bfae1` (string, optional) - This is purely informational and does not affect the quotation besides adding a reference to the product
                        + purchase_price (Money, nullable, optional) - the currency must match the account currency
        + discounts (array[CommercialDiscount], optional)
        + text: `Quotation text` (string, optional, nullable) - Uses Markdown formatting. A quotation needs `grouped_lines` and/or `text` to be valid
        + document_template_id: `179e1564-493b-4305-8c54-a34fc80920fc` (string, optional)
        + expiry (object) - only available if user has access to quotation expiry
            + expires_after: `2023-04-05` (string, nullable)
            + action_after_expiry (enum[string], required)
                + Members
                    + lock
                    + none

+ Response 204

### quotations.accept [POST /quotations.accept]

Mark a quotation as accepted.

+ Request (application/json)

    + Attributes (object)
        + id: `e7a3fe2b-2c75-480f-87b9-121816b5257b` (string, required)

+ Response 204

### quotations.delete [POST /quotations.delete]

Delete a quotation.

+ Request (application/json)

    + Attributes (object)
        + id: `4e235f27-0af0-40e5-82f3-d32d0aa9edb3` (string, required)

+ Response 204

# Group Calendar

## Meetings [/meetings]

### meetings.list [POST /meetings.list]

Get a list of meetings.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + `ids`: `e4eb5f08-fb6a-42c1-8a41-6f619cb6de80`, `f4e6bd3c-cff7-4da8-9217-0b84b9437231` (array[string], optional)
            + `employee_id`: `f29abf48-337d-44b4-aad4-585f5277a456` (string, optional)
            + `start_date`: `2019-02-04` (string, optional)
            + `end_date`: `2019-02-04` (string, optional)
            + `milestone_id`: `f29abf48-337d-44b4-aad4-585f5277a456` (string, optional)
            + `term`: `funny joke HR meeting` (string, optional)
            + `recurrence_id`: `1dfccc8e-68d0-0b83-8d1b-5cf1b0d99ab1` (string, optional)
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + scheduled_at
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `scheduled_at`
                    + order: `asc`
        + includes: `tracked_time` (string, optional) - when used, the response will include `tracked_time`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + title: `My meeting` (string)
                + description: `My meeting description` (string)
                + created_at: `2020-02-01T10:33:45+00:00` (string)
                + scheduled_at: `2020-02-04T16:44:33+00:00` (string)
                + duration (object)
                    + unit (enum)
                        + Members
                            + min - Minutes
                    + value: `60` (number)
                + `tracked_time` (object, optional) - Only included with request parameter `includes=tracked_time`
                    + total (object)
                        + unit (enum)
                            + Members
                                + min - Minutes
                        + value: `60` (number)
                + `estimated_time` (object, optional) - Only included with request parameter `includes=estimated_time`
                    + total (object)
                        + unit (enum)
                            + Members
                                + min - Minutes
                        + value: `60` (number)
                + customer (object, nullable)
                    + type: `contact` (enum)
                        + Members
                            + contact
                            + company
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + project (object, nullable)
                    + type: `project` (enum)
                        + Members
                            + project
                            + nextgenProject
                    + id: `bbbb772b-e7ad-06c5-935c-b0f6ef61d6bc` (string)
                + milestone (object, nullable)
                    + type: `milestone` (string)
                    + id: `bb8337d9-e669-0319-aa57-355ef6ff4f2d` (string)
                + attendees (array)
                    + (object)
                        + type (enum)
                            + Members
                                + user
                                + contact
                        + id: `b5094b3f-bb7a-0391-b01b-e709773f3509` (string)
                + status (enum)
                    + Members
                        + open
                        + done
                + recurrence (object, nullable)
                    + type: `recurrence` (string)
                    + id: `1dfccc8e-68d0-0b83-8d1b-5cf1b0d99ab1` (string)

### meetings.info [POST /meetings.info]

Get information about a meeting.

+ Request (application/json)

    + Attributes (object)
        + id: `70af3fdd-b037-0936-ad1a-6d784dd44cf4` (string, required)
        + includes: `tracked_time` (string, optional) - when used, the response will include `tracked_time`

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `70af3fdd-b037-0936-ad1a-6d784dd44cf4` (string)
            + title: `My meeting` (string)
            + description: `My meeting description` (string)
            + scheduled_at: `2020-02-04T16:44:33+00:00` (string)
            + duration (object)
                + unit (enum)
                    + Members
                        + min - Minutes
                + value: `60` (number)
            + `tracked_time` (object, optional) - Only included with request parameter `includes=tracked_time`
                + total (object)
                    + unit (enum)
                        + Members
                            + min - Minutes
                    + value: `60` (number)
            + `estimated_time` (object, optional) - Only included with request parameter `includes=estimated_time`
                + total (object)
                    + unit (enum)
                        + Members
                            + min - Minutes
                    + value: `60` (number)
            + customer (object, nullable)
                + type: `contact` (enum)
                    + Members
                        + contact
                        + company
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
            + project (object, nullable)
                + type: `project` (enum)
                    + Members
                        + project
                        + nextgenProject
                + id: `bbbb772b-e7ad-06c5-935c-b0f6ef61d6bc` (string)
            + milestone (object, nullable)
                + type: `milestone` (string)
                + id: `bb8337d9-e669-0319-aa57-355ef6ff4f2d` (string)
            + deal (object, nullable)
                + type: `deal` (string)
                + id: `08b979e5-90d6-01e0-ac28-d58db81c3b12` (string)
            + location (object, nullable)
                + One Of
                    + Properties
                        + type: `virtual` (string)
                    + Properties
                        + type: `contact` (enum)
                            + Members
                                + contact
                                + company
                        + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                        + address (object)
                            + line_1: `Dok Noord 3A 101` (string, nullable)
                            + postal_code: `9000` (string, nullable)
                            + city: `Ghent` (string, nullable)
                            + country: `BE` (string)
                            + area_level_two (object, nullable)
                                + type: `area_level_two` (string)
                                + id: `db232cf8-ad4a-024b-941f-15a7a74f0fd2` (string)
                    + Properties
                        + type: `address` (string)
                        + address (object)
                            + line_1: `Dok Noord 3A 101` (string, nullable)
                            + postal_code: `9000` (string, nullable)
                            + city: `Ghent` (string, nullable)
                            + country: `BE` (string)
                            + area_level_two (object, nullable)
                                + type: `area_level_two` (string)
                                + id: `db232cf8-ad4a-024b-941f-15a7a74f0fd2` (string)
                    + Properties
                        + type: `customLocation` (string)
                        + id: `4191c526-5e26-0818-8e16-9523215b5081` (string)
                        + address (object)
                            + line_1: `Dok Noord 3A 101` (string, nullable)
                            + postal_code: `9000` (string, nullable)
                            + city: `Ghent` (string, nullable)
                            + country: `BE` (string)
                            + area_level_two (object, nullable)
                                + type: `area_level_two` (string)
                                + id: `db232cf8-ad4a-024b-941f-15a7a74f0fd2` (string)
                    + Properties
                        + type: `calendarResource` (string)
            + online_meeting_room (object, nullable)
                + type: `onlineMeetingRoom` (string)
                + id: `89b76a74dcf842b298b90ea79a5d1f7a` (string)
            + attendees (array)
                + (object)
                    + type (enum)
                        + Members
                            + user
                            + contact
                    + id: `b5094b3f-bb7a-0391-b01b-e709773f3509` (string)
            + custom_fields (array[CustomField])
            + status (enum)
                + Members
                    + open
                    + done
            + recurrence (object, nullable)
                + type: `recurrence` (string)
                + id: `1dfccc8e-68d0-0b83-8d1b-5cf1b0d99ab1` (string)
            + `workOrder` (object, nullable)
                + type: `workOrder` (string)
                + id: `ad4d358e-adc2-47ed-94d6-9913e0445e9b` (string)

### meetings.schedule [POST /meetings.schedule]

Schedule a meeting.

+ Request (application/json)

    + Attributes (object)
        + title: `My meeting` (string, required)
        + starts_at: `2023-10-01T09:00:00+01:00` (string, required)
        + ends_at: `2023-10-01T10:00:00+01:00` (string, required)
        + description: `My meeting description` (string, optional)
        + attendees (array, required) - at least one user attendee must be present
            + (object)
                + `type`: `user` (enum[string])
                    + Members
                        + `user`
                        + `contact`
                + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
        + customer (object, optional)
            + type: `contact` (enum)
                + Members
                    + contact
                    + company
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + location (object, optional)
            + One Of
                + Properties
                    + type: `virtual` (string, required)
                + Properties
                    + type: `contact` (enum[string], required)
                        + Members
                            + contact
                            + company
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)
                    + `address` (object, required)
                        + line_1: `Dok Noord 3A 101` (string, required, nullable)
                        + postal_code: `9000` (string, required, nullable)
                        + city: `Ghent` (string, required, nullable)
                        + country: `BE` (string, required)
                        + area_level_two_id: `db232cf8-ad4a-024b-941f-15a7a74f0fd2`
                + Properties
                    + type: `address` (string, required)
                    + `address` (object, required)
                        + line_1: `Dok Noord 3A 101` (string, required, nullable)
                        + postal_code: `9000` (string, required, nullable)
                        + city: `Ghent` (string, required, nullable)
                        + country: `BE` (string, required)
                        + area_level_two_id: `db232cf8-ad4a-024b-941f-15a7a74f0fd2`
                + Properties
                    + type: `customLocation` (string, required)
                    + id: `4191c526-5e26-0818-8e16-9523215b5081` (string, required)
        + milestone_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional)
        + deal_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional)
        + work_order_id: `531132ea-7c81-0843-9a11-5f43ff9c5491` (string, optional) 
        + custom_fields (array[CustomFieldValue], optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `meeting` (string)
            + id: `00ed6266-a5bd-4aac-a292-2582017b6400` (string)

### meetings.update [POST /meetings.update]

Update a meeting.

+ Request (application/json)

    + Attributes (object)
        + id: `00ed6266-a5bd-4aac-a292-2582017b6400` (string, required)
        + title: `My meeting` (string, optional)
        + starts_at: `2023-10-01T09:00:00+01:00` (string, optional)
        + ends_at: `2023-10-01T10:00:00+01:00` (string, optional)
        + description: `My meeting description` (string, optional, nullable)
        + attendees (array, optional) - when provided, at least one user attendee must be present
            + (object)
                + `type`: `user` (enum[string])
                    + Members
                        + `user`
                        + `contact`
                + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
        + customer (object, optional, nullable)
            + type: `contact` (enum)
                + Members
                    + contact
                    + company
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + location (object, optional)
            + One Of
                + Properties
                    + type: `virtual` (string, required)
                + Properties
                    + type: `contact` (enum[string], required)
                        + Members
                            + contact
                            + company
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)
                    + `address` (object, required)
                        + line_1: `Dok Noord 3A 101` (string, required, nullable)
                        + postal_code: `9000` (string, required, nullable)
                        + city: `Ghent` (string, required, nullable)
                        + country: `BE` (string, required)
                        + area_level_two_id: `db232cf8-ad4a-024b-941f-15a7a74f0fd2`
                + Properties
                    + type: `address` (string, required)
                    + `address` (object, required)
                        + line_1: `Dok Noord 3A 101` (string, required, nullable)
                        + postal_code: `9000` (string, required, nullable)
                        + city: `Ghent` (string, required, nullable)
                        + country: `BE` (string, required)
                        + area_level_two_id: `db232cf8-ad4a-024b-941f-15a7a74f0fd2`
                + Properties
                    + type: `customLocation` (string, required)
                    + id: `4191c526-5e26-0818-8e16-9523215b5081` (string, required)
        + milestone_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional, nullable)
        + deal_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional, nullable)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 204

### meetings.complete [POST /meetings.complete]

Mark a meeting as complete.

+ Request (application/json)

    + Attributes (object)
        + id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, required)

+ Response 204

### meetings.delete [POST /meetings.delete]

Deletes a meeting.

+ Request (application/json)

    + Attributes (object)
        + id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, required)

+ Response 204

### meetings.createReport [POST /meetings.createReport]

Creates a report for a meeting.

+ Request (application/json)

    + Attributes (object)
        + id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, required)
        + attach_to (object, required)
            + `type`: `contact` (enum[string])
                + Members
                    + `contact`
                    + `company`
                    + `deal`
            + `id`: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + summary: `My meeting summary` (string, optional)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `meetingReport` (string)
            + id: `f4baa515-c813-4ca2-bfc2-a646d985e58d` (string)

## Calls [/calls]

### calls.list [POST /calls.list]

Get a list of calls.

+ Request (application/json)
    + Attributes (object)
        + filter (object, optional)
            + scheduled_after: `2021-11-21` (string) - Filter on calls occurring on or after a given date
            + scheduled_before: `2022-05-13` (string) - Filter on calls occurring on or before a given date
            + relates_to (object, optional) - Filter calls by related object (currently only companies allowed)
                + id: `415fa7e0-e319-0952-b973-f067f2b49d56` (string)
                + type: `company` (string)
            + call_outcome_id: `6bd20dd8-dc3f-0e68-8919-dee0be6efe55` (string, optional) - Filter on completed calls by outcome
        + page (object, optional)
            + size: `20` (number, optional) - The amount of entries returned per request, max 1 to 100
                + Default: `20`
            + number: `1` (number, optional) - The current page, the first page is 1
                + Default: `1`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
                + added_at: `2021-11-21T18:14:15+00:00` (string, nullable)
                + participant (object, nullable)
                    + customer (object, nullable)
                        + type: `company` (string)
                        + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
                    + contact (object, nullable)
                        + type: `contact` (string)
                        + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
                + description: `Call with customer` (string, nullable)
                + outcome (object, nullable)
                    + type: `callOutcome` (string)
                    + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
                + outcome_summary: `Called, but was not available` (string, nullable)
                + assignee (object, nullable)
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                    + type: `user` (string)
                + scheduled_at: `2021-11-21T19:14:15+00:00` (string)
                + status: `open` (enum[string])
                    + Members
                        + `open`
                        + `completed`
                + deal (object, nullable)
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                    + type: `deal` (string)
        + meta (object) - Only included with request parameter `includes=pagination`
            + page (Pagination)
            + matches: `12` (number)

### calls.info [POST /calls.info]

Get information about a call.

+ Request (application/json)

    + Attributes (object)
        + id: `6fac0bf0-e803-424e-af67-76863a3d7d16` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
            + added_at: `2016-02-01T16:44:33+00:00` (string, nullable)
            + completed_at: `2016-02-04T16:44:33+00:00` (string, nullable)
            + participant (object, nullable)
                + customer (object, nullable)
                    + type: `company` (string)
                    + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
                + contact (object, nullable)
                    + type: `contact` (string)
                    + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
            + description: `Description of the call` (string, nullable)
            + outcome (object, nullable)
                + type: `callOutcome` (string)
                + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
            + outcome_summary: `Called, but was not available` (string, nullable)
            + assignee (object, nullable)
                + type: `user` (string)
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
            + scheduled_at: `2016-02-04T16:00:00+00:00` (string)
            + status: `open` (enum[string])
                + Members
                    + `open`
                    + `completed`
            + deal (object, nullable)
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + type: `deal` (string)
            + custom_fields (array[CustomField])

### calls.add [POST /calls.add]

Add a new call.

+ Request (application/json)

    + Attributes
        + description: `Description of the call` (string, optional)
        + participant (object, required)
            + customer (object, required)
                + type (enum, required)
                    + Members
                        + company
                        + contact
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
        + due_at: `2016-02-04T16:00:00+00:00` (string, required)
        + assignee (object, required)
            + type (enum, required)
                + Members
                    + user
            + id: `98b2863e-7b01-4232-82f5-ede1f0b9db22` (string, required)
        + deal_id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, optional)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `call` (string)
            + id: `65a35860-dcca-4850-9fd6-47ff08469e0c` (string)

### calls.update [POST /calls.update]

Update a new call.

+ Request (application/json)

    + Attributes
        + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, required)
        + description: `Description of the call` (string, optional)
        + participant (object, optional)
            + customer (object, optional)
                + type (enum, required)
                    + Members
                        + company
                        + contact
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
        + due_at: `2016-02-04T16:00:00+00:00` (string, optional)
        + assignee (object, optional)
            + type (enum, required)
                + Members
                    + user
            + id: `98b2863e-7b01-4232-82f5-ede1f0b9db22` (string, required)
        + deal_id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, nullable, optional)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 204 (application/json)

### calls.complete [POST /calls.complete]

Mark a call as complete.

+ Request (application/json)

    + Attributes (object)
        + id: `6fac0bf0-e803-424e-af67-76863a3d7d16` (string, required)
        + call_outcome_id: `2b43633b-22d1-41b6-b87b-e1fd742325d4` (string, optional)
        + outcome_summary: `Called, but was not available` (string, optional)

+ Response 204 (application/json)

## Call Outcomes [/callOutcomes]

### callOutcomes.list [GET /callOutcomes.list]

+ Request (application/json)
    + Attributes (object)
        + page (object, optional)
            + size: `20` (number, optional)
                + Default: `20`
            + number: `1` (number, optional)
                + Default: `1`

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + id: `2b43633b-22d1-41b6-b87b-e1fd742325d4` (string)
                + name: `Foo Bar` (string)

## Calendar events [/events]

Calendar events are scheduled events in your calendar. A calendar event involves a particular activity type: a task, meeting or call.

*Required scopes: `events`*

### events.list [POST /events.list]

Get a list of calendar events.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `9c475de2-1e99-0328-bc19-271b27e921d8`,`6325b4e5-c6a6-060b-b010-b81892e82fa7` (array[string], optional)
            + user_id: `5309c8c9-e313-47b0-90ba-6850c3dc3e33` (string, optional)
            + activity_type_id: `edd94120-63e2-4b10-80ed-fdfcfaa0a515` (string, optional)
            + ends_after: `2017-01-01T00:00:00+00:00` (string, optional) - Start of the period for which to return events
            + starts_before: `2018-01-01T00:00:00+00:00` (string, optional) - End of the period for which to return events
            + term: `coffee` (string, optional) - Searches for a term in title or description
            + attendee (object, optional)
                + type (enum, required)
                    + Members
                        + contact
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
            + link (object, optional)
                + type (enum, required)
                    + Members
                        + contact
                        + company
                        + deal
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
            + task_id: `5309c8c9-e313-47b0-90ba-6850c3dc3e33` (string, optional)
            + done: false (boolean, optional)
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field: `starts_at` (enum, required)
                    + Members
                        + starts_at
                + order: `asc` (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: starts_at
                    + order: asc

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `6d64488c-75d8-4de9-b140-2555566fa27d` (string)
                + creator (object)
                    + type: `user` (string)
                    + id: `e51d1a0e-452e-4d5d-a2a1-2c8f75dde560` (string)
                + task (object)
                    + type: `task` (string)
                    + id: `eb399573-e1ae-4377-bbaf-34358eb19831` (string)
                + activity_type (object)
                    + type: `activityType` (string)
                    + id: `28158af3-2ef3-4178-ac8b-2542b1481af0` (string)
                + title: `Erlich Bachman's birthday` (string)
                + description (string)
                + starts_at: `2016-02-04T16:00:00+00:00` (string)
                + ends_at: `2016-02-04T18:00:00+00:00` (string)
                + location (string)
                + attendees (array)
                    + (object)
                        + type: `contact` (enum)
                            + Members
                                + user
                                + contact
                        + id: `8b3afad7-648d-4b4c-b38b-5726d3222282` (string)
                + links (array)
                    + (object)
                        + type (enum)
                            + Members
                                + company
                                + contact
                                + deal
                        + id: `c9258836-f9a5-40cb-aa2a-d55c22991b93` (string)


### events.info [POST /events.info]

Get details for a single calendar event.

+ Request (application/json)

    + Attributes (object)
        + id: `9a5a3984-abfc-40cd-a880-f97683c6a99c` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `9a5a3984-abfc-40cd-a880-f97683c6a99c` (string)
            + title: `Meeting with stakeholders` (string)
            + description (string)
            + creator (object)
                + type: `user` (string)
                + id: `6f45600a-4402-40e0-9dcc-7665384bcd48` (string)
            + task (object)
                + type: `task` (string)
                + id: `be80d753-f2ee-426d-9596-2a2e1a23a82e` (string)
            + activity_type (object)
                + type: `activityType` (string)
                + id: `4a1b1d8e-45da-4c5f-a986-3f93d174d352` (string)
            + starts_at: `2016-02-04T16:00:00+00:00` (string)
            + ends_at: `2016-02-04T18:00:00+00:00` (string)
            + location (string)
            + attendees (array)
                + (object)
                    + type: `contact` (enum)
                        + Members
                            + user
                            + contact
                    + id: `8b3afad7-648d-4b4c-b38b-5726d3222282` (string)
            + links (array)
                + (object)
                    + type (enum)
                        + Members
                            + company
                            + contact
                            + work_order
                            + deal
                    + id: `c9258836-f9a5-40cb-aa2a-d55c22991b93` (string)

### events.create [POST /events.create]

Create a new calendar event.

+ Request (application/json)

    + Attributes
        + title: `Meeting with stakeholders` (string, required)
        + description (string, optional)
        + activity_type_id: `b0a9ace5-fe82-4827-9d90-fc52f2c93050` (string, required)
        + starts_at: `2016-02-04T16:00:00+00:00` (string, required)
        + ends_at: `2016-02-04T18:00:00+00:00` (string, required)
        + location (string, optional)
        + work_type_id: `b37e2bc7-dea0-4fda-88e9-c092fb65667d` (string, optional)
        + attendees (array, optional)
            + (object)
                + type: `user` (enum, required)
                    + Members
                        + user
                        + contact
                + id: `6ddd2666-65a0-497f-9f01-54c4343ec1a6` (string, required)
        + links (array, optional)
            + (object)
                + type: `company` (enum, required)
                    + Members
                        + company
                        + contact
                        + deal - Only available for events of type meeting or call
                + id: `c9258836-f9a5-40cb-aa2a-d55c22991b93` (string, required)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `event` (string)
            + id: `9fc14045-5c6c-4ba8-8672-42ea3f26aa63` (string)

### events.update [POST /events.update]

Update a calendar event.

+ Request (application/json)

    + Attributes
        + id: `f22fc69d-5d07-40cf-af46-015698a74b63` (string, required)
        + title: `Meeting with stakeholders` (string, optional)
        + description (string, optional, nullable)
        + starts_at: `2016-02-04T16:00:00+00:00` (string, optional)
        + ends_at: `2016-02-04T18:00:00+00:00` (string, optional)
        + location (string, optional)
        + work_type_id: `b37e2bc7-dea0-4fda-88e9-c092fb65667d` (string, optional)
        + attendees (array, optional)
            + (object)
                + type: `user` (enum, required)
                    + Members
                        + user
                        + contact
                + id: `6ddd2666-65a0-497f-9f01-54c4343ec1a6` (string, required)
        + links (array, optional)
            + (object)
                + type: `company` (enum, required)
                    + Members
                        + company
                        + contact
                        + deal - Only available for events of type meeting or call
                + id: `c9258836-f9a5-40cb-aa2a-d55c22991b93` (string, required)

+ Response 204

### events.cancel [POST /events.cancel]

Cancel a calendar event (for all attendees).

+ Request (application/json)

    + Attributes (object)
        + id: `b519491e-ca80-4efb-bb7b-3f08544936b0` (string, required)

+ Response 204

## Activity Types [/activityTypes]

Activity types identify the different types of events that take place within your organisation. Currently only three activity types are available: tasks, meetings and calls.

### activityTypes.list [POST /activityTypes.list]

Get a list of all activity types.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `7fcf5609-25fe-47e2-97b2-dbd9c817796e`,`366b6100-7005-4b1b-a16a-7e88f445f496` (array[string], optional)
        + page (Page, optional)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `9feb5f61-c6dd-4f9d-9b37-2813ada4e343` (string)
                + name (string)

# Group Invoicing

## Invoices [/invoices]

Teamleader provides a whole set of endpoints to make it easy to develop integrations with invoices. New invoices are created in accordance with this flow: `invoice.draft` → `invoice.book`. Invoices can also be updated, deleted or credited.

*Required scopes: `invoices`*

### invoices.list [POST /invoices.list]

Get a list of invoices.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + `ids`: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5`,`f8a57a6f-dd1e-41a3-b8d3-428663f1d09e` (array[string], optional)
            + `term`: `Interesting invoice` (string, optional) - Filters on invoice number, purchase order number, payment reference and invoicee
            + `invoice_number`: `2017 / 5` (string, optional) - Filters on a full invoice number (fiscal year / number)
            + `department_id`: `af48fe9e-d44c-0eac-8813-8be051b10921` (string, optional) - Filters on a department (company entity)
            + `deal_id`: `4a219dae-7b80-4c79-97d2-bdadbab299ba` (string, optional) - Filters on a deal
            + `project_id`: `ba7d9731-c7d0-43d3-af95-fd7b3e818dbc` (string, optional) - Filters on a project
            + `subscription_id`: `8631bbbf-bead-4f6e-a2ab-58ec9bbd997a` (string, optional) - Filters on a subscription
            + `status` (array[enum], optional) - The statuses you want to filter by.
                + Members
                    + draft
                    + outstanding
                    + matched
            + `updated_since`: `2016-02-04T16:44:33+00:00` (string, optional)
            + `purchase_order_number`: `000023` (string, optional)
            + `payment_reference`: `+++084/2613/66074+++` (string, optional)
            + `invoice_date_after`: `2020-01-01` (string, optional) - This date is inclusive
            + `invoice_date_before`: `2022-01-01` (string, optional) - This date is inclusive
            + `customer` (object, optional)
                + type (enum, required)
                    + Members
                        + company
                        + contact
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + invoice_number
                        + invoice_date
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `invoice_number`
                    + order: `asc`
        + includes: `late_fees` (string, optional) - when used, the response will include `totals.due_incasso_inclusive`, `totals.fixed_late_fee` and `totals.interest`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `2aa4a6a9-9ce8-4851-a9b3-26aea2ea14c4` (string)
                + department (object)
                    + type: `department` (string)
                    + id: `5e90eb0a-b502-4344-aa0f-3b8525af6186` (string)
                + invoice_number: `2017 / 5` (string, nullable)
                + invoice_date: `2016-02-04` (string, nullable)
                + status: `matched` (enum)
                    + Members
                        + draft
                        + outstanding
                        + matched
                + due_on: `2016-03-03` (string, nullable)
                + paid: true (boolean)
                + paid_at: `2016-02-04T16:44:33+00:00` (string, nullable)
                + sent: true (boolean)
                + purchase_order_number: `000023` (string, nullable)
                + payment_reference: `+++084/2613/66074+++` (string, nullable)
                + invoicee (object)
                    + name: `De Rode Duivels` (string)
                    + vat_number: `BE0899623035` (string, nullable)
                    + customer (object)
                        + type: `contact` (string)
                        + id: `4b0f959a-27e3-4080-b1b2-a05b374863cb` (string)
                    + for_attention_of (object, nullable)
                        + name: `Radja Nainggolan` (string, nullable)
                        + contact (object, nullable)
                            + type: `contact` (string)
                            + id: `d4391f46-a32c-458c-b2ee-833fd27a348d` (string)
                + total (object)
                    + tax_exclusive (Money)
                    + tax_inclusive (Money)
                    + payable (Money)
                    + taxes (array)
                        + (object)
                            + rate: 0.21 (number)
                            + taxable (Money)
                            + tax (Money)
                    + due (Money)
                    + due_incasso_inclusive (Money) - Only included with request parameter `includes=late_fees`
                    + fixed_late_fee (Money) - Only included with request parameter `includes=late_fees`
                    + interest (Money) - Only included with request parameter `includes=late_fees`
                + currency_exchange_rate (object)
                    + from: `USD` (string)
                    + to: `EUR` (string)
                    + rate: 1.1234 (number)
                + created_at: `2016-02-04T16:44:33+00:00` (string)
                + updated_at: `2016-02-05T16:44:33+00:00` (string)
                + `web_url`: `https://focus.teamleader.eu/invoice_detail.php?id=2aa4a6a9-9ce8-4851-a9b3-26aea2ea14c4` (string)
                + file (object, nullable)
                    + type: `file` (string)
                    + id: `39a02b79-b9a9-46e3-a44d-6c473b2fe350` (string)
                + deal (object, nullable)
                    + type: `deal` (string)
                    + id: `a8ef428a-0e70-48a5-8696-58be0c45a772` (string)
                + project (object, nullable)
                    + type: `project` (string)
                    + id: `179e1564-493b-4305-8c54-a34fc80920fc` (string)

### invoices.info [POST /invoices.info]

Get details for a single invoice.

+ Request (application/json)

    + Attributes (object)
        + id: `27300f09-6250-4a23-8557-d84c52f99ecf` (string)
        + includes: `late_fees` (string, optional) - when used, the response will include `totals.due_incasso_inclusive`, `totals.fixed_late_fee` and `totals.interest`


+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `e540fe7e-dce2-459e-bf7e-24e605fc18b3` (string)
            + department (object)
                + type: `department` (string)
                + id: `8f802cba-443b-4c69-800f-5852e967000b` (string)
            + invoice_number: `2017 / 5` (string, nullable)
            + invoice_date: `2016-02-04` (string, nullable)
            + status: `outstanding` (enum)
                + Members
                    + draft
                    + outstanding
                    + matched
            + due_on: `2016-03-03` (string, nullable)
            + paid: true (boolean)
            + paid_at: `2016-02-04T16:44:33+00:00` (string, nullable)
            + sent: true (boolean)
            + purchase_order_number: `000023` (string, nullable)
            + invoicee (object)
                + name: `De Rode Duivels` (string)
                + vat_number: `BE0899623035` (string, nullable)
                + customer (object)
                    + type: `contact` (string)
                    + id: `c7db7f80-762a-4e65-8d0c-522700198284` (string)
                + for_attention_of (object, nullable)
                    + name: `Radja Nainggolan` (string, nullable)
                    + contact (object, nullable)
                        + type: `contact` (string)
                        + id: `f88ab83c-b8ca-497b-a2c6-1ad631fe1cea` (string)
                + email: `duivels@test.com` (string, nullable)
                + national_identification_number: `123` (string, nullable)
            + discounts (array[CommercialDiscount])
            + grouped_lines (array)
                + (object)
                    + section (object)
                        + title (string)
                    + line_items (array)
                        + (object)
                            + product (object, nullable)
                                + type: `product` (string)
                                + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)
                            + product_category (object, nullable)
                                + id: `e2314517-3cab-4aa9-8471-450e73449041` (string)
                                + type: `productCategory` (string)
                            + quantity: 3 (number)
                            + description: `An awesome product` (string)
                            + extended_description: `Some more information about this awesome product` (string, nullable) - Uses Markdown formatting
                            + unit (object, nullable)
                                + type: `unitOfMeasure` (string)
                                + id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string)
                            + unit_price (object)
                                + amount: `123.30` (number)
                                + tax: `excluding` (enum)
                                    + Members
                                        + excluding
                            + tax (object)
                                + type: `taxRate` (string)
                                + id: `e2314517-3cab-4aa9-8471-450e73449042` (string)
                            + discount (object, nullable)
                                + type: `percentage` (enum)
                                    + Members
                                        + percentage
                                + value: 15.00 (number)
                            + total
                                + tax_exclusive (Money)
                                + tax_exclusive_before_discount (Money)
                                + tax_inclusive (Money)
                                + tax_inclusive_before_discount (Money)
                            + withheld_tax (object, nullable)
                                + type: `withholding_tax` (string)
                                + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)
            + total (object)
                + tax_exclusive (Money)
                + tax_exclusive_before_discount (Money)
                + tax_inclusive (Money)
                + tax_inclusive_before_discount (Money)
                + taxes (array)
                    + (object)
                        + rate: 0.21 (number)
                        + taxable (Money)
                        + tax (Money)
                + withheld_taxes (array)
                    + (object)
                        + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)
                        + taxable (Money)
                        + withheld (Money)
                + payable (Money)
                + due (Money)
                + due_incasso_inclusive (Money) - Only included with request parameter `includes=late_fees`
                + fixed_late_fee (Money) - Only included with request parameter `includes=late_fees`
                + interest (Money) - Only included with request parameter `includes=late_fees`
            + payment_term (PaymentTerm)
            + payments (array)
                + (object)
                    + paid_at: `2016-03-03T16:44:33+00:00` (string)
                    + payment (object)
                        + Include Money
            + payment_reference: `+++084/2613/66074+++` (string, nullable)
            + note: `'Some extra remarks about the invoice'` (string, nullable) - plaintext
            + currency: `USD` (string)
            + currency_exchange_rate (object)
                + from: `USD` (string)
                + to: `EUR` (string)
                + rate: 1.1234 (number)
            + expected_payment_method (ExpectedPaymentMethod, nullable)
            + file (object, nullable)
                + type: `file` (string)
                + id: `39a02b79-b9a9-46e3-a44d-6c473b2fe350` (string)
            + deal (object, nullable)
                + type: `deal` (string)
                + id: `a8ef428a-0e70-48a5-8696-58be0c45a772` (string)
            + project (object, nullable)
                + type: `project` (string)
                + id: `179e1564-493b-4305-8c54-a34fc80920fc` (string)
            + on_hold_since: `2016-02-01` (string, nullable)
            + custom_fields (array[CustomField])
            + created_at: `2016-02-04T16:44:33+00:00` (string)
            + updated_at: `2016-02-05T16:44:33+00:00` (string)
            + document_template (object)
                + type: `documentTemplate` (string)
                + id: `179e1564-493b-4305-8c54-a34fc80920fc` (string)

### invoices.download [POST /invoices.download]

Download an invoice in a specific format.

+ Request (application/json)

    + Attributes (object)
        + id: `d885e5d5-bacb-4607-bde9-abc4a04a901b` (string, required)
        + format: `pdf` (enum, required)
            + Members
                + pdf
                + `ubl/e-fff`

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + location: `https://cdn.teamleader.eu/file` (string) - A temporary url where the requested file can be downloaded
            + expires: `2018-02-05T16:44:33+00:00` (string) - Expiration time of the temporary download link

### invoices.draft [POST /invoices.draft]

Draft a new invoice.

+ Request (application/json)

    + Attributes (object)
        + invoicee (object, required)
            + customer (object, required)
                + type (enum)
                    + Members
                        + contact
                        + company
                + id: `ebafa4c5-fa8a-4409-92e5-1b192243372f` (string)
            + for_attention_of (object, optional)
                + One Of
                    + name: `Finance Dept.` (string, required)
                    + contact_id: `417a2231-c3c7-4e1c-a6bb-1b014836ca60` (string, required)
        + department_id: `cef01135-7e51-4f6f-a6eb-6e5e5a885ac7` (string, required)
        + payment_term (PaymentTerm, required)
        + currency (object)
            + code: `EUR` (Currency, required)
            + exchange_rate: `1.1238` (number)
        + project_id: `624ca743-8998-4f8c-add1-c427bb022166` (string, optional)
        + purchase_order_number: `000023` (string, optional)
        + grouped_lines (array[InvoiceGroupedLinesWrite], required)
        + invoice_date: `2016-02-04` (string, optional)
        + discounts (array[CommercialDiscount], optional)
        + note: `Invoice comments` (string, optional)
        + expected_payment_method (ExpectedPaymentMethod, optional).
        + custom_fields (array[CustomFieldValue], optional)
        + document_template_id: `179e1564-493b-4305-8c54-a34fc80920fc` (string, optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `invoice` (string)
            + id: `e4bf74ca-e900-471f-84b1-276e5d3afae4` (string)

### invoices.update [POST /invoices.update]

Update a draft invoice. Booked invoices cannot be updated.

+ Request (application/json)

    + Attributes (object)
        + id: `b7023c11-455e-4fa5-bb96-87f37dbc7d07` (string, required)
        + invoicee (object, optional)
            + customer (object, required)
                + type (enum)
                    + Members
                        + contact
                        + company
                + id: `ebafa4c5-fa8a-4409-92e5-1b192243372f` (string)
            + for_attention_of (object, optional)
                + One Of
                    + name `Finance Dept.` (string, required)
                    + contact_id: `417a2231-c3c7-4e1c-a6bb-1b014836ca60` (string, required)
        + payment_term (PaymentTerm, optional)
        + currency (object)
            + code: `EUR` (Currency, required)
            + exchange_rate: `1.1238` (number)
        + project_id: `624ca743-8998-4f8c-add1-c427bb022166` (string, optional)
        + purchase_order_number: `000023` (string, optional)
        + grouped_lines (array[InvoiceGroupedLinesWrite], optional)
        + invoice_date: `2016-02-04` (string, optional)
        + note: `Some comments about the invoice` (string, optional, nullable)
        + discounts (array[CommercialDiscount], optional)
        + expected_payment_method (ExpectedPaymentMethod, optional, nullable)
        + custom_fields (array[CustomFieldValue], optional)
        + document_template_id: `179e1564-493b-4305-8c54-a34fc80920fc` (string, optional)

+ Response 204

### invoices.updateBooked [POST /invoices.updateBooked]

Update a booked invoice. Only available when editing booked invoices is allowed through the settings.

+ Request (application/json)

    + Attributes (object)
        + id: `b7023c11-455e-4fa5-bb96-87f37dbc7d07` (string, required)
        + invoicee (object, optional)
            + customer (object, required)
                + type (enum)
                    + Members
                        + contact
                        + company
                + id: `ebafa4c5-fa8a-4409-92e5-1b192243372f` (string)
            + for_attention_of (object, optional)
                + One Of
                    + name `Finance Dept.` (string, required)
                    + contact_id: `417a2231-c3c7-4e1c-a6bb-1b014836ca60` (string, required)
        + payment_term (PaymentTerm, optional)
        + project_id: `624ca743-8998-4f8c-add1-c427bb022166` (string, optional)
        + grouped_lines (array[InvoiceGroupedLinesWrite], optional)
        + invoice_date: `2016-02-04` (string, optional)
        + note: `Some comments about the invoice` (string, optional, nullable)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 204

### invoices.copy [POST /invoices.copy]

Creates a new draft invoice based on another invoice

+ Request (application/json)

    + Attributes (object)
        + id: `b7023c11-455e-4fa5-bb96-87f37dbc7d07` (string, required)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `invoice` (string)
            + id: `e4bf74ca-e900-471f-84b1-276e5d3afae4` (string)

### invoices.book [POST /invoices.book]

Book a draft invoice.

+ Request (application/json)

    + Attributes (object)
        + id: `7abb325c-e063-42a4-8fb4-1b730759645a` (string, required)
        + on: `2016-02-04` (string, required)

+ Response 204

### invoices.delete [POST /invoices.delete]

Delete an existing invoice. Only possible for draft invoices or the last booked invoice.

+ Request (application/json)

    + Attributes (object)
        + id: `7517d21c-75c1-4b89-8956-0e67f46c8532` (string, required)

+ Response 204

### invoices.registerPayment [POST /invoices.registerPayment]

Register a payment for an invoice.

+ Request (application/json)

    + Attributes (object)
        + id: `7abb325c-e063-42a4-8fb4-1b730759645a` (string, required)
        + payment (object, required)
            + Include Money
        + paid_at: `2016-03-03T16:44:33+00:00` (string, required)
        + payment_method_id: `bb9589ec-6e08-0d5f-9b23-7be9b9c3ea2d` (string, optional)

+ Response 204

### invoices.removePayments [POST /invoices.removePayments]

Marks an invoice as unpaid and removes all linked payments. This will also trigger a re-rendering of the invoice PDF.

+ Request (application/json)
    + Attributes (object)
        + id: `d885e5d5-bacb-4607-bde9-abc4a04a901b` (string, required)

+ Response 204

### invoices.credit [POST /invoices.credit]

Credit an invoice completely.

+ Request (application/json)

    + Attributes (object)
        + id: `d885e5d5-bacb-4607-bde9-abc4a04a901b` (string, required)
        + credit_note_date: `2016-02-04` (string, optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `creditNote` (string)
            + id: `d885e5d5-bacb-4607-bde9-abc4a04a901c` (string)


### invoices.creditPartially [POST /invoices.creditPartially]

Credit an invoice partially.

+ Request (application/json)

    + Attributes (object)
        + id: `d885e5d5-bacb-4607-bde9-abc4a04a901b` (string, required)
        + credit_note_date: `2016-02-04` (string, optional)
        + grouped_lines (array[InvoiceGroupedLinesWrite], required)
        + discounts (array[CommercialDiscount], optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `creditNote` (string)
            + id: `d885e5d5-bacb-4607-bde9-abc4a04a901c` (string)


### invoices.send [POST /invoices.send]

Send an invoice via e-mail.

+ Request (application/json)

    + Attributes (object)
        + id: `d885e5d5-bacb-4607-bde9-abc4a04a901b` (string, required)
        + content (object, required)
             + subject: `Invoice` (string, required)
             + body: `Please find your invoice attached to this mail` (string, required)
             + mail_template_id: `045cd6a9-7527-09c9-aa16-fd5ac7953e71` (string, optional, nullable)
        + recipients (object, optional)
            + to (array)
                + (object)
                    + customer (object, optional, nullable)
                        + type (enum, required)
                            + Members
                                + company
                                + contact
                        + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
                    + email: `info@teamleader.eu` (string, required)
            + cc (array, optional)
                + (object)
                    + customer (object, optional, nullable)
                        + type (enum, required)
                            + Members
                                + company
                                + contact
                        + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
                    + email: `info@teamleader.eu` (string, required)
           + bcc (array, optional)
                + (object)
                   + customer (object, optional, nullable)
                       + type (enum, required)
                           + Members
                               + company
                               + contact
                       + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
                   + email: `info@teamleader.eu` (string, required)
       + attachments: `e76d381a-f7ea-04d1-9a32-14aab27bc1e2` (array[string], optional) - an array of file ids

+ Response 204

## Credit Notes [/creditNotes]

Credit notes are created when certain products or services are not delivered according to their invoice. The credit note reduces the due amount of the credited invoice.

*Required scopes: `invoices`*

### creditNotes.list [POST /creditNotes.list]

List credit notes

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `cb8da52a-ce89-4bf6-8f7e-8ee6cb85e3b5`,`f8a57a6f-dd1e-41a3-b8d3-428663f1d09e` (array[string], optional)
            + department_id: `080aac72-ff1a-4627-bfe3-146b6eee979c` (string, optional) - The ID of the department you wish to filter on.
            + updated_since: `2016-02-04T16:44:33+00:00` (string, optional)
            + invoice_id: `60f03745-4289-4ae7-8c74-d797860bc887` (string, optional)
            + project_id: `082e6289-30c5-45ad-bcd0-190b02d21e81` (string, optional)
            + customer (object, optional)
                + type (enum, required)
                    + Members
                        + company
                        + contact
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
            + `credit_note_date_after`: `2022-01-01` (string, optional) - This date is inclusive
            + `credit_note_date_before`: `2023-01-01` (string, optional) - This date is exclusive
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + credit_note_number
                + order (enum, optional)
                    + Members
                        + asc
            + Default
                + (object)
                    + field: `credit_note_number`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `2b43633b-22d1-41b6-b87b-e1fd742325d4` (string)
                + department (object)
                    + type: `department` (string)
                    + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string)
                + credit_note_number: `2017/5` (string, nullable)
                + credit_note_date: `2016-02-04` (string, nullable)
                + status: `booked` (enum)
                    + Members
                        + booked
                + invoice (object, nullable)
                    + type: `invoice` (string)
                    + id: `53484141-8382-4948-9a4c-9cd7e79b30bd` (string)
                + paid: `true` (boolean)
                + paid_at: `2016-03-03T16:44:33+00:00` (string, nullable)
                + invoicee (object)
                    + name: `De Rode Duivels` (string)
                    + vat_number: `BE0899623035` (string, nullable)
                    + customer (object)
                        + type: `contact` (string)
                        + id: `dc2a40bf-f050-4c8e-a002-872a051150b9` (string)
                + total (object)
                    + tax_exclusive (Money)
                    + tax_inclusive (Money)
                    + payable (Money)
                    + taxes (array)
                        + (object)
                            + rate: `0.21` (number)
                            + taxable (Money)
                            + tax (Money)
                + created_at: `2016-02-04T16:44:33+00:00` (string)
                + updated_at: `2016-02-05T16:44:33+00:00` (string)

### creditNotes.info [POST /creditNotes.info]

Get details for a single credit note

+ Request (application/json)

    + Attributes (object)
        + id: `27300f09-6250-4a23-8557-d84c52f99ecf` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `27300f09-6250-4a23-8557-d84c52f99ecf` (string)
                + department (object)
                    + type: `department` (string)
                    + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string)
                + credit_note_number: `2017/5` (string, nullable)
                + credit_note_date: `2016-02-04` (string, nullable)
                + status: `booked` (enum)
                    + Members
                        + booked
                + invoice (object, nullable)
                    + type: `invoice` (string)
                    + id: `53484141-8382-4948-9a4c-9cd7e79b30bd` (string)
                + paid: `true` (boolean)
                + paid_at: `2016-03-03T16:44:33+00:00` (string, nullable)
                + invoicee (object)
                    + name: `De Rode Duivels` (string)
                    + vat_number: `BE0899623035` (string, nullable)
                    + customer (object)
                        + type: `contact` (string)
                        + id: `dc2a40bf-f050-4c8e-a002-872a051150b9` (string)
                    + email: `duivels@test.com` (string, nullable)
                    + national_identification_number: `123` (string, nullable)
                + discounts (array[CommercialDiscount], optional)
                + total (object)
                    + tax_exclusive (Money)
                    + tax_inclusive (Money)
                    + payable (Money)
                    + taxes (array)
                        + (object)
                            + rate: `0.21` (number)
                            + taxable (Money)
                            + tax (Money)
                + grouped_lines (array)
                    + (object)
                        + section (object)
                            + title (string)
                        + line_items (array)
                            + (object)
                                + product (object, nullable)
                                    + type: `product` (string)
                                    + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)
                                + product_category (object, nullable)
                                    + id: `e2314517-3cab-4aa9-8471-450e73449041` (string)
                                    + type: `productCategory` (string)
                                + quantity: `3` (number)
                                + description: `An awesome product` (string)
                                + extended_description: `Some more information about this awesome product` (string) - Uses Markdown formatting
                                + unit (object, nullable)
                                    + type: `unitOfMeasure` (string)
                                    + id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string)
                                + unit_price (object)
                                    + Include Money
                                    + tax: `excluding` (enum)
                                        + Members
                                            + excluding
                                + tax (object)
                                    + type: `taxRate` (string)
                                    + id: `e2314517-3cab-4aa9-8471-450e73449042` (string)
                                + discount (object, nullable)
                                    + type: `percentage` (enum)
                                        + Members
                                            + percentage
                                    + value: `15.00` (number)
                                + total
                                    + tax_exclusive (Money)
                                    + tax_exclusive_before_discount (Money)
                                    + tax_inclusive (Money)
                                    + tax_inclusive_before_discount (Money)
                + currency: `USD` (string)
                + currency_exchange_rate (object)
                    + from: `USD` (string)
                    + to: `EUR` (string)
                    + rate: 1.1234 (number)
                + created_at: `2016-02-04T16:44:33+00:00` (string)
                + updated_at: `2016-02-05T16:44:33+00:00` (string)
                + document_template (object)
                    + type: `documentTemplate` (string)
                    + id: `179e1564-493b-4305-8c54-a34fc80920fc` (string)

### creditNotes.download [POST /creditNotes.download]

Download a credit note in a specific format.

+ Request (application/json)

    + Attributes (object)
        + id: `d885e5d5-bacb-4607-bde9-abc4a04a901b` (string, required)
        + format: `pdf` (enum, required)
            + Members
                + pdf
                + `ubl/e-fff`

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + location: `https://cdn.teamleader.eu/file` (string) - A temporary url where the requested file can be downloaded
            + expires: `2018-02-05T16:44:33+00:00` (string) - Expiration time of the temporary download link

## Subscriptions [/subscriptions]

### subscriptions.list [POST /subscriptions.list]

Get a list of subscriptions

+ Request (application/json)
    + Attributes (object)
        + filter (object, optional)
            + ids: `46156648-87c6-478d-8aa7-1dc3a00dacab`, `46156648-87c6-478d-8aa7-1dc3a00daca4` (array[string], optional)
            + invoice_id: `60f03745-4289-4ae7-8c74-d797860bc887` (string, optional) - Find subscriptions that generated the given invoice
            + deal_id: `fddf42f9-bda1-0c49-a22b-0bf147cd1e3f` (string, optional) - Filter on subscriptions created from a deal
            + department_id: `af48fe9e-d44c-0eac-8813-8be051b10921` (string, optional) - Filter on subscriptions of a specific department (company entity)
            + customer (Customer)
            + status (array[enum], optional) - Filters on status
                + Members
                    + active - Filters on active subscriptions
                    + deactivated - Filters on deactivated subscriptions
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + title
                        + created_at
                        + status
                + order (enum, optional)
                    + Members
                        + asc
                        + desc

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + id: `e2314517-3cab-4aa9-8471-450e73449041` (string)
                + title: `Subscription for cookies` (string)
                + note: `Some more **information** about this subscription` (string, nullable) - Uses Markdown formatting
                + status: `active` (enum[string])
                    + Members
                        + active
                        + deactivated
                + department (object)
                    + type: `department` (string)
                    + id: `5e90eb0a-b502-4344-aa0f-3b8525af6186` (string)
                + invoicee (object)
                    + customer (Customer)
                    + for_attention_of (object, nullable)
                        + contact (object, nullable)
                            + type: `contact` (string)
                            + id: `d4391f46-a32c-458c-b2ee-833fd27a348d` (string)
                        + name: `Radja Nainggolan` (string, nullable)
                + project (object, nullable)
                    + type: `project` (string)
                    + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
                + starts_on: `2022-05-21` (string)
                + ends_on: `2023-07-21` (string, nullable)
                + next_renewal_date: `2022-06-21` (string, nullable)
                + billing_cycle (object)
                    + periodicity (Periodicity)
                    + days_in_advance: `7` (enum[number])
                        + Members
                            + 0
                            + 7
                            + 14
                            + 21
                            + 28
                + total (object)
                    + tax_exclusive (Money)
                    + tax_inclusive (Money)
                    + taxes (array)
                        + (object)
                            + rate: 0.21 (number)
                            + taxable (Money)
                            + tax (Money)
                + `web_url`: `https://focus.teamleader.eu/subscription_detail.php?id=e2314517-3cab-4aa9-8471-450e73449041` (string)


### subscriptions.info [POST /subscriptions.info]

Get details for a single subscription

+ Request (application/json)
    + Attributes (object)
        + id: `e2314517-3cab-4aa9-8471-450e73449041` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (object)
            + id: `e2314517-3cab-4aa9-8471-450e73449041` (string)
            + title: `Subscription for cookies` (string)
            + note: `Some more **information** about this subscription` (string, nullable) - Uses Markdown formatting
            + status: `active` (enum[string])
                + Members
                    + active
                    + deactivated
            + department (object)
                + type: `department` (string)
                + id: `5e90eb0a-b502-4344-aa0f-3b8525af6186` (string)
            + invoicee (object)
                + customer (Customer)
                + for_attention_of (object, nullable)
                    + contact (object, nullable)
                        + type: `contact` (string)
                        + id: `d4391f46-a32c-458c-b2ee-833fd27a348d` (string)
                    + name: `Radja Nainggolan` (string, nullable)
            + project (object, nullable)
                + type: `project` (string)
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
            + next_renewal_date: `2022-06-21` (string, nullable)
            + total (object)
                + tax_exclusive (Money)
                + tax_inclusive (Money)
                + taxes (array)
                    + (object)
                        + rate: 0.21 (number)
                        + taxable (Money)
                        + tax (Money)
            + `web_url`: `https://focus.teamleader.eu/subscription_detail.php?id=e2314517-3cab-4aa9-8471-450e73449041` (string)
            + starts_on: `2022-05-21` (string)
            + ends_on: `2023-07-21` (string, nullable)
            + billing_cycle (object) - Only available for api-version 9999-99-99
                + periodicity (Periodicity)
                + days_in_advance: `7` (enum[number])
                    + Members
                        + 0
                        + 7
                        + 14
                        + 21
                        + 28
            + payment_term (PaymentTerm)
            + grouped_lines (array)
                + (GroupedLineItem)
            + invoice_generation (object)
                + action: `book` (enum)
                    + Members
                        + draft
                        + book
                        + book_and_send
                + sending_methods (array, optional) - only provided when action is "book and send".
                    + (object)
                        + method: `email` (enum)
                            + Members
                                + email
                                + postal_service
                + payment_method (enum, optional)
                    + Members
                        + direct_debit
            + custom_fields (array[CustomField])
            + document_template (object)
                + type: `documentTemplate` (string)
                + id: `179e1564-493b-4305-8c54-a34fc80920fc` (string)
            + currency: `USD` (string)

### subscriptions.create [POST /subscriptions.create]

Create a new subscription.

+ Request (application/json)

    + Attributes (object)
        + invoicee (object, required)
            + customer (Customer, required)
            + for_attention_of (object, optional)
                + One Of
                    + name: `Finance Dept.` (string, required)
                    + contact_id: `417a2231-c3c7-4e1c-a6bb-1b014836ca60` (string, required)
        + department_id: `6a6343fc-fdd8-4bc0-aa69-3a004c710e87` (string, required)
        + starts_on: `2022-04-26` (string, required)
        + billing_cycle (object, required)
            + periodicity (Periodicity, required)
            + days_in_advance: `7` (enum[number], required)
                + Members
                    + 0
                    + 7
                    + 14
                    + 21
                    + 28
        + title: `Subscription for cookies` (string, required)
        + grouped_lines (array, required)
            + (object)
                + section (object)
                    + title (string)
                + line_items (array, required)
                    + (LineItem)
        + ends_on: `2022-05-26` (string, nullable, optional)
        + deal_id: `cef01135-7e51-4f6f-a6eb-6e5e5a885ac8` (string, optional)
        + project_id: `ebafa4c5-fa8a-4409-92e5-1b192243372f` (string, optional)
        + note: `Subscription comments` (string, optional)
        + payment_term (PaymentTerm, required)
        + invoice_generation (InvoiceGenerationCreate, required)
        + custom_fields (array[CustomFieldValue], optional)
        + document_template_id: `179e1564-493b-4305-8c54-a34fc80920fc` (string, optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `subscription` (string)
            + id: `e2314517-3cab-4aa9-8471-450e73449041` (string)

### subscriptions.update [POST /subscriptions.update]

Update a subscription.

+ Request (application/json)

    + Attributes (object)
        + id: `5b16f6ee-e302-0079-901b-50c26c4a55b1` (string, required)
        + starts_on: `2022-04-26` (string, optional) - can only be provided if no invoices have been created yet.
        + billing_cycle (object, optional) - can only be provided if no invoices have been created yet.
            + periodicity (Periodicity, required)
            + days_in_advance: `7` (enum[number], required)
                + Members
                    + 0
                    + 7
                    + 14
                    + 21
                    + 28
        + ends_on: `2022-05-26` (string, nullable, optional)
        + title: `Subscription for cookies` (string, optional)
        + invoicee (object, optional)
            + customer (Customer, required)
            + for_attention_of (object, optional)
                + One Of
                    + name: `Finance Dept.` (string, required)
                    + contact_id: `417a2231-c3c7-4e1c-a6bb-1b014836ca60` (string, required)
        + department_id: `6a6343fc-fdd8-4bc0-aa69-3a004c710e87` (string, optional)
        + payment_term (PaymentTerm, optional)
        + project_id: `cef01135-7e51-4f6f-a6eb-6e5e5a885ac8` (string, optional)
        + deal_id: `f6871b06-6513-4750-b5e6-ff3503b5a029` (string, optional)
        + note: `Subscription comments` (string, nullable, optional)
        + grouped_lines (array, optional)
            + (object)
                + section (object)
                    + title (string)
                + line_items (array, required)
                    + (LineItem)
        + invoice_generation (InvoiceGenerationUpdate, optional)
        + custom_fields (array[CustomFieldValue], optional)
        + document_template_id: `179e1564-493b-4305-8c54-a34fc80920fc` (string, optional)

+ Response 204

### subscriptions.deactivate [POST /subscriptions.deactivate]

+ Request (application/json)
    + Attributes (object)
        + id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, required)

+ Response 204

## Tax Rates [/taxRates]

Tax rates provide an overview of different taxation rates used to bill customers. Teamleader provides a default list of tax rates based on the country of residence of the company that’s using Teamleader. The end user also has the option to add additional tax rates.

### taxRates.list [POST /taxRates.list]

Get a list of available tax rates.

+ Request (application/json)

+ Attributes (object)
    + filter (object, optional)
        + department_id: `080aac72-ff1a-4627-bfe3-146b6eee979c` (string, optional) - The ID of the department you wish to filter on.
    + page (Page, optional)
    + sort (array, optional)
        + Default
            + (array)
                + (object)
                    + field: `department_id`
                    + order: `asc`
                + (object)
                    + field: `rate`
                    + order: `asc`
                + (object)
                    + field: `description`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `c93ddb52-0af8-47d9-8551-441435be66a7` (string)
                + description: `21%` (string)
                + rate: 0.21 (number)
                + department (object)
                    + type: `department` (string)
                    + id: `182af0a8-3f68-409b-8941-cf8caf8f28a0` (string)

## Payment Terms [/paymentTerms]

Payment terms are the conditions under which an invoice need to be paid.

### paymentTerms.list [POST /paymentTerms.list]

Get a list of available payment terms.

+ Request (application/json)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `c93ddb52-0af8-47d9-8551-441435be66a7` (string)
                + Include PaymentTerm
        + meta (object)
            + `default`: `c93ddb52-0af8-47d9-8551-441435be66a7` (string)

## Withholding Tax Rates [/withholdingTaxRates]

Withholding tax rates provide an overview of different taxation rates used to bill customers. Teamleader provides a default list of tax rates based on the country of residence of the company that’s using Teamleader. The countries that use withholding tax rates are Italy and Spain.

### withholdingTaxRates.list [POST /withholdingTaxRates.list]

Get a list of available withholding tax rates.

+ Request (application/json)

+ Attributes (object)
    + filter (object, optional)
        + department_id: `080aac72-ff1a-4627-bfe3-146b6eee979c` (string, optional) - The ID of the department you wish to filter on.

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `c93ddb52-0af8-47d9-8551-441435be66a7` (string)
                + department (object)
                    + type: `department` (string)
                    + id: `182af0a8-3f68-409b-8941-cf8caf8f28a0` (string)
                + description: `Ritenuta d'acconto 23% su 20%` (string)
                + rate: 0.046 (number)

## Commercial Discounts [/commercialDiscounts]

### commercialDiscounts.list [POST /commercialDiscounts.list]

Get a list of commercial discounts.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + department_id: `6a6343fc-fdd8-4bc0-aa69-3a004c710e87` (string, optional)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + name: `My holiday discount` (string)
                + department (object)
                    + type: `department` (string)
                    + id: `6a6343fc-fdd8-4bc0-aa69-3a004c710e87` (string)

## Payment Methods [/paymentMethods]

### paymentMethods.list [POST /paymentMethods.list]

+ Request (application/json)
    + Attributes (object)
        + filter (object, optional)
            + ids: `852bb293-9a61-05cb-ba3e-560212661144`, `1e8e3758-2c67-074a-911b-a93dd2a6af19` (array[string], optional)
            + status (array[enum], optional) - Filters on status
                + Members
                    + active
                    + archived
        + page (Page, optional)

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + id: `49b403be-a32e-0901-9b1c-25214f9027c6` (string)
                + name: `Coupons` (string)
                + status (enum, required)
                    + Members
                        + active
                        + archived

# Group Products

## Product Categories [/productCategories]

Product categories are used to group specific products. They can be linked to a ledger account, which is important for accounting.

*Required scopes: `products`*

### productCategories.list [POST /productCategories.list]

Get a list of product categories.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + department_id: `080aac72-ff1a-4627-bfe3-146b6eee979c` (string, optional) - The ID of the department you wish to filter on.

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `2aa4a6a9-9ce8-4851-a9b3-26aea2ea14c4` (string)
                + name: 'Asian Flowers' (string)
                + ledgers (array)
                    + (object)
                        + department (object)
                            + type: `department` (string)
                            + id: `2aa4a6a9-9ce8-4851-a9b3-26aea2ea14c6` (string)
                        + ledger_account_number: `70100` (string)

## Products [/products]

*Required scopes: `products`*

### products.list [POST /products.list]

Get a list of products.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `bbbfe0da-e692-4ee3-9d3d-0716808d6523`,`722e1eb9-53d5-4b8c-9d17-154dcc65c610` (array[string], optional)
            + term: `cookies` (string, optional) - Will filter on the name or the code.
            + updated_since: `2019-02-05T16:44:33+00:00` (string, optional)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `2aa4a6a9-9ce8-4851-a9b3-26aea2ea14c4` (string)
                + name: `cookies` (string, nullable)
                + description: `dark chocolate` (string, nullable) - The description of the product in Markdown
                + code: `COOK-DARKCHOC-42` (string, nullable)
                + unit (object, nullable)
                    + type: `unitOfMeasure` (string)
                    + id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string)
                + added_at: `2016-02-01T11:25:41+00:00` (string)
                + updated_at: `2016-02-01T11:25:41+00:00` (string)
                + stock (object, optional) - Only available when stock management feature is enabled
                    + amount: 123 (number, nullable)
                + configuration (ProductConfigurationRead, nullable)

### products.info [POST /products.info]

Get details for a single product.

+ Request (application/json)

    + Attributes (object)
        + id: `f8ae61ec-62f3-0538-b028-185c4a5f217f` (string)
        + includes: `suppliers` (string, optional) - Comma-separated list of optional includes

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `f8ae61ec-62f3-0538-b028-185c4a5f217f` (string)
            + name: `cookies` (string, nullable)
            + description: `dark chocolate` (string, nullable) - The description of the product in Markdown
            + code: `COOK-DARKCHOC-42` (string, nullable)
            + purchase_price (Money, nullable, optional) - The purchase price will only be returned if you have access to it
            + selling_price (Money, nullable)
            + unit (object, nullable)
                + type: `unitOfMeasure` (string)
                + id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string)
            + tax (object, nullable)
                + type: `taxRate` (string)
                + id: `df444ced-3129-0916-8f40-07ae5832bf98` (string)
            + suppliers (array, optional) - Only included with request parameter `includes=suppliers`
                + (object)
                    + supplier (object)
                        + type: `contact` (enum)
                            + Members
                                + company
                                + contact
                        + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)
                    + purchase_price (Money, nullable)
                    + product_code: `prod-111` (string)
                    + minimum_order_amount: `3` (number)
                    + classification (enum)
                        + Members
                            + primary
                            + secondary
            + custom_fields (array[CustomField])
            + price_list_prices (PriceListPricesRead)
            + product_category (object, nullable)
                + type: `productCategory` (string)
                + id: `e2314517-3cab-4aa9-8471-450e73449041` (string)
            + stock (object, optional) - Only available when stock management feature is enabled
                + amount: 123 (number, nullable)
            + configuration (ProductConfigurationRead, optional)
            + added_at: `2016-02-01T11:25:41+00:00` (string)
            + updated_at: `2016-02-01T11:25:41+00:00` (string)

### products.add [POST /products.add]

Add a new product.

+ Request (application/json)
    + Attributes (object)
        + One Of
            + Properties
                + name: `cookies` (string, required)
                + code: `COOK-DARKCHOC-42` (string, optional)
            + Properties
                + name: `cookies` (string, optional)
                + code: `COOK-DARKCHOC-42` (string, required)
        + description (string, optional) - The description of the product in Markdown
        + purchase_price (Money, optional)
        + selling_price (Money, optional)
        + unit_of_measure_id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string, optional, nullable)
        + price_list_prices (PriceListPricesWrite, optional)
        + stock (object, optional) - Only available when stock management feature is enabled
            + amount: 123 (number, nullable)
        + configuration (ProductConfigurationWrite, nullable)
        + department_id: `af48fe9e-d44c-0eac-8813-8be051b10921` (string, optional)
        + product_category_id: `624ca743-8998-4f8c-add1-c427bb022166` (string, optional)
        + tax_rate_id: `23097774-e51e-0371-9b42-98ef8ca8bbb6` (string, optional)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `product` (string)
            + id: `ee94b4c0-5786-0517-9d26-8dd1e6406f20` (string)

### products.update [POST /products.update]

Update a product.

+ Request (application/json)

    + Attributes (object)
        + id: `71e91f91-b222-033f-8c7e-59bcc1521e3d` (string, required)
        + name: `Hosting` (string, nullable, optional)
        + code: `c0d32` (string, nullable, optional)
        + purchase_price (Money, nullable, optional) - The currency must match the account currency
        + description: `Product used for hosting web solutions` (string, nullable, optional)
        + selling_price (Money, optional)
        + unit_of_measure_id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string, optional, nullable)
        + price_list_prices (PriceListPricesWrite, optional)
        + stock (object, optional) - Only available when stock management feature is enabled
            + amount: 123 (number, nullable)
        + configuration (ProductConfigurationWrite, nullable)
        + department_id: `af48fe9e-d44c-0eac-8813-8be051b10921` (string, optional)
        + product_category_id: `624ca743-8998-4f8c-add1-c427bb022166` (string, optional)
        + tax_rate_id: `23097774-e51e-0371-9b42-98ef8ca8bbb6` (string, optional)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 204

### products.delete [POST /products.delete]

Delete a product.

+ Request (application/json)

    + Attributes (object)
        + id: `71e91f91-b222-033f-8c7e-59bcc1521e3d` (string, required)

+ Response 204

# Units of Measure [/unitsOfMeasure]

### unitsOfMeasure.list [POST /unitsOfMeasure.list]

Get a list of units of measure.

+ Request (application/json)

+ Response 200 (application/json)
    + Attributes (object)
        + `data` (array)
            + (object)
                + id: `70af3fdd-b037-0936-ad1a-6d784dd44cf4` (string)
                + name: `kg` (string)

## Price Lists [/priceLists]

### priceLists.list [POST /priceLists.list]

Get a list of priceLists.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `5a37d173-78d3-05f3-b018-d51fadc1c5d2`,`97233974-7c29-05f5-a51d-fbe3238e6157` (array[string], optional)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `2aa4a6a9-9ce8-4851-a9b3-26aea2ea14c4` (string)
                + name: `price` (string)
                + calculation_method: `manual` (enum[string])
                    + Members
                        + manual
                        + based_on_price_list
                        + based_on_purchase_price

# Group Legacy Projects

> _This is the documentation of the legacy projects module. See the **New Projects** documentation for the endpoints concerning our new projects module._

## Legacy Projects [/projects]

Projects allow users to work together as a team on a single project. They consist of one or more milestones, have one or more participants and are limited in time and budget.

*Required scopes: `projects`*

### projects.list [POST /projects.list]

Get a list of projects.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + customer (object, optional)
                + type (enum, required)
                    + Members
                        + company
                        + contact
                + id: `ebafa4c5-fa8a-4409-92e5-1b192243372f` (string, required)
            + status (enum, optional)
                + Members
                    + active
                    + on_hold
                    + done
                    + cancelled
            + participant_id: `ed544eac-02e4-037b-8a1a-c8dd662bf621` (string, optional)
            + term: `coffee` (string, optional) - Searches for a term in title or description
            + updated_since: `2020-06-04T16:44:33+00:00` (string, optional)
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + due_on
                        + title
                        + created_at
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `due_on`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `624ca743-8998-4f8c-add1-c427bb022166` (string)
                + reference: `PRO-2` (string)
                + title: `New company website` (string)
                + description (string)
                + status: `active` (enum)
                    + Members
                        + active
                        + on_hold
                        + done
                        + cancelled
                + customer (object)
                    + type: `contact` (string)
                    + id: `abbf02c0-8ff9-4048-b83f-5195035161e1` (string)
                + starts_on: `2016-02-04` (string)
                + due_on: `2016-10-14` (string)
                + created_at: `2016-02-01T11:25:41+00:00` (string)
                + source (object)
                    + type: `deal` (string)
                    + id: `5023d7c2-80d7-4d4b-b2bd-0fcaa6a1f069` (string)
                + actuals (object) - Only accessible for administrators of this project
                    + `billable_amount` (Money)
                    + costs (Money)
                    + result (Money) - The billable amount minus the costs, so the profit or loss
                    + `profit_percentage` (number)
                + budget (object) - Only accessible for administrators of this project
                    + provided (Money)
                    + spent (object)
                        + total (Money)
                        + time (Money)
                        + materials (Money)
                    + remaining (Money)
                    + allocated (Money, nullable) - The amount of money still expected to be spent. This is null if there is not enough data to calculate
                    + forecasted (Money, nullable) - A prediction of the spent budget upon project completion. This is null if there is not enough data to calculate


### projects.info [POST /projects.info]

Get details for a single project.

+ Request (application/json)

    + Attributes (object)
        + id: `8a04371b-2ffb-407b-9b24-d5b5452009c7` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `8a04371b-2ffb-407b-9b24-d5b5452009c7` (string)
            + reference: `PRO-1` (string)
            + title: `New company website` (string)
            + description (string)
            + status: `active` (enum)
                + Members
                    + active
                    + on_hold
                    + done
                    + cancelled
            + customer (object)
                + type: `contact` (enum)
                    + Members
                        + contact
                        + company
                + id: `de41d3e8-808f-4279-b6ff-4706b04c8df2` (string)
            + starts_on: `2016-02-04` (string)
            + due_on: `2016-02-04` (string)
            + source (object)
                + type: `deal` (string)
                + id: `39abbf9e-9692-4cca-b20d-79577890752c` (string)
            + milestones (array)
                + (object)
                    + type: `milestone` (string)
                    + id: `7c6b5e26-3068-47a6-bf3b-431d7ab7e704` (string)
            + participants (array)
                + (object)
                    + participant (object)
                        + type: `user` (enum)
                            + Members
                                + user
                        + id: `b0ef899b-143c-4708-90ce-aecb3350e116` (string)
                    + role (enum)
                        + Members
                            + decision_maker
                            + member
            + purchase_order_number: `000023` (string, nullable)
            + custom_fields (array[CustomField])
            + actuals (object) - Only accessible for administrators of this project
                + `billable_amount` (Money)
                + costs (Money)
                + result (Money) - The billable amount minus the costs, so the profit or loss
                + `profit_percentage` (number)
            + budget (object) - Only accessible for administrators of this project
                + provided (Money)
                + spent (object)
                    + total (Money)
                    + time (Money)
                    + materials (Money)
                + remaining (Money)
                + allocated (Money, nullable) - The amount of money still expected to be spent. This is null if there is not enough data to calculate
                + forecasted (Money, nullable) - A prediction of the spent budget upon project completion. This is null if there is not enough data to calculate


### projects.create [POST /projects.create]

Create a new project.

+ Request (application/json)

    + Attributes (object)
        + title: `New company website` (string, required)
        + description (string, optional)
        + starts_on: `2016-02-04` (string, required)
        + milestones (array, required) - At least one milestone is required
            + (object)
                + starts_on: `2017-01-01` (string, optional, nullable)
                + due_on: `2018-01-01` (string, required)
                + name: `Initial setup` (string, required)
                + responsible_user_id: `e1240972-6cfc-4549-b49c-edda7568cc48` (string, required)
        + participants (array, required) - At least one decision making participant is required
            + (object)
                + participant (object, required)
                    + type: `user` (string, required)
                    + id: `e1240972-6cfc-4549-b49c-edda7568cc48` (string, required)
                + role (enum, optional)
                    + Members
                        + decision_maker
                        + member
                    + Default: `member`
        + purchase_order_number: `000023` (string, optional)
        + custom_fields (array[CustomFieldValue], optional)
        + customer (object, optional)
            + type (enum, required)
                + Members
                    + contact
                    + company
            + id: `ebafa4c5-fa8a-4409-92e5-1b192243372f` (string, required)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `project` (string)
            + id: `c47e8e40-9a16-468f-9b29-38aea8ae4210` (string)


### projects.update [POST /projects.update]

Update a project.

+ Request (application/json)

    + Attributes (object)
        + id: `dcc2e8ed-51be-4cb6-9c01-034aedac86fd` (string, required)
        + title: `New company website` (string)
        + description (string)
        + status: `active` (enum)
            + Members
                + active
                + on_hold
                + done
                + cancelled
        + starts_on: `2016-02-04` (string)
        + customer (object, nullable) - Null will unlink the customer from the project
            + type: `company` (enum)
                + Members
                    + contact
                    + company
            + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
        + budget (Money)
        + purchase_order_number: `000023` (string, nullable)
        + custom_fields (array[CustomFieldValue])

+ Response 204


### projects.close [POST /projects.close]

Closes a project, all its phases, and all tasks within each phase (but not meetings).

+ Request (application/json)

    + Attributes (object)
        + id: `01548b10-4932-4a18-8a89-005ad09db2c8` (string, required)

+ Response 204


### projects.reopen [POST /projects.reopen]

Reopens a project, changing its status to "active".

+ Request (application/json)

    + Attributes (object)
        + id: `01548b10-4932-4a18-8a89-005ad09db2c8` (string, required)

+ Response 204


### projects.delete [POST /projects.delete]

Delete a project.

+ Request (application/json)

    + Attributes (object)
        + id: `01548b10-4932-4a18-8a89-005ad09db2c8` (string, required)

+ Response 204


### projects.addParticipant [POST /projects.addParticipant]

Add a participant to a project.

+ Request (application/json)

    + Attributes (object)
        + id: `8dbfa9db-c53f-410c-97d3-755b19685809` (string, required)
        + participant (object, required)
            + type: `user` (string)
            + id: `a1388f3d-6116-4792-ac1c-04657697539e` (string)
        + role (enum, optional)
            + Members
                + decision_maker
                + member
            + Default: `member`

+ Response 204


### projects.updateParticipant [POST /projects.updateParticipant]

Update a participant's role for a project.

+ Request (application/json)

    + Attributes (object)
        + id: `55fbe14f-7399-48e5-b4e0-64b7f5c50451` (string, required)
        + participant (object, optional)
            + type: `user` (string)
            + id: `5ccbc008-f65e-4192-836c-4d7e21f54052` (string)
        + role (enum, required)
            + Members
                + decision_maker
                + member

+ Response 204

## Legacy Milestones [/milestones]

Every projects consists of one or more milestones which are limited in time and budget. Budget is however not included in this endpoints (yet).

*Required scopes: `projects`*

### milestones.list [POST /milestones.list]

Get a list of project milestones.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `bbbfe0da-e692-4ee3-9d3d-0716808d6523`,`722e1eb9-53d5-4b8c-9d17-154dcc65c610` (array[string], optional)
            + project_id: `082e6289-30c5-45ad-bcd0-190b02d21e81` (string, optional)
            + status (enum, optional)
                + Members
                    + open
                    + closed
            + due_before: `2017-01-01` (string, optional)
            + due_after: `2017-01-01` (string, optional)
            + term: `coffee` (string, optional) - Searches for a term in title
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + `starts_on`
                        + `due_on`
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `due_on`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `cfb4146d-06be-41f1-bb39-aa3c929c71dc` (string)
                + project (object)
                    + type: `project` (string)
                    + id: `944534fb-15f1-4eea-aab1-82a427aa2d0d` (string)
                + starts_on: `2017-01-01` (string, nullable)
                + due_on: `2018-01-01` (string)
                + name: `Initial setup` (string)
                + responsible_user (object)
                    + type: `user` (string)
                    + id: `e1240972-6cfc-4549-b49c-edda7568cc48` (string)
                + status: `open` (enum)
                    + Members
                        + open
                        + closed
                + `invoicing_method`: `time_and_materials` (enum)
                    + Members
                        + time_and_materials
                        + fixed_price
                        + non_invoiceable
                + depends_on (object, nullable)
                    + type: `milestone` (string)
                    + id: `0488d792-ba9b-059f-bd57-bea75d3f4f4e` (string)
                + dependency_for (array)
                    + (object)
                        + type: `milestone` (string)
                        + id: `b71ff11f-074e-0705-9450-589342af4f4f` (string)
                + actuals (object) - Only accessible for administrators of the project this milestone belongs to
                    + `billable_amount` (Money)
                    + costs (Money)
                    + result (Money) - The billable amount minus the costs, so the profit or loss
                + budget (object) - Only accessible for administrators of the project this milestone belongs to
                    + provided (Money)
                    + spent (Money)
                    + remaining (Money)
                    + allocated (Money, nullable) - The amount of money still expected to be spent. This is null if there is not enough data to calculate
                    + forecasted (Money, nullable) - A prediction of the spent budget upon milestone completion. This is null if there is not enough data to calculate

### milestones.info [POST /milestones.info]

Get details for a single milestone.

+ Request (application/json)

    + Attributes (object)
        + id: `64349fa2-6ca2-4b19-82e6-d3258ceab2d8` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `64349fa2-6ca2-4b19-82e6-d3258ceab2d8` (string)
            + project (object)
                + type: `project` (string)
                + id: `fffaf951-b65a-4cb1-bfb6-4b93e0e60c10` (string)
            + starts_on: `2017-01-01` (string, nullable)
            + due_on: `2018-01-01` (string)
            + name: `Initial setup` (string)
            + description (string)
            + responsible_user (object)
                + type: `user` (string)
                + id: `e1240972-6cfc-4549-b49c-edda7568cc48` (string)
            + status: `open` (enum)
                + Members
                    + open
                    + closed
            + `invoicing_method`: `time_and_materials` (enum)
                + Members
                    + time_and_materials
                    + fixed_price
                    + non_invoiceable
            + depends_on (object, nullable)
                + type: `milestone` (string)
                + id: `0488d792-ba9b-059f-bd57-bea75d3f4f4e` (string)
            + dependency_for (array)
                + (object)
                    + type: `milestone` (string)
                    + id: `b71ff11f-074e-0705-9450-589342af4f4f` (string)
            + actuals (object) - Only accessible for administrators of the project this milestone belongs to
                + `billable_amount` (Money)
                + costs (Money)
                + result (Money) - The billable amount minus the costs, so the profit or loss
            + budget (object) - Only accessible for administrators of the project this milestone belongs to
                + provided (Money)
                + spent (Money)
                + remaining (Money)
                + allocated (Money, nullable) - The amount of money still expected to be spent. This is null if there is not enough data to calculate
                + forecasted (Money, nullable) - A prediction of the spent budget upon milestone completion. This is null if there is not enough data to calculate
            + custom_fields (array[CustomField])

### milestones.create [POST /milestones.create]

Create a new milestone.

+ Request (application/json)

    + Attributes (object)
        + project_id: `1c159f98-4b07-438a-9f42-fb4206b9530d` (string, required)
        + starts_on: `2017-01-01` (string, optional, nullable)
        + due_on: `2018-01-01` (string, required)
        + name: `Initial setup` (string, required)
        + description (string, optional)
        + responsible_user_id: `e1240972-6cfc-4549-b49c-edda7568cc48` (string, required)
        + One Of
            + Properties
                + `billing_method` (enum)
                    + Members
                        + `non_invoiceable`
                        + `time_and_materials`
                    + Default
                        + `time_and_materials`
                + budget (Money) - If omitted, the budget will default to zero
            + Properties
                + `billing_method`: `fixed_price` (string, required)
                + price (Money, required)
        + depends_on: `0488d792-ba9b-059f-bd57-bea75d3f4f4e` (string, nullable)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `milestone` (string)
            + id: `51f19f91-6343-4001-a628-3afe45f674ad` (string)

### milestones.update [POST /milestones.update]

Update a milestone.

+ Request (application/json)

    + Attributes (object)
        + id: `67e80ad8-d14f-4510-a2bd-a4c6aa578c37` (string, required)
        + starts_on: `2017-01-01` (string, optional, nullable)
        + due_on: `2018-01-01` (string, optional)
        + name: `Initial setup` (string, optional)
        + description (string, optional)
        + responsible_user_id: `e1240972-6cfc-4549-b49c-edda7568cc48` (string, optional)
        + depends_on: `0488d792-ba9b-059f-bd57-bea75d3f4f4e` (string, nullable)
        + propagate_date_changes: false (boolean, optional)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 204

### milestones.delete [POST /milestones.delete]

Delete a milestone.

+ Request (application/json)

    + Attributes (object)
        + id: `67e80ad8-d14f-4510-a2bd-a4c6aa578c37` (string, required)

+ Response 204

### milestones.close [POST /milestones.close]

Close a milestone. All open tasks will be closed, open meetings will remain open. Closing the last open milestone will also close the project.

+ Request (application/json)

    + Attributes (object)
        + id: `67e80ad8-d14f-4510-a2bd-a4c6aa578c37` (string, required)

+ Response 204

### milestones.open [POST /milestones.open]

(Re)open a milestone. If the milestone's project is closed, the project will be reopened.

+ Request (application/json)

    + Attributes (object)
        + id: `67e80ad8-d14f-4510-a2bd-a4c6aa578c37` (string, required)

+ Response 204

# Group New Projects

## Projects [/projects-v2/projects]

> _This is the documentation of the new projects module. See the **Legacy Projects** documentation for the endpoints concerning our legacy projects module._

> ⚠️ (July 2023) The projects module has been completely overhauled and is currently only available for new project users. Existing project users only have access to the old projects module.
> Over the course of the next few months, next generation projects will also be made available to existing project users, including the migration of existing project data.

> To avoid naming collisions, all endpoints of the new projects module can be found under `/projects-v2`, for example `/projects-v2/projects.list`.
> To avoid confusing "new projects" with "creating a new project", we opted for "projects-v2" over "new" as the prefix.

*Required scopes: `projects`*

### projects.list [POST /projects-v2/projects.list]

Lists all projects that match the optional filters provided.

+ Request (application/json)
    + Attributes (object)
        + filter (object)
            + `ids`: `46156648-87c6-478d-8aa7-1dc3a00dacab`, `46156648-87c6-478d-8aa7-1dc3a00daca4` (array[string])
            + `status`: `open` (enum[string])
                + Members
                    + `open - Only shows open projects
                    + `planned` - Projects where the start date is in the future
                    + `running` - Projects where the start date is in the past, but the end date is in the future or empty
                    + `overdue` - Projects where the end date is in the past
                    + `over_budget` - Projects where the price is higher than the external budget, or where the cost is higher than the internal budget
                    + `closed` - Projects that are closed
            + `quotation_ids`: `132c7189-6e49-420c-889c-23267ce70660`, `cd740bde-d317-4c97-bec0-76bfad903a1e` (array[string])
            + `deal_ids`: `7ea73287-9f87-4b2b-b6f8-866b12b7364a`, `68f8bb28-e5d0-4ee2-b269-1dbeeda5bdcc` (array[string])
            + `term`: `Interesting project` (string, optional) - Filters on the project number, title, customer names, assignee names and owner names. Terms are split on spaces and all terms need to match.
            + `customers` (array)
                + (object)
                    + `type`: `contact` (enum[string])
                        + Members
                            + `contact`
                            + `company`
                    + `id`: `1106f231-0464-41b7-8b0b-19451af81afe` (string)
        + `page` (Page, optional)
        + `sort` (array, optional) - Sorting on `cost` or `margin` is only available to administrators and users with the "Costs on projects" permission
            + (object)
                + field (enum[string], required)
                    + Members
                        + `amount_billed`
                        + `amount_paid`
                        + `amount_unbilled`
                        + `cost`
                        + `end_date`
                        + `external_budget_spent`
                        + `external_budget`
                        + `internal_budget`
                        + `margin`
                        + `price`
                        + `project_key`
                        + `start_date`
                        + `status`
                        + `time_budget`
                        + `time_estimated`
                        + `time_tracked`
                        + `title`
                + order (enum[string], optional)
                    + Members
                        + `asc`
                        + `desc`
            + Default
                + (object)
                    + field: `project_key`
                    + order: `desc`
        + includes: `legacy_project,custom_fields` (string, optional) - Comma-separated list of optional includes

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + id: `49b403be-a32e-0901-9b1c-25214f9027c6` (string)
                + `project_key`: 123 (number) - Positive, sequential integer representing the index of the project for the account
                + title: `My project title` (string)
                + description: `My project description` (string, nullable)
                + status: `open` (enum[string])
                    + Members
                        + open
                        + closed
                + `billing_method`: `time_and_materials` (enum)
                    + Members
                        + `time_and_materials`
                        + `fixed_price`
                        + `non_billable`
                + `time_budget` (object, nullable) - Value in seconds, rounded to the nearest minute
                    + value: 43200 (number)
                    + unit: `seconds` (enum[string])
                        + Members
                            + seconds
                + `time_estimated` (object, nullable) - Combined value of all time estimated by lines linked to project, value in seconds, rounded to the nearest minute.
                    + value: 43200 (number)
                    + unit: `seconds` (enum[string])
                        + Members
                            + seconds
                + `time_tracked` (object, nullable)
                    + `value`: 43200 (number)
                    + `unit`: `seconds` (enum[string])
                        + Members
                            + `seconds`
                + `amount_billed` (Money, nullable)
                + `amount_unbilled` (Money, nullable) - Price of the project minus the amount billed
                + `fixed_amount_billed` (Money, nullable)
                + `amount_paid` (Money, nullable)
                + `external_budget` (Money, nullable) - Also known as "budget". Value set by user to compare with price
                + `external_budget_spent` (Money, nullable) - Simulated price if billing method were `time_and_materials` (dependent on type)
                + `internal_budget` (Money, nullable) - Also known as "cost budget". Value set by user to compare with cost
                + `price` (Money, nullable)
                + `fixed_price` (Money, nullable)
                + `calculated_price` (Money, nullable) - Sum of underlying tasks/materials prices
                + `cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
                + `margin` (Money, nullable) - Can be a negative (less than zero) amount, `null` if the user does not have access to "Costs on projects"
                + `margin_percentage` (number, nullable) - `null` if the user does not have access to "Costs on projects"
                + `start_date`: `2022-02-23` (string, nullable)
                + `end_date`: `2022-02-28` (string, nullable)
                + `company_entity` (object, nullable)
                    + `type`: `department` (string)
                    + `id`: `0d0dec5a-7096-4009-be37-07eab117db07` (string)
                + `owners` (array)
                    + (object)
                        + `type`: `user` (string)
                        + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                + `color`: `#00B2B2` (enum[string])
                    + Members
                        + `#00B2B2` - Mint
                        + `#008A8C` - Darker mint
                        + `#992600` - Ruby
                        + `#ED9E00` - Gold
                        + `#D157D3` - Purple
                        + `#A400B2` - Darker purple
                        + `#0071F2` - Aqua
                        + `#004DA6` - Darker aqua
                        + `#64788F` - Blue grey
                        + `#C0C0C4` - Light grey
                        + `#82828C` - Grey
                        + `#1A1C20` - Dark grey
                + `assignees` (array)
                    + (object)
                        + `assignee` (object)
                            + `type`: `user` (enum[string])
                                + Members
                                    + `team`
                                    + `user`
                            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                        + `assign_type`: `auto_assigned` (enum)
                            + Members
                                + `manual`
                                + `auto_assigned` - This user/team is included because they are assigned to underlying groups, tasks or materials.
                                + `manual_and_auto_assigned` - This user/team is both manually assigned and included because they are assigned to underlying groups, tasks or materials.
                + `customers` (array)
                    + (object)
                        + `type`: `contact` (enum[string])
                            + Members
                                + `contact`
                                + `company`
                        + `id`: `1106f231-0464-41b7-8b0b-19451af81afe` (string)
                + `deals` (array)
                    + (object)
                        + `type`: `deal` (string)
                        + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                + `quotations` (array)
                    + (object)
                        + `type`: `quotation` (string)
                        + `id`: `a7f15c40-3b65-09ae-9f1b-d55786bc7b01` (string)
                + `legacy_project` (object, nullable) - Only included if `legacy_project` is in the optional includes. `null` if there is no corresponding legacy project
                    + type: `project` (string)
                    + id: `624ca743-8998-4f8c-add1-c427bb022166` (string)
                + `custom_fields` (array[CustomField]) - Only included with request parameter `includes=custom_fields`
        + `meta` (object) - Only included with request parameter `includes=pagination`
            + `page` (Pagination)
            + `matches`: `10` (number)

### projects.info [POST /projects-v2/projects.info]

Returns all the information of a single project.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + includes: `legacy_project` (string, optional) - Comma-separated list of optional includes

+ Response 200 (application/json)
    + Attributes (object)
        + data (object)
            + `id`: `49b403be-a32e-0901-9b1c-25214f9027c6` (string)
            + `project_key`: 123 (number) - Positive, sequential integer representing the index of the project for the account
            + `title`: `My project title` (string)
            + `description`: `My project description` (string, nullable)
            + `status`: `open` (enum[string])
                + Members
                    + open
                    + closed
            + `update_rights`: `owners` (enum[string])
                + Members
                    + owners
                    + owners_and_assignees
                    + everyone
            + `billing_method`: `time_and_materials` (enum)
                + Members
                    + `time_and_materials`
                    + `fixed_price`
                    + `non_billable`
            + `time_budget` (object, nullable) - Value in seconds, rounded to the nearest minute
                + value: 43200 (number)
                + unit: `seconds` (enum[string])
                    + Members
                        + seconds
            + `time_tracked` (object, nullable)
                + `value`: 43200 (number)
                + `unit`: `seconds` (enum[string])
                    + Members
                        + `seconds`
            + `amount_billed` (Money, nullable)
            + `fixed_amount_billed` (Money, nullable)
            + `amount_paid` (Money, nullable)
            + `external_budget` (Money, nullable) - Also known as "budget". Value set by user to compare with price
            + `task_external_budget_spent` (Money, nullable) - Sum of underlying tasks `external_budget_spent` field
            + `material_external_budget_spent` (Money, nullable) - Sum of underlying materials `external_budget_spent` field
            + `external_budget_spent` (Money, nullable) - Simulated price if billing method were `time_and_materials` (dependent on type)
            + `internal_budget` (Money, nullable) - Also known as "cost budget". Value set by user to compare with cost
            + `price` (Money, nullable)
            + `fixed_price` (Money, nullable)
            + `calculated_price` (Money, nullable) - Sum of underlying tasks/materials prices
            + `cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
            + `margin` (Money, nullable) - Can be a negative (less than zero) amount, `null` if the user does not have access to "Costs on projects"
            + `margin_percentage` (number, nullable) - `null` if the user does not have access to "Costs on projects"
            + `start_date`: `2022-02-23` (string, nullable)
            + `end_date`: `2022-02-28` (string, nullable)
            + `purchase_order_number`: `000023` (string, nullable)
            + `company_entity` (object, nullable)
                + `type`: `department` (string)
                + `id`: `0d0dec5a-7096-4009-be37-07eab117db07` (string)
            + `owners` (array)
                + (object)
                    + `type`: `user` (string)
                    + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
            + `color`: `#00B2B2` (enum[string])
                + Members
                    + `#00B2B2` - Mint
                    + `#008A8C` - Darker mint
                    + `#992600` - Ruby
                    + `#ED9E00` - Gold
                    + `#D157D3` - Purple
                    + `#A400B2` - Darker purple
                    + `#0071F2` - Aqua
                    + `#004DA6` - Darker aqua
                    + `#64788F` - Blue grey
                    + `#C0C0C4` - Light grey
                    + `#82828C` - Grey
                    + `#1A1C20` - Dark grey
            + `assignees` (array)
                + (object)
                    + `assignee` (object)
                        + `type`: `user` (enum[string])
                            + Members
                                + `team`
                                + `user`
                        + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                    + `assign_type`: `auto_assigned` (enum)
                        + Members
                            + `manual`
                            + `auto_assigned` - This user/team is included because they are assigned to underlying groups, tasks or materials.
                            + `manual_and_auto_assigned` - This user/team is both manually assigned and included because they are assigned to underlying groups, tasks or materials.
            + `customers` (array)
                + (object)
                    + `type`: `contact` (enum[string])
                        + Members
                            + `contact`
                            + `company`
                    + `id`: `1106f231-0464-41b7-8b0b-19451af81afe` (string)
            + `deals` (array)
                + (object)
                    + `type`: `deal` (string)
                    + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
            + `quotations` (array)
                + (object)
                    + `type`: `quotation` (string)
                    + `id`: `a7f15c40-3b65-09ae-9f1b-d55786bc7b01` (string)
            + `custom_user_rates` (array)
                + (object)
                    + `user` (object)
                        + `type`: `user` (string)
                        + `id`: `55d3707c-14dc-4b62-a072-e3f4c1413462` (string)
                    + `custom_rate` (Money)
            + custom_fields (array[CustomField]) - Auto-increment custom fields are not supported on projects.
            + `legacy_project` (object, nullable) - Only included if `legacy_project` is in the optional includes. `null` if there is no corresponding legacy project
                + type: `project` (string)
                + id: `624ca743-8998-4f8c-add1-c427bb022166` (string)

### projects.create [POST /projects-v2/projects.create]

Create a new project. Only `title` is required. All the other fields are optional.

+ Request (application/json)
    + Attributes (object)
        + `title`: `My cool new project` (string, required)
        + `description`: `My project description` (string, optional)
        + `owner_ids`: `47e7e4a2-607d-465b-a121-7bdc9c64ade7`, `d8ebc8a5-800f-4714-97bb-3947a7ec274d` (array[string], optional) - The creator is automatically added as an owner, these are additional owners to be added
        + `time_budget` (object, optional)
            + value: 43200 (number, required)
            + unit: `minutes` (enum[string], required)
                + Members
                    + `hours`
                    + `minutes`
                    + `seconds`
        + `billing_method` (enum[string], optional)
            + Members
                + `time_and_materials`
                + `fixed_price`
                + `non_billable`
        + `external_budget` (Money, optional) - Also known as "budget". Value set by user to compare with price. Must be higher than or equal to zero, and lower than 100000000000 (100 billion). Only allowed for `time_and_materials` billing method. Currently only EUR is supported
        + `internal_budget` (Money, optional) - Also known as "cost budget". Value set by user to compare with cost. Must be higher than or equal to zero, and lower than 100000000000 (100 billion).
        + `fixed_price` (Money, optional) - Must be higher than or equal to zero, and lower than 100000000000 (100 billion). Only allowed for `fixed_price` billing method. Currently only EUR is supported
        + `start_date`: `2022-02-23` (string, optional) - Should not be after end_date if provided
        + `end_date`: `2022-02-28` (string, optional) - Should not be before start_date if provided
        + `purchase_order_number`: `000023` (string, optional)
        + `company_entity_id`: `0d0dec5a-7096-4009-be37-07eab117db07` (string, optional)
        + `color`: `#00B2B2` (enum[string], optional)
            + Members
                + `#00B2B2` - Mint
                + `#008A8C` - Darker mint
                + `#992600` - Ruby
                + `#ED9E00` - Gold
                + `#D157D3` - Purple
                + `#A400B2` - Darker purple
                + `#0071F2` - Aqua
                + `#004DA6` - Darker aqua
                + `#64788F` - Blue grey
                + `#C0C0C4` - Light grey
                + `#82828C` - Grey
                + `#1A1C20` - Dark grey
        + `customers` (array, optional)
            + (object)
                + `type`: `company` (enum, required)
                    + Members
                        + `contact`
                        + `company`
                + `id`: `9cb3e568-3931-4b8f-8db8-5a002e8cf253` (string, required)
        + `assignees` (array, optional)
            + (object)
                + `type`: `user` (enum[string], required)
                    + Members
                        + `user`
                        + `team`
                + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)
        + `deal_ids`: `3709b7e9-7722-4d2d-a663-b480789bafe4`, `39fb2767-90e0-4fe4-9bac-a244bee6552c` (array[string], optional)
        + `quotation_ids`: `e8e8e969-2054-49ee-81d1-47453de2aebb`, `fc41c04f-1841-4238-a31b-42c48c57713e` (array[string], optional)
        + `initial_time_tracked` (object, optional)
            + value: 43200 (number, required)
            + unit: `minutes` (enum[string], required)
                + Members
                    + `hours`
                    + `minutes`
                    + `seconds`
        + `initial_price` (Money, optional) - Must be higher than or equal to zero, and lower than 100000000000 (100 billion).
        + `initial_cost` (Money, optional) - Must be higher than or equal to zero, and lower than 100000000000 (100 billion).
        + `initial_amount_billed` (Money, optional) - Must be higher than or equal to zero, and lower than 100000000000 (100 billion).
        + `initial_amount_paid` (Money, optional) - Must be higher than or equal to zero, and lower than 100000000000 (100 billion).
        + `custom_fields` (array[CustomFieldValue], optional) - Auto-increment custom fields are not supported on projects.

+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
           + type: `nextgenProject` (string)
           + id: `49b403be-a32e-0901-9b1c-25214f9027c6` (string)

### projects.update [POST /projects-v2/projects.update]

Update a project. All attributes except for `id` are optional. Providing `null` will clear that value from the project (for properties that are nullable).

+ Request (application/json)
    + Attributes (object)
        + id: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + title: `A different project title` (string)
        + description: `Another description` (string, nullable)
        + `time_budget` (object, nullable)
            + value: 60 (number, required)
            + unit: `minutes` (enum[string], required)
                + Members
                    + hours
                    + minutes
                    + seconds
        + `billing_method` (object)
            + `value`: `time_and_materials` (enum[string], required)
                + Members
                    + `time_and_materials` - Can only be set using update_strategy "none"
                    + `fixed_price`
                    + `non_billable` - Can only be set using update_strategy "cascade"
            + `update_strategy`: `none` (enum[string], required)
                + Members
                    + `none` - Don't change the values of the group items.
                    + `cascade` - Change the billing method of the group, tasks and materials linked to this project, depending on the project billing method.
        + `external_budget` (Money, nullable) - Also known as "budget". Value set by user to compare with price. Must be higher than or equal to zero, and lower than 100000000000 (100 billion). Only allowed for `time_and_materials` billing method. Currently only EUR is supported
        + `internal_budget` (Money, nullable) - Also known as "cost budget". Value set by user to compare with cost. Must be higher than or equal to zero, and lower than 100000000000 (100 billion).
        + `fixed_price` (Money, nullable) - Must be higher than or equal to zero, and lower than 100000000000 (100 billion). Only allowed for `fixed_price` billing method. Currently only EUR is supported
        + `start_date`: `2022-02-23` (string, nullable) - Should not be after end_date if provided
        + `end_date`: `2022-02-28` (string, nullable) - Should not be before start_date if provided
        + `purchase_order_number`: `000023` (string, nullable)
        + `company_entity_id`: `0d0dec5a-7096-4009-be37-07eab117db07` (string, nullable, optional)
        + `color`: `#00B2B2` (enum[string])
            + Members
                + `#00B2B2` - Mint
                + `#008A8C` - Darker mint
                + `#992600` - Ruby
                + `#ED9E00` - Gold
                + `#D157D3` - Purple
                + `#A400B2` - Darker purple
                + `#0071F2` - Aqua
                + `#004DA6` - Darker aqua
                + `#64788F` - Blue grey
                + `#C0C0C4` - Light grey
                + `#82828C` - Grey
                + `#1A1C20` - Dark grey
        + `custom_fields` (array[CustomFieldValue], optional) - Auto-increment custom fields are not supported on projects.

+ Response 204

### projects.close [POST /projects-v2/projects.close]

Mark a project as closed.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `closing_strategy` (enum[string], required)
            + Members
                + `mark_tasks_and_materials_as_done`
                + `none`

+ Response 204

### projects.reopen [POST /projects-v2/projects.reopen]

Reopen a closed project.

+ Request (application/json)
    + Attributes (object)
        + id: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)

+ Response 204

### projects.duplicate [POST /projects-v2/projects.duplicate]

Duplicate a project.

+ Request (application/json)
    + Attributes (object)
        + `id`: `81df9996-6d2c-4844-86d6-202c08d2837e` (string, required)
        + `title`: `Copy of my project` (string, required)

+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
           + `type`: `nextgenProject` (string)
           + `id`: `49b403be-a32e-0901-9b1c-25214f9027c6` (string)

### projects.delete [POST /projects-v2/projects.delete]

Delete a project.

+ Request (application/json)
   + Attributes (object)
       + `id`: `81df9996-6d2c-4844-86d6-202c08d2837e` (string, required)
       + `delete_strategy`: `unlink_tasks_and_time_trackings` (enum[string], required)
           + Members
               + `unlink_tasks_and_time_trackings`
               + `delete_tasks_and_time_trackings`
               + `delete_tasks_unlink_time_trackings`

+ Response 204

### projects.addOwner [POST /projects-v2/projects.addOwner]

Add a user as owner. Doesn't fail if the user was already added.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `user_id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

### projects.removeOwner [POST /projects-v2/projects.removeOwner]

Remove a user as owner. Doesn't fail if the user wasn't linked.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `user_id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

### projects.assign [POST /projects-v2/projects.assign]

Assign a user or a team to a project.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `assignee` (object, required)
            + `type`: `user` (enum[string], required)
                + Members
                    + user
                    + team
            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

### projects.unassign [POST /projects-v2/projects.unassign]

Unassign a user or a team from a project.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `assignee` (object, required)
            + `type`: `user` (enum[string], required)
                + Members
                    + user
                    + team
            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

### projects.addCustomer [POST /projects-v2/projects.addCustomer]

Add a customer to the project. Doesn't fail if the customer was already added.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `customer` (object, required)
            + `type`: `contact` (enum[string], required)
                + Members
                    + `contact`
                    + `company`
            + `id`: `03148b5d-4cb0-4750-a3f2-8697cf8bce10` (string, required)

+ Response 204

### projects.removeCustomer [POST /projects-v2/projects.removeCustomer]

Remove a customer from the project. Doesn't fail if the customer was not added.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `customer` (object, required)
            + `type`: `contact` (enum[string], required)
                + Members
                    + `contact`
                    + `company`
            + `id`: `03148b5d-4cb0-4750-a3f2-8697cf8bce10` (string, required)

+ Response 204

### projects.addDeal [POST /projects-v2/projects.addDeal]

Add a deal to the project. Doesn't fail if the deal was already added.

+ Request (application/json)
    + Attributes (object)
        + `id`: `d27909aa-fc0e-4ed4-acec-fcbffda5111b` (string, required)
        + `deal_id`: `8385b072-587f-4ebf-a32b-5f48baea1b1c` (string, required)

+ Response 204

### projects.removeDeal [POST /projects-v2/projects.removeDeal]

Remove a deal from the project. Doesn't fail if the deal was already removed.

+ Request (application/json)
    + Attributes (object)
        + `id`: `d27909aa-fc0e-4ed4-acec-fcbffda5111b` (string, required)
        + `deal_id`: `8385b072-587f-4ebf-a32b-5f48baea1b1c` (string, required)

+ Response 204

### projects.addQuotation [POST /projects-v2/projects.addQuotation]

Add a quotation to the project. Doesn't fail if the quotation was already added.

+ Request (application/json)
    + Attributes (object)
        + `id`: `d27909aa-fc0e-4ed4-acec-fcbffda5111b` (string, required)
        + `quotation_id`: `8385b072-587f-4ebf-a32b-5f48baea1b1c` (string, required)

+ Response 204

### projects.removeQuotation [POST /projects-v2/projects.removeQuotation]

Remove a quotation from the project. Doesn't fail if the quotation was already removed.

+ Request (application/json)
    + Attributes (object)
        + `id`: `d27909aa-fc0e-4ed4-acec-fcbffda5111b` (string, required)
        + `quotation_id`: `8385b072-587f-4ebf-a32b-5f48baea1b1c` (string, required)

+ Response 204

## Project lines [/projects-v2/projectLines]

> A project line can be a group, a task, or a material.
> The `projectLines.list` endpoint only returns `{id, type}` pairs of those lines.

*Required scopes: `projects`*

### projectLines.list [POST /projects-v2/projectLines.list]

All line types (tasks, materials, groups) can be side-loaded.

+ Request (application/json)
    + Attributes (object)
        + `project_id`: `49b403be-a32e-0901-9b1c-25214f9027c6` (string, required)
        + `filter` (object, optional)
            + `types` (array)
                + Members
                    + `nextgenTask`
                    + `nextgenMaterial`
                    + `nextgenProjectGroup`
            + `assignees` (array, optional) - To fetch unassigned lines, provide `null` instead of the type/id object
                + (object)
                    + `type`: `user` (enum[string], required)
                        + Members
                            + user
                            + team
                    + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + `line` (object)
                    + `type`: `nextgenMaterial` (enum[string])
                        + Members
                            + `nextgenTask`
                            + `nextgenMaterial`
                            + `nextgenProjectGroup`
                    + `id`: `a14a464d-320a-49bb-b6ee-b510c7f4f66c` (string)
                + `group` (object, nullable) - If null, this line is not a part of a group.
                    + `type`: `nextgenProjectGroup` (string)
                    + `id`: `a14a464d-320a-49bb-b6ee-b510c7f4f66c` (string)

### projectLines.addToGroup [POST /projects-v2/projectLines.addToGroup]

Add an existing task or material to a group.

+ Request (application/json)
    + Attributes (object)
        + `line_id`: `a14a464d-320a-49bb-b6ee-b510c7f4f66c` (string, required) - The ID of the task or material. May not be a group.
        + `group_id`: `0daf76e6-5141-4fb0-866f-01916a873a38` (string, required)

+ Response 204

### projectLines.removeFromGroup [POST /projects-v2/projectLines.removeFromGroup]

Remove a task or material from the group it is currently in.

+ Request (application/json)
    + Attributes (object)
        + `line_id`: `a14a464d-320a-49bb-b6ee-b510c7f4f66c` (string, required) - The ID of the task or material. May not be a group.

+ Response 204

## Groups [/projects-v2/projectGroups]

*Required scopes: `projects`*

### projectGroups.list [POST /projects-v2/projectGroups.list]

Lists all the groups that match the optional filters provided.

+ Request (application/json)
    + Attributes (object)
        + filter (object)
            + `ids`: `0185a0af-97a6-7f44-8aec-254d8daf72f3`, `0185a0c3-b791-7629-8361-d60f3c0d7ce2` (array[string])
            + `project_id`: `01859b27-1525-7372-bd40-26a6363c8bfe` (string)

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + `id`: `0185a0af-97a6-7f44-8aec-254d8daf72f3` (string)
                + `project` (object)
                    + `type`: `nextgenProject` (string)
                    + `id`: `018536c0-bf23-77eb-81f5-10e87cad50bc` (string)
                + `title`: `Website frontpage` (string)
                + `color`: `#00B2B2` (enum[string])
                    + Members
                        + `#00B2B2` - Mint
                        + `#008A8C` - Darker mint
                        + `#992600` - Ruby
                        + `#ED9E00` - Gold
                        + `#D157D3` - Purple
                        + `#A400B2` - Darker purple
                        + `#0071F2` - Aqua
                        + `#004DA6` - Darker aqua
                        + `#64788F` - Blue grey
                        + `#C0C0C4` - Light grey
                        + `#82828C` - Grey
                        + `#1A1C20` - Dark grey
                + `billing_method`: `time_and_materials` (enum[string])
                    + Members
                        + `time_and_materials`
                        + `fixed_price`
                        + `parent_fixed_price`
                        + `non_billable`
                + `billing_status`: `not_billable` (enum[string])
                    + Members
                        + `not_billable`
                        + `not_billed`
                        + `partially_billed`
                        + `fully_billed`
                + `amount_billed` (Money, nullable)
                + `fixed_amount_billed` (Money, nullable)
                + `external_budget` (Money, nullable) - Value set by user to compare with price
                + `external_budget_spent` (Money, nullable) - Simulated price if billing method were `time_and_materials` (dependent on type)
                + `internal_budget` (Money, nullable) - Value set by user to compare with cost
                + `price` (Money, nullable)
                + `fixed_price` (Money, nullable)
                + `calculated_price` (Money, nullable) - Sum of underlying tasks/materials prices
                + `cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
                + `margin` (Money, nullable) - Can be a negative (less than zero) amount, `null` if the user does not have access to "Costs on projects"
                + `margin_percentage` (number, nullable) - `null` if the user does not have access to "Costs on projects"
                + `assignees` (array)
                    + (object)
                        + `assignee` (object)
                            + `type`: `user` (enum[string])
                                + Members
                                    + `team`
                                    + `user`
                            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                        + `assign_type`: `auto_assigned` (enum)
                            + Members
                                + `manual`
                                + `auto_assigned` - This user/team is included because they are assigned to underlying tasks or materials.
                                + `manual_and_auto_assigned` - This user/team is both manually assigned and included because they are assigned to underlying tasks or materials.
                + `start_date`: `2023-01-18` (string, nullable)
                + `end_date`: `2023-03-22` (string, nullable)
                + `time_estimated` (object, nullable) - The total of all time estimated for every item in this group. Value in seconds, rounded to the nearest minute.
                    + `value`: 28800 (number)
                    + `unit`: `seconds` (enum[string])
                        + Members
                            + `seconds`
                + `time_tracked` (object, nullable) - The total of all time tracked for every item in this group.
                    + `value`: 21100 (number)
                    + `unit`: `seconds` (enum[string])
                        + Members
                            + `seconds`

### projectGroups.info [POST /projects-v2/projectGroups.info]

Returns all the information for one group.

+ Request (application/json)
    + Attributes (object)
        + `id`: `cfe2666c-b0f4-4e85-8d6f-9e1284706d0a` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (object)
            + `id`: `cfe2666c-b0f4-4e85-8d6f-9e1284706d0a` (string)
            + `project` (object)
                + `type`: `nextgenProject` (string)
                + `id`: `018536c0-bf23-77eb-81f5-10e87cad50bc` (string)
            + `title`: `Website frontpage` (string)
            + `description`: `My elaborate description` (string, nullable)
            + `color`: `#00B2B2` (enum[string])
                + Members
                    + `#00B2B2` - Mint
                    + `#008A8C` - Darker mint
                    + `#992600` - Ruby
                    + `#ED9E00` - Gold
                    + `#D157D3` - Purple
                    + `#A400B2` - Darker purple
                    + `#0071F2` - Aqua
                    + `#004DA6` - Darker aqua
                    + `#64788F` - Blue grey
                    + `#C0C0C4` - Light grey
                    + `#82828C` - Grey
                    + `#1A1C20` - Dark grey
            + `billing_method`: `time_and_materials` (enum[string])
                + Members
                    + `time_and_materials`
                    + `fixed_price`
                    + `parent_fixed_price`
                    + `non_billable`
            + `billing_status`: `not_billable` (enum[string])
                + Members
                    + `not_billable`
                    + `not_billed`
                    + `partially_billed`
                    + `fully_billed`
            + `amount_billed` (Money, nullable)
            + `fixed_amount_billed` (Money, nullable)
            + `external_budget` (Money, nullable) - Also known as "budget". Value set by user to compare with price
            + `external_budget_spent` (Money, nullable) - Simulated price if billing method were `time_and_materials` (dependent on type)
            + `internal_budget` (Money, nullable) - Also known as "cost budget". Value set by user to compare with cost
            + `price` (Money, nullable)
            + `fixed_price` (Money, nullable)
            + `calculated_price` (Money, nullable) - Sum of underlying tasks/materials prices
            + `cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
            + `margin` (Money, nullable) - Can be a negative (less than zero) amount, `null` if the user does not have access to "Costs on projects"
            + `margin_percentage` (number, nullable) - `null` if the user does not have access to "Costs on projects"
            + `assignees` (array)
                + (object)
                    + `assignee` (object)
                        + `type`: `user` (enum[string])
                            + Members
                                + `team`
                                + `user`
                        + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                    + `assign_type`: `auto_assigned` (enum)
                        + Members
                            + `manual`
                            + `auto_assigned` - This user/team is included because they are assigned to underlying tasks or materials.
                            + `manual_and_auto_assigned` - This user/team is both manually assigned and included because they are assigned to underlying tasks or materials.
            + `start_date`: `2023-01-18` (string, nullable)
            + `end_date`: `2023-03-22` (string, nullable)
            + `time_estimated` (object, nullable) - The total of all time estimated for every item in this group. Value in seconds, rounded to the nearest minute.
                + `value`: 28800 (number)
                + `unit`: `seconds` (enum[string])
                    + Members
                        + `seconds`
            + `time_tracked` (object, nullable) - The total of all time tracked for every item in this group.
                + `value`: 21100 (number)
                + `unit`: `seconds` (enum[string])
                    + Members
                        + `seconds`

### projectGroups.create [POST /projects-v2/projectGroups.create]

Create a group. All properties except for `title` and `project_id` are optional.

+ Request (application/json)
    + Attributes (object)
        + `project_id`: `49b403be-a32e-0901-9b1c-25214f9027c6` (string, required)
        + `title`: `My project group` (string, required)
        + `description`: `Some long-winded description` (string, optional)
        + `color`: `#00B2B2` (enum[string], optional)
            + Members
                + `#00B2B2` - Mint
                + `#008A8C` - Darker mint
                + `#992600` - Ruby
                + `#ED9E00` - Gold
                + `#D157D3` - Purple
                + `#A400B2` - Darker purple
                + `#0071F2` - Aqua
                + `#004DA6` - Darker aqua
                + `#64788F` - Blue grey
                + `#C0C0C4` - Light grey
                + `#82828C` - Grey
                + `#1A1C20` - Dark grey
        + `billing_method` (enum[string], optional)
            + Members
                + `time_and_materials`
                + `fixed_price`
                + `parent_fixed_price` - The parent project must be `fixed_price`.
                + `non_billable`
        + `fixed_price` (Money, optional) - Only allowed if the `billing_method` is `fixed_price`, or the group is already `fixed_price`.
        + `external_budget` (Money, optional) - Also known as "budget". Value set by user to compare with price. Only allowed if the `billing_method` is `time_and_materials`, or the group is already `time_and_materials`.
        + `internal_budget` (Money, optional) - Also known as "cost budget". Value set by user to compare with cost.
        + `start_date`: `2023-01-18` (string, optional)
        + `end_date`: `2023-03-22` (string, optional)
        + `assignees` (array, optional)
            + (object)
                + `type`: `user` (enum[string], required)
                    + Members
                        + `user`
                        + `team`
                + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
           + type: `nextgenProjectGroup` (string)
           + id: `39c64ba9-ebf1-491a-8486-a0b96ff21c07` (string)

### projectGroups.update [POST /projects-v2/projectGroups.update]

Update a group. All attributes except for `id` are optional. Providing `null` will clear that value from the project (for properties that are nullable).

+ Request (application/json)
    + Attributes
        + `id`: `e8478f2c-05a1-4e69-b3c4-e08507640f01` (string, required)
        + `title`: `My updated group` (string)
        + `description`: `I updated this group because I felt like it` (string, nullable) - If `null`, the description is cleared.
        + `color`: `#00B2B2` (enum[string])
            + Members
                + `#00B2B2` - Mint
                + `#008A8C` - Darker mint
                + `#992600` - Ruby
                + `#ED9E00` - Gold
                + `#D157D3` - Purple
                + `#A400B2` - Darker purple
                + `#0071F2` - Aqua
                + `#004DA6` - Darker aqua
                + `#64788F` - Blue grey
                + `#C0C0C4` - Light grey
                + `#82828C` - Grey
                + `#1A1C20` - Dark grey
        + `billing_method` (object)
            + `value`: `time_and_materials` (enum[string], required)
                + Members
                    + `time_and_materials` - Can only be set using update_strategy "none"
                    + `fixed_price`
                    + `parent_fixed_price` - The parent project must be `fixed_price`.
                    + `non_billable` - Can only be set using update_strategy "cascade"
            + `update_strategy`: `none` (enum[string], required)
                + Members
                    + `none` - Don't change the values of the group items.
                    + `cascade` - Change the billing method of the group items depending on the group billing method.
        + `fixed_price` (Money, nullable) - Only allowed if the `billing_method` is `fixed_price`, or the group is already `fixed_price`.
        + `external_budget` (Money, nullable) - Also known as "budget". Value set by user to compare with price. Only allowed if the `billing_method` is `time_and_materials`, or the group is already `time_and_materials`.
        + `internal_budget` (Money, nullable) - Also known as "cost budget". Value set by user to compare with cost.
        + `start_date`: `2023-01-18` (string, nullable)
        + `end_date`: `2023-03-22` (string, nullable)

+ Response 204

### projectGroups.duplicate [POST /projects-v2/projectGroups.duplicate]

Duplicate a group and its entities, without any time trackings.

+ Request (application/json)
    + Attributes (object)
        + `origin_id`: `0186a6b5-2fdc-749a-983a-c4a1303546d7` (string, required) - The id of the group that is being duplicated

+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
           + type: `nextgenProjectGroup` (string)
           + id: `0186a6b5-682c-7b0e-95c9-090627a73d3b` (string)

### projectGroups.delete [POST /projects-v2/projectGroups.delete]

Delete a group.

+ Request (application/json)
    + Attributes (object)
        + `id`: `01866e6f-f264-7fe5-8b7c-a3f739fa292c` (string, required)
        + `delete_strategy`: `ungroup_tasks_and_materials` (enum[string], required)
            + Members
                + `ungroup_tasks_and_materials`
                + `delete_tasks_and_materials`
                + `delete_tasks_materials_and_unbilled_timetrackings`

+ Response 204

### projectGroups.assign [POST /projects-v2/projectGroups.assign]

Assign a user or a team to a group.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `assignee` (object, required)
            + `type`: `user` (enum[string], required)
                + Members
                    + `user`
                    + `team`
            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

### projectGroups.unassign [POST /projects-v2/projectGroups.unassign]

Unassign a user or a team from a group.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `assignee` (object, required)
            + `type`: `user` (enum[string], required)
                + Members
                    + `user`
                    + `team`
            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

## Tasks [/projects-v2/tasks]

> _These endpoints are for (new) project tasks. For documentation on endpoints for tasks not linked to a project, see **Tasks** below._

*Required scopes: `projects`*

### tasks.list [POST /projects-v2/tasks.list]

Lists all the tasks that match the optional filters provided.

+ Request (application/json)
    + Attributes (object)
        + filter (object)
            + ids: `46156648-87c6-478d-8aa7-1dc3a00dacab`, `46156648-87c6-478d-8aa7-1dc3a00daca4` (array[string])
        + `page` (Page, optional)

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + id: `39c64ba9-ebf1-491a-8486-a0b96ff21c07` (string)
                + `project` (object)
                    + `type`: `nextgenProject` (string)
                    + `id`: `018536c0-bf23-77eb-81f5-10e87cad50bc` (string)
                + `group` (object, nullable) - If `null`, the task is not in any group.
                    + `type`: `nextgenProjectGroup` (string)
                    + `id`: `eab232c6-49b2-4b7e-a977-5e1148dad471` (string)
                + `work_type` (object, nullable) - If null, the task does not have a specific work type.
                    + `type`: `workType` (string)
                    + `id`: `0f517e20-2e76-4684-8d6c-3334f6d7148c` (string)
                + `task_type` (object, nullable) - DEPRECATED - Use `work_type` instead.
                    + `type`: `workType` (string)
                    + `id`: `0f517e20-2e76-4684-8d6c-3334f6d7148c` (string)
                + `status`: `in_progress` (enum[string])
                    + Members
                        + `to_do`
                        + `in_progress`
                        + `on_hold`
                        + `done`
                + `title`: `Write API documentation` (string)
                + `billing_method`: `user_rate` (enum[string])
                    + Members
                        + `user_rate` - Based on the rate of the user who tracked time and the amount of time tracked.
                        + `work_type_rate` - Based on the rate of the work type and the amount of time tracked.
                        + `custom_rate` - Based on the custom rate set on the task and the amount of time tracked.
                        + `fixed_price`
                        + `parent_fixed_price` - The parent project or group must be `fixed_price`.
                        + `non_billable`
                + `billing_status`: `not_billable` (enum[string])
                    + Members
                        + `not_billable`
                        + `not_billed`
                        + `partially_billed`
                        + `fully_billed`
                + `custom_rate` (Money, nullable) - Null if the `billing_method` is anything other than `custom_rate`.
                + `amount_billed` (Money, nullable)
                + `external_budget` (Money, nullable) - Also known as "budget". Value set by user to compare with price
                + `external_budget_spent` (Money, nullable) - Simulated price if billing method were `time_and_materials` (dependent on type)
                + `internal_budget` (Money, nullable) - Also known as "cost budget". Value set by user to compare with cost
                + `price` (Money, nullable)
                + `unit_price` (Money) - The average of the external hourly rate
                + `fixed_price` (Money, nullable)
                + `cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
                + `unit_cost` (Money) - The average of the internal hourly rate, `null` if the user does not have access to "Costs on projects"
                + `margin` (Money, nullable) - Can be a negative (less than zero) amount, `null` if the user does not have access to "Costs on projects"
                + `margin_percentage` (number, nullable) - `null` if the user does not have access to "Costs on projects"
                + `assignees` (array)
                    + (object)
                        + `assignee` (object)
                            + `type`: `user` (enum[string])
                                + Members
                                    + `team`
                                    + `user`
                            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                        + `assign_type`: `manual` (enum)
                            + Members
                                + `manual`
                + `start_date`: `2023-01-18` (string, nullable)
                + `end_date`: `2023-03-22` (string, nullable)
                + `time_estimated` (object, nullable) - Value in seconds, rounded to the nearest minute.
                    + `value`: 28800 (number)
                    + `unit`: `seconds` (enum[string])
                        + Members
                            + `seconds`
                + `time_tracked` (object, nullable) - The total of all time tracked for this task.
                    + `value`: 21100 (number)
                    + `unit`: `seconds` (enum[string])
                        + Members
                            + `seconds`

### tasks.info [POST /projects-v2/tasks.info]

Returns all the information for one task.

+ Request (application/json)
    + Attributes (object)
        + `id`: `ff19a113-50ba-4afc-9fff-2e5c5c5a5485` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (object)
            + `id`: `ff19a113-50ba-4afc-9fff-2e5c5c5a5485` (string)
            + `project` (object)
                + `type`: `nextgenProject` (string)
                + `id`: `018536c0-bf23-77eb-81f5-10e87cad50bc` (string)
            + `group` (object, nullable) - If `null`, the task is not in any group.
                + `type`: `nextgenProjectGroup` (string)
                + `id`: `eab232c6-49b2-4b7e-a977-5e1148dad471` (string)
            + `work_type` (object, nullable) - If null, the task does not have a specific work type.
                + `type`: `workType` (string)
                + `id`: `0f517e20-2e76-4684-8d6c-3334f6d7148c` (string)
            + `task_type` (object, nullable) - DEPRECATED - Use `work_type` instead.
                + `type`: `workType` (string)
                + `id`: `0f517e20-2e76-4684-8d6c-3334f6d7148c` (string)
            + `status`: `in_progress` (enum[string])
                + Members
                    + `to_do`
                    + `in_progress`
                    + `on_hold`
                    + `done`
            + `title`: `Write API documentation` (string)
            + `description`: `I buy a house and garden somewhere, along a country road a piece` (string, nullable)
            + `billing_method`: `user_rate` (enum[string])
                + Members
                    + `user_rate` - Based on the rate of the user who tracked time and the amount of time tracked.
                    + `work_type_rate` - Based on the rate of the work type and the amount of time tracked.
                    + `custom_rate` - Based on the custom rate set on the task and the amount of time tracked.
                    + `fixed_price`
                    + `parent_fixed_price` - The parent project or group must be `fixed_price`.
                    + `non_billable`
            + `billing_status`: `not_billable` (enum[string])
                + Members
                    + `not_billable`
                    + `not_billed`
                    + `partially_billed`
                    + `fully_billed`
            + `custom_rate` (Money, nullable) - Null if the `billing_method` is anything other than `custom_rate`.
            + `amount_billed` (Money, nullable)
            + `external_budget` (Money, nullable) - Also known as "budget". Value set by user to compare with price
            + `external_budget_spent` (Money, nullable) - Simulated price if billing method were `time_and_materials` (dependent on type)
            + `internal_budget` (Money, nullable) - Also known as "cost budget". Value set by user to compare with cost
            + `price` (Money, nullable)
            + `unit_price` (Money) - The average of the external hourly rate
            + `fixed_price` (Money, nullable)
            + `cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
            + `unit_cost` (Money) - The average of the internal hourly rate, `null` if the user does not have access to "Costs on projects"
            + `margin` (Money, nullable) - Can be a negative (less than zero) amount, `null` if the user does not have access to "Costs on projects"
            + `margin_percentage` (number, nullable) - `null` if the user does not have access to "Costs on projects"
            + `assignees` (array)
                + (object)
                    + `assignee` (object)
                        + `type`: `user` (enum[string])
                            + Members
                                + `team`
                                + `user`
                        + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                    + `assign_type`: `manual` (enum)
                        + Members
                            + `manual`
            + `start_date`: `2023-01-18` (string, nullable)
            + `end_date`: `2023-03-22` (string, nullable)
            + `time_estimated` (object, nullable) - Value in seconds, rounded to the nearest minute.
                + `value`: 28800 (number)
                + `unit`: `seconds` (enum[string])
                    + Members
                        + `seconds`
            + `time_tracked` (object, nullable) - The total of all time tracked for this task.
                + `value`: 21100 (number)
                + `unit`: `seconds` (enum[string])
                    + Members
                        + `seconds`

### tasks.create [POST /projects-v2/tasks.create]

Create a task. All properties except for `title` and `project_id` are optional.

+ Request (application/json)
    + Attributes (object)
        + `project_id`: `49b403be-a32e-0901-9b1c-25214f9027c6` (string, required)
        + `title`: `My task` (string, required)
        + `group_id`: `0185968b-2c9e-73fd-9ce1-a12c0979783b` (string) - If omitted the task is not added to a group.
        + `work_type_id`: `0f517e20-2e76-4684-8d6c-3334f6d7148c` (string, optional) - Cannot be null if `billing_method` is `task_type_rate`.
        + `task_type_id`: `0f517e20-2e76-4684-8d6c-3334f6d7148c` (string, optional) - DEPRECATED - Use `work_type_id` instead.
        + `description`: `But nothing is any good without you cause baby you are my centerpiece` (string, optional)
        + `billing_method`: `fixed_price` (enum[string], optional)
            + Members
                + `user_rate` - Based on the rate of the user who tracked time and the amount of time tracked.
                + `work_type_rate` - Based on the rate of the work type and the amount of time tracked.
                + `custom_rate` - Based on the custom rate set on the task and the amount of time tracked.
                + `fixed_price`
                + `parent_fixed_price` - The parent project or group must be `fixed_price`.
                + `non_billable`
        + `fixed_price` (Money, optional) - Can only be provided if `billing_method` is `fixed_price`.
        + `external_budget` (Money, optional) - Also known as "budget". Value set by user to compare with price. Can only be provided if `billing_method` is `user_rate`, `work_type_rate`, or `custom_rate`.
        + `internal_budget` (Money, optional) - Also known as "cost budget". Value set by user to compare with cost.
        + `custom_rate` (Money, optional) - Can only be provided if `billing_method` is `custom_rate`.
        + `start_date`: `2023-01-18` (string, optional)
        + `end_date`: `2023-03-22` (string, optional)
        + `time_estimated` (object, optional)
            + `value`: `480` (number, required)
            + `unit`: `minutes` (enum[string], required)
                + Members
                    + `hours`
                    + `minutes`
                    + `seconds`
        + `assignees` (array, optional)
            + (object)
                + `type`: `user` (enum[string], required)
                    + Members
                        + `user`
                        + `team`
                + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
           + type: `nextgenTask` (string)
           + id: `39c64ba9-ebf1-491a-8486-a0b96ff21c07` (string)

### tasks.update [POST /projects-v2/tasks.update]

Update a task. All attributes except for `id` are optional. Providing `null` will clear that value from the project (for properties that are nullable).

+ Request (application/json)
    + Attributes (object)
        + `id`: `ff19a113-50ba-4afc-9fff-2e5c5c5a5485` (string, required)
        + `work_type_id`: `0f517e20-2e76-4684-8d6c-3334f6d7148c` (string, nullable, optional) - Cannot be null if `billing_method` is `work_type_rate`.
        + `task_type_id`: `0f517e20-2e76-4684-8d6c-3334f6d7148c` (string, nullable, optional) - DEPRECATED - Use `work_type_id` instead.
        + `status`: `on_hold` (enum[string], optional)
            + Members
                + `to_do`
                + `in_progress`
                + `on_hold`
                + `done`
        + `title`: `Write API documentation` (string, optional)
        + `description`: `But nothing is any good without you cause baby you are my centerpiece` (string, nullable, optional)
        + `billing_method`: `fixed_price` (enum[string], optional)
            + Members
                + `user_rate` - Based on the rate of the user who tracked time and the amount of time tracked.
                + `work_type_rate` - Based on the rate of the work type and the amount of time tracked.
                + `custom_rate` - Based on the custom rate set on the task and the amount of time tracked.
                + `fixed_price`
                + `parent_fixed_price` - The parent project or group must be `fixed_price`.
                + `non_billable`
        + `fixed_price` (Money, nullable, optional) - Can only be provided if `billing_method` is `fixed_price`.
        + `external_budget` (Money, nullable, optional) - Also known as "budget". Value set by user to compare with price. Can only be provided if `billing_method` is `user_rate`, `work_type_rate`, or `custom_rate`.
        + `internal_budget` (Money, nullable, optional) - Also known as "cost budget". Value set by user to compare with cost.
        + `custom_rate` (Money, nullable, optional) - Can only be provided if `billing_method` is `custom_rate`.
        + `start_date`: `2023-01-18` (string, nullable, optional)
        + `end_date`: `2023-03-22` (string, nullable, optional)
        + `time_estimated` (object, nullable, optional)
            + `value`: `480` (number, required)
            + `unit`: `minutes` (enum[string], required)
                + Members
                    + `hours`
                    + `minutes`
                    + `seconds`

+ Response 204

### tasks.duplicate [POST /projects-v2/tasks.duplicate]

Duplicate a task, without its time trackings.

+ Request (application/json)
    + Attributes (object)
        + `origin_id`: `0186a6b5-32d9-73d4-a416-d9f86cba567d` (string, required) - The id of the task that is being duplicated

+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
           + type: `nextgenTask` (string)
           + id: `0186a721-3879-729a-bf52-91576e0522f3` (string)

### tasks.delete [POST /projects-v2/tasks.delete]

Delete a task.

+ Request (application/json)
    + Attributes (object)
        + `id`: `ff19a113-50ba-4afc-9fff-2e5c5c5a5485` (string, required)
        + `delete_strategy`: `unlink_time_tracking` (enum[string], required)
            + Members
                + `unlink_time_tracking`
                + `delete_time_tracking`

+ Response 204

### tasks.assign [POST /projects-v2/tasks.assign]

Assign a user or a team to a task.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `assignee` (object, required)
            + `type`: `user` (enum[string], required)
                + Members
                    + `user`
                    + `team`
            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

### tasks.unassign [POST /projects-v2/tasks.unassign]

Unassign a user or a team from a task.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `assignee` (object, required)
            + `type`: `user` (enum[string], required)
                + Members
                    + `user`
                    + `team`
            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

## Materials [/projects-v2/materials]

*Required scopes: `projects`*

### materials.list [POST /projects-v2/materials.list]

Lists all the materials that match the optional filters provided.

+ Request (application/json)
    + Attributes (object)
        + filter (object)
            + ids: `46156648-87c6-478d-8aa7-1dc3a00dacab`, `46156648-87c6-478d-8aa7-1dc3a00daca4` (array[string])

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + id: `39c64ba9-ebf1-491a-8486-a0b96ff21c07` (string)
                + `project` (object)
                    + `type`: `nextgenProject` (string)
                    + `id`: `018536c0-bf23-77eb-81f5-10e87cad50bc` (string)
                + `group` (object, nullable) - If `null`, the material is not in any group.
                    + `type`: `nextgenProjectGroup` (string)
                    + `id`: `eab232c6-49b2-4b7e-a977-5e1148dad471` (string)
                + `title`: `Metal studs` (string)
                + `status`: `in_progress` (enum[string])
                    + Members
                        + `to_do`
                        + `in_progress`
                        + `on_hold`
                        + `done`
                + `billing_method`: `unit_price` (enum[string])
                    + Members
                        + `fixed_price`
                        + `unit_price`
                        + `non_billable`
                + `billing_status`: `not_billable` (enum[string])
                    + Members
                        + `not_billable`
                        + `not_billed`
                        + `partially_billed`
                        + `fully_billed`
                + `quantity` (number, nullable)
                + `unit_price` (Money, nullable)
                + `unit_cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
                + `unit` (object, nullable) - `null` if the default unit is used
                    + `type`: `priceunit` (string)
                    + `id`: `f1b7ae71-b610-02e0-8a10-443c31597e11` (string)
                + `amount_billed` (Money, nullable)
                + `external_budget` (Money, nullable) - Also known as "budget". Value set by user to compare with price
                + `external_budget_spent` (Money, nullable) - Simulated price if billing method were `time_and_materials` (dependent on type)
                + `internal_budget` (Money, nullable) - Also known as "cost budget". Value set by user to compare with cost
                + `price` (Money, nullable)
                + `fixed_price` (Money, nullable)
                + `cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
                + `margin` (Money, nullable) - Can be a negative (less than zero) amount, `null` if the user does not have access to "Costs on projects"
                + `margin_percentage` (number, nullable) - `null` if the user does not have access to "Costs on projects"
                + `assignees` (array)
                    + (object)
                        + `assignee` (object)
                            + `type`: `user` (enum[string])
                                + Members
                                    + `team`
                                    + `user`
                            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                        + `assign_type`: `manual` (enum)
                            + Members
                                + `manual`
                + `start_date`: `2023-01-18` (string, nullable)
                + `end_date`: `2023-03-22` (string, nullable)
                + `product` (object, nullable) - `null` if no product is coupled to the material
                    + `type`: `product` (string)
                    + `id`: `85fd7319-b094-462a-ae78-ff94d6bcb226` (string)

### materials.info [POST /projects-v2/materials.info]

Returns all the information for one material.

+ Request (application/json)
    + Attributes (object)
        + `id`: `ff19a113-50ba-4afc-9fff-2e5c5c5a5485` (string, required)

+ Response 200 (application/json)
    + Attributes (object)
        + data (object)
            + `id`: `ff19a113-50ba-4afc-9fff-2e5c5c5a5485` (string)
            + `project` (object)
                + `type`: `nextgenProject` (string)
                + `id`: `018536c0-bf23-77eb-81f5-10e87cad50bc` (string)
            + `group` (object, nullable) - If `null`, the material is not in any group.
                + `type`: `nextgenProjectGroup` (string)
                + `id`: `eab232c6-49b2-4b7e-a977-5e1148dad471` (string)
            + `title`: `WD-40® Multi-Use Product Industrial Size` (string)
            + `description`: `Protects metal from rust and corrosion, penetrates stuck parts, displaces moisture and lubricates almost anything.` (string, nullable) - Can be `null`.
            + `status`: `in_progress` (enum[string])
                + Members
                    + `to_do`
                    + `in_progress`
                    + `on_hold`
                    + `done`
            + `billing_method`: `unit_price` (enum[string])
                + Members
                    + `fixed_price`
                    + `unit_price`
                    + `non_billable`
            + `billing_status`: `not_billable` (enum[string])
                + Members
                    + `not_billable`
                    + `not_billed`
                    + `partially_billed`
                    + `fully_billed`
            + `quantity` (number, nullable)
            + `unit_price` (Money, nullable)
            + `unit_cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
            + `unit` (object, nullable) - `null` if the default unit is used
                + `type`: `priceunit` (string)
                + `id`: `f1b7ae71-b610-02e0-8a10-443c31597e11` (string)
            + `amount_billed` (Money, nullable)
            + `external_budget` (Money, nullable) - Also known as "budget". Value set by user to compare with price
            + `external_budget_spent` (Money, nullable) - Simulated price if billing method were `time_and_materials` (dependent on type)
            + `internal_budget` (Money, nullable) - Also known as "cost budget". Value set by user to compare with cost
            + `price` (Money, nullable)
            + `fixed_price` (Money, nullable)
            + `cost` (Money, nullable) - `null` if the user does not have access to "Costs on projects"
            + `margin` (Money, nullable) - Can be a negative (less than zero) amount, `null` if the user does not have access to "Costs on projects"
            + `margin_percentage` (number, nullable) - `null` if the user does not have access to "Costs on projects"
            + `assignees` (array)
                + (object)
                    + `assignee` (object)
                        + `type`: `user` (enum[string])
                            + Members
                                + `team`
                                + `user`
                        + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string)
                    + `assign_type`: `manual` (enum)
                        + Members
                            + `manual`
            + `start_date`: `2023-01-18` (string, nullable)
            + `end_date`: `2023-03-22` (string, nullable)
            + `product` (object, nullable) - `null` if no product is coupled to the material
                + `type`: `product` (string)
                + `id`: `85fd7319-b094-462a-ae78-ff94d6bcb226` (string)

### materials.create [POST /projects-v2/materials.create]

Create a material. All properties except for `title` and `project_id` are optional.

+ Request (application/json)
    + Attributes (object)
        + `project_id`: `49b403be-a32e-0901-9b1c-25214f9027c6` (string, required)
        + `title`: `Some material` (string, required)
        + `group_id`: `0185968b-2c9e-73fd-9ce1-a12c0979783b` (string) - If omitted the material is not added to a group.
        + `after_id`: `8ba797aa-107d-4934-9511-2a043bf3f766` (string, nullable) - If `after_id` is null, material is placed on top of the project/group. If `after_id` is not provided, material is placed at the bottom of the project/group.
        + `description`: `Protects metal from rust and corrosion, penetrates stuck parts, displaces moisture and lubricates almost anything.` (string, optional)
        + `billing_method`: `unit_price` (enum[string], optional)
           + Members
               + `fixed_price`
               + `unit_price`
               + `non_billable`
        + `quantity` (number, optional) - Can only be provided if `billing_method` is `unit_price`
        + `unit_price` (Money, optional) - Can only be provided if `billing_method` is `unit_price`
        + `unit_cost` (Money, optional) - Can only be provided if `billing_method` is `unit_price`. Access to "Costs on projects" is needed
        + `unit_id`: `69cbfbf2-fefe-4f03-9269-3ddc79117f4d` (string, optional)
        + `fixed_price` (Money, optional) - Can only be provided if `billing_method` is `fixed_price`
        + `external_budget` (Money, optional) - Also known as "budget". Value set by user to compare with price. Can only be provided if `billing_method` is `unit_price`
        + `internal_budget` (Money, optional) - Also known as "cost budget". Value set by user to compare with cost
        + `start_date`: `2023-01-18` (string, optional)
        + `end_date`: `2023-03-22` (string, optional)
        + `product_id`: `1c5cf7a1-7248-469c-9dcd-9f0581321ec2` (string, optional)
        + `assignees` (array, optional)
            + (object)
                + `type`: `user` (enum[string], required)
                    + Members
                        + `user`
                        + `team`
                + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
           + type: `nextgenMaterial` (string)
           + id: `b275487e-47d9-40b4-9cfe-5dfef77f4954` (string)

### materials.update [POST /projects-v2/materials.update]

Update a material. All attributes except for `id` are optional. Providing `null` will clear that value from the project (for properties that are nullable).

+ Request (application/json)
    + Attributes (object)
        + `id`: `ff19a113-50ba-4afc-9fff-2e5c5c5a5485` (string, required)
        + `title`: `WD-40® Multi-Use Product Industrial Size` (string, optional)
        + `description`: `Protects metal from rust and corrosion, penetrates stuck parts, displaces moisture and lubricates almost anything.` (string, nullable, optional)
        + `status`: `on_hold` (enum[string], optional)
            + Members
                + `to_do`
                + `in_progress`
                + `on_hold`
                + `done`
        + `billing_method`: `unit_price` (enum[string], optional)
           + Members
               + `fixed_price`
               + `unit_price`
               + `non_billable`
        + `quantity` (number, nullable, optional) - Can only be provided if `billing_method` is `unit_price`
        + `unit_price` (Money, nullable, optional) - Can only be provided if `billing_method` is `unit_price`
        + `unit_cost` (Money, nullable, optional) - Can only be provided if `billing_method` is `unit_price`. Access to "Costs on projects" is needed
        + `unit_id` (string, nullable, optional)
        + `fixed_price` (Money, nullable, optional) - Can only be provided if `billing_method` is `fixed_price`
        + `external_budget` (Money, nullable, optional) - Also known as "budget". Value set by user to compare with price. Can only be provided if `billing_method` is `unit_price`
        + `internal_budget` (Money, nullable, optional) - Also known as "cost budget". Value set by user to compare with cost
        + `start_date`: `2023-01-18` (string, nullable, optional)
        + `end_date`: `2023-03-22` (string, nullable, optional)
        + `product_id`: `1c5cf7a1-7248-469c-9dcd-9f0581321ec2` (string, nullable, optional)

+ Response 204

### materials.duplicate [POST /projects-v2/materials.duplicate]

Duplicate a material.

+ Request (application/json)
    + Attributes (object)
        + `origin_id`: `0186a74b-b640-7458-9717-7c84356b26fd` (string, required) - The id of the material that is being duplicated

+ Response 201 (application/json)
    + Attributes (object)
        + data (object)
           + type: `nextgenMaterial` (string)
           + id: `0186a2f3-32a5-7c81-b3a9-55809146ad0c` (string)

### materials.delete [POST /projects-v2/materials.delete]

Delete a material.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)

+ Response 204

### materials.assign [POST /projects-v2/materials.assign]

Assign a user or a team to a material.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `assignee` (object, required)
            + `type`: `user` (enum[string], required)
                + Members
                    + `user`
                    + `team`
            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

### materials.unassign [POST /projects-v2/materials.unassign]

Unassign a user or a team from a material.

+ Request (application/json)
    + Attributes (object)
        + `id`: `0184f276-811b-716d-8b79-17628c9573c6` (string, required)
        + `assignee` (object, required)
            + `type`: `user` (enum[string], required)
                + Members
                    + `user`
                    + `team`
            + `id`: `66abace2-62af-0836-a927-fe3f44b9b47b` (string, required)

+ Response 204

# Group Tasks

## Tasks [/tasks]

### tasks.list [POST /tasks.list]

Get a list of tasks.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `9c475de2-1e99-0328-bc19-271b27e921d8`,`6325b4e5-c6a6-060b-b010-b81892e82fa7` (array[string], optional)
            + user_id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, optional, nullable) - Returns tasks that are assigned to this user or to a team to which this user belongs. When passing `null`, it returns tasks that are unassigned.
            + milestone_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional)
            + completed: true (boolean, optional)
            + scheduled: true (boolean, optional)
            + due_by: `2019-02-04` (string, optional)
            + due_from: `2019-10-20` (string, optional)
            + term: `website design` (string, optional) - Searches for a term in the description.
            + customer (object, optional)
                + type (enum, required)
                    + Members
                        + company
                        + contact
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + due_on
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `due_on`
                    + order: `asc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + title: `Review code changes` (string)
                + description (string)
                + completed: false (boolean)
                + completed_at: `2016-02-04T16:44:33+00:00` (string, nullable)
                + due_on: `2016-02-04` (string)
                + added_at: `2016-02-04T16:44:33+00:00` (string, nullable)
                + estimated_duration (object)
                    + unit (enum)
                        + Members
                            + min - Minutes
                    + value: `60` (number)
                + work_type (object, nullable)
                    + type: `workType` (string)
                    + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
                + assignee (object, nullable) - Null if the task is unassigned
                    + type: `user` (enum)
                        + Members
                            + user
                            + team
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + customer (object, nullable)
                    + type: `contact` (enum)
                        + Members
                            + contact
                            + company
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + milestone (object, nullable)
                    + type: `milestone` (string)
                    + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
                + deal (object, nullable)
                    + type: `deal` (string)
                    + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
                + project (object, nullable)
                    + type: `project` (string)
                    + id: `bbbb772b-e7ad-06c5-935c-b0f6ef61d6bc` (string)
                + ticket (object, nullable)
                    + `type`: `ticket` (string)
                    + id: `8607faa8-3d2e-0a66-a71e-e69f447a2ed1` (string, required)
                + priority (Priority)

### tasks.info [POST /tasks.info]

Get information about a task.

+ Request (application/json)

    + Attributes (object)
        + id: `6fac0bf0-e803-424e-af67-76863a3d7d16` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `6fac0bf0-e803-424e-af67-76863a3d7d16` (string)
            + title: `Review code changes` (string)
            + description (string)
            + completed: false (boolean)
            + completed_at: `2016-02-04T16:44:33+00:00` (string, nullable)
            + due_on: `2016-02-04` (string)
            + estimated_duration (object)
                + unit (enum)
                    + Members
                        + min - Minutes
                + value: `60` (number)
            + work_type (object, nullable)
                + type: `workType` (string)
                + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
            + assignee (object) - Null if the task is unassigned
                + type: `user` (enum)
                    + Members
                        + user
                        + team
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
            + customer (object, nullable)
                + type: `contact` (enum)
                    + Members
                        + contact
                        + company
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
            + milestone (object, nullable)
                + type: `milestone` (string)
                + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
            + deal (object, nullable)
                + type: `deal` (string)
                + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
            + project (object, nullable)
                + type: `project` (string)
                + id: `bbbb772b-e7ad-06c5-935c-b0f6ef61d6bc` (string)
            + ticket (object, nullable)
                + `type`: `ticket` (string)
                + id: `8607faa8-3d2e-0a66-a71e-e69f447a2ed1` (string, required)
            + custom_fields (array[CustomField])
            + priority (Priority)

### tasks.create [POST /tasks.create]

Create a new task.

+ Request (application/json)

    + Attributes (object)
        + title (string, required)
        + description (string)
        + due_on: `2016-02-04` (string, required)
        + work_type_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, required)
        + milestone_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional) - Only available for users that have access to the old projects module
        + project_id: `0185aa33-603c-7fd5-bf0d-5bd83d503b96` (string, optional) - Only available for users that have access to the new projects module
        + deal_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional)
        + `ticket_id`: `8607faa8-3d2e-0a66-a71e-e69f447a2ed1` (string, optional)
        + estimated_duration (object, optional)
            + unit (enum, required)
                + Members
                    + min - Minutes
            + value: `60` (number, required)
        + assignee (object, optional, nullable) - Use null if the task is unassigned
            + type: `user` (enum)
                + Members
                    + user
                    + team
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + customer (object, optional)
            + type: `contact` (enum)
                + Members
                    + contact
                    + company
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `task` (string)
            + id: `1759dfc1-7365-4f1b-8d90-d29787a5d29d` (string)

### tasks.update [POST /tasks.update]

Update a task.

+ Request (application/json)

    + Attributes (object)
        + id: `00ed6266-a5bd-4aac-a292-2582017b6400` (string, required)
        + title (string, optional)
        + description (string, optional)
        + due_on: `2016-02-04` (string, optional)
        + work_type_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional)
        + `milestone_id`: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional, nullable) - Only available for users that have access to the old projects module
        + `project_id`: `0185aa33-603c-7fd5-bf0d-5bd83d503b96` (string, optional, nullable) - Only available for users that have access to the new projects module
        + deal_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional, nullable)
        + `ticket_id`: `8607faa8-3d2e-0a66-a71e-e69f447a2ed1` (string, optional, nullable)
        + estimated_duration (object, optional)
            + unit (enum, required)
                + Members
                    + min - Minutes
            + value: `60` (number, required)
        + assignee (object, optional, nullable) - Use null if the task is unassigned
            + type: `user` (enum)
                + Members
                    + user
                    + team
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + customer (object, optional)
            + type: `contact` (enum)
                + Members
                    + contact
                    + company
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + custom_fields (array[CustomFieldValue], optional)

+ Response 204

### tasks.complete [POST /tasks.complete]

Mark a task as complete.

+ Request (application/json)

    + Attributes (object)
        + id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, required)

+ Response 204

### tasks.reopen[POST /tasks.reopen]

Reopen a task that had been marked as complete.

+ Request (application/json)

    + Attributes (object)
        + id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, required)

+ Response 204

### tasks.delete [POST /tasks.delete]

Delete a task.

+ Request (application/json)

    + Attributes (object)
        + id: `5f0afd8a-8a40-48a4-bbe6-7d0e9c61bb6d` (string, required)

+ Response 204

### tasks.schedule [POST /tasks.schedule]

Schedule a task in your calendar.

+ Request (application/json)

    + Attributes (object)
        + id: `7c70c54e-6e50-4e6a-b5fd-80234eb535cf` (string, required)
        + starts_at: `2016-02-04T16:00:00+00:00` (string, required)
        + ends_at: `2016-02-04T18:00:00+00:00` (string, required)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `event` (string)
            + id: `d7d2d100-d440-46c2-a4a3-177ad4b2a860` (string)

# Group Time Tracking

## Time Tracking [/timeTracking]

Time tracking allows users to record time spent on tasks or projects and the type of work. You are able to follow-up on the budgets of your projects and eventually you are able to invoice the billable time.

### timeTracking.list [POST /timeTracking.list]

Get a list of tracked time.

+ Request (application/json)

    + Attributes (object)
        + filter (object, optional)
            + ids: `4f4288b2-c21b-4dac-87f6-a97511309079`,`d8b178d2-aaa5-014e-bc24-57371c90044e`, (array[string], optional)
            + user_id: `87982c96-f2fe-4b05-838c-ff42c0525758` (string, optional)
            + started_after: `2017-04-26T10:01:49+00:00` (string, optional) - Start of the period for which to return time tracking. This includes time tracking that started on the date provided.
            + started_before: `2017-04-26T10:01:49+00:00` (string, optional) - End of the period for which to return time tracking. This includes time tracking that started on the date provided.
            + ended_after: `2017-04-26T10:01:49+00:00` (string, optional) - Start of the period for which to return time tracking. This includes time tracking that ended at the date provided.
            + ended_before: `2017-05-26T10:01:49+00:00` (string, optional) - End of the period for which to return time tracking. This includes time tracking that ended at the date provided.
            + subject (object, optional)
                + type (enum, required)
                    + Members
                        + company
                        + contact
                        + event
                        + todo
                        + milestone
                        + ticket
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
            + subject_types (array, optional) - Include all tracked time with one of the provided subject types. For tracked time without a subject type, provide `null`
                + Members
                    + company
                    + contact
                    + event
                    + todo
                    + milestone
                    + ticket
            + relates_to (object, optional) - Find all tracked time linked directly and indirectly to a subject
                + type (enum, required)
                    + Members
                        + milestone
                        + project
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
        + sort (array, optional)
            + (object)
                + field (enum, required)
                    + Members
                        + `starts_on` - Per day, time tracking entries with an automatically generated start time are displayed first
                + order (enum, optional)
                    + Members
                        + asc
                        + desc
            + Default
                + (object)
                    + field: `starts_on`
                    + order: `asc`
        + page (Page, optional)
        + includes: `materials,relates_to` (string, optional) - Comma-separated list of optional includes


+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `4f4288b2-c21b-4dac-87f6-a97511309079` (string)
                + user (object)
                    + type: `user` (string)
                    + id: `eb1eb8b8-d0cb-4385-b60a-c995953ec6be` (string)
                + work_type (object)
                    + type: `workType` (string)
                    + id: `8a146eda-c9af-4b11-b63a-ddac47bb254d` (string)
                + started_on: `2017-04-26` (string)
                + started_at: `2017-04-26T10:01:49+00:00` (string, nullable)
                + ended_at: `2017-04-26T11:01:49+00:00` (string, nullable)
                + duration: 3600 (number) - In seconds
                + description: `Timer description` (string)
                + subject (object)
                    + type: `milestone` (enum)
                        + Members
                            + company
                            + contact
                            + event
                            + todo
                            + milestone
                            + ticket
                    + id: `58f5b799-51c4-4eb9-8308-b1aa02e0a873` (string)
                + invoiceable: true (boolean)
                + billing_info (object, nullable)
                    + type: `invoice` (enum)
                        + Members
                            + invoice
                            + prepaid
                    + invoice (object, nullable)
                        + type: `invoice` (string)
                        + id: `b2b4b2b4-4b2b-4b2b-4b2b-4b2b4b2b4b2b` (string)
                + `materials` (array) - Only included with request parameter `includes=materials`
                      + (object)
                          + `product` (object, nullable)
                              + type: `product` (string)
                              + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)
                          + `description`: `Product description` (string)
                          + `unit_price` (object)
                              + Include Money
                          + `quantity`: `5` (number)
                + `relates_to` (array) - Only included with request parameter `includes=relates_to`
                      + (object)
                          + `type` (TimeTrackingRelatesToTypes)
                          + `id`: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
                + `hourly_rate` (Money, optional) - Only included for users with access to invoicing

### timeTracking.info [POST /timeTracking.info]

Get information about tracked time.

+ Request (application/json)

    + Attributes (object)
        + id: `6caeea11-aa83-4da9-9859-5b62bbf3a476` (string, required)
        + includes: `materials,relates_to` (string, optional) - Comma-separated list of optional includes

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `6caeea11-aa83-4da9-9859-5b62bbf3a476` (string)
            + user (object)
                + type: `user` (string)
                + id: `56bc6b39-b722-42f5-9ea7-acea4814d7dd` (string)
            + work_type (object)
                + type: `workType` (string)
                + id: `d980dbc6-944e-47fc-bf16-2ed7d5a71889` (string)
            + started_on: `2017-04-26` (string)
            + started_at: `2017-04-26T10:01:49+00:00` (string, nullable)
            + ended_at: `2017-04-26T11:01:49+00:00` (string, nullable)
            + duration: 3600 (number) - In seconds
            + description: `Timer description` (string)
            + subject (object)
                + type: `milestone` (enum)
                    + Members
                        + company
                        + contact
                        + event
                        + todo
                        + milestone
                        + ticket
                + id: `5883723a-b5aa-4c9d-a02b-ec0dd25f6ca2` (string)
            + invoiceable: true (boolean)
            + locked: true (boolean) - If true, the freeze time window has passed since creating it
            + billing_info (object, nullable)
                + type: `invoice` (enum)
                    + Members
                        + invoice
                        + prepaid
                + invoice (object, nullable)
                    + type: `invoice` (string)
                    + id: `b2b4b2b4-4b2b-4b2b-4b2b-4b2b4b2b4b2b` (string)
            + `materials` (array) - Only included with request parameter `includes=materials`
                  + (object)
                      + `product` (object, nullable)
                          + type: `product` (string)
                          + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)
                      + `description`: `Product description` (string)
                      + `unit_price` (object)
                          + Include Money
                      + `quantity`: `5` (number)
            + `relates_to` (array) - Only included with request parameter `includes=relates_to`
                + (object)
                    + `type`: `contact` (TimeTrackingRelatesToTypes)
                    + `id`: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
            + `hourly_rate` (Money, optional) - Only included for users with access to invoicing
        + meta (object)
            + updatable: true (boolean) - If true, the current user can update the entry even if it is locked

### timeTracking.add [POST /timeTracking.add]

Add tracked time.

+ Request (application/json)

    Note that the time tracking entry will be split up if the time span passes midnight.

    + Attributes (object)
        + work_type_id: `2175597d-484e-4a1c-a781-cbc3d9f893ba` (string, optional)
        + One Of
            + Properties
                + started_at: `2017-04-26T10:01:49+00:00` (string, required)
                + duration: 3600 (number, required) - In seconds
            + Properties
                + started_at: `2017-04-26T10:01:49+00:00` (string, required)
                + ended_at: `2017-04-26T16:02:00+00:00` (string, required)
            + Properties
                + started_on: `2017-04-26` (string, required) - Only available if duration time tracking is enabled.
                + duration: 3600 (number, required) - In seconds
        + description (string, optional)
        + subject (object, optional)
            + type: `milestone` (enum, required)
                + Members
                    + company
                    + contact
                    + event
                    + todo
                    + milestone
                    + ticket
            + id: `b40ea20d-4ae5-4a56-be12-03766ecaefae` (string, required)
        + invoiceable: true (boolean, optional)
        + user_id: `87982c96-f2fe-4b05-838c-ff42c0525758` (string, optional) - To add tracked time for a different user.

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `timetracking` (string)
            + id: `6f052357-142e-499e-a647-36b55ecf447c` (string)

### timeTracking.update [POST /timeTracking.update]

Update tracked time.

+ Request (application/json)

    + Attributes (object)
        + id: `66621f54-3d0d-420f-8d4b-ddd7fc473bf2` (string, required)
        + work_type_id: `a12f4289-3580-4780-bb6d-b4e9f84f80ad` (string, optional, nullable)
        + One Of
            + Properties
                + started_at: `2017-04-26T10:01:49+00:00` (string, required)
                + duration: 3600 (number, required) - In seconds
            + Properties
                + started_on: `2017-04-26` (string, required) - Only available if duration time tracking is enabled.
                + duration: 3600 (number, required) - In seconds
        + description (string, optional, nullable)
        + subject (object, optional, nullable)
            + type: `milestone` (enum, required)
                + Members
                    + company
                    + contact
                    + event
                    + todo
                    + milestone
                    + ticket
            + id: `88f14220-55d3-4ca6-802b-425e2f53c850` (string, required)
        + invoiceable: true (boolean, optional)

+ Response 204

### timeTracking.resume [POST /timeTracking.resume]

Start a new timer based on previously tracked time.

+ Request (application/json)

    + Attributes (object)
        + id: `06dfa08a-b769-4005-a912-45ab885c5737` (string, required)
        + started_at: `2017-04-26T10:01:49+00:00` (string, optional) - If not provided, current time will be used

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `timer` (string)
            + id: `f01adf4a-bb9b-45de-b231-615cd0e941de` (string)

### timeTracking.delete [POST /timeTracking.delete]

Delete a tracked time.

+ Request (application/json)

    + Attributes (object)
        + id: `6caeea11-aa83-4da9-9859-5b62bbf3a476` (string, required)

+ Response 204

## Timers [/timers]

Timers are an easy way to track time. You can start, stop or resume a timer any time. However, only one timer can run simultaneously per user. Every action will result in the creation or update of a time tracking.

### timers.current [POST /timers.current]

Get the current running timer.

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `2b282dec-ba9d-4faa-9b39-944b99ee5c0a` (string)
            + user (object)
                + type: `user` (string)
                + id: `5443a1b9-7673-4922-921f-1da4ff557783` (string)
            + work_type (object)
                + type: `workType` (string)
                + id: `d02de940-9435-4e35-bc0b-3d17f3d0ea7b` (string)
            + started_at: `2017-04-26T10:01:49+00:00` (string)
            + description: `Timer description` (string)
            + subject (object)
                + type: `milestone` (enum)
                    + Members
                        + company
                        + contact
                        + event
                        + todo
                        + milestone
                        + ticket
                + id: `31931bc9-4ae8-4c50-ba8d-9ea88498c1c1` (string)
            + invoiceable: true (boolean)

### timers.start [POST /timers.start]

Start a new timer.

+ Request (application/json)

    + Attributes (object)
        + work_type_id: `db41328a-7a25-4e85-8fb9-830baacb7f40` (string, optional)
        + started_at: `2017-04-26T10:01:49+00:00` (string, optional) - If not provided, current time will be used
        + description (string, optional)
        + subject (object, optional)
            + type: `milestone` (enum, required)
                + Members
                    + company
                    + contact
                    + event
                    + todo
                    + milestone
                    + ticket
            + id: `29ff471c-7d8f-40d5-8c95-9a9cab841e65` (string, required)
        + invoiceable: true (boolean, optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `timer` (string)
            + id: `4ff475b2-f45b-4803-800e-350b9c02aeca` (string)

### timers.stop [POST /timers.stop]

Stop the current timer. This will add a new time tracking in the background.

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `timeTracking` (string)
            + id: `4ff475b2-f45b-4803-800e-350b9c02aeca` (string)

### timers.update [POST /timers.update]

Update the current timer. Only possible if there is a timer running.

+ Request (application/json)

    + Attributes (object)
        + work_type_id: `db41328a-7a25-4e85-8fb9-830baacb7f40` (string, optional, nullable)
        + started_at: `2017-04-26T10:01:49+00:00` (string, optional)
        + description: `Timer Description` (string, optional, nullable)
        + subject (object, optional, nullable)
            + type: `milestone` (enum, required)
                + Members
                    + company
                    + contact
                    + event
                    + todo
                    + milestone
                    + ticket
            + id: `29ff471c-7d8f-40d5-8c95-9a9cab841e65` (string, required)
        + invoiceable: true (boolean, optional)

+ Response 204

# Group Tickets

## Tickets [/tickets]

*Required scopes: `tickets`*

### tickets.list [POST /tickets.list]

Get a list of tickets.

+ Request (application/json)
    + Attributes (object)
        + filter (object, optional)
            + ids: `8607faa8-3d2e-0a66-a71e-e69f447a2ed1`, `21467288-3baa-0027-a910-cd952030dbc2` (array[string], optional)
            + relates_to (object, optional) - Only lists tickets related to given type.
                + type (enum, required)
                    + Members
                        + contact
                        + company
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
            + project_ids: `082e6289-30c5-45ad-bcd0-190b02d21e81` (array[string], optional) - an array of project ids
            + exclude (object, optional)
                + status_ids: `a344c251-2494-0013-b433-ccee8e8435e6`, `c11dc02c-3556-0daf-8035-c5b0376eb928` (array[string], optional)
        + page (Page, optional)

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + reference: `123` (number)
                + subject (string)
                + status (object)
                    + type: `ticketStatus` (string)
                    + id: `aba0ad66-bf59-49fa-b546-45dcbc5e7e6e` (string)
                + assignee (object, nullable) - Null if unassigned
                    + type: `user` (string)
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + created_at: `2017-05-09T11:25:11+00:00` (string)
                + closed_at: `2017-05-09T11:25:11+00:00` (string, nullable)
                + customer (object)
                    + type: `contact` (enum)
                        + Members
                            + company
                            + contact
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + participant (object, nullable)
                    + customer (object)
                        + type: `company` (string)
                        + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + project (object, nullable)
                    + type: `project` (string)
                    + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
                + milestone (object, nullable)
                    + type: `milestone` (string)
                    + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
                + last_message_at: `2017-05-09T11:25:11+00:00` (string, nullable)

### tickets.info [POST /tickets.info]

Get details for a single ticket.

+ Request (application/json)
    + Attributes (object)
        + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)

+ Response 200 (application/json)
    + Attributes (object)
        + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + reference: `123` (number)
        + subject (string)
        + status (object)
            + type: `ticketStatus` (string)
            + id: `aba0ad66-bf59-49fa-b546-45dcbc5e7e6e` (string)
        + assignee (object, nullable) - Null if unassigned
            + type: `user` (string)
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + created_at: `2017-05-09T11:25:11+00:00` (string)
        + closed_at: `2017-05-09T11:25:11+00:00` (string, nullable)
        + customer (object)
            + type: `contact` (enum)
                + Members
                    + company
                    + contact
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + participant (object, nullable)
            + customer (object)
                + type: `company` (string)
                + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + last_message_at: `2017-05-09T11:25:11+00:00` (string, nullable)
        + description: `My ticket details` (string)
        + project (object, nullable)
            + type: `project` (string)
            + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
        + milestone (object, nullable)
            + type: `milestone` (string)
            + id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string)
        + custom_fields (array[CustomField])


### tickets.create [POST /tickets.create]

Create a ticket.

+ Request (application/json)
    + Attributes (object)
        + subject: `My ticket subject` (string, required)
        + customer (object, required)
            + type: `company` (enum[string], required)
                + Members
                    + contact
                    + company
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)
        + ticket_status_id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, required)
        + assignee (object, optional)
            + type (enum[string], required)
                + Members
                    + `user`
            + id: `98b2863e-7b01-4232-82f5-ede1f0b9db22` (string, required)
        + custom_fields (array[CustomFieldValue], optional)
        + description: `My ticket details` (string, optional) - Uses Markdown formatting
        + participant (object, optional)
            + customer (object, required)
                + type (enum, required)
                    + Members
                        + `company`
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
        + initial_reply (enum, optional) - Create & send an initial autoreply according to configuration (default: automatic).
            + Members
                + `automatic`
                + `disabled`
        + milestone_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional)

+ Response 201 (application/json)

    + Attributes (object)
        + data (object)
            + type: `ticket` (string)
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)


### tickets.update [POST /tickets.update]

Update a ticket.

+ Request (application/json)
    + Attributes (object)
        + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)
        + subject: `My ticket subject` (string, optional)
        + description: `My ticket details` (string, optional) - Uses Markdown formatting
        + ticket_status_id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, optional)
        + customer (object, optional)
            + type: `company` (enum[string], required)
                + Members
                    + contact
                    + company
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)
        + assignee (object, optional, nullable)
            + type (enum[string], required)
                + Members
                    + `user`
            + id: `98b2863e-7b01-4232-82f5-ede1f0b9db22` (string, required)
        + participant (object, optional, nullable)
            + customer (object, required, nullable)
                + type (enum, required)
                    + Members
                        + `company`
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
        + custom_fields (array[CustomFieldValue], optional)
        + milestone_id: `32665afd-1818-0ed3-9e18-a603a3a21b95` (string, optional, nullable)

+ Response 204


### tickets.listMessages [POST /tickets.listMessages]

Lists messages of a ticket

+ Request (application/json)
    + Attributes (object)
        + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + filter (object, optional)
            + type: `customer` (enum, optional)
                + Members
                    + customer
                    + internal
                    + thirdParty
            + created_before: `2024-02-01T18:00:00+00:00` (string, optional)
            + created_after: `2024-01-01T18:00:00+00:00` (string, optional)
        + page (Page, optional)

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + message_id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + body: `<p>This is a message</p>` (string) - Uses HTML formatting
                + type: `customer` (enum, optional)
                    + Members
                        + customer
                        + internal
                        + thirdParty
                + created_at: `2017-05-09T11:25:11+00:00` (string)
                + sent_by (object)
                    + type: `contact` (enum)
                        + Members
                            + company
                            + contact
                            + user
                    + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
                + attachments (array)
                    + (object)
                        + `type`: `file` (string)
                        + `id`: `0686d0da-1797-475b-ae94-27191b2eca4d` (string)
        + meta (object) - Only included with request parameter `includes=pagination`
           + page (Pagination)
           + matches: `12` (number)


### tickets.getMessage [POST /tickets.getMessage]

Gets the ticket message.

+ Request (application/json)
    + Attributes (object)
        + message_id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)

+ Response 200 (application/json)
    + Attributes (object)
        + message_id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + body: `<p>This is a message</p>` (string) - Uses HTML formatting
        + raw_body: `<p>This is a message</p>` (string)- Uses HTML formatting
        + created_at: `2017-05-09T11:25:11+00:00` (string)
        + sent_by (object)
            + type: `contact` (enum)
                + Members
                    + company
                    + contact
                    + user
            + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)
        + ticket (object)
               + `type`: `ticket` (string)
               + `id`: `4f5c4ee1-9078-0eda-8817-03e4cba61bab` (string)
        + attachments (array)
           + (object)
               + `type`: `file` (string)
               + `id`: `0686d0da-1797-475b-ae94-27191b2eca4d` (string)
        + type: `customer` (enum)
            + Members
                + customer
                + internal
                + thirdParty


### tickets.importMessage [POST /tickets.importMessage]

Imports an existing message to a ticket.

+ Request (application/json)
    + Attributes (object)
        + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)
        + body: `<p>Hello world</p>` (string, required) - Uses HTML formatting
        + sent_by (object, required)
            + `type`: `contact` (enum, required)
                + Members
                    + company
                    + contact
                    + user
            + id: `4b3b07c6-a4bf-4c1b-9471-283fee71b049` (string, required)
        + sent_at: `2024-02-29T11:11:11+00:00` (string, required)
        + `attachments`: `4f4288b2-c21b-4dac-87f6-a97511309079` (array[string], optional) - All files must have the ticket as a subject

+ Response 200 (application/json)
    + Attributes (object)
        + data (object)
            + type: `ticketMessage` (string)
            + id: `e3de4c0d-787d-4720-b78f-af8df5c8182c` (string)


### tickets.addReply [POST /tickets.addReply]

Adds a message to a ticket.

+ Request (application/json)
    + Attributes (object)
        + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)
        + body: `<p>Hello world</p>` (string, required) - Uses HTML formatting
        + ticket_status_id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, optional)
        + `attachments`: `4f4288b2-c21b-4dac-87f6-a97511309079` (array[string], optional) - All files must have the ticket as a subject

+ Response 200 (application/json)
    + Attributes (object)
        + data (object)
            + type: `ticketMessage` (string)
            + id: `e3de4c0d-787d-4720-b78f-af8df5c8182c` (string)


### tickets.addInternalMessage [POST /tickets.addInternalMessage]

Adds an internal message to a ticket.

+ Request (application/json)
    + Attributes (object)
        + id: `f29abf48-337d-44b4-aad4-585f5277a456` (string, required)
        + body: `<p>Hello world</p>` (string, required) - Uses HTML formatting
        + ticket_status_id: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string, optional)
        + `attachments`: `4f4288b2-c21b-4dac-87f6-a97511309079` (array[string], optional) - All files must have the ticket as a subject

+ Response 200 (application/json)
    + Attributes (object)
        + data (object)
            + type: `ticketMessage` (string)
            + id: `e3de4c0d-787d-4720-b78f-af8df5c8182c` (string)

## Ticket Status [/ticketStatus]

### ticketStatus.list [POST /ticketStatus.list]

Get a list of ticket statuses.

+ Request (application/json)
    + Attributes (object)
        + filter (object, optional)
            + ids: `46156648-87c6-478d-8aa7-1dc3a00dacab`, `46156648-87c6-478d-8aa7-1dc3a00daca4` (array[string], optional)

+ Response 200 (application/json)
    + Attributes (object)
        + data (array)
            + (object)
                + `id`: `46156648-87c6-478d-8aa7-1dc3a00dacab` (string)
                + `status`: `new` (enum)
                    + Members
                        + `new`
                        + `open`
                        + `waiting_for_client`
                        + `escalated_thirdparty`
                        + `closed`
                        + `custom`
                + `label`: `Custom Label` (string) - Only available for `custom` type of status.

# Group Files

## Files [/files]

### files.list [POST /files.list]

Get a list of files.

+ Request (application/json)

    + Attributes (object)
        + filter (object, required)
            + subject (object, required)
                + `type`: `company` (enum[string], required)
                    + Members
                        + company
                        + contact
                        + deal
                        + invoice
                        + creditNote
                        + product
                        + project
                        + nextgenProject
                        + ticket
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
        + page (Page, optional)
        + sort (array, optional)
            + (object)
                + field (enum[string], required)
                    + Members
                        + updated_at
                + order (enum[string], optional)
                    + Members
                        + desc
            + Default
                + (object)
                    + field: `updated_at`
                    + order: `desc`

+ Response 200 (application/json)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `a856642a-a476-4b69-8e42-e7d1badb2ce9` (string)
                + subject (object, nullable)
                    + `type`: `company` (enum[string])
                        + Members
                            + company
                            + contact
                            + deal
                            + invoice
                            + creditNote
                            + nextgenProject
                            + ticket
                    + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
                + name: `meeting-report.pdf` (string)
                + mime_type (MimeType)
                + size: `1024` (number) - file size in bytes.
                + updated_at: `2019-10-15T17:30:58+00:00` (string)
                + uploaded_by (User, nullable)
                + folder : `Documents` (string)

### files.info [POST /files.info]

Get details for a single file.

+ Request (application/json)

    + Attributes (object)
        + id: `6fac0bf0-e803-424e-af67-76863a3d7d16` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + id: `a856642a-a476-4b69-8e42-e7d1badb2ce9` (string)
            + subject (object, nullable)
                + `type`: `company` (enum[string])
                    + Members
                        + company
                        + contact
                        + deal
                        + invoice
                        + creditNote
                        + meeting
                        + order
                        + product
                        + project
                        + nextgenProject
                        + ticket
                        + workOrder
                + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string)
            + name: `meeting-report.pdf` (string)
            + mime_type (MimeType)
            + size: `1024` (number) - file size in bytes.
            + updated_at: `2019-10-15T17:30:58+00:00` (string)
            + uploaded_by (User, nullable)
            + folder : `Documents` (string)

### files.download [POST /files.download]

Request the download link for a file.

+ Request (application/json)

    + Attributes (object)
        + id: `4afb0a9c-91c6-49ed-a2e5-ce7c1e3a87fb` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + location: `https://cdn.teamleader.eu/file` (string) - A temporary url where the requested file can be downloaded
            + expires_at: `2018-02-05T16:44:33+00:00` (string) - Expiration time of the temporary download url

### files.upload [POST /files.upload]

Request the upload link for a file.

+ Request (application/json)

    + Attributes (object)
        + name: `Important meeting note from August 2022.docx` (string, required) - Name under which the file will be stored. This name should contain the same extension as the file that the user wants to upload.
        + subject (object, required)
            + type: `company` (enum[string], required)
                + Members
                    + company
                    + contact
                    + deal
                    + invoice
                    + creditNote
                    + nextgenProject
                    + ticket
            + id: `2659dc4d-444b-4ced-b51c-b87591f604d7` (string, required)
        + folder: `My monthly notes` (string, optional) - Name of a folder under which the file will be stored. Defaults to `General` in account's language if not passed.

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + location: `https://files.teamleader.eu/upload/66726166a` (string) - The temporary API endpoint (URL) where user should send a POST request with file contents for the upload.
            + expires_at: `2019-10-30T11:44:33+00:00` (string) - Expiration time of the temporary API endpoint.

### files.delete [POST /files.delete]

Delete a file.

+ Request (application/json)

    + Attributes (object)
        + id: `4afb0a9c-91c6-49ed-a2e5-ce7c1e3a87fb` (string, required)

+ Response 204

# Group Templates

## Mail Templates [/mailTemplates]

### mailTemplates.list [POST /mailTemplates.list]

Get a list of all mail templates.

+ Request (application/json;charset=utf-8)

    + Attributes (object)
        + filter (object, required)
            + department_id: `a344c251-2494-0013-b433-ccee8e8435e5` (string, optional)
            + type: `invoice` (enum[string], required)
                + Members
                    + invoice
                    + quotation
                    + work_order
                    + credit_note

+ Response 200 (application/json;charset=utf-8)

    + Attributes (object)
        + data (array)
            + (object)
                + id: `a344c251-2494-0013-b433-ccee8e8435e5` (string)
                + department (object, nullable)
                    + type: `department` (string)
                    + id: `36386b05-936e-4cc0-9523-bd20d797ebf5` (string)
                + name: `Send link in english` (string)
                + content(object)
                    + subject: `Link for document` (string)
                    + body: `#LINK \n<link> Thank you for using our services` (string)
                + language: `en` (string)
                + type: `invoice` (enum[string])
                    + Members
                        + invoice
                        + quotation
                        + work_order
                        + credit_note

# Group Other

## Migrating [/migrate]

WARNING! These endpoints are not guaranteed to stay backwards compatible.
Their only use is to allow older integrations to migrate their data to the new API.

### migrate.id [POST /migrate.id]

Translates an ID from the deprecated API into a new UUID.

+ Request (application/json)

    + Attributes (object)
        + type: `contact` (enum)
            + Members
                + account
                + user
                + department
                + product
                + contact
                + company
                + deal
                + dealPhase
                + project
                + milestone
                + task
                + meeting
                + call
                + ticket
                + invoice
                + creditNote
                + subscription
                + quotation
                + timeTracking
                + customField
        + id: `1` (number)

+ Response 200 (application/json)

    + Attributes
        + data (object)
            + type: `contact` (enum)
                + Members
                    + account
                    + user
                    + department
                    + product
                    + contact
                    + company
                    + deal
                    + dealPhase
                    + project
                    + milestone
                    + todo
                    + event
                    + ticket
                    + invoice
                    + creditNote
                    + subscription
                    + quotation
                    + timeTracking
                    + customField
            + id: `6ad54ec6-ee2d-4500-afe6-0917c1aa7a38` (string)

### migrate.taxRate [POST /migrate.taxRate]

Translates tax rates from the deprecated API into a new UUID tax rate.

+ Request (application/json)

    + Attributes (object)
        + department_id: `6ad54ec6-ee2d-4500-afe6-0917c1aa7a38` (string)
        + tax_rate: `21` (string)

+ Response 200 (application/json)

    + Attributes
        + data (object)
            + type: `taxRate` (string)
            + id: `6ad54ec6-ee2d-4500-afe6-0917c1aa7a38` (string)

### migrate.activityType [POST /migrate.activityType]

Translates "meeting", "call" and "task" into their respective activity type UUID.

+ Request (application/json)

    + Attributes (object)
        + type: `meeting` (enum)
            + Members
                + meeting
                + call
                + task

+ Response 200 (application/json)

    + Attributes
        + data (object)
            + type: `activityType` (string)
            + id: `28f3639d-9b64-44a8-974d-a4df645af6a5` (string)

## Webhooks [/webhooks]

### webhooks.register [POST /webhooks.register]

Register a new webhook.

+ Request (application/json)

    + Attributes (WebHook)

+ Response 204

### webhooks.list [POST /webhooks.list]

List registered webhooks ordered by URL.

+ Request (application/json)

+ Response 200 (application/json)

    + Attributes (object)
        + data (array[WebHook])

### webhooks.unregister [POST /webhooks.unregister]

Unregister a webhook.

+ Request (application/json)

    + Attributes (WebHook)

+ Response 204

## Cloud Platforms [/cloudPlatforms]


### cloudPlatforms.url [POST /cloudPlatforms.url]

Fetch cloudPlatform url for type and id

+ Request (application/json)

    + Attributes (object)
        + type (enum, required)
            + Members
                + invoice
                + quotation
                + ticket
        + id: `b7023c11-455e-4fa5-bb96-87f37dbc7d07` (string, required)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + url: `https://teamleader.cloud/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.yUmR5yNZ45P_jHDbjAzuk4kRA8YNoM9ckSZOZpMIJmU/` (string)

## Accounts [/accounts]

### accounts.projects-v2-status [POST /accounts.projects-v2-status]

Fetch which version of Projects the account is using.

+ Request (application/json)

+ Response 200 (application/json)

    + Attributes (object)
        + data (object)
            + status: `projects-v2` (enum[string])
                + Members
                    + `projects-v2`
                    + `legacy`
            + will_be_automatically_switched_on: `2024-12-31` (string, optional) - Date when the account will be automatically switched to `projects-v2` version (optional).

# Data Structures

## Telephone (object)
+ type: `phone` (enum, required)
    + Members
        + phone
        + mobile
        + fax
+ number: `092980615` (string, required)

## CompanyTelephone (object)
+ type: `phone` (enum, required)
    + Members
        + phone
        + fax
+ number: `092980615` (string, required)

## AddressRequest (object)
+ line_1: `Dok Noord 3A 101` (string, required, nullable)
+ postal_code: `9000` (string, required, nullable)
+ city: `Ghent` (string, required, nullable)
+ country: `BE` (string, required)
+ area_level_two_id: `db232cf8-ad4a-024b-941f-15a7a74f0fd2`

## AddressResponse (object)
+ line_1: `Dok Noord 3A 101` (string, nullable)
+ postal_code: `9000` (string, nullable)
+ city: `Ghent` (string, nullable)
+ country: `BE` (string)
+ area_level_two (object, nullable)
    + type: `area_level_two` (string)
    + id: `db232cf8-ad4a-024b-941f-15a7a74f0fd2` (string)

## AddressWithAddresseeRequest (object)
+ addressee: `Teamleader HQ` (string, optional)
+ Include AddressRequest

## AddressWithAddresseeResponse (object)
+ addressee: `Teamleader HQ` (string, optional)
+ Include AddressResponse

## Currency (enum)
+ BAM
+ CAD
+ CHF
+ CLP
+ CNY
+ COP
+ CZK
+ DKK
+ EUR
+ GBP
+ INR
+ ISK
+ JPY
+ MAD
+ MXN
+ NOK
+ PEN
+ PLN
+ RON
+ SEK
+ TRY
+ USD
+ ZAR

## Money (object)
+ amount: `123.30` (number, required)
+ currency: `EUR` (Currency, required)

## Page
+ size: `20` (number, optional)
    + Default: `20`
+ number: `1` (number, optional)
    + Default: `1`

## Pagination
+ size: `10` (number)
+ number: `2` (number)

## PaymentTerm  (object)
+ type (enum)
    + Members
        + cash - Direct payment, often cash
        + end_of_month - End of the month of Xth day after the invoice date
        + after_invoice_date - X days after invoice date
+ days (number, optional) - Modifier "X" for the above statements. Not required when type is 'cash'.

## CustomField (object)
+ definition (object)
    + type: `customFieldDefinition` (string)
    + id: `bf6765de-56eb-40ec-ad14-9096c5dc5fe1` (string)
+ One Of
    + value: `092980616` (string)
    + value: `123` (number) - For integer, number and auto-increment fields
    + value: `foo`,`bar` (array[string]) - For multiple selection fields
    + value: true (boolean) - For Yes/No fields
    + value (object) - For related Teamleader objects
        + type: `company` (enum)
            + Members
                + company
                + contact
                + product
                + user
        + id: `bf6765de-56eb-40ec-ad14-9096c5dc5fe1` (string)

## CustomFieldValue (object)
+ id: `bf6765de-56eb-40ec-ad14-9096c5dc5fe1` (string)
+ One Of
    + value: `092980616` (string)
    + value: `123` (number) - For integer, number, money and auto-increment fields
    + value: `foo`,`bar` (array[string]) - For multiple selection fields
    + value: true (boolean) - For Yes/No fields
    + value (object) - For related Teamleader objects
        + type: `company` (enum)
            + Members
                + company
                + contact
                + product
                + user
        + id: `bf6765de-56eb-40ec-ad14-9096c5dc5fe1` (string)

## WebHook (object)
+ url: `https://example.com` (string, required) - Your webhook URL
+ types (array[enum], required) - Array of event types that fire the webhook
    + Members
        + account.deactivated
        + account.deleted
        + call.added
        + call.completed
        + call.deleted
        + call.updated
        + company.added
        + company.deleted
        + company.updated
        + contact.added
        + contact.deleted
        + contact.linkedToCompany
        + contact.unlinkedFromCompany
        + contact.updatedLinkToCompany
        + contact.updated
        + creditNote.booked
        + creditNote.deleted
        + creditNote.sent
        + creditNote.updated
        + deal.created
        + deal.deleted
        + deal.lost
        + deal.moved
        + deal.updated
        + deal.won
        + invoice.booked
        + invoice.deleted
        + invoice.drafted
        + invoice.paymentRegistered
        + invoice.paymentRemoved
        + invoice.sent
        + invoice.updated
        + meeting.created
        + meeting.completed
        + meeting.deleted
        + meeting.updated
        + milestone.created
        + milestone.updated
        + nextgenProject.created
        + nextgenProject.updated
        + nextgenProject.closed
        + nextgenProject.deleted 
        + product.added
        + product.updated
        + product.deleted
        + project.created
        + project.deleted
        + project.updated
        + subscription.added
        + subscription.deactivated
        + subscription.deleted
        + subscription.updated
        + task.completed
        + task.created
        + task.deleted
        + task.updated
        + ticket.closed
        + ticket.created
        + ticket.deleted
        + ticket.reopened
        + ticket.updated
        + ticketMessage.added
        + timeTracking.added
        + timeTracking.deleted
        + timeTracking.updated
        + user.deactivated

## ExpectedPaymentMethod (object)
+ One Of
    + Properties
        + method: `sepa_direct_debit` (enum[string], required)
            + Members
                + `sepa_direct_debit`
                + `direct_debit`
                + `credit_card`
        + reference: `AB1234` (string, optional, nullable)
    + Properties
        + method: `cash` (enum[string], required)
            + Members
                + `cash`
                + `cheque`
                + `bankers_draft`
                + `bank_transfer`
                + `payment_card`

## Duration (object)
+ unit: `s` (enum[string], required)
    + Members
        + `s` - Seconds
+ value: `10800` (number, required)

## User (object)
+ type: `user` (string)
+ id: `bef8c53b-b6bc-0fde-944e-5c4b16e5155a` (string)

## Customer (object)
+ type: `contact` (enum)
    + Members
        + contact
        + company
+ id: `f29abf48-337d-44b4-aad4-585f5277a456` (string)

## CommercialDiscount (object)
+ type: `percentage` (enum)
    + Members
        + percentage - Values between 0 and 100
+ value: 15.5 (number)
+ description: `winter promotion` (string)

## MimeType (enum)
+ `application/msword`
+ `application/octet-stream`
+ `application/pdf`
+ `application/vnd.ms-excel`
+ `application/vnd.ms-powerpoint`
+ `application/vnd.openxmlformats-officedocument.presentationml.presentation`
+ `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
+ `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
+ `application/xml`
+ `application/zip`
+ `audio/mpeg`
+ `audio/wav`
+ `image/gif`
+ `image/jpeg`
+ `image/png`
+ `text/css`
+ `text/csv`
+ `text/html`
+ `text/javascript`
+ `text/plain`
+ `video/3gpp`
+ `video/mpeg`
+ `video/quicktime`
+ `video/x-msvideo`

## Priority (enum)
+ `A`
+ `B`
+ `C`
+ `D`

## Language (enum)
+ en
+ nl
+ fr
+ ch
+ jp
+ de
+ es
+ pt
+ it
+ gr
+ tr
+ cs
+ so
+ sk
+ ru
+ ko
+ ir
+ iq
+ hu
+ gh
+ bg
+ bs
+ br
+ ar
+ ag
+ al
+ af
+ ro
+ pl
+ ca
+ da
+ uk
+ no
+ fi
+ sv

## InvoiceGenerationCreate (object)
+ One Of
    + Properties
        + action: `draft` (string, required)
    + Properties
        + action: `book` (string, required)
    + Properties
        + action: `book_and_send` (string, required)
        + sending_methods (array, required) - the `email` method is required.
            + (object)
                + method: `email` (enum, required)
                    + Members
                        + email
                        + postal_service
+ payment_method (enum, optional)
    + Members
        + direct_debit

## InvoiceGenerationUpdate (object)
+ One Of
    + Properties
        + action: `draft` (string, required)
    + Properties
        + action: `book` (string, required)
    + Properties
        + action: `book_and_send` (string, required)
        + sending_methods (array, required) - the `email` method is required.
            + (object)
                + method: `email` (enum, required)
                    + Members
                        + email
                        + postal_service
+ payment_method (enum, optional, nullable)
    + Members
        + direct_debit

## LineItem (object)
+ quantity: `3` (number, required)
+ description: `An awesome product` (string, required)
+ extended_description: `Some more information about this awesome product` (string, optional, nullable) - Uses Markdown formatting
+ unit_of_measure_id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string, optional, nullable)
+ unit_price (object, required)
    + amount: `123.30` (number, required)
    + tax: `excluding` (enum, required)
        + Members
            + excluding
+ tax_rate_id: `c0c03f1e-77e3-402c-a713-30ea1c585823` (string, required)
+ withholding_tax_rate_id: `c0c03f1e-77e3-402c-a713-30ea1c585824` (string, optional)
+ discount (object, optional)
    + value: 10 (number, required)
    + type (enum, required)
        + Members
            + percentage - Values between 0 and 100
+ product_category_id: `e2314517-3cab-4aa9-8471-450e73449041` (string, optional)
+ product_id: `d905ff57-e866-0f59-9d1e-1fd4538bfae1` (string, optional)

## Periodicity (object)
+ One Of
    + Properties
        + unit: `week` (string, required)
        + period: `2` (enum, required)
            + Members
                + 1
                + 2
                + 4
   + Properties
       + unit: `month` (string, required)
       + period: `4` (enum, required)
           + Members
               + 1
               + 2
               + 3
               + 4
               + 6
   + Properties
       + unit: `year` (string, required)
       + period: `7` (enum, required)
           + Members
               + 1
               + 2
               + 3
               + 4
               + 5
               + 6
               + 7
               + 8
               + 9
               + 10

## GroupedLineItem (object)
+ section (object)
    + title (string, nullable)
+ line_items (array)
    + (object)
        + product (object, nullable)
            + type: `product` (string)
            + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)
        + product_category (object, nullable)
            + type: `productCategory` (string)
            + id: `e2314517-3cab-4aa9-8471-450e73449041` (string)
        + quantity: 3 (number)
        + description: `An awesome product` (string)
        + extended_description: `Some more information about this awesome product` (string, nullable) - Uses Markdown formatting
        + unit (object, nullable)
            + type: `unitOfMeasure` (string)
            + id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string)
        + unit_price (object)
            + amount: `123.30` (number)
            + tax: `excluding` (enum)
                + Members
                    + excluding
        + tax (object)
            + type: `taxRate` (string)
            + id: `e2314517-3cab-4aa9-8471-450e73449042` (string)
        + discount (object, nullable)
            + type: `percentage` (enum)
                + Members
                    + percentage
            + value: 15.00 (number)
        + total
            + tax_exclusive (Money)
            + tax_exclusive_before_discount (Money)
            + tax_inclusive (Money)
            + tax_inclusive_before_discount (Money)
        + withheld_tax (object, nullable)
            + type: `withholding_tax` (string)
            + id: `e2314517-3cab-4aa9-8471-450e73449040` (string)

## PriceListRead (object)
+ `id`: `d905ff57-e866-0f59-9d1e-1fd4538bfae1` (string)
+ `type`: `priceList` (string)

## ProductPriceRead (object)
+ `amount`: 100 (number)
+ `currency`: `EUR` (string)

## PriceListPriceRead (object)
+ `price_list` (PriceListRead)
+ `price` (ProductPriceRead)

## PriceListPricesRead (array)
+ (array)
    + (PriceListPriceRead)

## ProductPriceWrite (object)
+ `amount`: 100 (number, required)
+ `currency`: `EUR` (string, required)

## PriceListPriceWrite (object)
+ `price_list_id`: `d905ff57-e866-0f59-9d1e-1fd4538bfae1` (string, required)
+ `price` (ProductPriceWrite, required)

## PriceListPricesWrite (array)
+ (array)
    + (PriceListPriceWrite, required)

## ProductConfigurationWrite (object)
+ `stock_threshold` (object, nullable) - Only available when stock management feature is enabled
    + `minimum`: 4 (number, required) - Cannot be negative
    + `action`: `notify` (enum, required)
        + Members
            + `notify`

## ProductConfigurationRead (object)
+ `stock_threshold` (object, nullable) - Only available when stock management feature is enabled
    + `minimum`: 4 (number)
    + `action`: `notify` (enum)
        + Members
            + `notify`

## InvoiceGroupedLinesWrite (object)
+ section (object, optional)
    + title (string, required)
+ line_items (array, required)
    + (object)
        + quantity: `3` (number, required)
        + description: `An awesome product` (string, required)
        + extended_description: `Some more information about this awesome product` (string, optional, nullable) - Uses Markdown formatting
        + unit_of_measure_id: `f79d3e04-b8dc-0637-8f18-ca7c8fc63b71` (string, optional, nullable)
        + unit_price (object)
            + amount: `123.30` (number, required)
            + tax: `excluding` (enum)
                + Members
                    + excluding
        + tax_rate_id: `c0c03f1e-77e3-402c-a713-30ea1c585823` (string, required)
        + withholding_tax_rate_id: `c0c03f1e-77e3-402c-a713-30ea1c585824` (string, optional)
        + discount (object, optional)
            + value: 10 (number, required)
            + type (enum, required)
                + Members
                    + percentage - Values between 0 and 100
        + product_category_id: `e2314517-3cab-4aa9-8471-450e73449041` (string, optional)
        + product_id: `d905ff57-e866-0f59-9d1e-1fd4538bfae1` (string, optional)

## NoteSubjectTypes (enum)
+ `company`
+ `contact`
+ `creditNote`
+ `deal`
+ `invoice`
+ `nextgenProject`
+ `product`
+ `quotation`
+ `subscription`

## EmailTrackingSubjectTypes (enum)
+ `contact`
+ `company`
+ `deal`
+ `invoice`
+ `creditNote`
+ `subscription`
+ `product`
+ `quotation`
+ `nextgenProject`

## Weekday (enum)
+ `monday`
+ `tuesday`
+ `wednesday`
+ `thursday`
+ `friday`
+ `saturday`
+ `sunday`

## TimeTrackingRelatesToTypes (enum)
+ `contact`
+ `company`
+ `project`
+ `milestone`
+ `ticket`
+ `nextgenProject`
+ `nextgenProjectGroup`