# Taken-API

Taken zijn de to-do's en follow-ups die aan uw account zijn gekoppeld — optioneel gekoppeld aan een contactpersoon, deal of campagne. Ze doorlopen de **fasen** van uw takenbord (uw kanban-kolommen) en hebben een **type** en **prioriteit**. Deze handleiding behandelt het beheer ervan via de API.

- **Basis-URL** — `https://api.youraiconnector.com/v1`
- **Authenticatie** — uw API-sleutel (zie [Authenticatie](authentication.md))
- **Fouten & paginering** — zie [Fouten & Paginering](errors-and-pagination.md)

Alle onderstaande voorbeelden tonen de `?apiKey=` query-vorm in cURL en de `X-API-Key` header in JavaScript en Python — beide werken op elk eindpunt.

---

## Het taakobject

```json
{
  "id": "tsk_abc123",
  "title": "Call Jane about her quote",
  "description": "She asked for pricing on the annual plan.",
  "type": "to_do",
  "priority": "high",
  "stage": "stage-1",
  "due_date": "2026-06-15T09:00:00.000Z",
  "remind_before_minutes": 15,
  "contact": "contacts/uid_whatsapp_15551234567",
  "campaign": "campaigns/abc123",
  "tags": ["sales"],
  "notes": "",
  "source": "api"
}
```

- **`type`** — `to_do`, `faq_update` of uw geconfigureerde taaktypen (zie [Taaktypen weergeven](#list-task-types)).
- **`priority`** — `none`, `low`, `normal`, `high` of `urgent`.
- **`stage`** — de id van een fase op uw takenbord (zie [Taakfasen weergeven](#list-task-stages)). Indien weggelaten bij het aanmaken, komt de taak in uw eerste fase terecht.
- **`remind_before_minutes`** — hoeveel minuten vóór `due_date` een herinnering moet worden verzonden. `0` betekent op de vervaltijd; laat dit weg of stuur `null` voor geen herinnering. Moet een geheel getal zijn van `0` tot `1440` (1 dag) — alles wat groter is, wordt geweigerd. De herinnering heeft een `due_date` nodig om te worden geactiveerd, en het opnieuw plannen van de taak verplaatst de herinnering mee.

---

## Een taak aanmaken

`POST /tasks` — alleen `title` is vereist.

::: note
**Let op:** `due_date` accepteert een ISO 8601-tijdstempel, inclusief een tijdstip. Combineer dit met `remind_before_minutes` om de herinnering te laten bezorgen via uw **Taken**-meldingsinstellingen. `contact_id`, `deal_id` en `campaign_id` koppelen de taak aan die records. `assigned_to` is de gebruikers-id van een teamlid.
:::


> **Zorg dat `assigned_to` correct is.** Dit moet de gebruikers-id zijn van de accounteigenaar of van een actief teamlid op hetzelfde account. Dit eindpunt controleert dit momenteel niet, dus een id die bij niemand hoort wordt geaccepteerd en exact zo opgeslagen als je deze hebt verzonden — je krijgt nog steeds een `201`. Kopieer de id in plaats van deze opnieuw te typen: deze id's combineren `l` met `L` en de letter `O` met het cijfer `0`, en één verkeerd teken is al genoeg. Om te controleren wat je daadwerkelijk hebt verzonden, open je de taak in het dashboard: het veld **Toegewezen aan** op het taakrecord laat de ruwe id zien wanneer deze bij niemand hoort, en de keuzelijst voor toewijzing in **Taak bewerken** toont **Niet toegewezen**.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call Jane about her quote",
    "priority": "high",
    "due_date": "2026-06-15T09:00:00.000Z",
    "contact_id": "uid_whatsapp_15551234567",
    "tags": ["sales"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Call Jane about her quote",
    priority: "high",
    due_date: "2026-06-15T09:00:00.000Z",
    contact_id: "uid_whatsapp_15551234567",
    tags: ["sales"],
  }),
});
const data = await res.json();
console.log(data.task_id);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "Call Jane about her quote",
        "priority": "high",
        "due_date": "2026-06-15T09:00:00.000Z",
        "contact_id": "uid_whatsapp_15551234567",
        "tags": ["sales"],
    },
)
print(res.json()["task_id"])
```

**Antwoord** (`201`)

```json
{ "success": true, "task_id": "tsk_abc123", "task": { "title": "Call Jane about her quote", "...": "..." } }
```

---

## Taken weergeven

`GET /tasks` — retourneert de taken voor uw account, met optionele filters.

**Queryparameters** (allemaal optioneel): `stage`, `priority`, `contact_id`, `deal_id`, `assigned_to`, `due_before`, `due_after` (ISO-tijdstempels).

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&stage=stage-1&priority=high"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks?stage=stage-1&priority=high", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { tasks } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-1", "priority": "high"},
)
tasks = res.json()["tasks"]
```

**Antwoord** (`200`)

```json
{ "success": true, "tasks": [{ "id": "tsk_abc123", "title": "Call Jane about her quote", "...": "..." }] }
```

---

## Taken zoeken

`POST /tasks/search` — full-text zoekopdracht op titel en beschrijving, met dezelfde optionele filters als bij het weergeven van een lijst.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/search?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "quote", "priority": "high" }'
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/search", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ query: "quote", priority: "high" }),
});
```

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/tasks/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"query": "quote", "priority": "high"},
)
```

