# Care API Documentation

This documentation is intended for developers and technical users who want to integrate with the Arxus Care API. It provides comprehensive information on how to authenticate, make requests, and handle responses.

## Accounts

### Account types

The Care API is designed to support two types of accounts: **customers** and **partners**.

- **Customers** are organizations that use the Care API to manage their own ITSM resources, such as cases, for their own contract.
- **Partners** are organizations that manage ITSM resources on behalf of one or more customers. Partners have access to additional features that allow them to act on behalf of their customers.


> **Note:** Some API endpoints and input fields behave differently depending on whether your account is a partner or a customer account. Refer to the endpoint documentation for details on permissions and available features.


### Contracts

A contract in the Care API represents the relationship between your account and a specific customer whose ITSM resources you can access and manage through the API.

All requests to the Care API that involve customer data must reference a contract, either directly (by contract ID) or indirectly (by operating within the context of a contract).
Contracts are used to scope permissions and data access, ensuring that users and partners only interact with resources they are authorized to manage.

When providing an invalid or unauthorized contract ID (directly or indirectly by operating within the context of the wrong contract), the API responds with a `403 Forbidden` status code and an error message indicating the validation failure(s).

- **Customers**: Your account will typically be associated with a single contract. This contract defines your organization's access to ITSM resources.
- **Partners**: Your account may be associated with multiple contracts—one for each customer you manage. Each contract allows you to act on behalf of that customer, with access to their ITSM resources as permitted.


### Email addresses for contacts

Every contact email address provided in a request is validated using the following rules.

When providing an invalid email address, the API responds with a `400 Bad Request` status code and an error message indicating the validation failure(s).

> **Note:** The statements regarding "partner" contacts only apply if the Care API account is assigned to a partner. If the account is assigned to a customer, only the customer statements are valid and partner-specific permissions do not apply.


| Endpoint | Input field | Allow contacts from |
|  --- | --- | --- |
| **Create case** | `contact` | Customer |
|  | `watchList` | Customer and Partner |
| **Create comment** | `contact` | Customer and Partner |
| **Create comment** (partnerComment) | `contact` | Partner |


## Environments

The Care API provides a **sandbox environment** for testing and development purposes. The sandbox environment allows you to experiment with the API without affecting production data.
You need a separate set of API credentials to access the sandbox environment.

All Care API responses include the `X-CareAPI-Env` header, which contains the environment the response was served from (`"Sandbox"` or `"Production"`).
This can be useful for debugging and support purposes.

### Authentication

The base URL for **authentication requests** is the same in both environments:

```http
https://api.arxus.eu/auth/v2
```

### Sandbox

Base URL for **Care API Sandbox**:

```http
https://api.arxus.eu/care/v0/sandbox
```

### Production

Base URL for **Care API Production**:

```http
https://api.arxus.eu/care/v0
```

## Input validation

The Care API validates and automatically converts input values to the required types for each field. This applies to both JSON request bodies and query string parameters. If a value cannot be converted to the required type, the API responds with a `400 Bad Request` status code and an error message indicating the validation failure(s).

### General rules

- **Type coercion:** The API attempts to coerce input values to the expected type whenever possible. For example, a string "7" can be accepted where an integer is required.
- **Strict validation:** If a value cannot be converted to the required type, the API responds with a `400 Bad Request` status code and an error message indicating the validation failure(s).
- **Query parameters:** All query string values are received as strings, but are validated and converted to the appropriate type based on the field definition.
- **JSON body**: Values in JSON bodies are validated according to their type in the schema. Both native types (e.g., int, bool) and string representations are accepted where appropriate.
- **Timezone**: If no timezone is specified in a datetime value, **UTC** is assumed.


### Value types

| Value type | Input type | Format | Example |
|  --- | --- | --- | --- |
| string | `str` |  | `"example value"` |
| integer | `int` or `float` |  | `7`, `-3.14` |
|  | `str` | `int` or `float` as string | `"7"`, `"3.14"` |
| float | `int` or `float` |  | `3.14`, `-2.5` |
|  | `str` | `int` or `float` as string | `"3.14"`, `"-2.5"` |
| boolean | `bool` |  | `true`, `false` |
|  | `int` |  | `1`, `0` |
|  | `str` | True values | `"True"`, `"true"`, `"t"`, `"on"`, `"yes"`, `"y"`, `"1"` |
|  | `str` | False values | `"False"`, `"false"`, `"f"`, `"off"`, `"no"`, `"n"`, `"0"` |
| datetime | `str` | `YYY-MM-DD[T]HH:MM[:SS[.ffffff]][Z]` | `"2025-08-03 14:30:00"` |
|  | `str` | `YYY-MM-DD[T]HH:MM[:SS[.ffffff]][[±]HH[:]MM]` | `"2025-09-07 14:30:00+02:00"` |
|  | `str` | `YYYY-MM-DD` | `"2025-08-03"` |
|  | `str` | Unix time, `int` or `float` as string | `"1754224200"` |
|  | `int` or `float` | Unix time | `1754224200` |
| date | `str` | `YYYY-MM-DD` | `"2025-08-03"` |
|  | `str` | Unix time, `int` or `float` as string | `"1754172000"` |
|  | `int` or `float` | Unix time | `1754172000` |
| time | `str` | `HH:MM[:SS[.ffffff]][Z]` | `"14:30:00"` |
|  | `str` | `HH:MM[:SS[.ffffff]][[±]HH[:]MM]` | `"14:30:00+02:00"` |
| timedelta | `int` or `float` | Seconds | `3600` |
|  | `str` | `[-][[DD]D,]HH:MM:SS[.ffffff]` | `"1,02:30:00"` |
|  | `str` | `[±]P[DD]DT[HH]H[MM]M[SS]S` | `"P1DT2H30M"` |
| array | `array` |  | `[1, 2, 3]` |
|  | `str` | Comma seperated list of values | `"1,2,3"`, `"open,closed"` |


