Piyzi API: connecting your own system to Piyzi

The Piyzi API lets you connect your own website, form or another piece of software to Piyzi: requests coming from outside turn into customer records and appointments inside Piyzi. You enable the module from Pi Store, create an API key on the Developer Tools page, and hand that key to whoever builds your system. All of this is done in the web panel only.

What it is for

• Turning someone who fills in the booking or contact form on your website into a customer record, with no manual re-typing.

• Querying your service list and a staff member's free time slots on a given day from outside Piyzi.

• Creating an appointment in a single request: the customer is matched by phone number or created, and the appointment and sales card are opened in Piyzi.

• Reading your customer source (where they came from) and tag definitions, and adding new ones when needed.

• Fetching country, city and district lists for address fields.

• WhatsApp: listing approved message templates, sending with a template (including templates with an image, video or PDF header and templates with named variables) or (while the 24-hour reply window is open) with free text, scheduling for a future date, cancelling a scheduled send and downloading message attachments (when the WhatsApp Business integration is connected).

• Webhooks: receiving incoming WhatsApp messages, outgoing messages and failed scheduled sends as real-time event notifications in your own system — you can build your own inbox.

Traffic can flow both ways: you call the endpoints and Piyzi answers; if you define a webhook, incoming and outgoing WhatsApp messages are also delivered to your system in real time.

Prerequisites

• A Piyzi account with an active subscription.

• To turn the module on or off, the Entegrasyonları yapabilir (manage integrations) permission in your role (the business owner can always do this).

• To see the Developer Tools page, the Piyzi API anahtarlarını ve geliştirici araçlarını görebilir (view Piyzi API keys and developer tools) permission; to create, edit, rotate and delete keys and the webhook, the Piyzi API anahtarlarını yönetebilir (oluşturma/silme/yenileme) (manage Piyzi API keys) permission. A user with view-only permission sees the buttons, but the action is rejected with “You don't have permission to do this.”

• A fixed outbound IP address on the server that will send the requests (recommended). For infrastructures that cannot provide a fixed IP there is a per-key option to use the key without an IP restriction (below).

• A developer to write the requests. The key is used on your server only, never in the browser.

Enabling the module

1. 1

   Open the Piyzi API window

   In the left menu, open My Business → Pi Store and click the Piyzi API card under the Special Modules heading.

2. 2

   Activate it

   Click Activate in the window. Because the page reloads straight away, you may not see a separate success message; you can tell the module is on from the Connected badge on the card.

3. 3

   Go to Developer Tools

   Developer Tools appears under My Business in the left menu. When you open the Piyzi API window again, the Go to Developer Tools button also takes you there.

Creating an API key

1. 1

   Open the new key window

   Open My Business → Developer Tools. On the API Keys tab, click Create Key at the top right (if there are no keys yet, you can also use the same button in the middle). The New API Key window opens.

2. 2

   Name it

   In Key Name, type a name that says where the key will be used (for example “Website Form”); the name must be 2–60 characters.

3. 3

   Choose the IP restriction

   Under IP restriction, Restrict to an IP list (recommended) is selected by default. Type your server's outbound IP address into Allowed IP Addresses; click Add IP to add another one. If you cannot provide a fixed outbound IP, select Use without IP restriction (for serverless infrastructures) and tick “I understand the risk; use this key without IP restriction.”; no IP list is needed in that mode.

4. 4

   Create it and copy the key

   Click Create. The Your API Key Is Ready window opens: copy the key with the copy icon next to it, store it somewhere safe, then click I've Copied It, Close.

• “The key name must be at least 2 characters.”: the name is too short.

• “You must enter at least one IP address.” or “You must enter at least one valid IP address.”: in IP list mode there is no address, or its format is invalid (write it like 203.0.113.10).

• “Confirm that you understand the risk to continue.”: use without IP restriction is selected but the confirmation box is not ticked.

• “The API key limit has been reached (at most 5 keys).”: delete a key you no longer use and try again.

A business can hold at most 5 keys. Creating a separate key per system is a good habit: if one leaks, you only rotate that key and your other integrations keep working.

The IP allowlist — your second line of defence

The key proves identity; the IP list limits where the key may be used from. Even if the key ends up in the wrong hands, a request from a server that is not on the list is rejected.