---

## Een taak ophalen

`GET /tasks/{taskId}`

```bash
curl "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

Een taak die niet bestaat in je account retourneert `404`.

---

## Een taak bijwerken

`PUT /tasks/{taskId}` — stuur alleen de velden die u wilt wijzigen (`title`, `description`, `type`, `priority`, `stage`, `due_date`, `remind_before_minutes`, `contact_id`, `deal_id`, `assigned_to`, `tags`, `notes`).

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "notes": "Left a voicemail." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ priority: "urgent", notes: "Left a voicemail." }),
});
```

```python
requests.put(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"priority": "urgent", "notes": "Left a voicemail."},
)
```

---

## Een taak voltooien

`POST /tasks/{taskId}/complete` — verplaatst de taak naar de voltooide fase van je bord. Een optioneel `notes`-veld legt een afsluitende notitie vast.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Closed — customer signed up." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ notes: "Closed — customer signed up." }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"notes": "Closed — customer signed up."},
)
```

---

## Verplaatsen & opnieuw ordenen (kanban)

**Verplaats een taak naar een andere fase** — `POST /tasks/{taskId}/move` met `new_stage_id` (de doelfase) en `new_position` (de op nul gebaseerde positie binnen die fase; vereist, moet een niet-negatief geheel getal zijn):

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-2", "new_position": 0 }'
```

**Taken binnen een fase opnieuw ordenen** — `POST /tasks/reorder` met `stage_id` en de taak-id's in hun nieuwe volgorde:

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"] }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/reorder", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stage_id: "stage-1", ordered_task_ids: ["tsk_3", "tsk_1", "tsk_2"] }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"]},
)
```

---

## Taken voor een contactpersoon

`GET /tasks/contact/{contactId}` — elke taak gekoppeld aan één contactpersoon.

```bash
curl "https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567?apiKey=YOUR_API_KEY"
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## Configuratie van het takenbord

### Takenfasen weergeven

`GET /tasks/stages` — de kolommen van je bord, in volgorde. Gebruik een fase `id` als het `stage`-veld bij het aanmaken of verplaatsen van taken.

```bash
curl "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY"
```

```json
{ "success": true, "stages": [{ "id": "stage-1", "name": "To Do", "is_completed_stage": false }, { "id": "stage-done", "name": "Done", "is_completed_stage": true }] }
```

### Takenfasen bijwerken

`PUT /tasks/stages` — vervang de faseconfiguratie van je bord. Stuur de volledige geordende `stages`-array.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stages": [
    { "id": "stage-1", "name": "To Do", "is_completed_stage": false },
    { "id": "stage-2", "name": "In Progress", "is_completed_stage": false },
    { "id": "stage-done", "name": "Done", "is_completed_stage": true }
  ] }'
```

### Taaktypen weergeven

`GET /tasks/types` — de taaktypen die op je account zijn geconfigureerd (gebruikt als het `type`-veld).

```bash
curl "https://api.youraiconnector.com/v1/tasks/types?apiKey=YOUR_API_KEY"
```

---

## Een FAQ-suggestie goedkeuren

Wanneer de AI-bot een nieuwe FAQ voorstelt, maakt deze een taak aan van het type `faq_update`. `POST /tasks/{taskId}/approve-faq` zet dat voorstel om in een echte FAQ in de kennisbank van de AI-agent die het heeft aangemaakt en voltooit de taak. Je kunt de vraag/het antwoord in de hoofdtekst overschrijven.

Voeg `"send_follow_up": true` toe om de AI het antwoord ook direct naar de gekoppelde contactpersoon van de taak te laten sturen, als een natuurlijk bericht in die chat (hetzelfde als wat de schakelaar **Stuur het antwoord nu naar de contactpersoon** in de app doet). Het antwoord wordt verstuurd via de AI-agent die die contactpersoon beheert.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_faq99/approve-faq?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Do you offer refunds?", "answer": "Yes, within 30 days.", "send_follow_up": true }'
```

```json
{ "success": true, "faq_id": "faq_xyz", "task_id": "tsk_faq99", "follow_up_status": "published" }
```

`follow_up_status` vertelt je wat er met het bericht is gebeurd: `not_requested` (vlag niet ingesteld), `published` (verzonden), `queued` (de bot was bezig met antwoorden aan die contactpersoon, het antwoord wordt verstuurd zodra deze klaar is), `skipped_no_contact` (de taak heeft geen gekoppelde contactpersoon), `skipped_no_campaign` (geen enkele agent of campagne kon antwoorden voor die contactpersoon) of `skipped_error`. De FAQ wordt in elk geval aangemaakt.

Zie de [FAQs API](faqs.md) om de resulterende FAQ te beheren.

---

## Een taak verwijderen

`DELETE /tasks/{taskId}`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
requests.delete("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## Volgende stappen

- [Contacts API](contacts.md) — taken koppelen aan de juiste contactpersoon
- [Webhooks API](webhooks.md) — ontvang meldingen over `Task Created`, `Task Updated` en `Task Completed`
- [API-referentie](reference.md) — de volledige interactieve endpoint-verkenner