{"openapi":"3.0.3","info":{"title":"Lynxbe Public API","version":"2c9d4bdbb018","description":"The Lynxbe platform public API. Authenticate with a business API key (lxb_...) in the X-API-Key header, or as a Bearer token. Create keys in the Lynxbe app: API Docs page (/automation/api-docs), API Keys tab. Full reference: https://lynxbe.co.il/api-reference Rate limits: Each API key may make 600 requests a minute by default; hourly and daily caps apply only when set on the key. All keys of one business together may make 60,000 requests a minute. AI requests may also run 40 a minute and 1,500 an hour per key, exports 30 a minute and bulk sends 10 a minute. Over a limit the API answers 429 with a Retry-After header, the limit and reset_in_seconds (the seconds until the window opens again). The public docs and openapi.json allow 60 requests a minute per IP. This copy lists the open categories only. Send your API key as Authorization: Bearer <key> for the full document."},"servers":[{"url":"https://api.lynxbe.co.il/api/v1"}],"tags":[{"name":"Booking","description":"Appointment scheduling, availability checks, and booking management."},{"name":"Customers (CRM)","description":"Customer management, contacts, and CRM operations."},{"name":"CRM Boards","description":"CRM boards, items, pipelines, and automation."},{"name":"Account","description":"Account and API key information endpoints."}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"paths":{"/bookings":{"get":{"operationId":"booking_list","summary":"List Bookings","description":"The business's bookings, earliest first. With no from / to it starts today. Filter by status, dates, employee, service or customer phone; page with limit / offset (pagination.total is the full count). Requires the booking module on the plan.\n\nRequired API key scope: `read:bookings`.","tags":["Booking"],"parameters":[{"name":"from","in":"query","description":"First day (YYYY-MM-DD). Default today, Israel time, when neither from nor to is given","schema":{"type":"string","example":"2026-10-01"}},{"name":"to","in":"query","description":"Last day (YYYY-MM-DD)","schema":{"type":"string","example":"2026-10-31"}},{"name":"status","in":"query","description":"One of: booking_request, pending_approval, pending, confirmed, awaiting_attendance_confirmation, attendance_confirmed, attendance_not_confirmed, arrived, in_service, completed, no_show, change_requested, cancellation_requested, cancelled, late_cancellation, consult_no_deal","schema":{"type":"string","example":"confirmed"}},{"name":"employee_id","in":"query","description":"Only this employee's bookings","schema":{"type":"integer","example":601}},{"name":"service_id","in":"query","description":"Only this service","schema":{"type":"integer","example":501}},{"name":"customer_phone","in":"query","description":"Customer phone in any form (0501234567, +972501234567, 972-50-123-4567): matched by its digits in 972 form","schema":{"type":"string","example":"0501234567"}},{"name":"limit","in":"query","description":"Page size (1-100, default 20; larger is clamped to 100)","schema":{"type":"integer","example":20}},{"name":"offset","in":"query","description":"Rows to skip (default 0)","schema":{"type":"integer","example":0}}],"responses":{"200":{"description":"Bookings","content":{"application/json":{"example":{"success":true,"data":[{"id":9001,"service_id":501,"employee_id":601,"customer_name":"Dana Levi","customer_phone":"0501234567","customer_email":"dana@example.com","booking_date":"2026-10-20T00:00:00.000Z","start_time":"10:00:00","end_time":"11:00:00","status":"confirmed"}],"pagination":{"limit":20,"offset":0,"total":1}}}}},"400":{"description":"A filter in the wrong shape (INVALID_INPUT, with field)"},"403":{"description":"Booking is not on the plan (MODULE_LOCKED)"}},"x-required-scope":"read:bookings"},"post":{"operationId":"booking_create","summary":"Create Booking","description":"Book a slot for a customer, e.g. from your own booking widget. Staff-blocked time and a slot already booked for the employee are refused; a group service (capacity above 1) takes bookings until its seats are full. Two simultaneous create calls for one slot never both succeed. Fires booking.created. Requires the booking module on the plan.\n\nRequired API key scope: `write:bookings`.","tags":["Booking"],"requestBody":{"description":"Booking details. At least one of customer_name, customer_phone or customer_email.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_name":{"type":"string","description":"Customer name","example":"Dana Levi"},"customer_phone":{"type":"string","description":"Customer phone","example":"0501234567"},"customer_email":{"type":"string","description":"Customer email","example":"dana@example.com"},"booking_date":{"type":"string","description":"Date (YYYY-MM-DD); default today, Israel time","example":"2026-10-20"},"start_time":{"type":"string","description":"Start time (HH:MM)","example":"10:00"},"end_time":{"type":"string","description":"End time (HH:MM); default one hour after start","example":"11:00"},"service_id":{"type":"integer","description":"One of your services (GET /api/v1/services)","example":501},"employee_id":{"type":"integer","description":"One of your employees","example":601},"party_size":{"type":"integer","description":"Seats to book (default 1). Above 1 only for a group service, up to its capacity","example":2},"notify_customer":{"type":"boolean","description":"true = send the customer the booking confirmation the business sends from its booking page (its own WhatsApp number and approved templates, or email), to the phone / email in this request - only when the business has confirmations on. Needs customer_name and a phone or email. Default false: nothing is sent, e.g. when your widget confirms the booking itself","example":false}},"required":["start_time"]}}}},"responses":{"201":{"description":"Booking created. notification: not_requested (notify_customer not true), sent (a confirmation went out), pending (still sending after 8 seconds; the booking is saved, do not retry it), or not_sent (asked, but nothing went out: confirmations off, no WhatsApp account or template, no phone / email, or the send was refused)","content":{"application/json":{"example":{"success":true,"data":{"id":9001,"booking_date":"2026-10-20T00:00:00.000Z","start_time":"10:00:00","end_time":"11:00:00","status":"confirmed","party_size":1,"customer_id":77,"notification":"not_requested"}}}}},"400":{"description":"Missing customer or start_time; a date, time or email in the wrong shape or end_time not after start_time (INVALID_INPUT); service_id is not one of your active services, or employee_id is not one of your employees - active or not (INVALID_REFERENCE); party_size not a whole number of at least 1 (INVALID_PARTY_SIZE) or above the service capacity (PARTY_SIZE_ABOVE_CAPACITY); notify_customer not a boolean; with notify_customer, customer_phone not a phone number or no customer_name (INVALID_INPUT)"},"403":{"description":"Booking is not on the plan (MODULE_LOCKED)"},"409":{"description":"The slot is blocked by staff; already booked for this employee (BOOKING_CONFLICT); or the class has no room (SLOT_FULL / NOT_ENOUGH_SEATS, with capacity and seats_remaining)","content":{"application/json":{"example":{"success":false,"error":"This session is full","code":"SLOT_FULL","capacity":3,"seats_remaining":0}}}},"503":{"description":"The plan could not be checked; try again (PLAN_CHECK_FAILED)"}},"x-required-scope":"write:bookings"}},"/bookings/{id}":{"get":{"operationId":"booking_get","summary":"Get Booking","description":"One booking of your business, with the service and employee names. Requires the booking module on the plan.\n\nRequired API key scope: `read:bookings`.","tags":["Booking"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking id","schema":{"type":"integer","example":9001}}],"responses":{"200":{"description":"The booking","content":{"application/json":{"example":{"success":true,"data":{"id":9001,"service_id":501,"employee_id":601,"customer_name":"Dana Levi","customer_phone":"0501234567","customer_email":"dana@example.com","booking_date":"2026-10-20T00:00:00.000Z","start_time":"10:00:00","end_time":"11:00:00","status":"confirmed","service_name":"Haircut","employee_name":"Noa Cohen","notes":null,"cancellation_reason":null,"created_at":"2026-10-13T09:00:00.000Z","updated_at":"2026-10-13T09:00:00.000Z"}}}}},"403":{"description":"Booking is not on the plan (MODULE_LOCKED)"},"404":{"description":"No booking with this id in your business"}},"x-required-scope":"read:bookings"},"patch":{"operationId":"booking_update","summary":"Update Booking","description":"Change a booking's notes and customer details (name, phone, email). Send only the fields to change; null or an empty string clears one. The slot, status, employee and service are not changed here - a move is Reschedule Booking, a cancellation is Cancel Appointment - and naming one of them, or any other field, is refused rather than ignored. A change may not leave the booking with no name, phone or email. A new phone moves the booking to the customer card of your business that already holds it (when only the email changes, the card that holds the new email); no such card, or details cleared, keeps the current card, and no card is created or renamed. customer_relinked says whether it moved. Works on a booking in any status (a note after the visit). Only fields that really change are saved (a phone in another format or an email in other letter case is the same value); fires booking.updated. The customer is not messaged.\n\nRequired API key scope: `write:bookings`.","tags":["Booking"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking ID","schema":{"type":"integer","example":9001}}],"requestBody":{"description":"The fields to change","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","description":"Notes on the booking (up to 5000 characters); null clears them","example":"Bring the X-ray"},"customer_name":{"type":"string","description":"Customer name (up to 255 characters)","example":"Dana Levi"},"customer_phone":{"type":"string","description":"Customer phone, 9-15 digits with an optional +; spaces, dashes and brackets are removed","example":"+972525550101"},"customer_email":{"type":"string","description":"Customer email; a new one is stored in lower case","example":"dana@example.com"}}}}}},"responses":{"200":{"description":"Saved; changed lists the fields that really changed (empty when the values were already the same)","content":{"application/json":{"example":{"success":true,"data":{"id":9001,"status":"confirmed","booking_date":"2026-10-20","start_time":"10:00:00","end_time":"11:00:00","notes":"Bring the X-ray","customer_name":"Dana Levi","customer_phone":"+972525550101","customer_email":"dana@example.com","customer_id":88,"customer_relinked":false,"changed":["customer_name","notes"]}}}}},"400":{"description":"No field to change (INVALID_INPUT); a value that is not valid (INVALID_INPUT, field names it); a field changed by another endpoint - status, booking_date, start_time, end_time, employee_id, service_id (FIELD_NOT_EDITABLE); an unknown field (UNKNOWN_FIELD); or the change would leave no name, phone or email (CONTACT_REQUIRED)"},"403":{"description":"Booking is not on the plan (MODULE_LOCKED)"},"404":{"description":"No booking with this id in your business"},"500":{"description":"The booking could not be updated; nothing was saved"},"503":{"description":"The plan check is temporarily unavailable (PLAN_CHECK_FAILED); retry"}},"x-required-scope":"write:bookings"}},"/availability":{"get":{"operationId":"booking_availability","summary":"Check Availability","description":"Get free time slots for a date, computed from business hours minus existing bookings and blocked slots. Calendar-sync busy times are validated at booking time.\n\nRequired API key scope: `read:bookings`.","tags":["Booking"],"parameters":[{"name":"date","in":"query","required":true,"description":"Date to check (YYYY-MM-DD)","schema":{"type":"string","example":"2026-01-15"}},{"name":"service_id","in":"query","description":"Service ID — slot length uses the service duration (default 60 minutes)","schema":{"type":"string"}},{"name":"employee_id","in":"query","description":"Specific employee (optional)","schema":{"type":"string"}}],"responses":{"200":{"description":"Available time slots","content":{"application/json":{"example":{"success":true,"data":{"date":"2026-01-15","slots":[{"start_time":"09:00","end_time":"10:00"}]}}}}}},"x-required-scope":"read:bookings"}},"/booking/staff":{"get":{"operationId":"booking_staff_list","summary":"List Booking Staff","description":"Who the app would book: the active staff of your business, by name. With service_id, only the staff allowed to perform that service, each with the length and price that person charges for it (their own setting, else the service's; a service with no length set counts 30 minutes, as the app books it). The public create and GET /api/v1/availability do not apply a person's own length: they use the service's length (60 minutes when it has none), so pass end_time to book a person's length - a slot GET /api/v1/availability shows can then still answer 409 BOOKING_CONFLICT if the longer booking does not fit. The create accepts any employee id of your business, inactive ones included, so pick from this list. Names only - no phone, email or pay. Requires the booking module on the plan.\n\nRequired API key scope: `read:bookings`.","tags":["Booking"],"parameters":[{"name":"service_id","in":"query","description":"Only staff who perform this service (an id from GET /api/v1/services)","schema":{"type":"integer","example":501}}],"responses":{"200":{"description":"data.staff; with service_id also data.service and each person's duration / price (without it data.service is null)","content":{"application/json":{"example":{"success":true,"data":{"service":{"id":501,"name":"Colour","duration_minutes":60,"price":"300.00"},"staff":[{"id":601,"name":"Avi Levi","branch_id":null,"duration_minutes":90,"price":"450.00"},{"id":602,"name":"Dana Cohen","branch_id":null,"duration_minutes":60,"price":"300.00"}]}}}}},"400":{"description":"service_id is not a positive integer (INVALID_SERVICE_ID)"},"401":{"description":"Unauthorized - invalid or missing API key"},"403":{"description":"Booking is not on the plan (MODULE_LOCKED), or the key has no read:bookings (\"Insufficient scope. Required: read:bookings\")"},"404":{"description":"No active service with this id in your business (SERVICE_NOT_FOUND)"},"500":{"description":"Failed to list staff (reported to us; retry)"}},"x-required-scope":"read:bookings"}},"/bookings/{id}/reschedule":{"post":{"operationId":"booking_reschedule","summary":"Reschedule Booking","description":"Move a booking to another date or time. The same checks as a new booking: staff-blocked time and a slot already booked for the employee are refused, a class takes the move only while it has seats, and two simultaneous API calls for one slot never both succeed. The employee and service stay. Only a booking still ahead can move (not arrived, in service, cancelled, completed or a no-show). Reminders are re-sent for the new time; fires booking.rescheduled with rescheduled_by \"api\". The customer is not messaged.\n\nRequired API key scope: `write:bookings`.","tags":["Booking"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking ID","schema":{"type":"integer","example":9001}}],"requestBody":{"description":"The new slot","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"booking_date":{"type":"string","description":"New date (YYYY-MM-DD)","example":"2026-10-21"},"start_time":{"type":"string","description":"New start time (HH:MM)","example":"12:00"},"end_time":{"type":"string","description":"New end time (HH:MM); default keeps the booking's length","example":"13:00"}},"required":["booking_date","start_time"]}}}},"responses":{"200":{"description":"Booking moved; previous is where it was","content":{"application/json":{"example":{"success":true,"data":{"id":9001,"booking_date":"2026-10-21","start_time":"12:00:00","end_time":"13:00:00","status":"confirmed","employee_id":601,"service_id":501,"previous":{"booking_date":"2026-10-20","start_time":"10:00:00","end_time":"11:00:00"}}}}}},"400":{"description":"booking_date / start_time missing or in the wrong shape, booking_date in the past, end_time not after start_time, the booking would run past midnight, or employee_id / service_id sent (they cannot change here) (INVALID_INPUT, with field)"},"403":{"description":"Booking is not on the plan (MODULE_LOCKED)"},"404":{"description":"No booking with this id in your business"},"409":{"description":"The new slot is blocked by staff; already booked for this employee (BOOKING_CONFLICT); the class has no room (SLOT_FULL / NOT_ENOUGH_SEATS); the booking is no longer ahead - arrived, in service, cancelled, completed or a no-show (BOOKING_NOT_ACTIVE); or it changed while moving (BOOKING_CHANGED - read it again and retry)"}},"x-required-scope":"write:bookings"}},"/bookings/{id}/confirm":{"post":{"operationId":"booking_confirm","summary":"Confirm Booking","description":"Confirm a booking that is a request, pending, waiting for approval, or has a change or cancellation request open. A cancelled booking or a no-show is not reopened here - make a new booking. The move must be one allowed from the booking's current status (409 INVALID_STATUS_TRANSITION names both); the same status again changes nothing (changed: false). Writes the status history and moves the CRM card; the business's own automation rules and workflows for this status run as for a change made in the app. The API sends its own message to the customer only with notify_customer true: the confirmation message (the business's consent, quiet-hours and channel rules apply). Fires booking.updated.\n\nRequired API key scope: `write:bookings`.","tags":["Booking"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking ID","schema":{"type":"integer","example":9001}}],"requestBody":{"description":"Optional","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Why, for the status history (up to 500 characters)","example":"Marked by the front desk"},"notify_customer":{"type":"boolean","description":"true: send the customer the business's own notice for this status (default false: no message)","example":false}}}}}},"responses":{"200":{"description":"Status set; changed is false when it already was. notification: not_requested (no notify_customer), requested (handed to the business's notice for this status), not_sent (notify_customer, but the status was already set)","content":{"application/json":{"example":{"success":true,"data":{"id":9001,"status":"confirmed","previous_status":"pending","changed":true,"notification":"not_requested","booking_date":"2026-10-20","start_time":"10:00:00","end_time":"11:00:00"}}}}},"400":{"description":"A field that is not reason or notify_customer (UNKNOWN_FIELD); a reason that is not text or is too long, or a notify_customer that is not true / false (INVALID_INPUT)"},"403":{"description":"Booking is not on the plan (MODULE_LOCKED)"},"404":{"description":"No booking with this id in your business"},"409":{"description":"Not allowed from the current status (INVALID_STATUS_TRANSITION, with from_status and to_status)"},"500":{"description":"The status could not be changed; nothing was saved"},"503":{"description":"The plan check is temporarily unavailable (PLAN_CHECK_FAILED); retry"}},"x-required-scope":"write:bookings"}},"/bookings/{id}/complete":{"post":{"operationId":"booking_complete","summary":"Complete Booking","description":"Mark a booking as completed once it has started (also corrects a no-show). The move must be one allowed from the booking's current status (409 INVALID_STATUS_TRANSITION names both); the same status again changes nothing (changed: false). Writes the status history and moves the CRM card; the business's own automation rules and workflows for this status run as for a change made in the app. The API sends its own message to the customer only with notify_customer true: the thank-you message (the business's consent, quiet-hours and channel rules apply). Fires booking.updated and booking.completed (the event an invoice for the meeting is raised from).\n\nRequired API key scope: `write:bookings`.","tags":["Booking"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking ID","schema":{"type":"integer","example":9001}}],"requestBody":{"description":"Optional","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Why, for the status history (up to 500 characters)","example":"Marked by the front desk"},"notify_customer":{"type":"boolean","description":"true: send the customer the business's own notice for this status (default false: no message)","example":false}}}}}},"responses":{"200":{"description":"Status set; changed is false when it already was. notification: not_requested (no notify_customer), requested (handed to the business's notice for this status), not_sent (notify_customer, but the status was already set)","content":{"application/json":{"example":{"success":true,"data":{"id":9001,"status":"completed","previous_status":"confirmed","changed":true,"notification":"not_requested","booking_date":"2026-10-20","start_time":"10:00:00","end_time":"11:00:00"}}}}},"400":{"description":"A field that is not reason or notify_customer (UNKNOWN_FIELD); a reason that is not text or is too long, or a notify_customer that is not true / false (INVALID_INPUT)"},"403":{"description":"Booking is not on the plan (MODULE_LOCKED)"},"404":{"description":"No booking with this id in your business"},"409":{"description":"Not allowed from the current status (INVALID_STATUS_TRANSITION, with from_status and to_status); or the booking has not started yet (BOOKING_NOT_STARTED)"},"500":{"description":"The status could not be changed; nothing was saved"},"503":{"description":"The plan check is temporarily unavailable (PLAN_CHECK_FAILED); retry"}},"x-required-scope":"write:bookings"}},"/bookings/{id}/no-show":{"post":{"operationId":"booking_no_show","summary":"Mark No-Show","description":"Mark that the customer did not come, once the booking has started (also corrects a completion). The move must be one allowed from the booking's current status (409 INVALID_STATUS_TRANSITION names both); the same status again changes nothing (changed: false). Writes the status history and moves the CRM card; the business's own automation rules and workflows for this status run as for a change made in the app. The API sends its own message to the customer only with notify_customer true: the no-show notice with the way to rebook (the business's consent, quiet-hours and channel rules apply). Fires booking.updated and the booking.no_show automation event.\n\nRequired API key scope: `write:bookings`.","tags":["Booking"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking ID","schema":{"type":"integer","example":9001}}],"requestBody":{"description":"Optional","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Why, for the status history (up to 500 characters)","example":"Marked by the front desk"},"notify_customer":{"type":"boolean","description":"true: send the customer the business's own notice for this status (default false: no message)","example":false}}}}}},"responses":{"200":{"description":"Status set; changed is false when it already was. notification: not_requested (no notify_customer), requested (handed to the business's notice for this status), not_sent (notify_customer, but the status was already set)","content":{"application/json":{"example":{"success":true,"data":{"id":9001,"status":"no_show","previous_status":"confirmed","changed":true,"notification":"not_requested","booking_date":"2026-10-20","start_time":"10:00:00","end_time":"11:00:00"}}}}},"400":{"description":"A field that is not reason or notify_customer (UNKNOWN_FIELD); a reason that is not text or is too long, or a notify_customer that is not true / false (INVALID_INPUT)"},"403":{"description":"Booking is not on the plan (MODULE_LOCKED)"},"404":{"description":"No booking with this id in your business"},"409":{"description":"Not allowed from the current status (INVALID_STATUS_TRANSITION, with from_status and to_status); or the booking has not started yet (BOOKING_NOT_STARTED)"},"500":{"description":"The status could not be changed; nothing was saved"},"503":{"description":"The plan check is temporarily unavailable (PLAN_CHECK_FAILED); retry"}},"x-required-scope":"write:bookings"}},"/bookings/{id}/cancel":{"post":{"operationId":"booking_cancel","summary":"Cancel Appointment","description":"Cancel an existing booking. Sets status to cancelled and fires the booking.cancelled webhook.\n\nRequired API key scope: `write:bookings`.","tags":["Booking"],"parameters":[{"name":"id","in":"path","required":true,"description":"Booking ID","schema":{"type":"integer"}}],"requestBody":{"description":"Cancellation reason","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Cancellation reason"}}}}}},"responses":{"200":{"description":"Booking cancelled"},"404":{"description":"Booking not found or already cancelled"}},"x-required-scope":"write:bookings"}},"/contacts":{"get":{"operationId":"customers_list","summary":"List Customers","description":"Get all customers with search and filtering.\n\nRequired API key scope: `read:contacts`.","tags":["Customers (CRM)"],"parameters":[{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","default":1,"example":1}},{"name":"limit","in":"query","description":"Items per page (1-100)","schema":{"type":"integer","default":20,"example":20}},{"name":"search","in":"query","description":"Search by name, email, or phone","schema":{"type":"string"}}],"responses":{"200":{"description":"List of customers"}},"x-required-scope":"read:contacts"},"post":{"operationId":"customers_create","summary":"Create Customer","description":"Create a new customer record.\n\nRequired API key scope: `write:contacts`.","tags":["Customers (CRM)"],"requestBody":{"description":"Customer information","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Full name"},"email":{"type":"string","description":"Email address"},"phone":{"type":"string","description":"Phone number: 6-15 digits, may start with +"},"tags":{"type":"array","items":{},"description":"Customer tags"}},"required":["phone"]}}}},"responses":{"201":{"description":"Customer created"}},"x-required-scope":"write:contacts"}},"/contacts/{id}":{"patch":{"operationId":"customers_update","summary":"Update Contact","description":"Update an existing contact. Only provided fields are changed. Fires the contact.updated webhook.\n\nRequired API key scope: `write:contacts`.","tags":["Customers (CRM)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Contact ID","schema":{"type":"integer"}}],"requestBody":{"description":"Contact fields to update","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Contact name"},"phone":{"type":"string","description":"Phone number"},"email":{"type":"string","description":"Email address"},"company":{"type":"string","description":"Company name"},"notes":{"type":"string","description":"Free-text notes"}}}}}},"responses":{"200":{"description":"Contact updated"},"404":{"description":"Contact not found"}},"x-required-scope":"write:contacts"}},"/contacts/{id}/activity":{"get":{"operationId":"customers_history","summary":"Contact Activity","description":"Get a contact activity timeline merged across channels (conversations and bookings matched by phone/email), sorted newest first (max 100 entries).\n\nRequired API key scope: `read:contacts`.","tags":["Customers (CRM)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Contact ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Contact with activity timeline","content":{"application/json":{"example":{"success":true,"data":{"contact":{"id":1,"name":"..."},"activity":[{"type":"conversation","id":"...","date":"2026-01-15T10:30:00Z","summary":"..."}]}}}}},"404":{"description":"Contact not found"}},"x-required-scope":"read:contacts"}},"/customers":{"get":{"operationId":"customer_cards_list","summary":"List Customer Cards","description":"The business's customer cards (the customer 360 the Customers page shows), newest activity first, archived cards left out. Search: every word must appear in the name, e-mail or company, or the typed digits (4 or more) in the phone.\n\nRequired API key scope: `read:contacts`.","tags":["Customers (CRM)"],"parameters":[{"name":"search","in":"query","description":"Words of the name, e-mail or company, or digits of the phone (max 100 characters)","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Cards per page (1-100)","schema":{"type":"integer","default":20}},{"name":"offset","in":"query","description":"Cards to skip","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Customer cards","content":{"application/json":{"example":{"success":true,"data":[{"id":27530,"full_name":"Dana Levi","phone":"972501234567","email":"dana@example.com","company_name":null,"city":"Haifa","segment":"new","lifecycle_stage":"lead","tags":["vip"],"last_channel":"whatsapp","last_active":"2026-10-21T10:00:00.000Z","created_at":"2026-10-01T08:00:00.000Z"}],"pagination":{"limit":20,"offset":0,"total":1}}}}},"400":{"description":"SEARCH_TOO_LONG or INVALID_PAGE"},"403":{"description":"Missing read:contacts, or the app user lacks customers:view (PERMISSION_DENIED)"}},"x-required-scope":"read:contacts"}},"/customers/{id}":{"get":{"operationId":"customer_cards_get","summary":"Get Customer Card","description":"One customer card of the business.\n\nRequired API key scope: `read:contacts`.","tags":["Customers (CRM)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Customer card id","schema":{"type":"integer"}}],"responses":{"200":{"description":"The card","content":{"application/json":{"example":{"success":true,"data":{"id":27530,"full_name":"Dana Levi","phone":"972501234567","email":"dana@example.com","company_name":null,"city":"Haifa","segment":"new","lifecycle_stage":"lead","tags":["vip"],"last_channel":"whatsapp","last_active":"2026-10-21T10:00:00.000Z","created_at":"2026-10-01T08:00:00.000Z"}}}}},"404":{"description":"NOT_FOUND - not a card of this business, or archived"}},"x-required-scope":"read:contacts"}},"/crm/boards":{"get":{"operationId":"crm_boards_list","summary":"List Boards","description":"Get all CRM boards with item counts.\n\nRequired API key scope: `read:crm`.","tags":["CRM Boards"],"responses":{"200":{"description":"List of boards"}},"x-required-scope":"read:crm"}},"/crm/boards/{boardId}/columns":{"get":{"operationId":"crm_columns_list","summary":"List Board Columns","description":"Get a board's columns (fields) with their keys and types. Use this before creating items so column keys/types match — the item cell keys must equal these column keys.\n\nRequired API key scope: `read:crm`.","tags":["CRM Boards"],"parameters":[{"name":"boardId","in":"path","required":true,"description":"Board ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"List of columns"},"404":{"description":"Board not found"}},"x-required-scope":"read:crm"},"post":{"operationId":"crm_columns_create","summary":"Create Board Columns","description":"Create one or more columns (fields) on a board. Accepts a single column object or {columns:[...]}. Idempotent on (board, key) — re-posting an existing key updates it instead of failing. Column types: text, long_text, phone, email, url, number, status, select, dropdown, checkbox, date, datetime, rating, progress.\n\nRequired API key scope: `write:crm`.","tags":["CRM Boards"],"parameters":[{"name":"boardId","in":"path","required":true,"description":"Board ID (UUID)","schema":{"type":"string"}}],"requestBody":{"description":"Column(s) to create","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Column display name (required if no key)"},"key":{"type":"string","description":"Stable column key (auto-slugged from name if omitted)"},"type":{"type":"string","description":"Column type (default text)"},"required":{"type":"boolean","description":"Whether the field is required"},"columns":{"type":"array","items":{},"description":"Array of column objects for batch creation"}}}}}},"responses":{"201":{"description":"Columns created/updated"},"400":{"description":"Invalid type or missing name/key"},"404":{"description":"Board not found"}},"x-required-scope":"write:crm"}},"/crm/boards/{boardId}/items":{"get":{"operationId":"crm_items_list","summary":"List Board Items","description":"Get all non-archived items in a CRM board, including their cell values, ordered by position.\n\nRequired API key scope: `read:crm`.","tags":["CRM Boards"],"parameters":[{"name":"boardId","in":"path","required":true,"description":"Board ID (UUID)","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Max results (default 20, max 100)","schema":{"type":"integer"}},{"name":"offset","in":"query","description":"Pagination offset","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of items with cells"}},"x-required-scope":"read:crm"},"post":{"operationId":"crm_item_create","summary":"Create Item","description":"Create a new CRM item on a board, optionally setting column values. The card is saved first; its column values are then set exactly as Set Item Cells does (deal gate, timeline row, update_crm_cells audit, crm.cells.updated webhook, automations), and the crm.item.created webhook goes out after them. If the cells are refused (a status option that needs a paid deal) the card is still created: the 201 carries warnings.cells_not_saved with the code (LIFECYCLE_REQUIRES_DEAL, or CELLS_WRITE_FAILED - retry with Set Item Cells). Unknown keys and refused smart values are listed in warnings.\n\nRequired API key scope: `write:crm`.","tags":["CRM Boards"],"parameters":[{"name":"boardId","in":"path","required":true,"description":"Board ID (UUID)","schema":{"type":"string"}}],"requestBody":{"description":"Item details","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Item name"},"group_key":{"type":"string","description":"Board group key"},"columnValues":{"type":"object","additionalProperties":true,"description":"Column values keyed by column key (JSON object)"}},"required":["name"]}}}},"responses":{"201":{"description":"Item created (check warnings.cells_not_saved when columnValues were sent)"},"404":{"description":"Board not found"}},"x-required-scope":"write:crm"}},"/crm/items/{itemId}":{"patch":{"operationId":"crm_item_update","summary":"Update Item","description":"Update a CRM item (name, group, archived flag) and optionally its column values. Fires the crm.item.updated webhook.\n\nRequired API key scope: `write:crm`.","tags":["CRM Boards"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Item ID (UUID)","schema":{"type":"string"}}],"requestBody":{"description":"Item fields to update","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Item name"},"group_key":{"type":"string","description":"Board group key"},"archived":{"type":"boolean","description":"Archive/unarchive the item"},"columnValues":{"type":"object","additionalProperties":true,"description":"Column values keyed by column key (JSON object)"}}}}}},"responses":{"200":{"description":"Item updated"},"404":{"description":"Item not found"},"409":{"description":"LIFECYCLE_REQUIRES_DEAL - a columnValues status option needs a paid deal first; nothing was changed"}},"x-required-scope":"write:crm"},"get":{"operationId":"crm_item_get","summary":"Get Item","description":"One CRM item (card) with its fields and its cell values, each cell tagged with its column key and type. Archived items are returned with archived: true. On a board set to show each user only their own cards, a key sees only cards with no owner, and none at all when the board also hides unowned cards - the same rule as List Board Items; a card a key cannot see answers 404.\n\nRequired API key scope: `read:crm`.","tags":["CRM Boards"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Item ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"The item with its cells","content":{"application/json":{"example":{"success":true,"data":{"id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","board_id":"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d","task_key":"CRM-482","group_key":"new","name":"Dana Levi","owner_id":null,"customer_id":1842,"archived":false,"deal_value":1500,"currency":"ILS","stage":"lead","priority":"high","source":"website","created_at":"2026-10-01T08:00:00.000Z","updated_at":"2026-10-02T08:00:00.000Z","cells":[{"column_id":"9b8a7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b","key":"phone","type":"phone","value_json":{"value":"+972501234567"},"updated_at":"2026-10-02T08:00:00.000Z"}]}}}}},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Item not found"}},"x-required-scope":"read:crm"},"delete":{"operationId":"crm_item_archive","summary":"Archive Item","description":"Archive a CRM item (card), as Delete does in the app: the card is hidden from the board and lists but nothing is deleted - PATCH it with archived: false to bring it back. Writes an archive_crm_item audit row and fires the crm.item.deleted webhook and the item.deleted automations. Archiving an archived card answers 200 with already_archived: true and fires nothing again.\n\nRequired API key scope: `write:crm`.","tags":["CRM Boards"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Item ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Item archived","content":{"application/json":{"example":{"success":true,"data":{"id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","archived":true,"already_archived":false}}}}},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Item not found"}},"x-required-scope":"write:crm"}},"/crm/boards/{boardId}/groups":{"get":{"operationId":"crm_groups_list","summary":"List Board Groups","description":"The groups (pipeline stages) used on a board, with how many open (non-archived) cards a key can see in each, largest first, up to 100 (truncated: true when there are more). A group whose cards are all archived is listed with 0; cards with no group are counted under group_key null. Groups exist only through cards, so a stage no card was ever in is not listed. Use a group_key when creating or moving an item.\n\nRequired API key scope: `read:crm`.","tags":["CRM Boards"],"parameters":[{"name":"boardId","in":"path","required":true,"description":"Board ID (UUID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Groups with card counts","content":{"application/json":{"example":{"success":true,"data":[{"group_key":"new","item_count":42},{"group_key":"qualified","item_count":17},{"group_key":"won","item_count":5}],"truncated":false}}}},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Board not found"}},"x-required-scope":"read:crm"}},"/crm/items/{itemId}/cells":{"put":{"operationId":"crm_item_cells","summary":"Set Item Cells","description":"Set a CRM item's cell values by column key, the way editing a card in the app does: a status option that needs a paid deal is refused (409 LIFECYCLE_REQUIRES_DEAL, nothing saved), the card timeline gets a row, an update_crm_cells audit row is written, and the crm.cells.updated webhook and the column/status automations fire. Only cells whose value really changed count; the timeline row and the webhook list each one as {column_id, key, old, new} (stored values, strings cut to 200 characters, at most 50 columns), and the webhook's source is {type: \"public_api\", key_prefix} (the key's prefix, as the API keys page shows it), so a sync can skip the echo of its own write (a change made in the app has source {type: \"user\", admin_user_id}). Keys that are not columns on the card's board and smart-column values that point at a record this business does not own are reported in warnings and skipped; the other cells are saved together. PATCH Update Item columnValues follow the same rules (a refused cell write changes no card field either); Create Item sets its cells this way after the card is created.\n\nRequired API key scope: `write:crm`.","tags":["CRM Boards"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Item ID (UUID)","schema":{"type":"string"}}],"requestBody":{"description":"The cells to set","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"columnValues":{"type":"object","additionalProperties":true,"description":"Values keyed by column key, e.g. {\"status\": \"Qualified\", \"phone\": \"+972501234567\"} - see GET /api/v1/crm/boards/{boardId}/columns for the keys"}},"required":["columnValues"]}}}},"responses":{"200":{"description":"Cells saved; the card's cells after the write","content":{"application/json":{"example":{"success":true,"data":{"item_id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","cells":[{"column_id":"9b8a7c6d-5e4f-4321-8a9b-0c1d2e3f4a5b","key":"status","type":"status","value_json":{"status":"Qualified"},"updated_at":"2026-10-11T08:00:00.000Z"}]},"warnings":{"unsaved_column_values":["budget"],"available_column_keys":["status","phone"],"hint":"These columnValues keys have no matching column on this board and were NOT saved."}}}}},"400":{"description":"columnValues missing, empty or not an object"},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Item not found (or not visible to a key on this board)"},"409":{"description":"LIFECYCLE_REQUIRES_DEAL - a status option that needs a paid deal first; nothing was saved"}},"x-required-scope":"write:crm"}},"/crm/items/{itemId}/comments":{"get":{"operationId":"crm_item_comments_list","summary":"List Item Comments","description":"The comments on a CRM item (card), oldest first, paged with limit (default 20, max 100) and offset. A reply carries parent_comment_id. A card the key cannot see (on a board limited to named users, or an owned card on a board set to show each user only their own cards) answers 403/404 as Get Item does.\n\nRequired API key scope: `read:crm`.","tags":["CRM Boards"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Item ID (UUID)","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (1-100, default 20)","schema":{"type":"number"}},{"name":"offset","in":"query","description":"Rows to skip (default 0)","schema":{"type":"number"}}],"responses":{"200":{"description":"Comments","content":{"application/json":{"example":{"success":true,"data":[{"id":"c3d4e5f6-0718-4293-a4b5-c6d7e8f90a1b","item_id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","parent_comment_id":null,"author_id":12,"author_name":"Dana Levi","body":"Called back, sending a quote tomorrow","mentions_json":[],"edited_at":null,"created_at":"2026-10-11T08:00:00.000Z","updated_at":"2026-10-11T08:00:00.000Z"}],"pagination":{"limit":20,"offset":0}}}}},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Item not found"}},"x-required-scope":"read:crm"},"post":{"operationId":"crm_item_comments_create","summary":"Add Item Comment","description":"Add a comment, or a reply to one, on a CRM item (card), as commenting in the app does: the comment, a timeline row and the card's last activity are saved together, then a create_crm_comment audit row is written and the crm.comment.created webhook fires. The comment is signed by the user who created the API key, with the author name \"API: <key name>\". Mentions and attachments are app-only.\n\nRequired API key scope: `write:crm`.","tags":["CRM Boards"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Item ID (UUID)","schema":{"type":"string"}}],"requestBody":{"description":"The comment","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Comment text (up to 10,000 characters)"},"parent_comment_id":{"type":"string","description":"Reply to this comment (UUID of a comment on the same item)"}},"required":["body"]}}}},"responses":{"201":{"description":"Comment added","content":{"application/json":{"example":{"success":true,"data":{"id":"c3d4e5f6-0718-4293-a4b5-c6d7e8f90a1b","item_id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","parent_comment_id":null,"author_id":12,"author_name":"API: website-sync","body":"Lead asked for a call on Sunday","mentions_json":[],"edited_at":null,"created_at":"2026-10-11T08:00:00.000Z","updated_at":"2026-10-11T08:00:00.000Z"}}}}},"400":{"description":"body missing, empty or too long; parent_comment_id not a UUID; KEY_HAS_NO_AUTHOR - the key has no creating user"},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Item not found, or PARENT_COMMENT_NOT_FOUND"}},"x-required-scope":"write:crm"}},"/crm/follow-ups":{"get":{"operationId":"crm_follow_ups_list","summary":"List Follow-Ups","description":"The business's follow-up tasks, in the app's order (urgent first, then by due date), paged with limit (default 20, max 100) and offset; pagination.total is the number of matching tasks. status is the task's state now: upcoming, overdue, snoozed or completed. Tasks on boards limited to named users, and owned cards on boards set to show each user only their own cards, are left out, as in List Items.\n\nRequired API key scope: `read:crm`.","tags":["CRM Boards"],"parameters":[{"name":"status","in":"query","description":"pending (default: every open task, upcoming + overdue), upcoming, overdue, snoozed, completed or all","schema":{"type":"string"}},{"name":"item_id","in":"query","description":"Only this item's (card's) tasks (UUID)","schema":{"type":"string"}},{"name":"board_id","in":"query","description":"Only tasks on cards of this board (UUID)","schema":{"type":"string"}},{"name":"assigned_to","in":"query","description":"Only tasks assigned to this user id","schema":{"type":"number"}},{"name":"limit","in":"query","description":"Page size (1-100, default 20)","schema":{"type":"number"}},{"name":"offset","in":"query","description":"Rows to skip (default 0)","schema":{"type":"number"}}],"responses":{"200":{"description":"Follow-ups","content":{"application/json":{"example":{"success":true,"data":[{"id":"a1b2c3d4-e5f6-4789-9abc-def012345678","item_id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","item_name":"Dana Levi","board_id":"0b1c2d3e-4f50-4617-8293-a4b5c6d7e8f9","assigned_to":12,"follow_up_type":"call","title":"Call back about the quote","description":null,"due_at":"2026-10-20T07:00:00.000Z","completed_at":null,"snoozed_until":null,"priority":"high","outcome":null,"created_by":12,"created_at":"2026-10-11T08:00:00.000Z","status":"upcoming"}],"pagination":{"limit":20,"offset":0,"total":1}}}}},"400":{"description":"A filter is not valid (status, item_id, board_id, assigned_to)"}},"x-required-scope":"read:crm"},"post":{"operationId":"crm_follow_ups_create","summary":"Create Follow-Up","description":"Add a follow-up task to a CRM item (card), as the app's Follow-Up Center does: the task and the card's next follow-up date are saved together, then a create_crm_follow_up audit row is written, the crm.follow_up.created webhook fires and the assignee (when it is not the key's creator) gets an in-app notification. The task is assigned to assigned_to, a user of this business, or to the user who created the API key.\n\nRequired API key scope: `write:crm`.","tags":["CRM Boards"],"requestBody":{"description":"The task","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_id":{"type":"string","description":"The CRM item (card) id (UUID)"},"title":{"type":"string","description":"What to do (up to 500 characters)"},"due_at":{"type":"string","description":"When: ISO 8601 date and time WITH its offset (Z or +03:00), e.g. 2026-10-20T10:00:00+03:00"},"description":{"type":"string","description":"Details (up to 10,000 characters)"},"assigned_to":{"type":"number","description":"User id of a user of this business (default: the key's creator)"},"priority":{"type":"string","description":"low, normal (default), high or urgent"},"follow_up_type":{"type":"string","description":"manual (default), call, whatsapp, email, meeting or task"}},"required":["item_id","title","due_at"]}}}},"responses":{"201":{"description":"Follow-up created","content":{"application/json":{"example":{"success":true,"data":{"id":"a1b2c3d4-e5f6-4789-9abc-def012345678","item_id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","item_name":"Dana Levi","board_id":"0b1c2d3e-4f50-4617-8293-a4b5c6d7e8f9","assigned_to":12,"follow_up_type":"call","title":"Call back about the quote","description":null,"due_at":"2026-10-20T07:00:00.000Z","completed_at":null,"snoozed_until":null,"priority":"high","outcome":null,"created_by":12,"created_at":"2026-10-11T08:00:00.000Z","status":"upcoming"}}}}},"400":{"description":"A field is missing or not valid (due_at without an offset is refused); ASSIGNEE_NOT_IN_BUSINESS; KEY_CREATOR_NOT_IN_BUSINESS - no assigned_to and the key creator has left the business; KEY_HAS_NO_AUTHOR - no assigned_to and the key has no creating user"},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Item not found"}},"x-required-scope":"write:crm"}},"/crm/follow-ups/{followUpId}/complete":{"post":{"operationId":"crm_follow_ups_complete","summary":"Complete Follow-Up","description":"Mark a follow-up task done, optionally with its outcome. A board set to require an outcome refuses an empty one (OUTCOME_REQUIRED), as the app does. The card's next follow-up date moves to its next open task; a complete_crm_follow_up audit row is written and the crm.follow_up.completed webhook fires.\n\nRequired API key scope: `write:crm`.","tags":["CRM Boards"],"parameters":[{"name":"followUpId","in":"path","required":true,"description":"Follow-up ID (UUID)","schema":{"type":"string"}}],"requestBody":{"description":"The outcome (optional unless the board requires it)","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","description":"What happened (up to 2,000 characters)"}}}}}},"responses":{"200":{"description":"Follow-up completed","content":{"application/json":{"example":{"success":true,"data":{"id":"a1b2c3d4-e5f6-4789-9abc-def012345678","item_id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","item_name":"Dana Levi","board_id":"0b1c2d3e-4f50-4617-8293-a4b5c6d7e8f9","assigned_to":12,"follow_up_type":"call","title":"Call back about the quote","description":null,"due_at":"2026-10-20T07:00:00.000Z","completed_at":"2026-10-20T07:30:00.000Z","snoozed_until":null,"priority":"high","outcome":"Booked a visit","created_by":12,"created_at":"2026-10-11T08:00:00.000Z","status":"completed"}}}}},"400":{"description":"OUTCOME_REQUIRED - the board requires an outcome; outcome too long"},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Follow-up not found"},"409":{"description":"ALREADY_COMPLETED"}},"x-required-scope":"write:crm"}},"/crm/items/{itemId}/timeline":{"get":{"operationId":"crm_item_timeline_list","summary":"Get Item Timeline","description":"Everything that happened on a CRM item (card), newest first: notes, messages, calls, bookings, leads, comments and system changes. Each entry has a type and a payload whose keys depend on the type (for example a note carries text, an attachment fileName, mimeType, size and caption). Internal keys (storage keys, links, file paths) are left out at every depth; open an attachment in the app. Paged with limit (default 20, max 100) and offset; pagination.total is the number of entries. A card the key cannot see answers 403/404 as Get Item does.\n\nRequired API key scope: `read:crm`.","tags":["CRM Boards"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Item ID (UUID)","schema":{"type":"string"}},{"name":"type","in":"query","description":"Only entries of this type, e.g. note, message_received, message_sent, booking_created, system. A type no entry has returns an empty list; empty means no filter.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size (1-100, default 20)","schema":{"type":"number"}},{"name":"offset","in":"query","description":"Rows to skip (default 0)","schema":{"type":"number"}}],"responses":{"200":{"description":"Timeline entries","content":{"application/json":{"example":{"success":true,"data":[{"id":"d4e5f607-1829-4a3b-8c4d-5e6f7a8b9c0d","item_id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","type":"note","created_by":12,"created_at":"2026-10-11T09:00:00.000Z","payload":{"text":"Sent the price list","source":"public_api","created_by_name":"API: website-sync"}},{"id":"e5f60718-293a-4b4c-9d5e-6f7a8b9c0d1e","item_id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","type":"booking_created","created_by":null,"created_at":"2026-10-10T12:00:00.000Z","payload":{"title":"Booking created","bookingId":812,"serviceName":"Consultation","dateTime":"2026-10-14T10:00:00+03:00"}}],"pagination":{"limit":20,"offset":0,"total":2}}}}},"400":{"description":"type is not a word (lowercase letters and _ only)"},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Item not found"}},"x-required-scope":"read:crm"},"post":{"operationId":"crm_item_timeline_note","summary":"Add Item Note","description":"Add a note to a CRM item's (card's) timeline, as the app's \"add note\" does: the note and the card's last activity time are saved together, then a create_crm_timeline_entry audit row is written and the crm.timeline.created webhook fires. The note is signed \"API: <key name>\" and attributed to the user who created the key, who must still be a user of the business. Notes only: attachments and the other entry types stay in the app.\n\nRequired API key scope: `write:crm`.","tags":["CRM Boards"],"parameters":[{"name":"itemId","in":"path","required":true,"description":"Item ID (UUID)","schema":{"type":"string"}}],"requestBody":{"description":"The note","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Note text (up to 10,000 characters)"},"type":{"type":"string","description":"Optional; only \"note\" is accepted"}},"required":["text"]}}}},"responses":{"201":{"description":"Note added","content":{"application/json":{"example":{"success":true,"data":{"id":"d4e5f607-1829-4a3b-8c4d-5e6f7a8b9c0d","item_id":"6f1d2c3b-4a59-4687-9a10-b2c3d4e5f607","type":"note","created_by":12,"created_at":"2026-10-11T09:00:00.000Z","payload":{"text":"Sent the price list","source":"public_api","created_by_name":"API: website-sync"}}}}}},"400":{"description":"text missing, empty or too long; type other than note; KEY_HAS_NO_AUTHOR - the key has no creating user; KEY_CREATOR_NOT_IN_BUSINESS - the key creator has left the business"},"403":{"description":"BOARD_RESTRICTED_FOR_API_KEY - the board is limited to named users in the app"},"404":{"description":"Item not found"}},"x-required-scope":"write:crm"}},"/leads":{"post":{"operationId":"crm_lead_capture","summary":"Capture Lead","description":"Capture an external lead (website form, landing page) into a CRM board. Auto-creates the customer and fires the lead.created webhook. When the business has CRM switched off or not in its plan, the lead is still saved but no CRM card is written: the response carries crmItemId null and crm_item_skipped (crm_turned_off | crm_not_in_plan); the lead.created webhook carries the same field. Customer mode (board_id with customer and/or event): the board keeps ONE card per person - found by phone in any spelling (052-..., 972..., +972...), then e-mail, then the customer the card is linked to - and each event she registers to is a sub-item under it. A found card is updated only where a sent value is new (nothing is cleared; tags are added to). The same event (name + date) updates its sub-item instead of adding another, so a retry or a later payment update adds nothing. A status column takes the label words and the label is added when the column has none with these words. A NEW event sub-item runs the board's automations with trigger event.registered (narrow with event_name / form_code, or conditions on payload.event_name, payload.form_code, payload.event_date ...); a new card also runs item.created with payload.form_code.\n\nRequired API key scope: `write:contacts`.","tags":["CRM Boards"],"requestBody":{"description":"Lead details. At least one of name, phone or email is required (400 otherwise).","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Lead full name"},"phone":{"type":"string","description":"Phone number"},"email":{"type":"string","description":"Email address"},"message":{"type":"string","description":"Free-text message from the lead"},"source":{"type":"string","description":"Lead source label (e.g. website, facebook)"},"subject":{"type":"string","description":"Form subject or the service the lead asked about"},"consent":{"type":"boolean","description":"true when the lead ticked the marketing consent box. Recorded as a marketing opt-in for the phone, so broadcasts and marketing templates reach the lead. Send only what the lead ticked."},"consent_text":{"type":"string","description":"The exact consent wording the lead saw, kept as proof of the opt-in"},"page_url":{"type":"string","description":"URL of the page the form was on"},"referrer":{"type":"string","description":"Referrer of that page"},"form_code":{"type":"string","description":"Optional. The code of the form that sent the lead (up to 100 characters). Saved as the lead's source (it wins over source), put on a board column keyed form_code (or named \"קוד טופס\") when there is one, and handed to automations as payload.form_code, so a journey can start per form.","example":"networking"},"customer":{"type":"object","additionalProperties":true,"description":"Optional, needs board_id. Cells of the customer's card as { \"<column key or column name>\": value } (up to 50): text, a number, yes/no, a date, a status label's words, or a list of tags. name / full_name, phone and email here also fill the lead when the top level leaves them out. A key with no column, or a value its column cannot take, is listed in unsaved_values and not saved.","example":{"עיר":"עפולה","קהילה":"עמק יזרעאל","tags":["נטוורקינג"]}},"event":{"type":"object","additionalProperties":true,"description":"Optional, needs board_id. The event she registered to, saved as a sub-item of her card: name (required, the sub-item's name), date (2027-01-04, 2027-01-04T10:00 or 04/01/2027 10:00, Israel time), location, amount, payment_status, payment_date, confirmed, and any other sub-item column by key or name. The fixed fields land in the sub-item column with that key or a known name (date: event_date / \"תאריך האירוע\"; amount: \"סכום\"; payment_status: \"סטטוס חיוב\"; payment_date: \"תאריך חיוב\"; confirmed: \"אישר הגעה\"; name: event_name / \"שם אירוע\").","example":{"name":"מפגש נטוורקינג עפולה","date":"2027-01-04T10:00","location":"היכל התרבות עפולה","amount":30,"payment_status":"ממתין לתשלום"}},"answers":{"type":"object","additionalProperties":true,"description":"The form's other answers as an object { \"<question or column name>\": \"<answer>\" } (up to 50). Each fills the CRM board column whose key or name equals the question; the rest are listed in the card's notes. Add a column named like a question and it fills from then on, with no change to the form."},"board_id":{"type":"string","description":"Optional. The id of the CRM board the lead lands on (from GET /api/v1/crm/boards). Leave it out and the lead lands on your default leads board, as before. The board must be one of your business's boards, have a phone or email column, and take cards from an API key. The same phone already on that board lands on its existing card (returning lead) instead of a new one.","example":"11111111-1111-4111-8111-111111111111"}}}}}},"responses":{"201":{"description":"Lead captured (into a CRM board unless crm_item_skipped is set). Or: Customer mode (board_id with customer / event): item_id is her card, subitem_id the event; *_created / *_updated say what changed (all false on a retry). unsaved_values lists what had no column or the wrong shape.","content":{"application/json":{"example":{"success":true,"data":{"submissionId":9,"crmItemId":null,"createdAt":"2026-10-05T09:00:00.000Z","customer_id":77,"crm_item_skipped":"crm_not_in_plan"}}}}},"400":{"description":"Customer mode input: INVALID_FORM_CODE, INVALID_CUSTOMER, INVALID_EVENT (no name, or not an object), INVALID_EVENT_DATE, BOARD_ID_REQUIRED (customer or event without board_id). Or: None of name, phone or email was sent; or board_id is not a board id (INVALID_BOARD_ID), the board has no phone or email column (BOARD_NOT_FOR_LEADS), or it does not take cards from an API key (BOARD_CLOSED_TO_KEY)","content":{"application/json":{"example":{"success":false,"error":"customer and event need board_id: the board whose cards are your customers.","code":"BOARD_ID_REQUIRED"}}}},"401":{"description":"Unauthorized"},"404":{"description":"board_id is not a board of your business (BOARD_NOT_FOUND)","content":{"application/json":{"example":{"success":false,"error":"There is no board with this id in your business.","code":"BOARD_NOT_FOUND"}}}}},"x-required-scope":"write:contacts"}},"/me":{"get":{"operationId":"account_me","summary":"API Key Info","description":"Get information about the current API key, including scopes and rate limits.","tags":["Account"],"responses":{"200":{"description":"API key details including name, scopes, environment, and rate limits"}}}},"/capabilities":{"get":{"operationId":"account_capabilities","summary":"Capability Manifest","description":"Self-describing manifest of everything this key can do: live endpoints WITH their request-body field schemas, granted scopes, webhook events, the CRM column-type vocabulary (types + value formats + status/select config), and the entity model (customer 360 vs contact vs CRM card). Filtered to your key's scopes. Fetch this to discover the platform instead of hardcoding paths.","tags":["Account"],"responses":{"200":{"description":"Capability manifest scoped to the API key"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","scheme":"bearer"}}}}