### Example JSON Response

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_2_1_administrations.html.md

The expected JSON structure returned by the administrations query.

```json
{
  "data": {
    "administrations": [
      {
        "name": "Acme Company",
        "companyNumber": "0123123123",
        "accountManager": "account.manager@acme.be",
        "emails": [
          {
            "type": "purchase",
            "emailAddress": "aankoop-0123123123@acme.clearfacts.be"
          },
          {
            "type": "purchase",
            "emailAddress": "achat-0123123123@acme.clearfacts.be"
          }
        ],
        "address": {
          "streetAddress": "Street 16",
          "country": {
            "iso2": "BE",
            "name": "Belgium"
          }
        }
      }
    ]
  }
}
```

--------------------------------

### POST /graphql (Get Administrations)

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieves all client administrations that the authenticated user has access to.

```APIDOC
## POST /graphql

### Description
Retrieves all client administrations (companies) that the authenticated user has access to, including contact information and email addresses.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql
```

--------------------------------

### Initialize and Start Slate

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/README.md

Commands to launch the Slate documentation server either locally or within a Vagrant environment.

```shell
# either run this to run locally
bundle install
bundle exec middleman server

# OR run this to run with vagrant
vagrant up
```

--------------------------------

### Example JSON Response

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_1_journals.html.md

The structure of the data returned by the journals query.

```json
{
  "data": {
    "journals": [
      {
        "id": "CFAK",
        "name": "ClearFacts Aankopen",
        "creditNote": false
      }
    ]
  }
}
```

--------------------------------

### POST /graphql (Get Administration)

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieves a specific administration by company number.

```APIDOC
## POST /graphql

### Description
Retrieves a specific administration by company number.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Query Parameters
- **companyNumber** (String) - Required - The company number to filter by.
```

--------------------------------

### OpenID Connect Discovery

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieves the OpenID Connect configuration for automatic client setup.

```APIDOC
## GET /.well-known/openid-configuration

### Description
Retrieves the OpenID Connect configuration for automatic client setup.

### Method
GET

### Endpoint
https://login.clearfacts.be/.well-known/openid-configuration

### Request Example
```shell
curl -X GET \
  https://login.clearfacts.be/.well-known/openid-configuration
