Plans and connections

Connecting your own systems

For owners: what API keys and webhooks are, how to set them up safely in Settings, and how to check they are working. Hand the technical part to your developer with a link to the developer documentation.

What integrations are for#

Many businesses already run other software: a clinic system that holds patient records, a CRM, a billing system, a screen in the lobby, a chatbot. Integrations let that software work with Line Me Up instead of beside it. The staff app puts it in one line: "API keys let it read and change your lines, and webhooks tell it when something happens."

• An API key is a password for a piece of software. With it, your system can ask Line Me Up for things — the lines, who is waiting, a visit — and, if you allow it, change them: add a visit when a patient is registered in your clinic system, call the next person, pause a line.
• A webhook goes the other way. You give Line Me Up the address of your system, and Line Me Up sends it a message within seconds whenever something happens: a visit is added, a customer is called or served, a line is paused, a desk goes on a break.

You set both up in the staff app. Your developer then uses the developer documentation to write the software that uses them.

Before you start#

• Only the owner can see or change integrations. They are a section of Settings, which is the owner's.
• API keys and webhooks are included from Basic up. When your plan's limits apply and your plan does not include them, the section says so at the top. Anything you made before stays listed, and you can still revoke a key or delete a webhook.
• At the live demo the section is read-only: you can look around, but keys and webhooks cannot be made or changed there.

To open Integrations:

1. Open Settings in the sidebar.
2. Press Integrations ("API keys, webhooks and usage"). It has three cards: API keys, Webhooks and Usage, and a link to the Developer documentation.

What a key can and cannot do#

Each key belongs to your business only, and can never see another business. It does only what you allow, from four permissions:

You can also limit a key to some lines — it then sees and acts on those lines only, and everything else is as if it did not exist — and, for Run desks, to some desks.

Whatever you tick, a key can never do what only an owner does: it cannot change your team, your Settings, your billing, or other keys and webhooks. Everything a key does is recorded in the name of the owner who made it, so a visit's history shows it came through that key.

Make an API key#

1. In Settings › Integrations, press New key on the API keys card. A panel opens beside the page.
2. In Name, say what will use it — "Clinic CRM", "Lobby screen" — so you recognise it later.
3. Under What it may do, tick the permissions it needs. Read is ticked to start with; at least one must stay ticked.
4. Under Lines, leave Every line, or choose the lines it may reach.
5. Under Desks, leave Every desk, or choose the desks where it may call and serve. This matters only if you ticked Run desks.
6. Under Ends, choose Never, In 30 days, In 90 days or In 365 days. A key for a trial or a contractor is safer with an end date. The end date cannot be changed later.
7. Press Make key.
8. The panel now shows Your new key. Press Copy (it changes to Copied) and paste the key straight into your system, or into a password manager to give to your developer.
9. Press I have copied it.

The new key appears in the list with its name, what it may do, its lines and desks, Never used until your system first uses it, and its end date if it has one. A business can hold up to 25 keys at once; when it is full, the card says so, and you revoke one to make another.

Check or change a key#

1. Press the key in the API keys list.
2. The panel shows its State (Active, Expired, Revoked or Needs a new key), how it is known — its first characters and last four, so you can match it to the one in your system — who made it and when, when it was Last used, and when it Ends.
3. To change it, edit its Name, its permissions, or its Lines and Desks, then press Save changes. The change applies to the very next thing your system asks.

A revoked or expired key can be read but not changed. To replace a key — because it ended, or because it may have leaked — make a new one, put it in your system, then revoke the old one.

Revoke a key#

1. Press the key in the API keys list.
2. Press Revoke key.
3. The panel asks: "Revoke … ? Anything using it stops working at once. This cannot be undone." Press Revoke key again to confirm, or Keep it to go back.

Add a webhook#

A webhook is an address on the internet, run by your system, where Line Me Up posts what happens. Your developer gives you the address. Each message is signed, so your system can check it really came from Line Me Up.

1. In Settings › Integrations, press Add webhook on the Webhooks card.
2. In Address, paste the full address, starting https://. It must be reachable from the internet.
3. In Note, optionally write something for yourself — "Clinic CRM, live".
4. Under Events, choose what to send. All are ticked to start with; at least one must stay ticked:
   • Visit added — at the desk, from a phone, as a booking, or through a key.
   • Visit status changed — called, served, completed, cancelled, a no-show, put back, checked in.
   • Visit changed — its urgency, booked time, line or who it is for.
   • Line paused and Line resumed.
   • Desk status changed — a shift starts or ends, or a break.
