Entwickler / Schnellstart

Schnellstart

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

1. API-Schlüssel erstellen

Öffne in der App Einstellungen > Versand > API (direkt dorthin). Das geht für Inhaber und Manager.
Gib dem Schlüssel einen Namen und wähle Lesen und Anfragen senden, wenn er senden soll.
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.

Terminal

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.

curlJavaScriptPython

JavaScript

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);

Antwort

200

{
  "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.

curlJavaScriptPython

curl

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

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

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

201

{
  "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.

curlJavaScriptPython

JavaScript

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

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

200

{
  "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 kommt jede Bewertung und jedes Feedback sofort an deine Adresse.

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

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