> For the complete documentation index, see [llms.txt](https://engyon.gitbook.io/engyon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engyon.gitbook.io/engyon/en/api/introduction.md).

# Introduction

With the Engyon REST API, external systems can integrate with Engyon in a controlled and secure manner. Typical integrations include creating client organisations from a CRM, creating audits from a practice management system, and exchanging audit data with other tools in your audit firm's IT landscape.

This documentation is written for system integrators. It covers the basic principles of the API, how to configure a service account, how to authenticate requests, and how to implement the most common use cases.

{% hint style="info" %}
The interactive API reference (Swagger) is available at <https://audit.engyon.io/api/v1/docs/>. You must be logged into Engyon to open that page. Use that page as an authoritative reference at the field level while you build your integration.
{% endhint %}

### Base URL

All API requests use the following base URL:

```
https://audit.engyon.io/api/v1
```

For example, the token endpoint is:

```
https://audit.engyon.io/api/v1/oauth/token/
```

### How the API relates to Engyon

The API unlocks selected Engyon functionality that you already know from the application, such as:

* **Client organisations** — your audit firm's clients
* **Legal entities** — the companies belonging to a client (for example, a holding and its subsidiaries)
* **Audits** — audit files, including group audits (consolidated audits) and their component audits
* **Users and roles** — assigning existing Engyon users to clients and audits

A service account always acts on behalf of one **audit firm** (your audit firm). That organisation is derived from the credentials of the service account. You never include an identifier for the audit firm in the request body.

### External IDs

In the API, each resource is identified with an **external ID**. In request and response bodies, this value appears as the `id` field.

External IDs form the bridge between your own systems and Engyon:

* When creating a resource, you can provide an `id` yourself (for example, the client number from your CRM).
* If you omit the `id`, Engyon will generate one for you.
* Once created, the **`id` cannot be changed**. Treat it as a permanent identifier.
* Path parameters such as `{client_organisation_id}` and `{audit_id}` always refer to this external ID, not to an internal database ID.

#### Uniqueness

External IDs are unique within a defined scope:

| Resource            | Uniqueness scope                      |
| ------------------- | ------------------------------------- |
| Client organisation | Unique within your audit firm         |
| Legal entity        | Unique within its client organisation |
| Audit               | Unique within your audit firm         |

{% hint style="warning" %}
Choose stable identifiers beforehand. Because external IDs cannot be changed after creation, a poorly chosen ID can only be corrected by creating a new resource (and cleaning up the old one where possible).
{% endhint %}

#### Example

When you create the client Fictiva Holding with id `fictiva-holding`, that is the same value with which you address the client in each subsequent call:

```
GET /api/v1/client-organisations/fictiva-holding/
POST /api/v1/client-organisations/fictiva-holding/legal-entities/
POST /api/v1/audits/   # with "client_organisation_id": "fictiva-holding"
```

### Authentication in brief

The API uses the OAuth 2.0 **client credentials** flow:

1. An administrator creates a **service account** in Engyon and receives a `client_id` and `client_secret`.
2. Your integration exchanges those credentials for a short-lived access token.
3. Each API request includes that token in the `Authorization` header.

You set this up in Configuration and practice the token flow in [Basic operations](/engyon/en/api/basic-operations.md).

### What to read next

1. [Configuration](/engyon/en/api/configuration.md): creating a service account and choosing the right roles
2. [Basic operations](/engyon/en/api/basic-operations.md): retrieving a token, authenticating requests, pagination, and rate limits
3. [Use cases](/engyon/en/api/use-cases.md): end-to-end flows such as creating a client or an audit