5. Under Lines, leave Every line, or choose lines: only what happens on those lines is sent.
6. Press Add webhook.
7. The panel shows Your webhook's signing secret. Press Copy, give it to your developer to put in your system, and press I have copied it.

Like a key, the signing secret is shown only once. The webhook then appears in the list as Sending, with how many events and lines it covers. A business can have up to 10 webhooks.

Send a test event#

The quickest way to check your system receives what Line Me Up sends, without waiting for a real customer.

1. Press the webhook in the Webhooks list.
2. Under Send test event, choose an Event — a sample of any event, or the plain test event.
3. Press Send test event. It says Test event queued., with a way into the log.
4. Open the Delivery log to see whether it arrived: Delivered means your system answered that all was well; Failed means it did not.

A test is marked as a test, so your system can tell it from a real event. A test can be sent only while the webhook is switched on — otherwise the panel says "Switch the endpoint on to send a test event."

Read the delivery log#

Every message sent to a webhook is in its log, newest first: the event, its state, how many attempts it took and your system's last answer.

1. Press Delivery log beside the webhook in the list, or inside its panel.
2. To narrow it, choose a Status (or Any) and an Event (or Any event).
3. Press a delivery to see it in full: its event id, when it was made, when it was delivered or will next be tried, each Attempt with your system's answer and how long it took, and the Request as sent.
4. Press Back to the log to return to the list as you left it.

What each state means:

• Queued — about to be sent.
• Retrying — your system did not accept it, and Line Me Up will try again. It tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours and 10 hours — seven attempts over about 18 hours.
• Delivered — your system accepted it.
• Failed — a test event or a redelivery your system did not accept. These are tried once only, since you are watching.
• Gave up — every attempt failed, or sending was stopped.

The log keeps each webhook's last 200 deliveries at least, and everything from the last 30 days. Show older deliveries loads more.

Send a delivery again#

If your system was down, or your developer has fixed a fault, you can send a missed event again.

1. Open the webhook's Delivery log and press the delivery.
2. Press Redeliver. The same event is sent again as a new row in the log.

While the delivery is still being sent or retried, Redeliver waits: "Still being sent — Redeliver once it has finished."

Pause, roll the secret or delete a webhook#

Stop sending for a while#

1. Press the webhook in the list.
2. Switch Sending off. It acts at once; the list shows it as Off.
3. Switch it back on when you are ready. Sending starts again from the next event — what happened while it was off is not sent.

Change the signing secret#

If the secret may have leaked, or your developer asks for a new one:

1. Press the webhook and find Signing secret.
2. Press Roll secret.
3. Copy Your new signing secret and press I have copied it. For the next 24 hours, deliveries are signed with both the old and the new secret, so your developer can change your system before the old one stops.

Delete a webhook#

1. Press the webhook and press Delete webhook.
2. The panel asks: "Delete this webhook and its delivery log? Nothing more is sent to it. This cannot be undone." Press Delete webhook again, or Keep it.

When a webhook switches itself off#

If deliveries to a webhook keep failing — at least 50 failures in a row, with no success for three days — Line Me Up stops sending to it. The list shows it as Off — failing, and its panel says when it last succeeded.

To get it working again:

1. Ask your developer to fix the system at that address.
2. Press the webhook and switch Sending back on.
3. Press Send test event and check the Delivery log shows Delivered.
4. If you need events missed while it was off, open them in the log and press Redeliver.

Watch how your integrations are used#

The Usage card covers the last 30 days of your business:

• a chart of API requests a day, with the totals beside it: Requests, Errors, Rate limited and Webhooks delivered;
• for each key: requests Today and over 30 days, its errors and how often it was rate limited, Time to answer, its Busiest requests and when it was Last used;
• for each webhook: the share Delivered first time or on a retry, how many were delivered, failed or gave up, how quickly your system answered, and its Latest failures.

Hand over to your developer#

Give your developer:

• the API key, through a password manager or another safe channel — never by plain email;
• for a webhook, its signing secret, the same way;
• a link to the developer documentation. The Quickstart gets a first request working in minutes; Scopes and restrictions explains the permissions above; and Webhooks explains every event and how to check a signature.