```

### Response
#### Success Response (200)
- **issuer** (string) - The issuer identifier for the OpenID Connect provider.
- **authorization_endpoint** (string) - The authorization endpoint URL.
- **token_endpoint** (string) - The token endpoint URL.
- **userinfo_endpoint** (string) - The userinfo endpoint URL.
- **jwks_uri** (string) - The JSON Web Key Set (JWKS) URI.
- **response_types_supported** (array) - Supported response types.
- **subject_types_supported** (array) - Supported subject types.
- **id_token_signing_alg_values_supported** (array) - Supported signing algorithms for ID tokens.
- **scopes_supported** (array) - Supported scopes.

#### Response Example
```json
{
  "issuer": "https://login.clearfacts.be",
  "authorization_endpoint": "https://login.clearfacts.be/oauth2-server/authorize",
  "token_endpoint": "https://login.clearfacts.be/oauth2-server/token",
  "userinfo_endpoint": "https://login.clearfacts.be/oauth2-server/userinfo",
  "jwks_uri": "https://login.clearfacts.be/oauth2-server/jwks.json",
  "response_types_supported": ["code", "token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": ["openid", "profile", "email"]
}
```

### Note
For accountant-specific branding, use the following endpoint:
`https://<accountant_subdomain>.clearfacts.be/.well-known/openid-configuration`
```

--------------------------------

### Retrieve OpenID Connect Configuration

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Fetch the OIDC configuration for client setup, including endpoints and supported scopes. Accountant-specific branding can be retrieved by replacing the domain prefix.

```shell
# Get OIDC configuration
curl -X GET \
  https://login.clearfacts.be/.well-known/openid-configuration

# Response:
# {
#   "issuer": "https://login.clearfacts.be",
#   "authorization_endpoint": "https://login.clearfacts.be/oauth2-server/authorize",
#   "token_endpoint": "https://login.clearfacts.be/oauth2-server/token",
#   "userinfo_endpoint": "https://login.clearfacts.be/oauth2-server/userinfo",
#   "jwks_uri": "https://login.clearfacts.be/oauth2-server/jwks.json",
#   "response_types_supported": ["code", "token"],
#   "subject_types_supported": ["public"],
#   "id_token_signing_alg_values_supported": ["RS256"],
#   "scopes_supported": ["openid", "profile", "email"]
# }

# For accountant-specific branding (optional):
curl -X GET \
  https://acme.clearfacts.be/.well-known/openid-configuration
```

--------------------------------

### Archive Categories Response Format

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_3_3_archive_categories.html.md

Example JSON response containing the various and permanent category arrays.

```json
{
  "data": {
    "archiveCategories": {
      "various": [
        {
          "id": "f5c3d05a-2d05-4329-ae31-3f144bfbeb41",
          "name": "Beleggingen"
        }
      ],
      "permanent": [
        {
          "id": "2fcff67d-3753-11e8-8c32-02907d97d1d8",
          "name": "Huurovereenkomst"
        }
      ]
    }
  }
}
```

--------------------------------

### GraphQL Query Response

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_3_2_document.html.md

Example JSON response structure returned after querying a document.

```json
{
 "data": {
    "document": {
      "date": "2025-01-01",
      "type": "PURCHASE",
      "paymentState": "UNPAID"
    }
  }
}
```

--------------------------------

### Company Statistics Response Format

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_3_company_statistics.html.md

Example JSON response structure returned by the getCompanyStatistics query.

```json
{
  "data": {
    "getCompanyStatistics": [
      {
        "companyNumber": "BE0123123123",
        "items": [
          {
            "period": "01/2025",
            "value": 5
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### GraphQL Customer Query Response

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_2_customers.html.md

Example JSON response structure for a customer query. Each customer object contains an `id` and `name`.

```json
{
  "data": {
    "customers": [
      {
        "id": "ACME",
        "name": "Acme Corporation"
      }
    ]
  }
}
```

--------------------------------

### Introduction

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/index.html.md

Overview of the Clearfacts API and its capabilities.

```APIDOC
## Introduction

This document provides a comprehensive reference for the Clearfacts API. It covers authentication, available endpoints for managing data, and response formats.

### Key Features

*   **Data Management**: Access and modify various data entities.
*   **Document Processing**: Upload and manage documents.
*   **Authentication**: Securely authenticate your API requests.
```

--------------------------------

### Retrieve OIDC Configuration

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/22_authentication_oidc.html.md

Use the discovery endpoint to automatically configure OIDC clients and inspect supported features.

```shell
curl -X GET \
  https://login.clearfacts.be/.well-known/openid-configuration
```

```json
{
	"issuer": "https://login.clearfacts.be",
	"authorization_endpoint": "https://login.clearfacts.be/oauth2-server/authorize",
	"token_endpoint": "https://login.clearfacts.be/oauth2-server/token",
	"userinfo_endpoint": "https://login.clearfacts.be/oauth2-server/userinfo",
	"jwks_uri": "https://login.clearfacts.be/oauth2-server/jwks.json",
	"response_types_supported": ["code", "token"],
	"subject_types_supported": ["public"],
	"id_token_signing_alg_values_supported": ["RS256"],
	"scopes_supported": ["openid", "profile", "email"]
}
```

--------------------------------

### Query Customers (Paginated)

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieves customers for a specific administration. Results are paginated with a default of 100 customers per request. Use offset for subsequent pages.

```shell
# First page
curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -d '{"query": "query customers { customers (companyNumber: \"0123123123\") { id, name } }"}'

# With pagination offset for subsequent pages
curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -d '{"query": "query customers { customers (companyNumber: \"0123123123\", offset: 100) { id, name } }"}'
```

--------------------------------

### Query All Administrations

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieve all client administrations accessible to the authenticated user. This includes contact details and email addresses.

```shell
curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -d '{"query": "query admins { administrations { name, companyNumber, accountManager, emails { type, emailAddress }, address { streetAddress, country { iso2, name } } } }"}'
```

--------------------------------

### Test Personal Access Token

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/21_authentication_personal_access_token.html.md

Use this curl command to test your personal access token by retrieving user information. Replace `<token>` with your actual token.

```shell
# Replace <token> with your actual personal access token.
curl -H "Authorization: Bearer <token>" \
  -X GET \
  https://login.clearfacts.be/oauth2-server/userinfo
```

```json
{
  "sub":"user@domain.com",
  "username":"user@domain.com",
  "email":"user@domain.com"
}
```

--------------------------------

### Mutation - Update App Info

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Creates or updates customization settings for an application connected to your integration, including badges and icons.

```APIDOC
## POST /graphql

### Description
Creates or updates customization settings for an application connected to your integration, including badges and icons.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Parameters
#### Query Parameters
- **query** (String!) - Required - The GraphQL mutation string.
- **variables** (JSON!) - Required - The variables for the GraphQL mutation.

### Request Body
This endpoint uses `multipart/form-data` for the `query` and `variables`.

### Request Example
```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -F 'query=mutation update ($vatnumber: String!, $imageUrl: String, $emailAddress: String, $badgeText: String, $badgeTextColor: String, $badgeColor: String, $iconType: String, $iconColor: String) { updateAppInfo (vatnumber: $vatnumber, imageUrl: $imageUrl, emailaddress: $emailAddress, badge: { text: $badgeText, textColor: $badgeTextColor, color: $badgeColor }, icon: { type: $iconType, color: $iconColor }) { vatnumber, imageUrl, emailaddress, icon { type, color }, badge { text, textColor, color } } }' \
  -F 'variables={ "vatnumber": "0123123123", "imageUrl": "https://example.com/logo.png", "emailAddress": "test@clearfacts.be", "badgeText": "NEW", "badgeTextColor": "#d5a855", "badgeColor": "red", "iconType": "trophy", "iconColor": "yellow" }'
```

### Response
#### Success Response (200)
- **data** (Object) - The result of the mutation.
  - **updateAppInfo** (Object) - Information about the updated app settings.
    - **vatnumber** (String) - The VAT number of the application.
    - **imageUrl** (String) - The URL of the application's image.
    - **emailaddress** (String) - The email address of the application.
    - **icon** (Object) - The application's icon settings.
      - **type** (String) - The type of the icon.
      - **color** (String) - The color of the icon.
    - **badge** (Object) - The application's badge settings.
      - **text** (String) - The text of the badge.
      - **textColor** (String) - The text color of the badge.
      - **color** (String) - The color of the badge.

#### Response Example
```json
{
  "data": {
    "updateAppInfo": {
      "vatnumber": "0123123123",
      "imageUrl": "https://example.com/logo.png",
      "emailaddress": "test@clearfacts.be",
      "icon": {
        "type": "trophy",
        "color": "yellow"
      },
      "badge": {
        "text": "NEW",
        "textColor": "#d5a855",
        "color": "red"
      }
    }
  }
}
```
```

--------------------------------

### POST /graphql (Administration Query)

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_2_2_administration.html.md

Retrieves details for a specific administration based on the provided company number.

```APIDOC
## POST /graphql

### Description
Queries a specific administration that the user has access to using a GraphQL query.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Parameters
#### Request Body (GraphQL)
- **companyNumber** (String) - Required - The unique identifier for the company.

### Request Example
query admin {
  administration (companyNumber: "0123123123") {
    name,
    companyNumber,
    accountManager,
    emails {
      type,
      emailAddress
    }
    address {
      streetAddress,
      country {
        iso2,
        name
      }
    }
  }
}

### Response
#### Success Response (200)
- **data.administration** (Object) - The administration object containing company details.

#### Response Example
{
  "data": {
    "administration": {
      "name": "Acme Company",
      "companyNumber": "0123123123",
      "accountManager": "account.manager@acme.be",
      "emails": [
        {
          "type": "purchase",
          "emailAddress": "aankoop-0123123123@acme.clearfacts.be"
        }
      ],
      "address": {
        "streetAddress": "Street 16",
        "country": {
          "iso2": "BE",
          "name": "Belgium"
        }
      }
    }
  }
}
```

--------------------------------

### POST /graphql (Upload File)

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Uploads a document to the Inbox of a specific administration.

```APIDOC
## POST /graphql

### Description
Uploads a document (invoice) to the Inbox of a specific administration. Supports PDF, JPEG images, and XML files.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Request Body
- **vatNumber** (String) - Required - The VAT number of the administration.
- **fileName** (String) - Required - The name of the file.
- **invoiceType** (InvoiceTypeArgument) - Required - The type of invoice (e.g., PURCHASE).
- **file** (File) - Required - The file content.
```

--------------------------------

### POST /graphql - Query Customers

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieves customers (business partners) for a specific administration with pagination support.

```APIDOC
## POST /graphql

### Description
Retrieves customers (business partners) for a specific administration. Results are paginated with a maximum of 100 customers per request.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Request Body
- **query** (string) - Required - GraphQL query string containing companyNumber and optional offset.
```

--------------------------------

### POST /graphql - Query Administrations

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_2_1_administrations.html.md

Retrieves a list of administrations that the authenticated user has access to, including company details, contact emails, and address information.

```APIDOC
## POST /graphql

### Description
Queries all the administrations the user has access to.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Request Body
```graphql
query admins {
  administrations {
    name,
    companyNumber,
    accountManager,
    emails {
      type,
      emailAddress
    }
    address {
      streetAddress,
      country {
        iso2,
        name
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The root object containing the query results.
- **administrations** (array) - A list of Administration objects.

#### Response Example
{
  "data": {
    "administrations": [
      {
        "name": "Acme Company",
        "companyNumber": "0123123123",
        "accountManager": "account.manager@acme.be",
        "emails": [
          {
            "type": "purchase",
            "emailAddress": "aankoop-0123123123@acme.clearfacts.be"
          }
        ],
        "address": {
          "streetAddress": "Street 16",
          "country": {
            "iso2": "BE",
            "name": "Belgium"
          }
        }
      }
    ]
  }
}
```

--------------------------------

### Upload File Mutation using cURL

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_3_1_upload_file.html.md

Use this cURL command to upload a file via the Clearfacts API. Ensure you replace `<token>` with your actual API token and provide the correct file path. The mutation and variables are sent as form-data.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -F 'query=<query>' \
  -F 'variables={ "vatNumber": "0123123123", "fileName": "test_upload.pdf", "invoiceType": "PURCHASE" }' \
  -F file=@/home/user/Documents/example.pdf
```

--------------------------------

### Update App Info Mutation

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Use this mutation to create or update customization settings for an application, including badges and icons. Requires authentication with a Bearer token.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -F 'query=mutation update ($vatnumber: String!, $imageUrl: String, $emailAddress: String, $badgeText: String, $badgeTextColor: String, $badgeColor: String, $iconType: String, $iconColor: String) { updateAppInfo (vatnumber: $vatnumber, imageUrl: $imageUrl, emailaddress: $emailAddress, badge: { text: $badgeText, textColor: $badgeTextColor, color: $badgeColor }, icon: { type: $iconType, color: $iconColor }) { vatnumber, imageUrl, emailaddress, icon { type, color }, badge { text, textColor, color } } }' \
  -F 'variables={ "vatnumber": "0123123123", "imageUrl": "https://example.com/logo.png", "emailAddress": "test@clearfacts.be", "badgeText": "NEW", "badgeTextColor": "#d5a855", "badgeColor": "red", "iconType": "trophy", "iconColor": "yellow" }'
```

--------------------------------

### Query Administration Details via GraphQL

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_2_2_administration.html.md

Use this GraphQL query to retrieve details for a specific administration, such as name, company number, account manager, emails, and address. Requires an authentication token.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql
```

```graphql
query admin {
  administration (companyNumber: "0123123123") {
    name,
    companyNumber,
    accountManager,
    emails {
      type,
      emailAddress
    }
    address {
      streetAddress,
      country {
        iso2,
        name
      }
    }
  }
}
```

```json
{
  "data": {
    "administration": {
      "name": "Acme Company",
      "companyNumber": "0123123123",
      "accountManager": "account.manager@acme.be",
      "emails": [
        {
          "type": "purchase",
          "emailAddress": "aankoop-0123123123@acme.clearfacts.be"
        },
        {
          "type": "purchase",
          "emailAddress": "achat-0123123123@acme.clearfacts.be"
        }
      ],
      "address": {
        "streetAddress": "Street 16",
        "country": {
          "iso2": "BE",
          "name": "Belgium"
        }
      }
    }
  }
}
```

--------------------------------

### Upload Archive File using cURL

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_3_4_upload_archive_file.html.md

Use this cURL command to upload an archive file. Ensure you replace <token> with your actual API token and provide the correct file path. The variables include vatNumber, fileName, type, and category.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -F 'query=<query>' \
  -F 'variables={ "vatNumber": "0123123123", "fileName": "test_upload.pdf", "type": "VARIOUS", "category": "f5c3d05a-2d05-4329-ae31-3f144bfbeb41" }' \
  -F file=@/home/user/Documents/example.pdf
```

--------------------------------

### Upload Archive File

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Uploads a file to the Various or Permanent Archive. Requires administration VAT number, filename, type, and category ID.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -F 'query=mutation upload ($vatNumber: String!, $fileName: String!, $type: VariousType!, $category: String!) { uploadArchiveFile (vatnumber: $vatNumber, filename: $fileName, type: $type, category: $category) { uuid, amountOfPages } }' \
  -F 'variables={ "vatNumber": "0123123123", "fileName": "test_upload.pdf", "type": "VARIOUS", "category": "f5c3d05a-2d05-4329-ae31-3f144bfbeb41" }' \
  -F file=@/home/user/Documents/example.pdf
```

--------------------------------

### GraphQL Mutation for Updating App Info

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_4_update_app_info.html.md

This GraphQL mutation defines the structure for updating app information, including VAT number, image URL, email, badge customization, and icon customization. It specifies the input arguments and the fields to be returned.

```graphql
mutation update ($vatnumber: String!, $imageUrl: String, $emailAddress: String, $badgeText: String, $badgeTextColor: String, $badgeColor: String, $iconType: String, $iconColor: String) {
  updateAppInfo (vatnumber: $vatnumber, imageUrl: $imageUrl, emailaddress: $emailAddress, badge: { text: $badgeText, textColor: $badgeTextColor, color: $badgeColor }, icon: { type: $iconType, color: $iconColor }) {
    vatnumber,
    imageUrl,
    emailaddress,
    icon { type, color },
    badge { text, textColor, color }
  }
}
```

--------------------------------

### POST /graphql - getCompanyStatistics

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_3_company_statistics.html.md

Queries company statistics for administrations accessible to the user, filtered by type and time period.

```APIDOC
## POST /graphql

### Description
Queries the company statistics of a specific administration the user has access to. The statistics can be filtered by type (AIR or processing) and a specific date range.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Parameters
#### Request Body (GraphQL Query)
- **type** (String) - Required - The type of statistics to retrieve: 'AIR' (Automatic Invoice Recognition) or 'processing' (documents processed into accountant software).
- **startPeriod** (String) - Required - The start date for the statistics period (format: YYYY-MM-DD).
- **endPeriod** (String) - Required - The end date for the statistics period (format: YYYY-MM-DD).

### Request Example
```graphql
query statistics {
  getCompanyStatistics (type: "AIR", startPeriod: "2025-01-01", endPeriod: "2025-12-31") {
    companyNumber,
    items {
      period,
      value
    }
  }
}
```

### Response
#### Success Response (200)
- **companyNumber** (String) - The identifier of the administration.
- **items** (Array) - A list of statistics objects per period.
- **period** (String) - The month/year period of the statistic.
- **value** (Integer) - The count of items for the given period.

#### Response Example
{
  "data": {
    "getCompanyStatistics": [
      {
        "companyNumber": "BE0123123123",
        "items": [
          {
            "period": "01/2025",
            "value": 5
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Upload File Mutation

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Upload a document to an administration's Inbox. Supported formats include PDF, JPEG, and specific XML types. Requires VAT number, filename, and invoice type.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -F 'query=mutation upload ($vatNumber: String!, $fileName: String!, $invoiceType: InvoiceTypeArgument!) { uploadFile (vatnumber: $vatNumber, filename: $fileName, invoicetype: $invoiceType) { uuid, amountOfPages } }' \
  -F 'variables={ "vatNumber": "0123123123", "fileName": "test_upload.pdf", "invoiceType": "PURCHASE" }' \
  -F file=@/home/user/Documents/example.pdf
```

--------------------------------

### GraphQL Mutation Response for App Info Update

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_4_update_app_info.html.md

This JSON object represents the successful response from the `updateAppInfo` GraphQL mutation. It confirms the updated app information, including VAT number, image URL, email, icon details, and badge customization.

```json
{
  "data": {
    "updateAppInfo": {
      "vatnumber": "0123123123",
      "imageUrl" : "XXX",
      "emailaddress": "test@clearfacts.be",
      "icon": {
        "type": "trophy",
        "color": "yellow"
      },
      "badge": {
        "text": "NEW",
        "textColor": "#d5a855",
        "color": "red"
      }
    }
  }
}
```

--------------------------------

### Mutation - Update App Info

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_4_update_app_info.html.md

This mutation allows you to create or update customization for the app connected to your integration. Contact support@clearfacts.be if you need an app connected to your integration.

```APIDOC
## POST /graphql

### Description
Allows creation or update of app customization settings.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Parameters
#### Query Parameters
- **query** (String!) - Required - The GraphQL query string.
- **variables** (JSON) - Required - A JSON object containing the variables for the mutation.

### Request Body
This endpoint uses `multipart/form-data` for the `query` and `variables`.

#### Request Example (Shell)
```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql
  -F 'query=<query>' \
  -F 'variables={ "vatnumber": "0123123123", "imageUrl": "XXX", "emailAddress": "test@clearfacts.be", "badgeText": "NEW", "badgeTextColor": "#d5a855", "badgeColor": "red", "iconType": "trophy", "iconColor":"yellow" }'
```

#### Request Example (GraphQL Variables)
```json
{
  "vatnumber": "String!",
  "imageUrl": "String",
  "emailAddress": "String",
  "badgeText": "String",
  "badgeTextColor": "String",
  "badgeColor": "String",
  "iconType": "String",
  "iconColor": "String"
}
```

### Response
#### Success Response (200)
- **vatnumber** (String) - The VAT number of the app.
- **imageUrl** (String) - The URL of the app's image.
- **emailaddress** (String) - The email address associated with the app.
- **icon** (Object) - Information about the app's icon.
  - **type** (String) - The type of the icon.
  - **color** (String) - The color of the icon.
- **badge** (Object) - Information about the app's badge.
  - **text** (String) - The text displayed on the badge.
  - **textColor** (String) - The text color of the badge.
  - **color** (String) - The background color of the badge.

#### Response Example
```json
{
  "data": {
    "updateAppInfo": {
      "vatnumber": "0123123123",
      "imageUrl" : "XXX",
      "emailaddress": "test@clearfacts.be",
      "icon": {
        "type": "trophy",
        "color": "yellow"
      },
      "badge": {
        "text": "NEW",
        "textColor": "#d5a855",
        "color": "red"
      }
    }
  }
}
```
```

--------------------------------

### Authentication

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/index.html.md

Details on how to authenticate your API requests using different methods.

```APIDOC
## Authentication

Clearfacts API supports multiple authentication methods to secure your requests.

### Personal Access Token

Personal Access Tokens (PATs) can be generated and used for authentication. Ensure your token is kept secure.

### OpenID Connect (OIDC)

Integrate with Clearfacts using OpenID Connect for a standardized authentication flow.

### Scopes

API requests may require specific scopes to access certain resources or perform particular actions. Refer to the documentation for detailed scope requirements for each endpoint.
```

--------------------------------

### GraphQL Query for Administrations

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_2_1_administrations.html.md

Retrieve administration details including name, company number, account manager, emails, and address.

```graphql
query admins {
  administrations {
    name,
    companyNumber,
    accountManager,
    emails {
      type,
      emailAddress
    }
    address {
      streetAddress,
      country {
        iso2,
        name
      }
    }
  }
}
```

--------------------------------

### Query Accountant Details

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieve organization information, contact details, and address for the authenticated user.

```shell
curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -d '{"query": "query accountant { accountant { name, companyNumber, email, address { streetAddress, country { iso2, name } } } }"}'

# Response:
# {
#   "data": {
#     "accountant": {
#       "name": "Acme Company",
#       "companyNumber": "0123123123",
#       "email": "accountant@acme.be",
#       "address": {
#         "streetAddress": "Street 16",
#         "country": {
#           "iso2": "BE",
#           "name": "Belgium"
#         }
#       }
#     }
#   }
# }
```

--------------------------------

### Query Archive Categories

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieves available archive categories for a specific administration. Includes both various and permanent categories.

```shell
curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -d '{"query": "query categories { archiveCategories (vatnumber: \"0123123123\") { various { id, name }, permanent { id, name } } }"}'
```

--------------------------------

### Query Associates

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Fetch a list of employees belonging to the accountant organization.

```shell
curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -d '{"query": "query associates { associates { id, email } }"}'

# Response:
# {
#   "data": {
#     "associates": [
#       {
#         "id": "123e4567-e89b-12d3-a456-426614174000",
#         "email": "account.manager@acme.be"
#       }
#     ]
#   }
# }
```

--------------------------------

### Add Associate Mutation Request

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_1_4_add_associate.html.md

Use this `curl` command to send a POST request to the GraphQL endpoint to add a new associate. Ensure you replace `<token>` with your valid authentication token.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql
  -F 'query=<query>' \
  -F 'variables={ "associate": { "firstName": "Test", "lastName": "Associate", "email": "associate@acme.be", "type": "ADMIN", "associateGroups": [{ "id": "2ff2f0a8-3753-11e8-8c32-02907d97d1d8" }], "active": true, "language": "nl_BE", "sendActivationMail": false } }'
```

--------------------------------

### POST /graphql - Query Archive Categories

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieves available archive categories (various and permanent) for a specific administration.

```APIDOC
## POST /graphql

### Description
Retrieves available archive categories (various and permanent) for a specific administration.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Request Body
- **query** (string) - Required - GraphQL query string containing the vatnumber.

### Response
#### Success Response (200)
- **data.archiveCategories** (object) - Contains lists of various and permanent categories.
```

--------------------------------

### POST /graphql - Mutation Upload Archive File

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Uploads a file to the Various or Permanent Archive of a specific administration.

```APIDOC
## POST /graphql

### Description
Uploads a file to the Various or Permanent Archive of a specific administration, categorized by archive category ID.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Request Body
- **query** (string) - Required - The mutation definition.
- **variables** (object) - Required - Contains vatNumber, fileName, type, and category.
- **file** (binary) - Required - The file content to upload.

### Response
#### Success Response (200)
- **data.uploadArchiveFile** (object) - Returns the uuid and amountOfPages of the uploaded file.
```

--------------------------------

### GraphQL Query for Customers

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_2_customers.html.md

This GraphQL query retrieves customer IDs and names for a specified company number. The results are paginated, with a maximum of 100 customers per request. Use the `offset` argument for subsequent pages.

```graphql
query customers {
  customers (companyNumber: "0123123123") {
    id,
    name
  }
}
```

--------------------------------

### POST /graphql - uploadArchiveFile

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_3_4_upload_archive_file.html.md

Uploads a file to the Various or Permanent Archive of a specific administration.

```APIDOC
## POST /graphql

### Description
Uploads a file to the Various or Permanent Archive of a specific administration the user has access to.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Parameters
#### Request Body (GraphQL Variables)
- **vatNumber** (String) - Required - The VAT number of the administration.
- **fileName** (String) - Required - The name of the file being uploaded.
- **type** (VariousType) - Required - The type of the archive file.
- **category** (String) - Required - The ID of the category retrieved via the Archive Categories query.

### Request Example
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -F 'query=mutation upload ($vatNumber: String!, $fileName: String!, $type: VariousType!, $category: String!) { uploadArchiveFile (vatnumber: $vatNumber, filename: $fileName, type: $type, category: $category) { uuid, amountOfPages } }' \
  -F 'variables={ "vatNumber": "0123123123", "fileName": "test_upload.pdf", "type": "VARIOUS", "category": "f5c3d05a-2d05-4329-ae31-3f144bfbeb41" }' \
  -F file=@/home/user/Documents/example.pdf

### Response
#### Success Response (200)
- **uuid** (String) - The unique identifier of the uploaded file.
- **amountOfPages** (Int) - The number of pages in the uploaded file.

#### Response Example
{
  "data": {
    "uploadArchiveFile": {
      "uuid": "B74D7E7D-2408-4517-AA31-BB76018E844D",
      "amountOfPages": 1
    }
  }
}
```

--------------------------------

### Query Customers API

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_2_customers.html.md

This endpoint allows you to query customers associated with a specific company. The results are paginated, with a maximum of 100 customers per request. You can use the `offset` argument to retrieve subsequent pages of results.

```APIDOC
## POST /graphql

### Description
Queries all the customers of a specific administration the user has access to. For performance reasons, this list is paginated. A maximum of 100 customers will be returned per request. If there are more customers to retrieve, you can use the `offset` argument to get the next page.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Parameters
#### Query Parameters
- **companyNumber** (String) - Required - The company number for which to retrieve customers.
- **offset** (Int) - Optional - Used for pagination to retrieve subsequent pages of results.

### Request Example
```json
{
  "query": "query customers($companyNumber: String!, $offset: Int) {\n  customers (companyNumber: $companyNumber, offset: $offset) {\n    id,\n    name\n  }\n}",
  "variables": {
    "companyNumber": "0123123123",
    "offset": 0
  }
}
```

### Response
#### Success Response (200)
- **data** (Object) - Contains the query results.
  - **customers** (Array of BusinessPartner objects) - A list of customer objects.
    - **id** (String) - The unique identifier for the customer.
    - **name** (String) - The name of the customer.

#### Response Example
```json
{
  "data": {
    "customers": [
      {
        "id": "ACME",
        "name": "Acme Corporation"
      }
    ]
  }
}
```
```

--------------------------------

### Query Specific Administration

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Retrieve details for a specific client administration using its company number. This query returns contact and address information.

```shell
curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -d '{"query": "query admin { administration (companyNumber: \"0123123123\") { name, companyNumber, accountManager, emails { type, emailAddress }, address { streetAddress, country { iso2, name } } } }"}'
```

--------------------------------

### Execute GraphQL Query via cURL

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_3_2_document.html.md

Use this cURL command to send a POST request to the ClearFacts GraphQL endpoint with an authorization token.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql
```

--------------------------------

### Update App Info Mutation Request

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_4_4_update_app_info.html.md

Use this cURL command to send a POST request to the GraphQL endpoint to update app information. Ensure you replace `<token>` with your actual bearer token and provide the necessary variables.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -F 'query=<query>' \
  -F 'variables={ "vatnumber": "0123123123", "imageUrl": "XXX", "emailAddress": "test@clearfacts.be", "badgeText": "NEW", "badgeTextColor": "#d5a855", "badgeColor": "red", "iconType": "trophy", "iconColor":"yellow" }'
```

--------------------------------

### Administrations API

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/index.html.md

Endpoints for managing administration-related data.

```APIDOC
## Administrations API

Endpoints for accessing and managing administration data.

### List Administrations

Retrieves a list of all administrations.

### Method
GET

### Endpoint
`/api/administrations`

### Response
#### Success Response (200)
- **administrations** (array) - A list of administration objects.
  - **id** (integer) - The administration's unique identifier.
  - **name** (string) - The name of the administration.

#### Response Example
```json
{
  "administrations": [
    {
      "id": 101,
      "name": "Adminstration Alpha"
    }
  ]
}
```

### Get Administration by ID

Retrieves a specific administration by its ID.

### Method
GET

### Endpoint
`/api/administrations/{administration_id}`

### Path Parameters
- **administration_id** (integer) - Required - The ID of the administration to retrieve.

### Response
#### Success Response (200)
- **id** (integer) - The administration's unique identifier.
- **name** (string) - The name of the administration.

#### Response Example
```json
{
  "id": 101,
  "name": "Adminstration Alpha"
}
```
```

--------------------------------

### POST /graphql - Add Associate

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_1_4_add_associate.html.md

Adds a new associate to the accountant the user is linked to. Note that the plain password is only returned during this creation process.

```APIDOC
## POST /graphql

### Description
Adds a new associate to the accountant the user is linked to. This is the only opportunity to retrieve the plain password for the new associate.

### Method
POST

### Endpoint
https://api.clearfacts.be/graphql

### Request Body
- **associate** (AddAssociateArgument!) - Required - Object containing associate details including firstName, lastName, email, type, associateGroups, active, language, and sendActivationMail.

### Request Example
{
  "query": "mutation add ($associate: AddAssociateArgument!) { addAssociate (associate: $associate) { id, associateGroups { id, name }, plainPassword } }",
  "variables": {
    "associate": {
      "firstName": "Test",
      "lastName": "Associate",
      "email": "associate@acme.be",
      "type": "ADMIN",
      "associateGroups": [{"id": "2ff2f0a8-3753-11e8-8c32-02907d97d1d8"}],
      "active": true,
      "language": "nl_BE",
      "sendActivationMail": false
    }
  }
}

### Response
#### Success Response (200)
- **id** (String) - The unique identifier of the new associate.
- **associateGroups** (Array) - List of groups the associate belongs to.
- **plainPassword** (String) - The generated password for the new associate.

#### Response Example
{
  "data": {
    "addAssociate": {
      "id": "198772ef-d095-4859-9328-dc47950853b9",
      "associateGroups": [
        {
          "id": "2ff2f0a8-3753-11e8-8c32-02907d97d1d8",
          "name": "Test Group"
        }
      ],
      "plainPassword": "generatedPassword123"
    }
  }
}
```

--------------------------------

### Query Associates via GraphQL API

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_1_2_associates.html.md

Use this request to retrieve a list of associates linked to the authenticated user's accountant.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql
```

```graphql
query associates {
  associates {
    id,
    email
  }
}
```

```json
{
  "data": {
    "associates": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "account.manager@acme.be"
      }
    ]
  }
}
```

--------------------------------

### Query Associate Groups via GraphQL

Source: https://github.com/clearfacts/cf_developer_docs/blob/master/source/includes/30_1_3_associate_groups.html.md

Use this request to fetch associate groups. Requires a valid Bearer token in the Authorization header.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql
```

```graphql
query groups {
  associateGroups {
    id,
    name
  }
}
```

```json
{
  "data": {
    "associateGroups": [
      {
        "id": "2ff2f0a8-3753-11e8-8c32-02907d97d1d8",
        "name": "Test Group"
      }
    ]
  }
}
```

--------------------------------

### Add Associate Mutation

Source: https://context7.com/clearfacts/cf_developer_docs/llms.txt

Use this mutation to create a new associate within an accountant organization. The generated password is only available at creation time.

```shell
curl -H "Authorization: Bearer <token>" \
  -X POST \
  https://api.clearfacts.be/graphql \
  -F 'query=mutation add ($associate: AddAssociateArgument!) { addAssociate (associate: $associate) { id, associateGroups { id, name }, plainPassword } }' \
  -F 'variables={ "associate": { "firstName": "Test", "lastName": "Associate", "email": "associate@acme.be", "type": "ADMIN", "associateGroups": [{ "id": "2ff2f0a8-3753-11e8-8c32-02907d97d1d8" }], "active": true, "language": "nl_BE", "sendActivationMail": false } }'
```