# Connecting Yuki

## Prerequisites

- An active Yuki account on the **Business Plan** (API access is not available on free plans)
- Portal Administrator or Management role (required to generate an API key)
- Your Yuki administration ID (a GUID)

## Steps

1. **Get your API Key (WebserviceAccessKey)**
   - Log in to Yuki at [yuki.nl](https://www.yuki.nl) or [yuki.be](https://www.yuki.be)
   - Navigate to **Settings** > **Web service access code**
   - Generate a new API key (or copy the existing one)
   - See [Yuki's guide](https://support.yuki.nl/en/support/solutions/articles/80000787231-web-service-access-code-web-service-api-key-webserviceaccesskey-)

2. **Find your Administration ID**
   - Your Yuki administrator can provide this
   - It's a GUID (e.g., `a1b2c3d4-e5f6-7890-abcd-ef1234567890`)
   - If unsure, ask Yuki support or check the Administrations API method

3. **(Optional) Find your Domain ID**
   - Required for customer/supplier operations on Yuki environments where the
     Domain GUID differs from the Administration GUID
   - Your Yuki administrator can provide this — it's a GUID
   - If omitted, the connection falls back to using the Administration ID

4. **Configure the connection**
   - Enter your **API Key** (WebserviceAccessKey)
   - Enter your **Administration ID**
   - (Optional) Enter your **Domain ID**
   - Select your **Region** (Netherlands or Belgium)
   - Click **Save**

## Settings

| Setting | Required | Description |
|---------|----------|-------------|
| API Key | Yes | Your WebserviceAccessKey from Yuki admin settings |
| Administration ID | Yes | The GUID of the Yuki administration to connect |
| Domain ID | No | Optional — GUID of the Yuki domain. Required for customer/supplier operations on multi-domain setups. Falls back to the Administration ID when left empty. |
| Region | Yes | Netherlands (`api.yukiworks.nl`) or Belgium (`api.yukiworks.be`) |

## Rate Limits

| Plan | Calls/day |
|------|-----------|
| Default | 1,000 |
| Yuki Webservice | 5,000 |
| Yuki Webservice Extended | 10,000 |

Each API operation uses 2 calls (authenticate + request), so effective capacity is half the listed limit.

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Authentication failed" | Verify your API key is correct and not expired |
| "No data returned" | Check that the Administration ID matches an active administration |
| Empty responses | Ensure the selected administration has data (invoices, contacts, etc.) |
| 403/Forbidden | Confirm your Yuki account is on the Business Plan with API access |
| "Invalid domain ID" on customers/suppliers | Set the **Domain ID** setting to the correct GUID (see step 3) |
| Customer/supplier list empty despite created contacts | Yuki only flags a contact as a customer/supplier after their first invoice is created. Use the invoices endpoint to create an invoice for the contact, then the list will return it. |