Entwickler / API-Referenz

Diese Seite gibt es nur auf Englisch.

API reference

Every endpoint of the REST API with its parameters, an example call, an example answer and its errors. Generated from the OpenAPI document.

View as Markdown OpenAPI document

Base URL https://api.citypicked.com/v1. JSON in and out, times in ISO 8601 UTC, ids are UUIDs. Send your key as Authorization: Bearer cp_live_xxxxxxxx (how). Lists take limit (1 to 100, default 25) and cursor, and answer next_cursor, which is null on the last page.

The OpenAPI document has the full schemas. Errors and limits are on Rate limits and errors.

Account

GET`/v1/me`

The account, this key and whether it can sendScope read

The connection test of every integration: 200 for every working key.

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

Answer fields

accountobject · required
account.iduuid · required
account.namestring · required
account.planstring or null · required
account.languagestring · required
account.time_zonestring · required
keyobject · required
key.namestring · required
key.scopesarray of (read | send) · required
can_sendboolean · required: False when the key lacks send, the plan has no API sending, or the account is behind the plan wall.
creditsobject · required
credits.balanceinteger · required: SMS credits (one SMS uses one or more by length and country; e-mail uses none).

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

Locations

GET`/v1/locations`

The locations this key can seeScope read

Newest first by created_at. Pass next_cursor as cursor for the next page; null means there is none. Polling triggers dedupe by id and filter with since.

Parameters

limitquery · string: 1 to 100, default 25.
cursorquery · string: next_cursor of the previous answer.

curlJavaScriptPython

JavaScript

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

Answer 200

{
  "data": [
    {
      "id": "5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40",
      "name": "Sunnyside Salon Downtown",
      "country": "US",
      "review_link": "https://go.citypicked.com/sunnyside-salon",
      "created_at": "2026-11-08T09:30:00Z"
    }
  ],
  "next_cursor": null
}

Answer fields

dataarray of object · required
data[].iduuid · required
data[].namestring · required
data[].countrystring · required
data[].review_linkstring or null · required
data[].created_atstring (date-time) · required
next_cursorstring or null · required: Pass as cursor for the next page; null when there is none.

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

GET`/v1/locations/{id}/review-link`

A location's review page link, or its QR code as SVG or PNGScope read

Parameters

idpath · uuid · required
formatquery · json | svg | png: json (default): the link. svg or png (1024 px): its QR code as an image.

curlJavaScriptPython

JavaScript

const res = await fetch("https://api.citypicked.com/v1/locations/5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40/review-link", {
  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/locations/5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40/review-link",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx"},
)
print(res.status_code, res.json())

Answer 200

{
  "location_id": "5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40",
  "url": "https://go.citypicked.com/sunnyside-salon",
  "qr_svg_url": "https://api.citypicked.com/v1/locations/5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40/review-link?format=svg",
  "qr_png_url": "https://api.citypicked.com/v1/locations/5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40/review-link?format=png"
}

With format=svg or format=png the answer is the QR code itself (image/svg+xml, or image/png at 1024 px) instead of JSON.

Answer fields

location_iduuid · required
urlstring · required
qr_svg_urlstring · required
qr_png_urlstring · required

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
404not_found: nothing with this id for this key
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

Requests

GET`/v1/requests`

Review requestsScope read

Newest first by created_at. Pass next_cursor as cursor for the next page; null means there is none. Polling triggers dedupe by id and filter with since. Triggers: status=rated (request rated), status=public_click (a click to a review site).

Parameters

location_idquery · uuid: Only this location's requests.
statusquery · scheduled | sent | delivered | failed | clicked | rated | public_click | feedback | canceled: Has reached: rated lists every request with a rating (also those that went on to public_click or feedback), public_click every one whose customer went on to a review site, clicked every opened one; scheduled and canceled are the current status.
sincequery · string (date-time): Inclusive. Without status: created at or after. With status: reached that status at or after (rated_at, ...).
limitquery · string: 1 to 100, default 25.
cursorquery · string: next_cursor of the previous answer.

curlJavaScriptPython

JavaScript

const res = await fetch("https://api.citypicked.com/v1/requests?status=rated&limit=10", {
  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",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx"},
    params={
        "status": "rated",
        "limit": "10",
    },
)
print(res.status_code, res.json())

Answer 200

{
  "data": [
    {
      "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"
    }
  ],
  "next_cursor": null
}

Answer fields

