Use cases

1. Customer served in person → lead in a follow-up campaign

Your point-of-sale or front-desk system creates the lead and, in the same request, puts it in a prospecting or recontact campaign: the campaign's AI Employee follows up on its own.

Customer at the counter → Your POS → POST /leads + campaign_id → AI Employee follows up

1. Pick the campaign. GET /campaigns?type=prospecting and keep the id of a campaign with enrollable: true.
2. Create the lead with campaign_id. Send external_id (the customer id in your POS) so you never need the SpaceKru id.

   curl -X POST "https://app.spacekru.com/api/public/v1/leads" \
     -H "Authorization: Bearer $SPACEKRU_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: typeform-resp-8f2a1c" \
     -d '{
     "full_name": "Laura Gomez",
     "work_phone": "+573001112233",
     "external_id": "pos-88412",
     "campaign_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
     "tags": [
       "walk-in"
     ]
   }'

   const res = await fetch('https://app.spacekru.com/api/public/v1/leads', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.SPACEKRU_API_KEY}`,
       'Content-Type': 'application/json',
       'Idempotency-Key': 'typeform-resp-8f2a1c',
     },
     body: JSON.stringify({
       "full_name": "Laura Gomez",
       "work_phone": "+573001112233",
       "external_id": "pos-88412",
       "campaign_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
       "tags": [
         "walk-in"
       ]
     }),
   });
   const body = await res.json();
   if (!res.ok) {
     // Branch on body.error.code; quote body.error.request_id to support.
     throw new Error(`${body.error.code}: ${body.error.message} (request ${body.error.request_id})`);
   }
   console.log(body);

   import os
   
   import requests
   
   r = requests.post(
       "https://app.spacekru.com/api/public/v1/leads",
       headers={
           "Authorization": f"Bearer {os.environ['SPACEKRU_API_KEY']}",
           "Idempotency-Key": "typeform-resp-8f2a1c",
       },
       json={
           "full_name": "Laura Gomez",
           "work_phone": "+573001112233",
           "external_id": "pos-88412",
           "campaign_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
           "tags": ["walk-in"],
       },
       timeout=30,
   )
   body = r.json()
   if not r.ok:
       # Branch on body["error"]["code"]; quote body["error"]["request_id"] to support.
       raise RuntimeError(f"{body['error']['code']}: {body['error']['message']} (request {body['error']['request_id']})")
   print(body)

3. Read the outcome. The response has enrollment.status: enrolled, already_in_campaign or excluded with a reason (no_contact, no_channel_match, email_unverified).

2. Two-way sync with your CRM or platform

A lead edited in your platform updates SpaceKru, and a lead edited in SpaceKru (by your team or an AI Employee) updates your platform — without echo loops.

Your platform → PUT /leads/external/{id} → SpaceKru → lead.updated (triggered_by: app) → Your platform

1. Write with PUT /leads/external/{external_id}: it creates, updates or adopts the lead.
2. Subscribe to lead.created and lead.updated with exclude_own_changes: true.
3. On each webhook, update your record by data.external_id (or store data.id the first time).

The full recipe: Two-way sync.

3. Your AI Employee inside your app or website

Your customers write in your app; your Customer Service AI Employee answers with everything it can do in WhatsApp: quote, book, check the catalog and the knowledge base, or call a person.

Customer writes in your app → POST /conversations/{id}/messages → AI Employee replies → Your app shows the reply

Requirements, lifecycle and costs: AI conversations.

4. Catalog and stock from your e-commerce or ERP

Your AI Employees quote and sell with the prices and stock of your real catalog.

1. Create each product once with POST /products and your external_id (your SKU id).
2. When price or stock changes in your system, send PATCH /products/{id} (or PATCH /products/{id}/variants/{variant_id} for a variant).
3. Listen to product.updated to bring back the stock SpaceKru deducts when it creates orders.

5. Bookings from your website or booking system

GET /availability → Customer picks a slot → POST /bookings → booking.created

1. GET /availability?date=2026-10-24&party_size=4 returns the free slots in the time zone of the business.
2. POST /bookings with the resource_id and times of the slot. A taken slot answers 409 SLOT_UNAVAILABLE.
3. Bookings your AI Employees make in WhatsApp reach you as booking.created.

6. Website or Typeform → lead in SpaceKru

Every form response becomes a SpaceKru lead in seconds, without duplicates.

Form response → Zapier / Make / n8n → POST /leads → Lead in SpaceKru

1. Create an API key. In SpaceKru → Integrations → API & Webhooks, create a key with Read & write access. Name it "Zapier — forms".
2. Trigger. In Zapier, use your form tool's trigger, for example Typeform → New Entry.
3. Action. Add Webhooks by Zapier → POST. URL: https://app.spacekru.com/api/public/v1/leads. Payload Type: json. Header: Authorization = Bearer <your key>.
4. Map the fields. In Data, add full_name, work_email, work_phone and tags (a comma-separated value such as typeform, spring-promo works). Fields you leave empty are ignored.
5. Turn it on. Test it once, then publish. If the person already exists, SpaceKru answers 409 with existing_id instead of creating a duplicate.

7. New SpaceKru lead → contact in HubSpot (or any CRM)

Every new lead — from WhatsApp, Instagram, forms, CSV imports or the Lead Finder — reaches your other CRM in seconds.

New lead in SpaceKru → lead.created → Zapier Catch Hook → HubSpot contact

1. Catch Hook. In Zapier, create a Zap with the trigger Webhooks by Zapier → Catch Hook and copy its URL.
2. Register the webhook once. Run this request once with your key and the Catch Hook URL. Save the secret it returns.

   curl -X POST "https://app.spacekru.com/api/public/v1/subscriptions" \
     -H "Authorization: Bearer $SPACEKRU_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "event_type": "lead.created",
     "target_url": "https://hooks.zapier.com/hooks/catch/1234567/abcdefg/"
   }'

   const res = await fetch('https://app.spacekru.com/api/public/v1/subscriptions', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.SPACEKRU_API_KEY}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       "event_type": "lead.created",
       "target_url": "https://hooks.zapier.com/hooks/catch/1234567/abcdefg/"
     }),
   });
   const body = await res.json();
   if (!res.ok) {
     // Branch on body.error.code; quote body.error.request_id to support.
     throw new Error(`${body.error.code}: ${body.error.message} (request ${body.error.request_id})`);
   }
   console.log(body);

   import os
   
   import requests
   
   r = requests.post(
       "https://app.spacekru.com/api/public/v1/subscriptions",
       headers={
           "Authorization": f"Bearer {os.environ['SPACEKRU_API_KEY']}",
       },
       json={
           "event_type": "lead.created",
           "target_url": "https://hooks.zapier.com/hooks/catch/1234567/abcdefg/",
       },
       timeout=30,
   )
   body = r.json()
   if not r.ok:
       # Branch on body["error"]["code"]; quote body["error"]["request_id"] to support.
       raise RuntimeError(f"{body['error']['code']}: {body['error']['message']} (request {body['error']['request_id']})")
   print(body)

3. Map to HubSpot. Add HubSpot → Create or Update Contact and map data.work_email, data.full_name, data.work_phone and data.company_name.

8. Deal won → message on Slack

Deal marked won → deal.stage_changed → Filter: status is won → Slack message

1. Subscribe. Subscribe a Catch Hook URL to deal.stage_changed.
2. Filter. Continue only if data.status is won and changes.status exists.
3. Slack. Add Slack → Send Channel Message: "🎉 {data.title} won — {data.value}".

9. Order paid → accounting or Google Sheets

Payment recorded → order.status_changed → Filter: payment_status is paid → New row in Sheets

1. Subscribe a Catch Hook URL to order.status_changed.
2. Continue only if changes.payment_status exists and its second value is paid.
3. Add the row with data.number, data.total, data.amount_paid and data.items.

10. Nightly sync to your data warehouse or ERP

Scheduled job → GET with updated_since → Follow next_cursor → Upsert by id

1. Save the time the job starts.
2. Call GET /leads?updated_since=<last run>&limit=100 and follow next_cursor until has_more is false.
3. Upsert every record by id. Repeat for /deals, /quotes, /orders, /products and /bookings.
4. Store the start time as the next updated_since.

The complete code is in Pagination & sync. Use a Read only key for this job.

11. Campaign reply → alert the sales rep

Lead replies to a campaign → campaign_lead.replied → Your automation → Email, Slack or SMS to the rep

1. Subscribe to campaign_lead.replied.
2. Send data.lead.full_name, data.lead.work_email and data.campaign_id to the rep through your tool.

12. Agencies: one integration per client

• Each client account has its own keys (up to 5 active) and its own webhooks. A key can only ever see the account it belongs to.
• Name keys after the tool and the client ("Zapier — Client A") so the panel tells you what each one does.
• Revoking one key stops that tool and deactivates the webhooks it created, without touching anything else.