Your AI Connector Docs

Deals API

En affär är en försäljningsmöjlighet på din försäljningspipeline — en titel, ett värde, stadiet den befinner sig i, och valfritt den kontakt den tillhör och den teammedlem den är tilldelad. Den här guiden täcker hur du läser och hanterar affärer via API:et.

Alla exempel nedan visar frågeformuläret ?apiKey= i cURL och headern X-API-Key i JavaScript och Python — båda fungerar på alla slutpunkter.

Affärsobjektet 

{
  "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 är id:t för ett av dina pipelinesteg — läs dem med GET /pipelines (se Pipelines nedan). Steg-id:n är unika för alla dina pipelines, så pipeline_id härleds från steget och är skrivskyddat: default är din huvudpipeline, och den är null när steget inte längre finns. Tidsstämplar är ISO 8601.

En affär lagrar endast fälten som visas ovan. När du skapar eller uppdaterar en, nekas alla andra fält med ett 400 som namnger dem, så att inget du skickar går förlorat i tysthet. Spara extra data i den länkade kontaktens anpassade fält.

Lista affärer

GET /deals — returnerar affärerna på ditt konto, med de nyaste först.

Frågeparametrar (alla valfria): stage (ett steg-id), pipeline_id (endast affärer i den pipelinen), contact_id, limit (standard 50, max 200), cursor (från föregående sidas next_cursor).

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"]

Svar (200)

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

Hämta en affär

GET /deals/{dealId}

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

Svar (200)

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

En affär som inte existerar, eller som tillhör ett annat konto, returnerar 404.

Skapa en affär

POST /deals — title och stage krävs; stage måste vara ett av din pipelines stadie-id:n.

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" }'

Svar (201)

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

Uppdatera en affär

PUT /deals/{dealId} — skicka endast de fält du vill ändra (title, description, notes, value, stage, status, priority, contact_id, …). value måste vara ett nummer.

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" }'

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

Flytta en affär till ett annat stadium

POST /deals/{dealId}/move — body { "new_stage_id": "stage-3", "new_position": 0 }. Position 0 placerar kortet högst upp i kolumnen.

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 }'

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

Ta bort en affär

DELETE /deals/{dealId} — tar bort affären. Detta går inte att ångra.

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

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

Pipelines

Varje konto har en huvudpipeline (id: "default"); du kan lägga till upp till nio till, var och en med sina egna steg. Steg-id:n och trigger-taggar måste vara unika för alla pipelines på kontot, och varje pipeline kan markera ett steg som sitt won och ett som sitt lost resultat.

Lista pipelines

GET /pipelines — varje pipeline, huvudpipelinen först, var och en med sina steg sorterade efter position.

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

Svar (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" }
        ]
      }
    ]
  }
}

Skapa en pipeline

POST /pipelines — brödtext { "id"?, "name", "stages"?, "settings"? }. Lämna id tomt för att få ett genererat. Varje steg använder samma fält som dialogrutan Steg: id, name, color, position, valfritt trigger_tag (en taggsökväg, users/{uid}/tags/{tagId}), default_value, auto_move_after_days + auto_move_to_stage (ett steg i samma pipeline) och outcome ("won" eller "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" }
    ]
  }'

Svar (201): { "success": true, "data": { "pipeline": { ... } } }. Ett steg-id eller en trigger-tagg som redan används av en annan pipeline är en 400 som namnger den pipelinen; ett id som redan finns är en 409.

Uppdatera en pipeline

PUT /pipelines/{pipelineId} — brödtext { "name"?, "stages"?, "settings"? }. stages ersätter hela listan, precis som i dialogrutan Steg. Använd default för huvudpipelinen. Själva pipeline-id:t kan inte ändras.

Ta bort en pipeline

DELETE /pipelines/{pipelineId} — tar bort en extra pipeline (huvudpipelinen kan inte tas bort). Om det fortfarande finns affärer i dess steg svarar anropet 409 med deal_count; lägg till ?delete_deals=true för att ta bort dessa affärer tillsammans med pipelinen. Detta kan inte ångras.

Svar (204).

Nästa steg

  • Försäljningspipeline — hur stadier, stadieetiketter, flera pipelines och tavlan fungerar.
  • Tasks API — uppgifter kan kopplas till en affär med deal_id.
  • Automatiseringar — stegen Hitta affärer och Hitta affär läser samma data i ett arbetsflöde.