Developers / Quickstart

Quickstart

Four steps from nothing to your first review request. You need a Citypicked account and a terminal.

1. Make an API key

In the app, open Settings > Sending > API (go there). Owners and managers can do this.
Name the key and pick Read and send requests if it should send.
Copy the key right away. It is shown only once.

Keep it in a variable for the next steps. The examples show a placeholder.

Terminal

export CITYPICKED_API_KEY=cp_live_xxxxxxxx

Sending requests through the API is part of the Pro and Business plans. Reading works on every plan.

2. Make your first call

GET /v1/me shows the account, the key and whether it can send. Every working key gets 200 here.

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

Answer

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. Send one review request

POST /v1/requests sends to up to 100 customers at once. consent: true confirms the customers agreed to hear from you. With an Idempotency-Key, the same call within 24 hours goes out only once.

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

Answer

201

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

created means the request is on its way
duplicate means this customer was asked recently. The window is 30 days unless the account changed it in the app
opted_out, invalid, no_credits and consent_method_missing say why nothing went out

For SMS, use "channel": "sms" and a number like +1 201 555 0123. SMS to US and Canadian numbers also need consent_method and go out from the business's own number once the carriers have checked its business details.

4. Read the result

Use the request_id from the answer to check where it stands. status moves from sent through delivered and clicked to rated, and rating shows the stars.

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

Answer

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

Instead of asking again, you can have it sent to you. With webhooks every rating and every piece of feedback arrives at your URL right away.

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