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.

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.

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.

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.

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.

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

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

Base URL for Care API Sandbox:

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

Base URL for Care API Production:

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

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).

• 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.

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

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.

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.

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

  GET /cases?page[size]=150

• Retrieve the second page of cases, with up to 100 items per page

  GET /cases?page[number]=2&page[size]=100

• Retrieve the third page, with up to 50 items per page (implicit, default page size)

  GET /cases?page[number]=3

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

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).

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

Values are validated and converted according to the field's type. Refer to the Input validation section for details on supported value types and formats.

• Filter cases with status equal to open:

  GET /cases?filter[status]=10

• Filter cases created after a specific date:

  GET /cases?filter[createdAt][ge]=2025-01-01

• Filter cases with priority critical or high:

  GET /cases?filter[priority][in]=1,2

• Filter cases where the incident field is not null:

  GET /cases?filter[incident][notNull]

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.

• 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).

• Sort cases by created in ascending order:

  GET /cases?sort=created

• Sort cases by priority descending:

  GET /cases?sort=-priority

• Sort cases by status ascending, then by created descending:

  GET /cases?sort=status,-created

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

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.

• Single resource
  {
    "meta": {},
    "data": {
      "id": "12345",
      ... other fields ...
    }
  }

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

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

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

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

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.

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 to manually trigger webhook events in the sandbox environment.

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