dataarray of object · required
data[].iduuid · required
data[].location_iduuid · required
data[].channelsms | email | whatsapp | qr · required
data[].sourcemanual | csv | trigger | qr | integration | api · required
data[].statusscheduled | sent | delivered | failed | clicked | rated | public_click | feedback | canceled · required
data[].contactobject · required: Masked the way the app's sent list masks contacts: Anna M., an***@example.org, +49 170 ... 67.
data[].contact.namestring or null · required
data[].contact.emailstring or null · required
data[].contact.phonestring or null · required
data[].ratinginteger or null · required
data[].created_atstring (date-time) · required
data[].sent_atstring (date-time) or null · required
data[].clicked_atstring (date-time) or null · required
data[].rated_atstring (date-time) or null · required
next_cursorstring or null · required: Pass as cursor for the next page; null when there is none.

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
404not_found: nothing with this id for this key
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

POST`/v1/requests`

Send review requestsScope send

The same way as the send form: same checks, same credits, same duplicate window. Up to 100 contacts per call, body up to 256 KB. Each contact gets an outcome; a call where no contact can be sent still answers 201, only a malformed body is 400. Idempotency-Key, per API key: the same key within 24 hours returns the first answer and sends nothing again; with a different body it is 409 idempotency_conflict. send_at plans the requests up to 30 days ahead inside the sending hours. A WhatsApp result carries whatsapp_url: the business sends it from its own phone. Needs the send scope and a plan with API sending; behind the plan wall 402.

Parameters

Idempotency-Keyheader · string: Any string up to 200 characters, per API key. The same key within 24 hours returns the first answer and sends nothing again; with another body 409 idempotency_conflict.

Body

location_iduuid: Optional when the key sees exactly one location.
channelsms | email | whatsapp · required
send_atstring (date-time): When to send, at most 30 days ahead; default now. Moved into the location's sending hours like a send from the app.
consenttrue · required: You confirm that these customers agreed to be contacted.
consent_methodbooking | in_person | form | written: Required for SMS to US and CA numbers: how these customers agreed.
contactsarray of object · required
contacts[].namestring: The customer's name, used in the message.
contacts[].emailstring: Needed for channel email.
contacts[].phonestring: Needed for sms and whatsapp. International format (+49 170 ...) or the location's national format.

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
}

Answer fields

resultsarray of object · required
results[].indexinteger · required: Position in contacts.
results[].outcomecreated | duplicate | invalid | opted_out | no_credits | consent_method_missing · required
results[].request_iduuid or null · required
results[].messagestring: Why, when the outcome is not created.
results[].whatsapp_urlstring: WhatsApp only, created: the wa.me link the business opens on its own phone to send the message, as in the app.
createdinteger · required

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
402plan_wall: the account cannot send (trial over or plan without access)
403forbidden (scope missing, plan without API sending) or account_closed
404not_found: nothing with this id for this key
409idempotency_conflict (the Idempotency-Key came with another body) or not_cancelable (the request already went out)
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

POST`/v1/requests/{id}/cancel`

Cancel a request that is still plannedScope send

200 with the request (status canceled, also when it was canceled before); 409 not_cancelable once it went out.

Parameters

idpath · uuid · required

curlJavaScriptPython

JavaScript

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

Python

import requests

res = requests.post(
    "https://api.citypicked.com/v1/requests/c3f1a9e2-7b4d-4e8a-b6c2-1f9d3e5a7b20/cancel",
    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": "canceled",
  "contact": {
    "name": "Emma C.",
    "email": "em***@example.com",
    "phone": null
  },
  "rating": null,
  "created_at": "2026-11-08T09:30:00Z",
  "sent_at": null,
  "clicked_at": null,
  "rated_at": null
}

Answer fields

iduuid · required
location_iduuid · required
channelsms | email | whatsapp | qr · required
sourcemanual | csv | trigger | qr | integration | api · required
statusscheduled | sent | delivered | failed | clicked | rated | public_click | feedback | canceled · required
contactobject · required: Masked the way the app's sent list masks contacts: Anna M., an***@example.org, +49 170 ... 67.
contact.namestring or null · required
contact.emailstring or null · required
contact.phonestring or null · required
ratinginteger or null · required
created_atstring (date-time) · required
sent_atstring (date-time) or null · required
clicked_atstring (date-time) or null · required
rated_atstring (date-time) or null · required

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
404not_found: nothing with this id for this key
409idempotency_conflict (the Idempotency-Key came with another body) or not_cancelable (the request already went out)
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

GET`/v1/requests/{id}`

One review requestScope read

Parameters

