Deals API

En handel er en salgsmulighed på din Salgspipeline-tavle — en titel, en værdi, det stadie den befinder sig i, og valgfrit den kontaktperson den tilhører, og det teammedlem den er tildelt. Denne guide dækker læsning og håndtering af handler via API’et.

Base URL — https://api.youraiconnector.com/v1
Autentificering — din API-nøgle (se Autentificering)
Fejl & paginering — se Fejl & Paginering

Alle eksempler herunder viser ?apiKey= forespørgselsformen i cURL og X-API-Key headeren i JavaScript og Python — begge virker på alle slutpunkter.

Handelsobjektet

{
  "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 er id’et på et af dine pipelinestadier — læs dem med GET /pipelines (se Pipelines nedenfor). Stadie-id’er er unikke på tværs af alle dine pipelines, så pipeline_id er afledt af stadiet og er skrivebeskyttet: default er din hovedpipeline, og den er null, når stadiet ikke længere eksisterer. Tidsstempler er ISO 8601.

En aftale gemmer kun de felter, der er vist ovenfor. Når du opretter eller opdaterer en, afvises ethvert andet felt med en 400, der navngiver det, så intet af det, du sender, går tabt uden videre. Gem ekstra data i den tilknyttede kontakts brugerdefinerede felter.

List handler

GET /deals — returnerer handlerne på din konto, nyeste først.

Forespørgselsparametre (alle valgfrie): stage (et stadie-id), pipeline_id (kun handlerne på den pipeline), contact_id, limit (standard 50, maks 200), cursor (fra den forrige sides 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 }

Hent en handel

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 handel, der ikke eksisterer, eller som tilhører en anden konto, returnerer 404.

Opret en handel

POST /deals — title og stage er påkrævet; stage skal være et af din pipelines stadie-id’er.

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

Opdater en handel

PUT /deals/{dealId} — send kun de felter, du vil ændre (title, description, notes, value, stage, status, priority, contact_id, …). value skal være et tal.

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

Flyt en handel til et andet stadie

POST /deals/{dealId}/move — body { "new_stage_id": "stage-3", "new_position": 0 }. Position 0 placerer kortet øverst i kolonnen.

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 }

Slet en handel

DELETE /deals/{dealId} — fjerner handlen. Dette kan ikke fortrydes.

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

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

Pipelines

Hver konto har en hovedpipeline (id: "default"); du kan tilføje op til ni mere, hver med sine egne stadier. Stadie-id’er og trigger-tags skal være unikke på tværs af alle pipelines på kontoen, og hver pipeline kan markere ét stadie som sit won og ét som sit lost resultat.

List pipelines

GET /pipelines — hver pipeline, hovedpipelinen først, hver med sine stadier sorteret 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" }
        ]
      }
    ]
  }
}

Opret en pipeline

POST /pipelines — brødtekst { "id"?, "name", "stages"?, "settings"? }. Udelad id for at få genereret et. Hvert stadie bruger de samme felter som Stadier-dialogen: id, name, color, position, valgfri trigger_tag (en tag-sti, users/{uid}/tags/{tagId}), default_value, auto_move_after_days + auto_move_to_stage (et stadie i samme pipeline) og 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": { ... } } }. Et stadie-id eller trigger-tag, der allerede bruges af en anden pipeline, er en 400, der navngiver den pipeline; et id, der allerede eksisterer, er en 409.

Opdater en pipeline

PUT /pipelines/{pipelineId} — brødtekst { "name"?, "stages"?, "settings"? }. stages erstatter hele listen, ligesom Stadier-dialogen. Brug default til hovedpipelinen. Selve pipeline-id’et kan ikke ændres.

Slet en pipeline

DELETE /pipelines/{pipelineId} — fjerner en ekstra pipeline (hovedpipelinen kan ikke slettes). Hvis der stadig er handler i dens stadier, svarer kaldet 409 med deal_count; tilføj ?delete_deals=true for at slette disse handler sammen med pipelinen. Dette kan ikke fortrydes.

Svar (204).

Næste skridt

Salgspipeline — hvordan stadier, stadietags, flere pipelines og tavlen fungerer.
Tasks API — opgaver kan linkes til en handel med deal_id.
Automatiseringer — trinnene Find handler og Find handel læser de samme data i et workflow.

Deals API #

Handelsobjektet #

List handler #

Hent en handel #

Opret en handel #

Opdater en handel #

Flyt en handel til et andet stadie #

Slet en handel #

Pipelines #

List pipelines #

Opret en pipeline #

Opdater en pipeline #

Slet en pipeline #

Næste skridt #