# Schnellstart

In vier Schritten von null zur ersten Bewertungsanfrage. Du brauchst ein Citypicked-Konto und ein Terminal.

Source: https://citypicked.com/de/developers/quickstart

## 1. API-Schlüssel erstellen

1. Öffne in der App **Einstellungen > Versand > API** ([direkt dorthin](https://app.citypicked.com/settings/api)). Das geht für Inhaber und Manager.
2. Gib dem Schlüssel einen Namen und wähle **Lesen und Anfragen senden**, wenn er senden soll.
3. Kopiere den Schlüssel sofort. Er wird nur einmal angezeigt.

Leg ihn für die nächsten Schritte in eine Variable. Die Beispiele zeigen einen Platzhalter.

```bash
export CITYPICKED_API_KEY=cp_live_xxxxxxxx
```

> Anfragen über die API senden ist in den Paketen Pro und Business enthalten. Lesen geht mit jedem Paket.

## 2. Erste Abfrage

`GET /v1/me` zeigt das Konto, den Schlüssel und ob er senden darf. Jede funktionierende Verbindung bekommt hier 200.

curl:

```bash
curl "https://api.citypicked.com/v1/me" \
  -H "Authorization: Bearer cp_live_xxxxxxxx"
```

JavaScript:

```js
const res = await fetch("https://api.citypicked.com/v1/me", {
  headers: {
    Authorization: "Bearer cp_live_xxxxxxxx",
  },
});
const data = await res.json();
console.log(res.status, data);
```

Python:

```python
import requests

res = requests.get(
    "https://api.citypicked.com/v1/me",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx"},
)
print(res.status_code, res.json())
```

Antwort

```json
{
  "account": {
    "id": "0b7c8f4e-5a1d-4c2e-9f3a-6d8e2b1c4a70",
    "name": "Sunnyside Salon",
    "plan": "pro",
    "language": "en",
    "time_zone": "America/New_York"
  },
  "key": {
    "name": "Booking system",
    "scopes": [
      "read",
      "send"
    ]
  },
  "can_send": true,
  "credits": {
    "balance": 180
  }
}
```

## 3. Eine Bewertungsanfrage senden

`POST /v1/requests` sendet an bis zu 100 Kunden auf einmal. `consent: true` bestätigt, dass die Kunden einverstanden sind. Mit einem `Idempotency-Key` geht derselbe Aufruf innerhalb von 24 Stunden nur einmal raus.

curl:

```bash
curl -X POST "https://api.citypicked.com/v1/requests" \
  -H "Authorization: Bearer cp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-1042" \
  -d '{
  "location_id": "5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40",
  "channel": "email",
  "consent": true,
  "contacts": [
    {
      "name": "Emma Clark",
      "email": "emma@example.com"
    }
  ]
}'
```

JavaScript:

```js
const res = await fetch("https://api.citypicked.com/v1/requests", {
  method: "POST",
  headers: {
    Authorization: "Bearer cp_live_xxxxxxxx",
    "Content-Type": "application/json",
    "Idempotency-Key": "booking-1042",
  },
  body: JSON.stringify({
    "location_id": "5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40",
    "channel": "email",
    "consent": true,
    "contacts": [
      {
        "name": "Emma Clark",
        "email": "emma@example.com"
      }
    ]
  }),
});
const data = await res.json();
console.log(res.status, data);
```

Python:

```python
import requests

res = requests.post(
    "https://api.citypicked.com/v1/requests",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx", "Idempotency-Key": "booking-1042"},
    json={
        "location_id": "5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40",
        "channel": "email",
        "consent": True,
        "contacts": [
            {
                "name": "Emma Clark",
                "email": "emma@example.com",
            },
        ],
    },
)
print(res.status_code, res.json())
```

Antwort

```json
{
  "results": [
    {
      "index": 0,
      "outcome": "created",
      "request_id": "c3f1a9e2-7b4d-4e8a-b6c2-1f9d3e5a7b20"
    }
  ],
  "created": 1
}
```

- `created` heißt, die Anfrage ist unterwegs
- `duplicate` heißt, dieser Kunde wurde vor Kurzem schon gefragt. Die Sperre dauert 30 Tage, solange das Konto sie in der App nicht ändert
- `opted_out`, `invalid`, `no_credits` und `consent_method_missing` sagen, warum nichts rausging

> Für SMS nimmst du `"channel": "sms"` und eine Nummer wie `+49 171 39200 12`. SMS an Nummern in den USA und Kanada brauchen zusätzlich `consent_method` und gehen von der eigenen Nummer des Unternehmens raus, sobald die Netzbetreiber seine Firmendaten geprüft haben.

## 4. Ergebnis lesen

Mit der `request_id` aus der Antwort fragst du den Stand ab. `status` geht von `sent` über `delivered` und `clicked` zu `rated`, `rating` zeigt die Sterne.

curl:

```bash
curl "https://api.citypicked.com/v1/requests/c3f1a9e2-7b4d-4e8a-b6c2-1f9d3e5a7b20" \
  -H "Authorization: Bearer cp_live_xxxxxxxx"
```

JavaScript:

```js
const res = await fetch("https://api.citypicked.com/v1/requests/c3f1a9e2-7b4d-4e8a-b6c2-1f9d3e5a7b20", {
  headers: {
    Authorization: "Bearer cp_live_xxxxxxxx",
  },
});
const data = await res.json();
console.log(res.status, data);
```

Python:

```python
import requests

res = requests.get(
    "https://api.citypicked.com/v1/requests/c3f1a9e2-7b4d-4e8a-b6c2-1f9d3e5a7b20",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx"},
)
print(res.status_code, res.json())
```

Antwort

```json
{
  "id": "c3f1a9e2-7b4d-4e8a-b6c2-1f9d3e5a7b20",
  "location_id": "5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40",
  "channel": "email",
  "source": "api",
  "status": "rated",
  "contact": {
    "name": "Emma C.",
    "email": "em***@example.com",
    "phone": null
  },
  "rating": 5,
  "created_at": "2026-11-08T09:30:00Z",
  "sent_at": "2026-11-08T09:30:04Z",
  "clicked_at": "2026-11-08T10:12:40Z",
  "rated_at": "2026-11-08T10:13:05Z"
}
```

Statt nachzufragen kannst du dir das auch schicken lassen. Mit [Webhooks](https://citypicked.com/de/developers/webhooks) kommt jede Bewertung und jedes Feedback sofort an deine Adresse.