## Pagination

List endpoints in the Care API support pagination to efficiently manage large sets of results.

### Query parameter format

Pagination is controlled using the following query parameters:

- `page[number]=2`
The page number to retrieve. The first page is 1.
- `page[size]=100`
The number of items per page. The default is 50. The maximum allowed value is 200.


> **Note:** If you request a page that does not exist, the API will return an empty array.


### Response format

Responses from list endpoints include pagination metadata in the `meta` key of the response body. The `page` object contains the following properties:

- `number`
The current page number.
- `size`
The number of items per page.
- `count`
The number of items in the current page.
- `totalCount`
The total number of items across all pages.


### Examples

- Retrieve the first page (implicit), with up to 150 items per page

```http
GET /cases?page[size]=150
```
- Retrieve the second page of cases, with up to 100 items per page

```http
GET /cases?page[number]=2&page[size]=100
```
- Retrieve the third page, with up to 50 items per page (implicit, default page size)

```http
GET /cases?page[number]=3
```


## Filtering

List endpoints in the Care API support advanced filtering using query parameters. Filters allow you to retrieve only the resources that match specific criteria.

### Query parameter format

Filters are provided as query parameters using the following formats:

> **Note:** `field`, `operator` and `value` are placeholders and should be replaced with actual field names, operators, and values.


- `filter[field][operator]=value`
Specify the field, operator, and value to filter results.
- `filter[field]=value`
Shorthand for `filter[field][eq]=value` (equality check).
- `filter[field][operator]`
For operators that do not require a value (e.g., `null`), the value can be omitted.
- `filter[field][operator]=value1,value2,value3`
For operators that accept multiple values (e.g., `in`), provide a comma-separated list.


You can combine multiple filters in a single request by adding multiple `filter` parameters.

When providing an invalid field, operator or value, the API responds with a `400 Bad Request` status code and an error message indicating the validation failure(s).

### Operators

> **Note:** Not every field or value type supports all operators. Refer to the specific endpoint documentation for details on supported fields and operators.


| Operator | Description | Value |
|  --- | --- | --- |
| `empty` | Field must be empty | None |
| `notEmpty` | Field must not be empty | None |
| `null` | Field must be null | None |
| `notNull` | Field must not be null | None |
| `exists` | Field must exist | None |
| `notExists` | Field must not exist | None |
| `eq` | Equal to value | Single value |
| `ne` | Not equal to value | Single value |
| `lt` | Less than value | Single value |
| `le` | Less than or equal to value | Single value |
| `gt` | Greater than value | Single value |
| `ge` | Greater than or equal to value | Single value |
| `contains` | Contains value | Single value |
| `notContains` | Does not contain value | Single value |
| `like` | Matches value (wildcards) | Single value |
| `notLike` | Does not match value (wildcards) | Single value |
| `match` | Matches value (regex) | Single value |
| `notMatch` | Does not match value (regex) | Single value |
| `startswith` | Starts with value | Single value |
| `notStartswith` | Does not start with value | Single value |
| `endswith` | Ends with value | Single value |
| `notEndswith` | Does not end with value | Single value |
| `sameas` | Equal to the value of another field | Single value |
| `notSameas` | Not equal to the value of another field | Single value |
| `in` | One of the provided values | Comma-separated values |
| `notIn` | Not one of the provided values | Comma-separated values |
| `between` | Value falls within the range | Two comma-separated values |
| `notBetween` | Value falls outside the range | Two comma-separated values |


### Value types

Values are validated and converted according to the field's type. Refer to the [Input validation](#section/Documentation/Input-validation) section for details on supported value types and formats.

### Examples

- Filter cases with status equal to `open`:

```http
GET /cases?filter[status]=10
```
- Filter cases created after a specific date:

```http
GET /cases?filter[createdAt][ge]=2025-01-01
```
- Filter cases with priority `critical` or `high`:

