Kontakt-API #

En kontakt er en enkelt person, du sender beskeder til — deres navn, telefonnummer, e-mail, kanal, tags, brugerdefinerede felter samt de lister og kampagner, de tilhører. Kontakt-API’et giver dig mulighed for at oprette kontakter, slå dem op, opdatere dem, tilføje tags, importere dem i bulk og fjerne dem, alt sammen uden at bruge dashboardet.

Alle stier på denne side er relative til basis-URL’en:

https://api.youraiconnector.com/v1

Så /contacts betyder https://api.youraiconnector.com/v1/contacts.

Er du ny til API’et? Læs API-adgang først — den dækker, hvordan du genererer din API-nøgle, de tre måder at godkende på, hastighedsbegrænsninger og fejlformatet. Alt på denne side forudsætter, at du allerede har en fungerende API-nøgle.

Om kontakt-ID’er #

Hver kontakt har et unikt ID. Det ID, du får tilbage, når du opretter en kontakt (i data.contactId), er det samme ID, som du bruger alle andre steder — til at hente, opdatere, tilføje tags, sende en besked eller slette den pågældende kontakt. Gem det én gang og genbrug det.

Du behøver ikke at oprette en kontakt for at få dens ID. Du kan også slå et ID op via telefonnummer eller e-mail (se Hent en kontakt), eller gennemse alle dine kontakter (se List kontakter). Hver af disse returnerer det samme ID.

Opret en kontakt #

POST /contacts

Tilføjer en ny kontakt til din konto. Et telefonnummer med landekode er påkrævet — en e-mail alene er ikke nok. Alt andet er valgfrit.

Du kan valgfrit tilføje den nye kontakt direkte til en eller flere lister med listId (en enkelt liste) eller listIds (et array). Hvis begge sendes, vinder listIds.

Ethvert felt, du sender, som ikke er et af standardfelterne til oprettelse, der er angivet i tabellen Opret en kontakt nedenfor (phoneNumber, firstName, lastName, email, channel, is_bot_active, is_private, lead_profile, listId, listIds, custom_fields), gemmes automatisk som et brugerdefineret felt — så en flad payload fra et værktøj som Make eller Zapier fungerer uden indlejring. Du kan også sende et eksplicit custom_fields-objekt.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "is_bot_active": true,
    "listIds": ["list123", "list456"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+15551234567",
    firstName: "Jane",
    lastName: "Smith",
    email: "jane@example.com",
    is_bot_active: true,
    listIds: ["list123", "list456"],
  }),
});
const data = await res.json();
console.log(data.data.contactId);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+15551234567",
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "jane@example.com",
        "is_bot_active": True,
        "listIds": ["list123", "list456"],
    },
)
print(res.json()["data"]["contactId"])

Svar

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "contact_abc123",
    "listsAdded": ["list123", "list456"]
  }
}

Den nye kontakts ID findes på data.contactId. De lister, den blev tilføjet til, returneres i data.listsAdded.

Dubletter oprettes ikke. Hvis en kontakt med det samme telefonnummer allerede findes, opretter eller returnerer opkaldet til oprettelse den ikke. Svaret kommer tilbage med HTTP-status 200 og en error_code på 409 i brødteksten, så forgrening bør ske på error_code frem for på HTTP-status:

{ "success": false, "error_code": 409, "error": "A contact with this phone number already exists for the current user." }

For at arbejde med en eksisterende kontakt efter en error_code på 409, skal du slå den op med Hent en kontakt via telefon eller e-mail — GET /contacts?phoneNumber=... — og genbruge det ID, den returnerer.

Tilsvarende WhatsApp-stavemåder tæller som det samme nummer. Nogle lande har to gyldige stavemåder for den samme mobiltelefonlinje, og WhatsApp kan rapportere begge: Mexico (+52… og den ældre +521…), Brasilien (med eller uden det niende ciffer) og Argentina (med eller uden 9 efter +54). Dubletkontrollen ved oprettelse og GET /contacts?phoneNumber= matcher på tværs af begge stavemåder, så du får den eksisterende kontakt tilbage, uanset hvilken form du sender. Det phone_number, der er gemt på kontakten, bliver aldrig overskrevet.

Hent en kontakt via telefon eller e-mail #

GET /contacts?phoneNumber=... eller GET /contacts?email=...

Slår en enkelt kontakt op og returnerer det fulde, berigede kontaktobjekt — inklusive dens lister, tags og kampagner opløst til { id, name }-par, plus den sidst udvekslede besked.

