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.

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.

Requests are always started by your system: you ask Piyzi, Piyzi answers. Piyzi does not call your system on its own when something changes, so when you need current information you have to query the relevant endpoint again.

Prerequisites

• A Piyzi account with an active subscription.

• Pi Store edit permission, or being the workspace owner — required to enable the module.

• Manage Piyzi API keys permission — required to create, rotate and delete keys. A user with view-only permission can open the page but cannot issue keys.

• A fixed outbound IP address on the server that will send the requests. The key's IP list is mandatory.

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

Enabling the module

1. In the left menu, open My Business → Pi Store.

2. Under Custom Modules, click the Piyzi API card.

3. In the dialog that opens, click “Activate”.

4. The Developer Tools page appears in the My Business menu.

Creating an API key

1. Open My Business → Developer Tools.

2. On the API Keys tab, click “Create Key”.

3. Give the key a name that says where it will be used (for example “Website Form”).

4. Enter the allowed IP addresses; at least one address is required.

5. Save. The key is shown on screen once — copy it and store it somewhere safe.

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 IP list is mandatory and cannot be left empty. A key accepts at most 20 addresses.

• 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 error message 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.

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, 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, and an oversized body returns 413; slow down 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 error code list and cURL / JavaScript / PHP / Python samples for every endpoint. You can download the Postman collection from 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.

• Phone numbers written as 05xx, 5xx or starting with +90 are all accepted and normalised to a single format.

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

• If automatic approval of online appointments is enabled in your appointment settings, the appointment arrives approved; if not, it lands in the Pending Approvals list.

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

• 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.

Rotating, disabling and deleting a key

• Rotating: a new key is generated and shown once; the old key becomes invalid at the same moment. This is the first thing to do if you suspect the key has leaked.

• Disabling: switching a key off in the list makes requests fail immediately. The key is not deleted; you can switch it back on whenever you like.

• Deleting: the key is removed and requests made with it stop instantly.

• Editing: you can update a key's name and IP list at any time; the key itself does not change.

• The list shows each key's last usage date — that is how you tell which key is actually in use.

Turning the module off

1. Open My Business → Pi Store.

2. Click the Piyzi API card.

3. Click “Deactivate”.

• 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.

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 error 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 error code tells you which one filled up.

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

• Appointments do not show up: if the request succeeds, the appointment is most likely in the Pending Approvals list; 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.