idpath · uuid · required

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

Answer fields

iduuid · required
location_iduuid · required
channelsms | email | whatsapp | qr · required
sourcemanual | csv | trigger | qr | integration | api · required
statusscheduled | sent | delivered | failed | clicked | rated | public_click | feedback | canceled · required
contactobject · required: Masked the way the app's sent list masks contacts: Anna M., an***@example.org, +49 170 ... 67.
contact.namestring or null · required
contact.emailstring or null · required
contact.phonestring or null · required
ratinginteger or null · required
created_atstring (date-time) · required
sent_atstring (date-time) or null · required
clicked_atstring (date-time) or null · required
rated_atstring (date-time) or null · required

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
404not_found: nothing with this id for this key
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

Feedback

GET`/v1/feedback`

Private feedback from the review pageScope read

Newest first by created_at. Pass next_cursor as cursor for the next page; null means there is none. Polling triggers dedupe by id and filter with since. Trigger: new private feedback.

Parameters

location_idquery · uuid: Only this location's feedback.
statusquery · new | in_progress | resolved
sincequery · string (date-time): Only items created at or after this time (ISO 8601, inclusive).
limitquery · string: 1 to 100, default 25.
cursorquery · string: next_cursor of the previous answer.

curlJavaScriptPython

JavaScript

const res = await fetch("https://api.citypicked.com/v1/feedback?status=new", {
  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/feedback",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx"},
    params={
        "status": "new",
    },
)
print(res.status_code, res.json())

Answer 200

{
  "data": [
    {
      "id": "9e2a4c6b-1d3f-4a5e-8b7c-2e4f6a8c0d10",
      "location_id": "5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40",
      "request_id": "c3f1a9e2-7b4d-4e8a-b6c2-1f9d3e5a7b20",
      "rating": 2,
      "text": "We waited 20 minutes past our booking time.",
      "contact": {
        "name": "Emma C."
      },
      "status": "new",
      "created_at": "2026-11-08T09:30:00Z"
    }
  ],
  "next_cursor": null
}

Answer fields

dataarray of object · required
data[].iduuid · required
data[].location_iduuid · required
data[].request_iduuid or null · required
data[].ratinginteger or null · required
data[].textstring or null · required
data[].contactobject · required
data[].contact.namestring or null · required
data[].statusnew | in_progress | resolved · required
data[].created_atstring (date-time) · required
next_cursorstring or null · required: Pass as cursor for the next page; null when there is none.

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
404not_found: nothing with this id for this key
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

Stats

GET`/v1/stats`

Numbers for a range of daysScope read

One location or every location the key sees, in the account's time zone, as Analytics counts them.

Parameters

