# Einen Kontakt anlegen und einen Tag hinzufügen

> Schritt für Schritt mit curl, Python und TypeScript. Lege einen Kontakt an, füge einen Tag hinzu und lies ihn zurück. Dem Kontakt wird nichts gesendet.

Stand: 2026-10-30. Quelle: https://docs.smartchat.marketing/de/guides/create-a-contact/

Du brauchst einen Schlüssel mit der Stufe **Draft** oder höher (Recht `contacts:write`). In dieser Anleitung wird keine Nachricht gesendet.

Die drei Schritte erzählen eine Geschichte: Mia wird angelegt, bekommt den Tag `vip` und wird mit diesem Tag zurückgelesen. Die Antworten auf dieser Seite gehören zusammen.

## 1. Den Kontakt anlegen

**curl**

```bash
curl -X POST "https://api.smartchat.marketing/v1/contacts" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Mia Muster",
  "phone": "+4915112345678",
  "email": "mia@example.com"
}'
```

**Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.smartchat.marketing/v1/contacts",
    headers={
        "Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Mia Muster",
        "phone": "+4915112345678",
        "email": "mia@example.com",
    },
)
response.raise_for_status()
print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://api.smartchat.marketing/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Mia Muster",
    "phone": "+4915112345678",
    "email": "mia@example.com"
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

Response (201):


```json
{
  "object": "contact",
  "id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "name": "Mia Muster",
  "phone": "+4915112345678",
  "email": "mia@example.com",
  "language": "en",
  "status": "unconfirmed",
  "optin_whatsapp": "none",
  "optin_whatsapp_at": null,
  "purpose": "marketing",
  "source": "api",
  "tags": [],
  "tag_details": [],
  "created_at": "2026-10-25T09:41:07Z"
}
```

Aufrufe, die etwas anlegen, brauchen einen `Idempotency-Key` ([warum](https://docs.smartchat.marketing/de/concepts/idempotency/)). Der neue Kontakt hat `optin_whatsapp` auf `none`, bis der Kontakt bestätigt. Die API setzt nie einen Kontakt auf `confirmed`.

Gibt es schon einen Kontakt mit derselben Telefonnummer oder E-Mail, lautet die Antwort [`contact_already_exists`](https://docs.smartchat.marketing/de/errors/#contact_already_exists) mit der ID des bestehenden Kontakts in `existing_id`. Ändere diesen Kontakt stattdessen mit [`update_contact`](https://docs.smartchat.marketing/en/api/reference/contacts/update_contact/).

## 2. Einen Tag hinzufügen

Tags werden einem oder mehreren Kontakten auf einmal hinzugefügt. Der Tag wird angelegt, wenn es ihn noch nicht gibt.

**curl**

```bash
curl -X POST "https://api.smartchat.marketing/v1/contacts/tags" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "contact_ids": [
    "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234"
  ],
  "add_tags": [
    "vip"
  ]
}'
```

**Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.smartchat.marketing/v1/contacts/tags",
    headers={
        "Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "contact_ids": [
            "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
        ],
        "add_tags": [
            "vip",
        ],
    },
)
response.raise_for_status()
print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://api.smartchat.marketing/v1/contacts/tags", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "contact_ids": [
      "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234"
    ],
    "add_tags": [
      "vip"
    ]
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

Response (200):


```json
{
  "object": "contact_tags_update",
  "updated": 1,
  "unchanged": 0,
  "not_found": 0,
  "failed": 0,
  "results": [
    {
      "contact_id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
      "status": "updated",
      "tags": [
        "vip"
      ],
      "error_code": null
    }
  ]
}
```

## 3. Den Kontakt zurücklesen

**curl**

```bash
curl "https://api.smartchat.marketing/v1/contacts/con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.smartchat.marketing/v1/contacts/con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
    headers={"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]},
)
response.raise_for_status()
print(response.json())
```

**TypeScript**

```typescript
const response = await fetch("https://api.smartchat.marketing/v1/contacts/con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
  },
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
```

Response (200):


```json
{
  "object": "contact",
  "id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
  "name": "Mia Muster",
  "phone": "+4915112345678",
  "email": "mia@example.com",
  "language": "en",
  "status": "unconfirmed",
  "optin_whatsapp": "none",
  "optin_whatsapp_at": null,
  "purpose": "marketing",
  "source": "api",
  "tags": [
    "vip"
  ],
  "tag_details": [
    {
      "name": "vip",
      "origin": "manual",
      "added_at": "2026-10-25T09:42:30Z"
    }
  ],
  "created_at": "2026-10-25T09:41:07Z"
}
```

Der Kontakt hat jetzt den Tag `vip`.

## Als Nächstes

- Frage den Kontakt nach dem Opt-in: [`create_optin_confirmations`](https://docs.smartchat.marketing/en/api/reference/contacts/create_optin_confirmations/). Siehe [Einwilligung und das 24-Stunden-Fenster](https://docs.smartchat.marketing/de/concepts/consent-and-24h-window/).
- Finde Kontakte nach Tag: [`search_contacts`](https://docs.smartchat.marketing/en/api/reference/contacts/search_contacts/).