• The default mode is the IP list; a key can have at most 20 addresses.

• For infrastructures that cannot provide a fixed egress IP (such as Cloudflare Workers, Vercel, AWS Lambda) there is a per-key “Use without IP restriction” mode. It is selected with a risk confirmation box while creating or editing the key and shows a “No IP restriction” badge in the list. Rate limits and brute-force protection remain fully active in this mode.

• Add your server's outbound (egress) IP address — not the visitor's and not your office's.

• A request from an address that is not listed returns 403 IP_NOT_ALLOWED, and the message in the response states which IP was seen; this is how you can find your server's real outbound address.

• If your server's IP changes (new hosting, new server), update the list; you do not need to rotate the key.

Rotating, disabling and deleting a key

In the key list, each key shows its name, first characters, allowed IPs, the Last Used and Active columns, and at the end of the row the edit (pencil), Regenerate Key (circular arrows) and Delete (bin) icons.

• Rotating: click the Regenerate Key icon and confirm “Regenerate the key?” with Yes, Regenerate. The new key is shown once in the Your API Key Is Ready window; the old key becomes invalid at the same moment. Rotating a disabled key switches it back on. This is the first thing to do if you suspect the key has leaked.

• Disabling: switching a key off in the Active column makes requests with it fail immediately. The key is not deleted; when you switch it back on it works with the same value.

• Deleting: click the bin and confirm “Delete the key?” with Yes, Delete; the key is removed and requests made with it stop instantly. A deleted key cannot be brought back and no longer counts towards the 5-key limit.

• Editing: the pencil opens the Edit Key window; change the name, the IP list or the IP restriction mode and click Save. The key's value does not change.

• The Last Used column shows when a request with the key was last accepted; it is not an expiry date, and keys do not expire. A key that has never been used shows “-”. That is how you tell which key is actually in use.

Receiving events with a webhook

On the Developer Tools page, the Webhook tab lets you register an HTTPS address; Piyzi delivers WhatsApp message events to that address as signed POST requests. This way you can build your business inbox in your own software and reply to customers from your own screen (free text while the reply window is open, approved templates at any time). A business can define one webhook.

1. 1

   Have the endpoint prepared

   Your developer prepares an endpoint following the Webhooks page of the Documentation tab. While you register it, Piyzi sends this address a GET request carrying a challenge parameter; the endpoint must answer with a 2xx status code and echo the challenge value back exactly, as plain text.

2. 2

   Register the address

   On the Webhook tab, click Define Webhook. Type a public HTTPS address into Webhook URL (port 443; IP addresses and private network addresses are not accepted). Under Events to send, Incoming message, Outgoing message and Failed delivery are all ticked by default; untick the ones you do not want (at least one must stay ticked), then click Save. If verification succeeds, “Webhook created and verified.” appears; if the endpoint is not ready, the registration does not complete.

3. 3

   Store the signing key

   The Your webhook signing key window shows the key only once. Copy it, hand it to your developer over a secure channel, then click I saved the key, close. Your developer verifies the X-Piyzi-Signature header of every request with this key (HMAC-SHA256).

4. 4

   Test and monitor

   Send a sample event with Send Test; the result appears under the card. Follow deliveries in the Recent Deliveries table; each delivery shows its time, event, attempt number, result and duration there.

• Edit changes the address or the events; if the address changes, it is verified again.

• Pause stops delivery; Activate verifies the address again and resumes delivery. Events that happen while the webhook is paused or stopped are not sent later.

• Regenerate Key changes the signing key; the old key becomes invalid immediately and the new one is shown once.

• Delete stops event delivery; the delivery history is cleared automatically within 14 days.

• A failed delivery is attempted at most 5 times; the order of events is not guaranteed.

Technical summary for your developer

Base URL and authentication

• Base URL: https://api.piyzi.com/api/v1

• Authentication: an X-Api-Key header on every request (X-Api-Key: pyz_live_…). Authorization: Bearer pyz_live_… is also accepted.

• Response envelope: on success { "success": true, "data": … }, on failure { "success": false, "error": { "code", "message" } }.

• This surface is separate and isolated from the API behind the Piyzi dashboard: the dashboard's session token (JWT) is not valid here, the API key is the only credential. The reverse holds too — an API key cannot reach dashboard endpoints.