location_idquery · uuid: Only this location; every location the key sees otherwise.
fromquery · string (date): First day (YYYY-MM-DD, in the account's time zone, inclusive), default 30 days ago; at most 366 days before to.
toquery · string (date): Last day (inclusive), default today.

curlJavaScriptPython

JavaScript

const res = await fetch("https://api.citypicked.com/v1/stats?from=2026-10-10&to=2026-11-08", {
  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/stats",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx"},
    params={
        "from": "2026-10-10",
        "to": "2026-11-08",
    },
)
print(res.status_code, res.json())

Answer 200

{
  "location_id": "5b1d0c7e-2f4a-4c3e-9a51-7d2e8f1b6a40",
  "from": "2026-10-10",
  "to": "2026-11-08",
  "requests_sent": 120,
  "clicked": 64,
  "rated": 41,
  "average_rating": 4.6,
  "public_clicks": 33,
  "feedback": 8
}

Answer fields

location_iduuid or null · required
fromstring (date) · required
tostring (date) · required
requests_sentinteger · required
clickedinteger · required: Requests whose link was opened.
ratedinteger · required: Requests that got stars.
average_ratingnumber or null · required: All stars of the days, as Analytics shows them (with QR code and direct link guests).
public_clicksinteger · required: Requests that went on to a review site.
feedbackinteger · required: Private feedback received.

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
404not_found: nothing with this id for this key
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

Webhooks

GET`/v1/webhooks`

The webhooks this key madeScope read

Newest first by created_at. Pass next_cursor as cursor for the next page; null means there is none. Polling triggers dedupe by id and filter with since. Without secret: it is shown only when a webhook is made.

Parameters

limitquery · string: 1 to 100, default 25.
cursorquery · string: next_cursor of the previous answer.

curlJavaScriptPython

JavaScript

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

Answer 200

{
  "data": [
    {
      "id": "7a5c3e1b-9d2f-4b6a-8c4e-3f1a5c7e9b30",
      "url": "https://example.com/hooks/citypicked",
      "events": [
        "feedback.created",
        "request.rated"
      ],
      "status": "active",
      "disabled_reason": null,
      "created_at": "2026-11-08T09:30:00Z",
      "last_success_at": "2026-11-08T09:30:04Z",
      "last_failure_at": null
    }
  ],
  "next_cursor": null
}

Answer fields

dataarray of object · required
data[].iduuid · required
data[].urlstring · required
data[].eventsarray of (feedback.created | request.rated | request.public_click | request.sent | request.failed) · required
data[].statusactive | disabled · required
data[].disabled_reasonfailing | gone | key_revoked or null · required: failing: deliveries kept failing; gone: the URL answered 410; key_revoked: the key that made it stopped.
data[].created_atstring (date-time) · required
data[].last_success_atstring (date-time) or null · required
data[].last_failure_atstring (date-time) or null · required
next_cursorstring or null · required: Pass as cursor for the next page; null when there is none.

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

POST`/v1/webhooks`

Subscribe a URL to events (REST hook)Scope send

The URL gets each chosen event as a signed POST (see webhooks). https with a host name that resolves to public addresses only, checked now and before every delivery. The answer carries the signing secret, once. At most 50 webhooks per account. A webhook belongs to this key: it gets the events of the locations the key can see, and it stops when the key is revoked.

Body

urlstring · required: https, a host name (no IP address, no user:password), at most 2000 characters, resolving to public addresses only.
eventsarray of (feedback.created | request.rated | request.public_click | request.sent | request.failed) · required: The events this URL gets.

curlJavaScriptPython

curl

curl -X POST "https://api.citypicked.com/v1/webhooks" \
  -H "Authorization: Bearer cp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/citypicked",
  "events": [
    "feedback.created",
    "request.rated"
  ]
}'

JavaScript

const res = await fetch("https://api.citypicked.com/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: "Bearer cp_live_xxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://example.com/hooks/citypicked",
    "events": [
      "feedback.created",
      "request.rated"
    ]
  }),
});
const data = await res.json();
console.log(res.status, data);

Python

import requests

res = requests.post(
    "https://api.citypicked.com/v1/webhooks",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx"},
    json={
        "url": "https://example.com/hooks/citypicked",
        "events": [
            "feedback.created",
            "request.rated",
        ],
    },
)
print(res.status_code, res.json())

Answer 201

{
  "id": "7a5c3e1b-9d2f-4b6a-8c4e-3f1a5c7e9b30",
  "url": "https://example.com/hooks/citypicked",
  "events": [
    "feedback.created",
    "request.rated"
  ],
  "status": "active",
  "disabled_reason": null,
  "created_at": "2026-11-08T09:30:00Z",
  "last_success_at": null,
  "last_failure_at": null,
  "secret": "cpwh_xxxxxxxx"
}

Answer fields

iduuid · required
urlstring · required
eventsarray of (feedback.created | request.rated | request.public_click | request.sent | request.failed) · required
statusactive | disabled · required
disabled_reasonfailing | gone | key_revoked or null · required: failing: deliveries kept failing; gone: the URL answered 410; key_revoked: the key that made it stopped.
created_atstring (date-time) · required
last_success_atstring (date-time) or null · required
last_failure_atstring (date-time) or null · required
secretstring · required: cpwh_...: signs every delivery (Citypicked-Signature). Shown only in this answer.

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

GET`/v1/webhooks/{id}`

One webhook of this keyScope read

Parameters

idpath · uuid · required

curlJavaScriptPython

JavaScript

const res = await fetch("https://api.citypicked.com/v1/webhooks/7a5c3e1b-9d2f-4b6a-8c4e-3f1a5c7e9b30", {
  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/webhooks/7a5c3e1b-9d2f-4b6a-8c4e-3f1a5c7e9b30",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx"},
)
print(res.status_code, res.json())

Answer 200

{
  "id": "7a5c3e1b-9d2f-4b6a-8c4e-3f1a5c7e9b30",
  "url": "https://example.com/hooks/citypicked",
  "events": [
    "feedback.created",
    "request.rated"
  ],
  "status": "active",
  "disabled_reason": null,
  "created_at": "2026-11-08T09:30:00Z",
  "last_success_at": "2026-11-08T09:30:04Z",
  "last_failure_at": null
}

Answer fields

