DEVELOPER REFERENCE · V1

Connect every customer touchpoint.

Send website enquiries to NEmployee and keep bookings in step with your existing software. The same API key works for both endpoints.

JSON over HTTPSBearer authenticationBritish English responses

01 / START HERE

Getting started

Open Workspace → API access, give your integration a name and create an API key. Copy it when shown: the full key appears only once. Create separate keys for separate integrations so you can revoke one without interrupting the others.

Base URLhttps://employee.nesdzo.co.uk

Make all requests from a server or trusted automation platform. Send Authorization: Bearer YOUR_API_KEY and Content-Type: application/json.

Message intake and bookings accept POST requests; message replies can also be read with GET. API keys are scoped to the business where they were created; there is no business ID to pass in the body.

02 / CUSTOMER ENQUIRIES

Send a message

POST/api/v1/messages

Use this endpoint for a website form, chat widget or another source of inbound customer messages. NEmployee saves the message, updates the lead and may generate a reply. A human handover or the free manual inbox can produce a null reply. Free workspaces can send up to 300 team replies per UTC month; incoming messages continue after that limit.

curl -X POST https://employee.nesdzo.co.uk/api/v1/messages \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "website-customer-123",
    "messageId": "form-submission-456",
    "name": "Alex Smith",
    "email": "alex@example.co.uk",
    "message": "Could I arrange a consultation?"
  }'

Field	Type	Details
`message`	string · required	Customer message. Leading and trailing whitespace is removed; the stored text is limited to 5,000 characters.
`customerId`	string · recommended	Stable identifier for this customer in your integration, up to 240 characters. Reuse it across messages to continue the same API conversation.
`messageId`	string · recommended	Stable identifier for this incoming message. Reuse it when retrying the same delivery to avoid processing a duplicate.
`name`	string · optional	Customer name, up to 120 characters.
`email`	string · optional	Customer email address, up to 240 characters.
`phone`	string · optional	Customer telephone number, up to 60 characters.

Successful response

{
  "conversationId": "8e8c4d1f-8f20-4bd6-a89a-f12345678901",
  "leadId": "ff2e81a0-33c2-46a9-8b00-f12345678901",
  "reply": "Of course — what day would suit you?",
  "handoff": false,
  "duplicate": false
}

To retrieve staff replies for an API conversation, call GET /api/v1/messages?conversationId=THE_CONVERSATION_ID with the same business API key. The response contains up to 100 recent outbound messages, ordered oldest first; use each message ID to avoid displaying a reply twice.

reply is the text you may display to the customer when present. handoff: true means your team should continue in the NEmployee inbox. If you retry a messageId, duplicate is true and no new reply is generated. When risk screening is enabled, suppressed: true means the message was silently filtered or its sender is blocked; reply, conversationId and leadId may then be null. Treat this as a successful delivery and do not retry or send your own automated reply. Do not send the returned reply through another channel unless your integration is responsible for that delivery.

03 / APPOINTMENTS

Import or update a booking

POST/api/v1/bookings

Use this endpoint when a booking tool creates or changes an appointment. The combination of provider and externalId identifies one booking. Send the same pair again to update it; the API creates no duplicate appointment for that pair.

curl -X POST https://employee.nesdzo.co.uk/api/v1/bookings \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "my_booking_app",
    "externalId": "booking-123",
    "name": "Alex Smith",
    "email": "alex@example.co.uk",
    "service": "Consultation",
    "start": "2026-10-15T10:00:00+01:00",
    "locationName": "City centre clinic",
    "status": "confirmed"
  }'

Field	Type	Details
`provider`	string · required	Your integration identifier, 2–60 lower-case letters, digits, underscores or hyphens.
`externalId`	string · required	Stable booking ID from your system, up to 160 characters.
`status`	string · optional	requested or confirmed; defaults to confirmed. Send cancelled to cancel an existing booking.
`name`	string · required*	Customer name, up to 120 characters. *Not needed for a cancellation.
`start`	ISO 8601 · required*	Appointment start with a time-zone offset, for example 2026-10-15T10:00:00+01:00. *Not needed for a cancellation.
`end`	ISO 8601 · optional	End time with a time-zone offset. If omitted, the location’s slot length is used. The end must be after the start and no more than 12 hours later.
`locationId`	UUID · optional	An active location ID. Use this or locationName; locationId takes precedence.
`locationName`	string · optional	Exact active location name, up to 120 characters; matching ignores letter case. Required when multiple active locations exist unless locationId is supplied.
`email`	string · optional	Customer email address, up to 240 characters. Used to find an existing lead when possible.
`phone`	string · optional	Customer telephone number, up to 80 characters.
`service`	string · optional	Service name, up to 160 characters.
`notes`	string · optional	Booking notes, up to 1,000 characters.

Capacity and timing

The default is one appointment every 30 minutes. Each business and location can set its own interval and simultaneous capacity in Workspace → Calendar → Appointment rules. Requested and confirmed appointments occupy capacity; a cancellation request continues to occupy it until cancelled. A full slot returns 409. Times must fall on the configured interval in the business’s time zone.

Successful response

{
  "appointmentId": "19b0e3e2-9a43-4f61-9a32-f12345678901",
  "leadId": "ff2e81a0-33c2-46a9-8b00-f12345678901",
  "status": "confirmed",
  "created": true
}

A new booking returns 201; an update returns 200. The booking appears in the workspace calendar and appointments list.

Cancel a booking

Send the same provider and externalId with status: cancelled. Customer details and times are not needed for this action. A cancellation for an unknown ID returns 404.

curl -X POST https://employee.nesdzo.co.uk/api/v1/bookings \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "my_booking_app",
    "externalId": "booking-123",
    "status": "cancelled"
  }'

04 / RESPONSES

Responses and errors

Errors are JSON objects with an error message. Treat the HTTP status as the source of truth; the wording of error messages may change.

Status	Meaning	What to do
`400`	Invalid or missing data	Check required fields, time-zone offsets, location and slot alignment.
`401`	Missing, invalid or revoked key	Check the Bearer header and the key in API access.
`403`	Business cannot accept live bookings	Check its activation and subscription status.
`404`	Booking to cancel was not found	Check the provider and external ID.
`409`	Appointment capacity reached	Ask the customer for another time or location.
`413`	Booking payload too large	Keep the JSON body below 16,000 characters.
`429`	Rate limit reached	Retry later with backoff.

Each API key is limited to 120 message requests and 120 booking requests per minute. The counters are separate.

05 / KEEP IT SAFE

Security and operational notes

Keep API keys on your server. Never include one in browser JavaScript, a public repository or a URL.
Use HTTPS. Create one key per integration and revoke a key from API access if it is exposed.
Use stable customerId and messageId values for message continuity and safe retries.
Use a stable provider and externalId pair for booking updates and cancellations.
Check a 409 response before telling anyone a booking is confirmed.

For help with an integration, email contact@nesdzo.co.uk.