Angiv enten phoneNumber (i internationalt format) eller email. Hvis du ikke angiver nogen af dem, skifter dette samme slutpunkt i stedet til List kontakter-tilstand.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?phoneNumber=%2B15551234567&apiKey=YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551234567");
const res = await fetch(`https://api.youraiconnector.com/v1/contacts?phoneNumber=${phone}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.contact);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"phoneNumber": "+15551234567"},
)
print(res.json()["contact"])

Svar

{
  "success": true,
  "contactId": "contact_abc123",
  "contact": {
    "id": "contact_abc123",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phoneNumber": "+15551234567",
    "channel": "whatsapp",
    "isBotActive": true,
    "isPrivate": false,
    "doNotDisturb": false,
    "lead_profile": null,
    "avatarUrl": "https://example.com/photo.jpg",
    "customFields": {},
    "lists": [{ "id": "list123", "name": "VIP customers" }],
    "tags": [{ "id": "tagHotLead", "name": "Hot lead" }],
    "campaigns": [{ "id": "campaign789", "name": "Spring promo" }],
    "currentCampaign": { "id": "campaign789", "name": "Spring promo" },
    "lastMessage": {
      "direction": "inbound",
      "body": "Sounds good, thanks!",
      "status": "received",
      "timestamp": "2026-06-09T10:21:00.000Z"
    }
  }
}

Kontakt-ID’et returneres både på øverste niveau (contactId) og inde i objektet (contact.id). Hvis intet matcher, får du en 404 med { "success": false, "message": "Contact not found" }.

avatarUrl er kontaktens profilbillede, hentet fra WhatsApp eller Meta, når de sender dig en besked. Det er skrivebeskyttet: Du kan ikke indstille det, og det er null for kontakter, der ikke har et billede, eller som kontakter dig via en kanal, der ikke deler et. Betragt linket som midlertidigt frem for at gemme det, da nogle af disse billedlinks udløber og opdateres automatisk. (I liste-slutpunktet nedenfor kaldes den samme værdi avatar_url.)

Telefonnumre i URL’er. Et +-tegn i en forespørgselsstreng skal være URL-kodet som %2B, ellers læses det som et mellemrum. Eksemplerne ovenfor gør dette for dig.

Hent en kontakt via ID #

GET /contacts/{contactId}

Når du allerede har en kontakts ID, kan du hente den direkte. Svarets form er identisk med opslaget ovenfor.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.contact);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["contact"])

Et kontakt-ID, der ikke findes på din konto, returnerer en 404.

Hent kontaktstatistik #

GET /contacts/{contactId}/stats

Returnerer samlet beskedstatistik for én kontakt: totaler, AI- kontra menneskelige svar, brugte kreditter og tidsstempler for første/sidste besked.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.totalMessages, data.creditsUsed);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["totalMessages"], data["creditsUsed"])

Svar

{
  "success": true,
  "totalMessages": 48,
  "sent": 21,
  "received": 27,
  "aiReplies": 18,
  "humanReplies": 3,
  "creditsUsed": 34,
  "botMessageCount": 18,
  "firstMessageAt": "2026-05-01T09:00:00.000Z",
  "lastMessageAt": "2026-06-09T10:21:00.000Z"
}

botMessageCount er den samme AI-beskedtæller, som “nulstil”-knappen i appen for en kontakt nulstiller. creditsUsed er den løbende kredit-total for denne kontakt, ikke kun tallene for dette svar. Et kontakt-ID, der ikke findes på din konto, returnerer en 404.

List kontakter #

GET /contacts

Kald GET /contacts med hverken phoneNumber eller email for at gennemse alle dine kontakter, med de nyeste først. Hver side returnerer kompakte kontaktoversigter (lister, tags og kampagner returneres som ID-arrays i stedet for fulde objekter) og en next_cursor.

For at gennemgå hver side: foretag det første kald uden en markør (cursor), og fortsæt derefter med at sende den returnerede next_cursor tilbage som cursor. Stop når next_cursor er null — det betyder, at der ikke er flere resultater.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?limit=50&apiKey=YOUR_API_KEY"

# next page:
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?limit=50&cursor=contact_abc123&apiKey=YOUR_API_KEY"

JavaScript

async function listAllContacts() {
  const all = [];
  let cursor = null;
  do {
    const url = new URL("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
    const data = await res.json();
    all.push(...data.contacts);
    cursor = data.next_cursor;
  } while (cursor);
  return all;
}

Python

import requests

def list_all_contacts():
    all_contacts = []
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(
            "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
            headers={"X-API-Key": "YOUR_API_KEY"},
            params=params,
        )
        data = res.json()
        all_contacts.extend(data["contacts"])
        cursor = data["next_cursor"]
        if not cursor:
            break
    return all_contacts

Svar

{
  "success": true,
  "contacts": [
    {
      "id": "contact_abc123",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone_number": "+15551234567",
      "channel": "whatsapp",
      "is_bot_active": true,
      "is_private": false,
      "do_not_disturb": false,
      "avatar_url": "https://example.com/photo.jpg",
      "custom_fields": {},
      "created_at": "2026-06-01T09:00:00.000Z",
      "list_ids": ["list123"],
      "tag_ids": ["tagHotLead"],
      "campaign_ids": ["campaign789"],
      "current_campaign_id": "campaign789"
    }
  ],
  "next_cursor": "contact_abc123"
}

Tæl kontakter #

GET /contacts/count

Returnerer hvor mange kontakter der matcher et filter, plus en opdeling pr. kanal, uden at skulle gennemse dem side for side. Dette er det rette kald til ethvert “hvor mange”-spørgsmål — en dashboard-flise, en automatisering eller når du spørger Champ. Alle filtre er valgfrie, og kombination af flere indsnævrer optællingen (en kontakt skal matche hver enkelt, du sender).

Send slet intet filter, og du får det samlede antal kontakter på din konto.

cURL

# everything
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count?apiKey=YOUR_API_KEY"

# only the contacts one agent handles on Messenger
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count?agentId=agent_xyz789&channel=messenger&apiKey=YOUR_API_KEY"

JavaScript

const url = new URL("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count");
url.searchParams.set("agentId", "agent_xyz789");
url.searchParams.set("channel", "messenger");

const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const data = await res.json();
console.log(data.total);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"agentId": "agent_xyz789", "channel": "messenger"},
)
data = res.json()
print(data["total"])

Svar

{
  "success": true,
  "total": 3423,
  "by_channel": { "messenger": 2744, "instagram": 667, "none": 12 },
  "filters": { "agentId": "agent_xyz789" }
}

by_channel opdeler det samme totalantal pr. kanal; kontakter, der ikke er på nogen kanal, tælles under none. filters sender de anvendte filtre retur, så du kan kontrollere, at kaldet gjorde, hvad du forventede.

Opdater en kontakt #

PUT /contacts/{contactId}

Opdaterer en eksisterende kontakt. Kun de felter, du inkluderer, ændres — udelad alt, du ikke ønsker at røre ved. Du skal sende mindst ét felt, ellers får du en 400 (“Ingen felter at opdatere”).

cURL

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Jane", "do_not_disturb": true }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ firstName: "Jane", do_not_disturb: true }),
});
const data = await res.json();
console.log(data.message);

Python

import requests

res = requests.put(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"firstName": "Jane", "do_not_disturb": True},
)
print(res.json()["message"])

Svar

{
  "success": true,
  "message": "Contact updated successfully"
}

Brugerdefinerede felter flettes, ikke erstattes. Afsendelse af { "custom_fields": { "tier": "gold" } } indstiller kun tier — alle andre brugerdefinerede felter på kontakten forbliver præcis, som de var. For at fjerne et brugerdefineret felt helt på tværs af alle kontakter, skal du bruge Slet et brugerdefineret felt.

Tilføj eller fjern tags #

POST /contacts/{contactId}/tags

Tilføjer og/eller fjerner tags på en enkelt kontakt i ét kald. Send tag-ID’er i addTagIds og removeTagIds. Mindst ét af de to skal være ikke-tomt.

Tags skal allerede eksistere på din konto — opret dem først via tags-endpointet. Hvis kontakten eller et refereret tag ikke findes, får du en 404.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "addTagIds": ["tagHotLead"], "removeTagIds": ["tagColdLead"] }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    addTagIds: ["tagHotLead"],
    removeTagIds: ["tagColdLead"],
  }),
});
const data = await res.json();
console.log(data.added, data.removed);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"addTagIds": ["tagHotLead"], "removeTagIds": ["tagColdLead"]},
)
data = res.json()
print(data["added"], data["removed"])

Svar

{
  "success": true,
  "contact_id": "contact_abc123",
  "added": 1,
  "removed": 1
}

Administrer dit tag-bibliotek #

Disse slutpunkter administrerer selve tagget — omdøbning eller sletning af det på din konto — i modsætning til at tilføje eller fjerne et tag på en kontakt (se Tilføj eller fjern tags ovenfor). Hvert tag på din konto har et ID (tagId): det, der vises i dit dashboards tag-administrator, og det, der returneres som data.tag_id, når du opretter et tag med POST /tags og en JSON-krop på { "name": "..." } (ingen phoneNumber, email eller contactId).

Opdater et tag #

PUT /tags/{tagId}

Send kun de felter, du ændrer.

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags/tagHotLead?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Hot lead (Q3)" }'

Svar

{ "success": true, "tag_id": "tagHotLead" }

Et tagId, der ikke findes på din konto, returnerer en 404.

Slet et tag #

DELETE /tags/{tagId}

Sletter ét tag efter ID. Dette kan ikke fortrydes — kontakter, der bærer tagget, mister det blot. Sletning af et tag, der allerede er væk (eller aldrig har eksisteret), returnerer 200 med deleted: 0 i stedet for en 404, da der ikke er noget at tælle op.

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags/tagColdLead?apiKey=YOUR_API_KEY"

Svar

{ "success": true, "deleted": 1 }

Slet flere tags på én gang #

DELETE /tags

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tagIds": ["tagColdLead", "tagUnsubscribed"] }'

Svar

{ "success": true, "deleted": 2 }

ID’er, der ikke findes, eller som tilhører en anden konto, springes over uden fejlmeddelelse og tælles ikke med i deleted.

Masseindstil et flag #

POST /contacts/bulk-flag

Indstiller ét boolesk flag på mange kontakter på én gang. Op til 500 kontakt-id’er pr. anmodning. Id’er, der ikke findes på din konto, springes over og tælles i skipped.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["contactId1", "contactId2"],
    "field": "bot_active",
    "value": false
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactIds: ["contactId1", "contactId2"],
    field: "bot_active",
    value: false,
  }),
});
const data = await res.json();
console.log(data.updated, data.skipped);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactIds": ["contactId1", "contactId2"],
        "field": "bot_active",
        "value": False,
    },
)
data = res.json()
print(data["updated"], data["skipped"])

Svar

{
  "success": true,
  "updated": 2,
  "skipped": 0
}

Masseimport af kontakter #

POST /contacts/import

Opretter op til 500 kontakter i ét kald fra et JSON-array. Hver post kræver et phone_number i internationalt format; alt andet er valgfrit. Poster med ugyldige telefonnumre eller ikke-understøttede kanaler springes over (oprettes ikke), og hver overspringet post rapporteres med sit indeks og årsag — så du kun behøver at rette fejlene og prøve igen.

Telefonnumre, der allerede findes på din konto, springes som standard over som duplicate. Send updateExisting: true for at opdatere disse kontakter i stedet: felterne i posten overskriver kontaktens (first_name, last_name, email, lead_profile og custom_fields flettes nøgle for nøgle), tags tilføjes, og kontakten føjes til listId. Kanal, telefonnummer og bot-flag ændres aldrig på en eksisterende kontakt.

Du kan valgfrit tilføje hver importeret (eller opdateret) kontakt til en liste med listId, angive en defaultChannel for poster, der ikke angiver en, og tagge poster med tags (tagnavne — manglende tags oprettes, eksisterende matches uafhængigt af store/små bogstaver).

Top-niveau felter

Felter pr. post

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee", "tags": ["vip", "newsletter"] },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "listId": "list123",
    "defaultChannel": "whatsapp_web",
    "updateExisting": true
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee", tags: ["vip", "newsletter"] },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    listId: "list123",
    defaultChannel: "whatsapp_web",
    updateExisting: true,
  }),
});
const data = await res.json();
console.log(`Imported ${data.imported}, updated ${data.updated}, skipped ${data.skipped.length}`);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee", "tags": ["vip", "newsletter"]},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "listId": "list123",
        "defaultChannel": "whatsapp_web",
        "updateExisting": True,
    },
)
data = res.json()
print(f"Imported {data['imported']}, updated {data['updated']}, skipped {len(data['skipped'])}")

Svar

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contact_abc123", "contact_def456"],
  "updated": 0,
  "updated_contact_ids": [],
  "skipped": []
}

Hvis nogle poster ikke kan oprettes, vises de i skipped med årsagen (her uden updateExisting, så det eksisterende nummer springes over):

{
  "success": true,
  "imported": 1,
  "contact_ids": ["contact_abc123"],
  "updated": 0,
  "updated_contact_ids": [],
  "skipped": [
    { "index": 1, "phone_number": "+12025551235", "reason": "duplicate" }
  ]
}

Med updateExisting: true rapporterer den samme anmodning den eksisterende kontakt under updated / updated_contact_ids i stedet.

Mulige årsager til spring over: invalid_record, missing_phone_number, invalid_phone_number, invalid_channel, duplicate_in_request, duplicate, contact_limit_reached, create_failed.

Planbegrænsninger. Hvis din plans kontaktgrænse ikke tillader så mange nye kontakter, afvises hele anmodningen på forhånd med en 403. Hvis grænsen nås undervejs, returneres de resterende poster som sprunget over med årsagen contact_limit_reached.

Importér kontakter fra en CSV-fil #

Ved importer, der er større end hvad bulk import understøtter (op til cirka 50.000 rækker), skal du køe et asynkront importjob mod en CSV-fil, der allerede ligger i din kontos lager, og derefter polle det, indtil det er fuldført.

Start importen #

POST /contacts/import-csv

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csvStoragePath": "users/abc123/imports/leads.csv",
    "listName": "Webinar signups"
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    csvStoragePath: "users/abc123/imports/leads.csv",
    listName: "Webinar signups",
  }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "csvStoragePath": "users/abc123/imports/leads.csv",
        "listName": "Webinar signups",
    },
)
job_id = res.json()["job_id"]

Svar (202 — importen er sat i kø, ikke færdig endnu)

{
  "success": true,
  "job_id": "csvimp_abc123",
  "status": "queued"
}

Få filen ind i lageret. Dette endepunkt starter og sporer importjobbet; det accepterer ikke selv en upload. CSV-filen skal allerede findes på csvStoragePath, før du kalder det — dashboardets egen CSV-importør gør dette som sit første skridt.

Polling af importjobbet #

GET /contacts/import-csv/{jobId}

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv/csvimp_abc123?apiKey=YOUR_API_KEY"

Svar

{
  "success": true,
  "job_id": "csvimp_abc123",
  "status": "completed",
  "imported": 812,
  "updated": 0,
  "skipped": 14,
  "errors": [],
  "error_message": null
}

status bevæger sig gennem queued → processing → completed eller failed med årsagen i error_message. Et jobId, der ikke findes på din konto, returnerer en 404.

Eksportér kontakter #

Starter en asynkron CSV-eksport af dine kontakter og returnerer et job, som du kan polle for færdiggørelse.

Start eksporten #

POST /contacts/export

Hvis begge udelades, eksporteres alle kontakter på din konto.

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listId": "list123" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ listId: "list123" }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"listId": "list123"},
)
job_id = res.json()["job_id"]

Svar (202 — eksporten er sat i kø)

{
  "success": true,
  "job_id": "export_abc123",
  "status": "queued"
}

Forespørg eksportjobbet #

GET /contacts/export/{jobId}

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export/export_abc123?apiKey=YOUR_API_KEY"

Svar

{
  "success": true,
  "job_id": "export_abc123",
  "status": "completed",
  "export_id": "exp_xyz789",
  "contact_count": 812,
  "error_message": null
}

Når status er "completed", modtager du export_id og contact_count. Download af den genererede CSV-fil sker fra dit kontrolpanels Eksport-side.

Send en besked til en kontakt #

POST /contacts/{contactId}/send-message

Sender en besked til en eksisterende kontakt på den kanal, de allerede befinder sig på. Beskeden sættes i kø og leveres i baggrunden — svaret bekræfter, at den blev accepteret, ikke at den er blevet leveret endnu.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Hi! Your appointment is confirmed." }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ body: "Hi! Your appointment is confirmed." }),
});
const data = await res.json();
console.log(data.messageId);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"body": "Hi! Your appointment is confirmed."},
)
print(res.json()["messageId"])

Svar

{
  "success": true,
  "messageId": "aB3dE5fG7hI9jK1lM2nO",
  "contactId": "contact_abc123",
  "channel": "whatsapp",
  "message": "Message created successfully. Delivery is being processed."
}

Kan ikke sende lige nu? Hvis kontakten har aktiveret forstyr-ikke eller privat tilstand, eller ikke er på en kanal, der kan modtage udgående beskeder, afvises anmodningen med en 422 og en forklarende error.

For afsendelse via telefonnummer, Instagram-id eller anden kanalidentitet i stedet for et kontakt-id — og for mere om beskeder generelt — se Messages API.

Tildel en AI-agent til en kontakt #

POST /contacts/{contactId}/assign-agent

Flytter en eksisterende samtale til en anden AI-agent fra og med den næste besked. Det svarer til Tildel AI-agent i en chats menu, og det er det samme trin, som handlingen Tildel AI-agent eller kampagne i Automatiseringer bruger.

Vær forsigtig med triggerAIResponse: true — den sender en besked til kontakten med det samme, så brug den kun, når du ønsker, at de skal kontaktes nu. På Messenger og Instagram fejler beskeden, hvis kontakten sidst skrev til dig for mere end 24 timer siden.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "agent_xyz789" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ agentId: "agent_xyz789" }),
});
const data = await res.json();
console.log(data.data.agentId);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agentId": "agent_xyz789"},
)
print(res.json()["data"]["agentId"])

Svar

{
  "success": true,
  "data": {
    "contactId": "contact_abc123",
    "agentId": "agent_xyz789",
    "aiResponseTriggered": false
  }
}

Agenten skal tilhøre den samme konto som kontakten; ellers afvises anmodningen med en 404 eller 403. Find agent-ID’er på siden AI-agenter (hver agents URL slutter med dens ID).

Tildel en AI-agent til mange kontakter #

POST /contacts/bulk-assign-agent

Flytter mange samtaler til en anden AI-agent i ét kald — eller rydder tildelingen for dem alle med null. Det er udelukkende en routing-ændring: ingen besked sendes, og agenten svarer ikke nogen. Hver kontakt får blot den nye agent, næste gang de skriver. (Det er derfor, der ikke er nogen triggerAIResponse her.)

Send præcis én af contactIds, filter eller rules.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xyz789",
    "filter": { "agentId": "agent_abc123", "channel": "messenger" }
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "agent_xyz789",
    filter: { agentId: "agent_abc123", channel: "messenger" },
  }),
});
const data = await res.json();
console.log(data.updated, data.remaining);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "agentId": "agent_xyz789",
        "filter": {"agentId": "agent_abc123", "channel": "messenger"},
    },
)
data = res.json()
print(data["updated"], data["remaining"])

Svar

{
  "success": true,
  "agentId": "agent_xyz789",
  "matched": 3415,
  "updated": 500,
  "skipped": 0,
  "remaining": 2915,
  "filters": { "agentId": "agent_abc123" }
}

matched er hvor mange kontakter udvalget fandt i alt, updated hvor mange der blev flyttet af dette kald, skipped hvor mange af de ID’er, du sendte, der ikke blev fundet på din konto, og remaining hvor mange der stadig matcher nu, hvor kaldet er færdigt.

Flytning af alle. Da et kald flytter maksimalt 500 kontakter, kræver en stor gruppe nogle få kald. Brug et filter, der holder op med at matche en kontakt, når den er flyttet — for eksempel filter: { "agentId": "agent_abc123" } mens der tildeles til agent_xyz789 — og gentag det præcis samme kald, indtil remaining kommer tilbage som 0. Når du i stedet sender contactIds, er remaining altid 0.

Tildel en kontakt til en afdeling #

POST /contacts/{contactId}/department

“Tildel dette lead til Salg” — placerer en kontakt under en navngiven afdeling og giver den som standard til den person i afdelingen, der i øjeblikket har færrest kontakter. Dette er adskilt fra tildeling af en AI-agent: en afdeling besvarer “hvilket team ejer dette,” en agent besvarer “hvilken AI besvarer dette,” og indstilling af den ene sletter aldrig den anden.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "department_id": "dept_sales" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ department_id: "dept_sales" }),
});
const data = await res.json();
console.log(data.assigned_to);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"department_id": "dept_sales"},
)
print(res.json()["assigned_to"])

Svar

{
  "success": true,
  "department_id": "dept_sales",
  "assigned_to": "member_uid_123"
}

assigned_to er null, når kontakten allerede var ejet af nogen, eller du sendte hand_to_member: false.

Link en kontakt på tværs af kanaler #

“Fortsæt på WhatsApp” (eller SMS) finder eller opretter denne persons kontakt på en anden telefonbaseret kanal og linker de to sammen, så resten af appen genkender dem som den samme person.

Link til en anden kanal #

POST /contacts/{contactId}/link-channel

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/link-channel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms" }'

Svar

{
  "success": true,
  "data": {
    "contact_id": "contact_def456",
    "person_id": "person_xyz789",
    "created": true
  }
}

created fortæller dig, om en ny kontakt blev oprettet til målkanalen, eller om en eksisterende blev fundet og linket. Det er sikkert at kalde dette en anden gang — det returnerer den samme contact_id med created: false i stedet for at oprette en dublet.

En 422 betyder, at kontoen ikke kan udføre dette link lige nu: kontakten er allerede på den kanalfamilie, den har intet telefonnummer at bruge, eller der er ingen forbundet afsender til målkanalen. En 409 betyder, at de to kontakter allerede er linket til to forskellige personer — fjern linket for den ene først.

Vis en kontakts linkede samtaler #

GET /contacts/{contactId}/linked

Returnerer de andre samtaler, der er den samme person som denne kontakt. En ikke-linket kontakt returnerer et tomt array, ikke en 404 — “denne person har ingen andre kanaler” er en normal tilstand.

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/linked?apiKey=YOUR_API_KEY"

Svar

{
  "success": true,
  "data": [
    {
      "contact_id": "contact_def456",
      "channel": "sms",
      "custom_channel": null,
      "first_name": "Jane",
      "last_name": "Smith",
      "phone_number": "+15551234567",
      "last_message": "Sounds good, thanks!",
      "last_message_timestamp": "2026-06-09T10:21:00.000Z",
      "linked_from": {
        "contact_id": "contact_abc123",
        "channel": "whatsapp",
        "linked_at": "2026-06-01T09:00:00.000Z",
        "reason": "continue_on_channel"
      }
    }
  ]
}

Fjern link for en kontakt #

DELETE /contacts/{contactId}/link

Fjerner denne kontakt fra sin person, ensidigt — alle andre kontakter, der stadig er linket til den person, beholder deres link, så at fjerne linket for én ud af tre opløser ikke gruppen.

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/link?apiKey=YOUR_API_KEY"

Svar

{ "success": true }

Hent en kontakts profilbillede #

POST /contacts/{contactId}/profile-pic

Henter (og cacher) kontaktens WhatsApp- eller Meta-profilbillede efter behov — det samme billede, der returneres som avatarUrl i Hent en kontakt, opdateret.

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/profile-pic?apiKey=YOUR_API_KEY"

Svar

{
  "success": true,
  "avatar_url": "https://example.com/photo.jpg",
  "cached": false
}

cached: true betyder, at URL’en kom fra et nyligt opslag i stedet for et frisk udbyderopslag — billeder caches i 7 dage, og en kontakt, som udbyderen rapporterer ikke har et tilgængeligt billede, caches som utilgængelig i 24 timer. Når der ikke er noget billede at hente, udelades avatar_url, og message forklarer hvorfor.

Auto-tag kontakter med AI #

Kører din kontos tag-regler over en eller flere kontakters fulde samtaleliste og tilføjer (eller fjerner) tags præcis som den realtids-tagging, der kører under en live chat — samme regler, samme kreditomkostning pr. tag.

Start en kørsel #

POST /contacts/auto-tag

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/auto-tag?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "contacts", "contact_ids": ["contact_abc123", "contact_def456"] }'

En enkelt kontakt køres inline og returnerer resultatet med det samme:

{ "success": true, "result": { "tags_applied": 2, "tags_removed": 0 } }

To eller flere kontakter (eller scope: "agent") køres som et baggrundsjob og returnerer 202 med det samme:

{ "success": true, "run_id": "m1x2y3-a1b2c3d4", "total": 214 }

Forespørg en kørsel #

GET /contacts/auto-tag/run

Returnerer kontoens nuværende (eller seneste) kørsel, så du kan forespørge om status uden selv at skulle spore run_id.

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/auto-tag/run?apiKey=YOUR_API_KEY"

Svar

{
  "success": true,
  "run": {
    "run_id": "m1x2y3-a1b2c3d4",
    "status": "running",
    "total": 214,
    "processed": 58,
    "tagged_contacts": 12,
    "tags_applied": 15,
    "tags_removed": 2,
    "credits_charged": 15
  }
}

run er null, når kontoen aldrig har startet en. status flytter sig fra "running" til "completed" eller "failed".

Kun én bulk-kørsel kan være i gang pr. konto ad gangen — hvis du starter en anden, mens en anden kører, returneres 409 med error_code: "auto_tag_run_in_progress". Hvis du løber tør for kreditter under en kørsel for en enkelt kontakt, returneres 402 med error_code: "insufficient_credits"; en bulk-kørsel stopper i stedet sig selv tidligt og rapporterer, hvor langt den nåede i run.

Slet en kontakt #

DELETE /contacts/{contactId}

Sletter permanent én kontakt via ID, sammen med dens beskedhistorik. Dette kan ikke fortrydes. For at slette flere kontakter i et enkelt kald, brug Slet kontakter herunder.

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Svar

{
  "success": true
}

Et kontakt-id, der ikke findes på din konto, eller som tilhører en anden konto, returnerer en 404.

Slet kontakter #

DELETE /contacts

Sletter permanent en eller flere kontakter via id i et enkelt kald (op til 500 id’er). Id’er, der ikke findes på din konto, springes over og tælles i skipped. Dette kan ikke fortrydes.

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contactId1", "contactId2"] }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts", {
  method: "DELETE",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ contactIds: ["contactId1", "contactId2"] }),
});
const data = await res.json();
console.log(`Deleted ${data.deleted}, skipped ${data.skipped}`);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contactId1", "contactId2"]},
)
data = res.json()
print(f"Deleted {data['deleted']}, skipped {data['skipped']}")

Svar

{
  "success": true,
  "deleted": 2,
  "skipped": 0
}

Slet et brugerdefineret felt #

DELETE /contacts/custom-fields/{fieldKey}

Fjerner én brugerdefineret feltnøgle fra alle kontakter på din konto. Brug dette til at rydde op efter omdøbning eller fjernelse af et brugerdefineret felt. Nøglen må kun indeholde bogstaver, tal, understregninger og bindestreger. Returnerer hvor mange kontakter der blev opdateret. Dette kan ikke fortrydes.

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(`Removed from ${data.updated} contacts`);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(f"Removed from {res.json()['updated']} contacts")

Svar

{
  "success": true,
  "updated": 42
}

Lister #

Lister grupperer kontakter. En liste er enten statisk (du bestemmer, hvem der er på den) eller smart (medlemskab beregnes ud fra regler og holdes automatisk opdateret — se Organisering af lister og kontakter).

Opret en liste #

POST /lists

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Hot leads (active)",
        "type": "smart",
        "smart_rules": {
          "match": "all",
          "conditions": [
            { "field": "tags", "op": "has_any", "value": ["tagHotLead"] },
            { "field": "last_activity_at", "op": "within_last", "value": { "amount": 90, "unit": "days" } }
          ]
        }
      }'

Svar

{
  "success": true,
  "list_id": "list_abc123",
  "evaluation": { "added": 3, "removed": 0, "total": 3 }
}

En smart liste evalueres inline i den samme anmodning, så evaluation fortæller dig præcis, hvem der endte på den. På en statisk liste er evaluation lig med null.

Opdater en liste #

PUT /lists/{listId}

Send kun de felter, du ændrer. Ændring af smart_rules gen-evaluerer listen med det samme og returnerer det samme evaluation-objekt.

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists/list_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "smart_rules": { "match": "any", "conditions": [ { "field": "tags", "op": "has_any", "value": ["tagHotLead", "tagWebinar"] } ] } }'

Du kan skifte en liste mellem de to typer:

• Statisk → smart: send { "type": "smart", "smart_rules": { … } }. Reglerne tager over med det samme.
• Smart → statisk: send { "type": "static" }. Reglerne fjernes, og alle, der er på listen, bliver der.

Formen på smart_rules #

{
  "match": "all",
  "conditions": [
    { "field": "tags", "op": "has_any", "value": ["tagHotLead"] },
    { "field": "channel", "op": "is_any", "value": ["whatsapp", "sms"] },
    { "field": "last_incoming_message_at", "op": "not_within_last", "value": { "amount": 7, "unit": "days" } },
    { "field": "created_at", "op": "after", "value": "2026-01-01" },
    { "field": "is_bot_active", "op": "is", "value": true },
    { "field": "email", "op": "is_set" },
    { "field": "custom_field", "key": "Plan", "op": "eq", "value": "pro" }
  ]
}

• match — all (alle betingelser skal være sande) eller any (mindst én).
• conditions — 1 til 20 betingelser, hver med højst 100 værdier, strenge på op til 200 tegn.

not_within_last matcher også kontakter, hvor datoen aldrig er blevet sat (“mere end N siden, eller aldrig”), og tekstsammenligninger ignorerer store/små bogstaver.

AI-engagement. has_interacted_with_ai er lifetime-flaget: true for enhver kontakt, som din AI har sendt mindst én besked til, false for alle andre (inklusive kontakter, som kun dit team nogensinde har svaret). Det stemples ved AI’ens første besked til en kontakt og slettes aldrig, så at slå AI-svar fra for kontakten eller flytte dem til en anden kampagne nulstiller det ikke. For en periode — “de kontakter min AI håndterede i denne måned”, det sædvanlige faktureringsspørgsmål — skal du bruge et interval over last_ai_interaction_at i stedet:

{ "field": "last_ai_interaction_at", "op": "within_last", "value": { "amount": 30, "unit": "days" } }

Forveksl ikke nogen af dem med is_bot_active (AI’en har tilladelse til at svare, ikke at den har gjort det) eller has_ever_responded (kontakten skrev tilbage, til hvem som helst). De samme to stempler returneres på hver kontakt som first_ai_interaction_at / last_ai_interaction_at, og hele regelsættet fungerer også på GET /contacts?rules=, så du kan tælle matches uden at oprette en liste.

Få vist et regelsæt #

POST /lists/preview

Tæller og sampler de kontakter, som et regelsæt ville matche, uden at oprette eller ændre noget. Brug det til at kontrollere reglerne, før du gemmer dem.

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists/preview?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "smart_rules": { "match": "all", "conditions": [ { "field": "tags", "op": "has_any", "value": ["tagHotLead"] } ] } }'

Svar

{
  "success": true,
  "count": 3,
  "sample": [
    {
      "id": "contact_abc123",
      "first_name": "Sofia",
      "last_name": "Martinez",
      "phone_number": "+31600000000",
      "email": "sofia@example.com",
      "channel": "whatsapp"
    }
  ]
}

sample indeholder op til 10 kontakter, sorteret efter seneste aktivitet først.

Kør en smart liste igen nu #

POST /lists/{listId}/evaluate

Tvinger en øjeblikkelig genberegning (det samme som Opdater nu gør i dashboardet). Smarte lister opdateres allerede, når en kontakt ændres, og hvert 15. minut for tidsbaserede regler, så dette er kun nødvendigt, når du vil have resultatet lige nu.

Svar

{
  "success": true,
  "list_id": "list_abc123",
  "evaluation": { "added": 2, "removed": 1, "total": 4 }
}

evaluation.skipped: true betyder, at en anden evaluering af den samme liste allerede kørte, og dette kald gjorde intet.

Smarte lister afviser manuelt tilføjede medlemmer #

Medlemskabs-endpoints returnerer 409 med "This is a smart list — its members are computed from its rules. Edit the rules instead.", når mållisten er smart. Det dækker POST /contacts/lists, DELETE /contacts/lists, POST /contacts/lists/batch, contact_ids på POST /lists og PUT /lists/{listId}, samt valg af en smart liste som mål for CSV-import. Ændr reglerne i stedet.

At kalde POST /lists/{listId}/evaluate på en statisk liste er også en 409 — den har ingen regler at køre.

Kontakter API-fejl #

Kontakt-endpoints returnerer standardfejlkonvolutten:

{
  "success": false,
  "error": "Contact not found"
}

Nogle slutpunkter inkluderer også error_code, som normalt matcher HTTP-status — den eneste undtagelse er tilfældet med dublerede kontakter nedenfor, hvor HTTP-status er 200, og kun error_code bærer 409. Koderne, der er specifikke for kontaktslutpunkter:

En 403 på et kontaktslutpunkt kan også betyde et problem med kontaktgrænse eller listetilladelse frem for abonnementsadgang. De delte koder, som ethvert slutpunkt kan returnere — 401, 403 (dit abonnement inkluderer ikke API-adgang), 429 (rate limit) og 500 — er angivet med vejledning til genforsøg i Fejl & Sidetal.

Næste skridt #

• Besked-API — send beskeder via kanalidentitet og administrer samtaler.
• API-reference — fuld liste over endpoints, inklusive tags og lister.
• API-adgang — godkendelse, hastighedsbegrænsninger og fejlhåndtering.