iduuid · required
urlstring · required
eventsarray of (feedback.created | request.rated | request.public_click | request.sent | request.failed) · required
statusactive | disabled · required
disabled_reasonfailing | gone | key_revoked or null · required: failing: deliveries kept failing; gone: the URL answered 410; key_revoked: the key that made it stopped.
created_atstring (date-time) · required
last_success_atstring (date-time) or null · required
last_failure_atstring (date-time) or null · required

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
404not_found: nothing with this id for this key
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

DELETE`/v1/webhooks/{id}`

Unsubscribe: remove a webhook of this keyScope send

Nothing is delivered to it afterwards.

Parameters

idpath · uuid · required

curlJavaScriptPython

JavaScript

const res = await fetch("https://api.citypicked.com/v1/webhooks/7a5c3e1b-9d2f-4b6a-8c4e-3f1a5c7e9b30", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer cp_live_xxxxxxxx",
  },
});
const data = await res.json();
console.log(res.status, data);

Python

import requests

res = requests.delete(
    "https://api.citypicked.com/v1/webhooks/7a5c3e1b-9d2f-4b6a-8c4e-3f1a5c7e9b30",
    headers={"Authorization": "Bearer cp_live_xxxxxxxx"},
)
print(res.status_code, res.json())

Answer 200

{
  "id": "7a5c3e1b-9d2f-4b6a-8c4e-3f1a5c7e9b30",
  "deleted": true
}

Answer fields

iduuid · required
deletedtrue · required

Errors

400invalid_request: the query or body is not valid (field names the wrong one), or the webhook URL is not a public https address
401unauthorized: no API key, or the key does not work (revoked, or its member can no longer use it)
403forbidden (scope missing, plan without API sending) or account_closed
404not_found: nothing with this id for this key
429rate_limited: wait for Retry-After seconds
500server_error: something went wrong on our side

OpenAPI document

GET`/v1/openapi.json`

This documentNo key needed

curlJavaScriptPython

Answer 200

{
  "openapi": "3.1.0",
  "info": {
    "title": "Citypicked API",
    "version": "..."
  },
  "paths": "..."
}

The whole document is OpenAPI 3.1, including the events under webhooks. Import it into Postman, Insomnia or a code generator.

API reference

Account

GET/v1/me

Errors

Locations

GET/v1/locations

Parameters

Errors

GET/v1/locations/{id}/review-link

Parameters

Errors

Requests

GET/v1/requests

Parameters

Errors

POST/v1/requests

Parameters

Body

Errors

POST/v1/requests/{id}/cancel

Parameters

Errors

GET/v1/requests/{id}

Parameters

Errors

Feedback

GET/v1/feedback

Parameters

Errors

Stats

GET/v1/stats

Parameters

Errors

Webhooks

GET/v1/webhooks

Parameters

Errors

POST/v1/webhooks

Body

Errors

GET/v1/webhooks/{id}

Parameters

Errors

DELETE/v1/webhooks/{id}

Parameters

Errors

OpenAPI document

GET/v1/openapi.json

GET/v1/me

Errors

Locations

GET/v1/locations

Parameters

Errors

GET/v1/locations/{id}/review-link

Parameters

Errors

Requests

GET/v1/requests

Parameters

Errors

POST/v1/requests

Parameters

Body

Errors

POST/v1/requests/{id}/cancel

Parameters

Errors

GET/v1/requests/{id}

Parameters

Errors

Feedback

GET/v1/feedback

Parameters

Errors

Stats

GET/v1/stats

Parameters

Errors

Webhooks

GET`/v1/me`

GET`/v1/locations`

GET`/v1/locations/{id}/review-link`

GET`/v1/requests`

POST`/v1/requests`

POST`/v1/requests/{id}/cancel`

GET`/v1/requests/{id}`

GET`/v1/feedback`

GET`/v1/stats`

GET`/v1/webhooks`

POST`/v1/webhooks`

GET`/v1/webhooks/{id}`

DELETE`/v1/webhooks/{id}`

GET`/v1/openapi.json`

GET`/v1/me`

GET`/v1/locations`

GET`/v1/locations/{id}/review-link`

GET`/v1/requests`

POST`/v1/requests`

POST`/v1/requests/{id}/cancel`

GET`/v1/requests/{id}`

GET`/v1/feedback`

GET`/v1/stats`

GET`/v1/webhooks`

POST`/v1/webhooks`

GET`/v1/webhooks/{id}`

DELETE`/v1/webhooks/{id}`

GET`/v1/openapi.json`