Deals API

Een deal is één verkoopkans op je Sales Pipeline-bord — een titel, een waarde, de fase waarin deze zich bevindt, en optioneel de contactpersoon waartoe deze behoort en het teamlid aan wie deze is toegewezen. Deze handleiding behandelt het lezen en beheren van deals via de API.

Basis-URL — https://api.youraiconnector.com/v1
Authenticatie — uw API-sleutel (zie Authenticatie)
Fouten & paginering — zie Fouten & Paginering

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 deal-object

{
  "id": "deal_abc123",
  "title": "Annual plan – Jane's Clinic",
  "description": "Asked for pricing on the annual plan.",
  "company": "Jane's Clinic",
  "notes": "Prefers a call after 5pm.",
  "stage": "stage-2",
  "pipeline_id": "default",
  "value": 4800,
  "probability": 60,
  "priority": "high",
  "status": "open",
  "source": "whatsapp",
  "position": 0,
  "contact_id": "ctc_9f8e7d",
  "assigned_to": "usr_4a2b",
  "tags": ["clinic"],
  "close_date": "2026-10-01T00:00:00.000Z",
  "created_at": "2026-09-05T09:12:00.000Z",
  "updated_at": "2026-09-05T09:40:00.000Z",
  "stage_entered_at": "2026-09-05T09:40:00.000Z"
}

stage is de id van een van je pijplijnfasen — lees ze met GET /pipelines (zie Pijplijnen hieronder). Fase-ids zijn uniek voor al je pijplijnen, dus pipeline_id is afgeleid van de fase en is alleen-lezen: default is je hoofdpijplijn, en deze is null wanneer de fase niet langer bestaat. Tijdstempels zijn ISO 8601.

Een deal slaat alleen de hierboven getoonde velden op. Wanneer je er een aanmaakt of bijwerkt, wordt elk ander veld geweigerd met een 400 waarin dit wordt benoemd, zodat niets wat je verstuurt stilletjes verloren gaat. Bewaar extra gegevens in de aangepaste velden van de gekoppelde contactpersoon.

Deals weergeven

GET /deals — retourneert de deals in je account, de nieuwste eerst.

Queryparameters (allemaal optioneel): stage (een fase-id), pipeline_id (alleen de deals in die pijplijn), contact_id, limit (standaard 50, max 200), cursor (van de next_cursor van de vorige pagina).

cURL

curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/deals?stage=stage-2&limit=50", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { deals, next_cursor } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/deals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-2", "limit": 50},
)
deals = res.json()["deals"]

Antwoord (200)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

Een deal ophalen

GET /deals/{dealId}

curl "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Antwoord (200)

{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }

Een deal die niet bestaat, of die bij een ander account hoort, retourneert 404.

Een deal aanmaken

POST /deals — title en stage zijn verplicht; stage moet een van de fase-id’s van je pipeline zijn.

curl -X POST "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }'

Antwoord (201)

{ "success": true, "deal_id": "deal_abc123" }

Een deal bijwerken

PUT /deals/{dealId} — stuur alleen de velden die je wilt wijzigen (title, description, notes, value, stage, status, priority, contact_id, …). value moet een getal zijn.

curl -X PUT "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5200, "priority": "high" }'

Antwoord (200): { "success": true, "deal_id": "deal_abc123" }

Verplaats een deal naar een andere fase

POST /deals/{dealId}/move — body { "new_stage_id": "stage-3", "new_position": 0 }. Positie 0 plaatst de kaart bovenaan de kolom.

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

Antwoord (200): { "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }

Een deal verwijderen

DELETE /deals/{dealId} — verwijdert de deal. Dit kan niet ongedaan worden gemaakt.

curl -X DELETE "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Antwoord (200): { "success": true }

Pijplijnen

Elk account heeft een hoofdpijplijn (id: "default"); je kunt er maximaal negen toevoegen, elk met zijn eigen fasen. Fase-ids en trigger-tags moeten uniek zijn voor alle pijplijnen in het account, en elke pijplijn kan één fase markeren als zijn won en één als zijn lost resultaat.

Pijplijnen weergeven

GET /pipelines — elke pijplijn, de hoofd-pijplijn eerst, elk met zijn fasen gesorteerd op positie.

curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"

Antwoord (200):

{
  "success": true,
  "data": {
    "pipelines": [
      {
        "id": "default",
        "name": "Sales",
        "position": 0,
        "is_default": true,
        "settings": { "sync_stage_tags": false },
        "stages": [
          { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null },
          { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" }
        ]
      }
    ]
  }
}

Een pijplijn aanmaken

POST /pipelines — body { "id"?, "name", "stages"?, "settings"? }. Laat id weg om er een te laten genereren. Elke fase gebruikt dezelfde velden als het dialoogvenster Fasen: id, name, color, position, optioneel trigger_tag (een tagpad, users/{uid}/tags/{tagId}), default_value, auto_move_after_days + auto_move_to_stage (een fase van dezelfde pijplijn) en outcome ("won" of "lost").

curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviews",
    "name": "Review requests",
    "stages": [
      { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 },
      { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" }
    ]
  }'

Antwoord (201): { "success": true, "data": { "pipeline": { ... } } }. Een fase-id of trigger-tag die al door een andere pijplijn wordt gebruikt, is een 400 die die pijplijn benoemt; een id die al bestaat is een 409.

Een pijplijn bijwerken

PUT /pipelines/{pipelineId} — body { "name"?, "stages"?, "settings"? }. stages vervangt de hele lijst, zoals in het dialoogvenster Fasen. Gebruik default voor de hoofdpijplijn. De pijplijn-id zelf kan niet worden gewijzigd.

Een pijplijn verwijderen

DELETE /pipelines/{pipelineId} — verwijdert een extra pijplijn (de hoofdpijplijn kan niet worden verwijderd). Als er nog deals in de fasen staan, antwoordt de aanroep met 409 met deal_count; voeg ?delete_deals=true toe om die deals samen met de pijplijn te verwijderen. Dit kan niet ongedaan worden gemaakt.

Antwoord (204).

Volgende stappen

Sales Pipeline — hoe fasen, fasetags, meerdere pijplijnen en het bord werken.
Tasks API — taken kunnen worden gekoppeld aan een deal met deal_id.
Automations — de stappen Find deals en Find deal lezen dezelfde gegevens binnen een workflow.

Deals API #

Het deal-object #

Deals weergeven #

Een deal ophalen #

Een deal aanmaken #

Een deal bijwerken #

Verplaats een deal naar een andere fase #

Een deal verwijderen #

Pijplijnen #

Pijplijnen weergeven #

Een pijplijn aanmaken #

Een pijplijn bijwerken #

Een pijplijn verwijderen #

Volgende stappen #