```http
GET /cases?filter[priority][in]=1,2
```
- Filter cases where the `incident` field is not null:

```http
GET /cases?filter[incident][notNull]
```


## Sorting

List endpoints in the Care API support sorting of results using the `sort` query parameter. Sorting allows you to control the order in which resources are returned.

### Query parameter format

- Use the `sort` query parameter with a comma-separated list of field names to specify the sort order.
- To sort a field in descending order, prefix the field name with a `-` (minus sign).
- By default, sorting is in ascending order.


When providing an invalid field, the API responds with a `400 Bad Request` status code and an error message indicating the validation failure(s).

### Examples

- Sort cases by `created` in ascending order:

```http
GET /cases?sort=created
```
- Sort cases by `priority` descending:

```http
GET /cases?sort=-priority
```
- Sort cases by `status` ascending, then by `created` descending:

```http
GET /cases?sort=status,-created
```


## Responses

### Headers

All responses include the `X-CareAPI-Env` header, which contains the environment the response was served from (`"Sandbox"` or `"Production"`).

### Response format

The Care API uses a consistent response format for all endpoints. Each response contains the following top-level keys:

- `meta`
Metadata about the response, such as pagination information.
- `data`
The primary data of the response, which can be a single resource object or an array of resource objects.


### Examples

- **Single resource**

```json
{
  "meta": {},
  "data": {
    "id": "12345",
    ... other fields ...
  }
}
```
- **Array of resources**

```json
{
  "meta": {
    "page": {
      "number": 1,
      "size": 50,
      "count": 50,
      "totalCount": 127
    }
  },
  "data": [
    {
      "id": "12345",
      ... other fields ...
    },
    {
      "id": "12346",
      ... other fields ...
    },
    ... more items ...
  ]
}
```


## Errors

### Headers

All responses include the `X-CareAPI-Env` header, which contains the environment the response was served from (`"Sandbox"` or `"Production"`).

### Response format

When an error occurs, the Care API returns an error response with the following top-level keys:

- `meta`
Metadata about the response.
- `errors`
An array of error objects, each containing details about the error.


All responses include the `X-CareAPI-Env` header, which contains the environment the response was served from (`"Sandbox"` or `"Production"`).

### Examples

```json
{
  "meta": {},
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "body.contract: Field required",
      "code": ""
    },
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "body.shortDescription: Field required",
      "code": ""
    }
  ]
}
```

## Webhooks

The Care API allows you to configure webhooks to receive real-time notifications about changes to your ITSM resources. Webhooks can be managed via CRUD endpoints, enabling you to create, update, list, and delete webhook configurations as needed.

### Sandbox

Webhook events are not automatically triggered in the sandbox environment. This is to prevent accidental triggering of webhooks during development and testing.
You can however test your webhook integration by using the [Event Triggers](#tag/Event-Triggers) to manually trigger webhook events in the sandbox environment.

### Webhook configuration

A webhook configuration consists of the following properties:

- **URL**: The endpoint to which webhook events will be delivered.
- **Contract(s)**: Restrict the webhook to trigger only for specific contract(s) you control (wildcards permitted).
- **Event type(s)**: Restrict the webhook to trigger only for specific event types (wildcards permitted).
- **Authorization**: (Optional) The authorization to use when sending events to the webhook. You can specify:
  - Basic auth (username and password).
  - Bearer token auth (token only).
  - Header auth (header name and value).
  - A list of the above (to support multiple headers).


You can configure a webhook to listen to all events, or only to a subset by specifying contracts and/or event types.

### Webhook events

Webhook events only trigger for resources associated with contracts you control. If a resource is not associated with any contract you control, no webhook events will be triggered.

Actions performed by your own API account will not trigger webhook events. For example, a case updated through your account will not trigger a `case.updated` event, while a case updated by a case agent will trigger the event.

The following **event types** are currently supported:

- `case.contract.assigned`
Triggered when one of your Care API contracts is assigned to a case. From this point, you can manage the case through the API. The webhook payload contains the case resource and additional data in the `meta` key.
A case can be created without a contract (for example through phone or mail). When a contract is later assigned to the case, this event is triggered.
If a case is created with a contract already assigned, this event is triggered immediately.
- `case.contract.unassigned`
Triggered when the contract on a case is changed to a contract not under your control. The webhook payload contains the case resource (before the change) and additional data in the `meta` key.
This is an edge case that should not normally occur. But human mistakes happen, and this event allows you to clean up any local state associated with the case.
- `case.updated`
Triggered when one or more fields of a case are updated. The webhook payload contains the updated case resource and additional data in the `meta` key.
The `meta` key also contains an `updated` array listing the fields that were changed.
- `case.attachment.created`
Triggered when an attachment is uploaded to a case. The webhook payload contains the attachment resource and additional data in the `meta` key.
- `case.comment.created`
Triggered when a comment is created on a case. The webhook payload contains the comment resource and additional data in the `meta` key.