Resources are addressed by uid

Database identifiers are never exposed. Services, staff, customers, appointments, customer sources and locations are all carried by their uid field: serviceUid, staffUid, customerUid, appointmentUid, sourceUid, countryUid, cityUid, districtUid. Tags are carried by their title instead of a uid. Do not invent an identifier or copy one from elsewhere; read it from the matching list endpoint.

Limits

• 120 requests per minute per key.

• Write (POST) endpoints have an extra limit: 30 per minute and 2,000 per day.

• Failed key attempts: 20 per minute per IP.

• The request body may be at most 200 KB.

• Exceeding a limit returns 429, an oversized body returns 413, and a body that is not valid JSON returns 400 INVALID_JSON; slow down or fix the body and retry.

Where the endpoint list and code samples live

The full reference is inside the app: My Business → Developer Tools → Documentation. It carries parameter tables, sample responses, the list of codes the endpoints can return and cURL / JavaScript / PHP / Python samples for every endpoint. You can download the Postman collection with the Download Postman Collection button on the same page.

• Connection test: GET /me — returns which business the key belongs to.

• Definitions: customer sources, tags and country / city / district lists.

• Booking flow: services, free slots, creating a customer and creating an appointment.

What happens when an appointment is created through the API

• The customer is matched by phone number: an existing record is reused, otherwise a new customer is created. That way the form does not produce duplicates every time it is submitted.

• Only Turkish mobile numbers (10 digits starting with 5) are accepted; numbers written as 05xx, 5xx or starting with 90 or +90 are normalised to a single format. An invalid number returns 400 INVALID_PHONE.

• The appointment is created in the “Pending” state and its source is marked as API.

• If “Auto-approve Online Bookings” is on under My Business → Settings → Appointment Settings, the appointment arrives approved; if not, it lands on the Appointment Requests tab of the Pending Approvals panel in the top bar.

• The customer's open sales card for that day is reused for the appointment; if there is none, a new sales card is opened.

• Piyzi does not send the customer an SMS for this appointment on its own. If you want to notify them, set up an automation with the “When an Appointment Is Created” trigger; it also runs for appointments created through the API. The “When a New Customer Registers” automation does not run for customers created through the API.

• If the chosen time was taken in the meantime, the request is rejected with 409 TIME_SLOT_CONFLICT; fresh slots must be fetched and the request retried. A time in the past is rejected with 400 DATE_IN_PAST.

Turning the module off

1. 1

   Open the Piyzi API window

   On the My Business → Pi Store page, click the Piyzi API card.

2. 2

   Deactivate it

   Click Deactivate and confirm “Disable the Piyzi API?” with Yes, Disable.

• All API requests are rejected with 403 INTEGRATION_DISABLED.

• The Developer Tools page disappears from the menu.

• Your keys are not deleted; when you enable the module again the same keys keep working.

• Customers and appointments already created through the API stay in Piyzi exactly as they are.

• A defined webhook does not stop when you turn the module off. If you also want to stop event delivery, pause the webhook with Pause or delete it on the Webhook tab before turning the module off.

Troubleshooting

• 401 MISSING_API_KEY: the request was sent without the key header, or the value sent is not shaped like a Piyzi key.

• 401 INVALID_API_KEY: the key is wrong, deleted, disabled, or stale because it was rotated.

• 403 IP_NOT_ALLOWED: the IP the request came from is not on the key's list. Add the address from the response message to the list.

• 403 INTEGRATION_DISABLED: the Piyzi API module is off in Pi Store; enable it.

• A 429 was returned: a limit was hit. The general request, per-minute write, daily write and failed-key-attempt limits are counted separately; the code field in the response tells you which one filled up.

• 404 NOT_FOUND: the URL is misspelled. The list of valid endpoints is on the Documentation tab.

• The webhook cannot be saved: “Webhook verification failed” means the endpoint did not answer the GET request with 2xx and echo the challenge value exactly; “Webhook URL is invalid” means the address is not a public HTTPS address.

• Appointments do not show up: if the request succeeds, the appointment is most likely on the Appointment Requests tab of the Pending Approvals panel; approve it there when automatic approval is off.

• The same person was recorded twice: matching is done by phone number, so the two records were created with different numbers.