PricingCustom builds
Log inStart free trial
One inboxEvery chat in one listLead sourcesThe ad or page behind each chatAuto-repliesAn answer at once, after hours tooReportsReply times and a Monday reportBookingsViewings and appointments from the chatPhone appThe same inbox on your team's phonesWebhooks and calendarChats and bookings to your systems
All channelsFour channels in one inboxWhatsAppYour number, through Meta's official platformInstagramDirect messages and story repliesMessengerYour Facebook Page's chatsWebsite chatA chat on your site, working today
Online shopsClinics and dentistsCar dealersReal estate and developersHotels and guesthousesBeauty and salonsRestaurants and deliveryFitness and studiosSchools and coursesRepair and services

All industries →

Data API

How your system keeps an mpulse list current: one call when an item changes, and the AI assistant answers from it on the next message.

On this page

The keyThe callsWhat comes backExamplesOrder, retries and deletesPersonal detailsLeadsErrorsLimits
  1. The key
  2. The calls
  3. What comes back
  4. Examples
  5. Order, retries and deletes
  6. Personal details
  7. Leads
  8. Errors
  9. Limits

The key

Every call carries the key in a header: Authorization: Bearer mpk_live_… The owner makes keys on the list's sheet; each is shown once.

Start with a test key (mpk_test_…). It writes to the list's test side, which the agent never reads, and it adds no fields to the list: a field it sends comes back as new_field and stays out of the list's fields, so GET /sources/{list} shows only the fields a live key has sent. Switch to a live key when it works.

A key belongs on a server. Never put it in a web page, and never in an address: a key sent in an address is switched off at once.

The calls

https://app.mpulse.ge/api/v1

GET/mewho the key is and which lists it may touch
GET/sources/{list}the list's fields, what each value means, the id and version fields
PUT/sources/{list}/items/{id}one item, whole: created or replaced
PATCH/sources/{list}/items/{id}only the fields sent change; null removes one
POST/sources/{list}/items?mode=mergethe id in the body; creates the item when it's new
DELETE/sources/{list}/items/{id}?version=takes it off the list
POST/sources/{list}/batchup to 500 at once: {"upsert": [...], "delete": [...]}
GET/sources/{list}/items/{id}one item as mpulse has it (keys that may read); for an id that holds /, use /items?id=
GET/sources/{list}/items?since=every change after a cursor, deletions too (keys that may read)
GET/leadswhere each customer came from, in the order stored (live keys that may read, with Leads on)

What comes back

A write answers {"object": "item", "id", "version", "seq", "changed", "warnings"}. changed names the fields that changed (empty when nothing did), warnings what was stored with a remark (the codes below), and seq is the item's place in the list's order of changes. A key that may read also gets the item back in data, with the fields the owner has switched on: a field the list first sees is stored but stays out of data (and out of GET /items) until the owner looks at it, so price and status sent once may not show yet. A test key's answer echoes every field it was sent, new ones too, because the test side adds no fields to the list: a live key's answer can then show fewer. A key the owner lets read hidden fields gets them all. With ?dry_run=true the answer is the same plus "dry_run": true, and nothing is stored.

A batch answers with its counts: {"object": "batch", "created", "updated", "unchanged", "deleted", "stale", "failed", "errors", "warnings"}. Each error and warning carries its operation's index and id.

GET /items answers {"object": "list", "data": [...], "has_more", "next_cursor"}, oldest change first. Send next_cursor back as ?cursor= for the next page. Keep the last one: later, ?since= with it gives only what changed after it, deleted items included as {"id", "deleted": true, "version"}. since=0 starts from the beginning.

GET /items/{id} answers the item, {"object": "item", "id", "data", "version", "seq", "created_at", "updated_at"}, or 404 item_not_found (with "deleted": true for one that was deleted).

Examples

export MPULSE_KEY=mpk_test_...    # a test key firstAPI=https://app.mpulse.ge/api/v1SRC=<list id>AUTH="Authorization: Bearer $MPULSE_KEY"JSON="Content-Type: application/json" # Is the key right, and what may it touch?curl -s $API/me -H "$AUTH" # The list's fields and what each value meanscurl -s $API/sources/$SRC -H "$AUTH" # What would happen, without writing anythingcurl -s -X PUT "$API/sources/$SRC/items/A-12?dry_run=true" \  -H "$AUTH" -H "$JSON" \  -d '{"apartment_no":"A-12","price":128000,"status":"A",       "updated_at":"2026-11-11T14:02:11+04:00"}' # One item, whole (created or replaced)curl -s -X PUT "$API/sources/$SRC/items/A-12" \  -H "$AUTH" -H "$JSON" \  -d '{"apartment_no":"A-12","price":128000,"status":"A",       "updated_at":"2026-11-11T14:02:11+04:00"}' # It sold: only that changes, with your system's time as the versioncurl -s -X POST "$API/sources/$SRC/items?mode=merge" \  -H "$AUTH" -H "$JSON" -H "Idempotency-Key: deal-8812-sold" \  -d '{"apartment_no":"A-12","status":"S",       "updated_at":"2026-11-11T15:00:00+04:00"}' # Taken off the listcurl -s -X DELETE -H "$AUTH" \  "$API/sources/$SRC/items/A-12?version=2026-11-11T16:00:00%2B04:00" # Many at once, up to 500 a call: {"upsert": [...], "delete": [...]}KEY=load-$(shasum -a 256 items-1.json | cut -c1-40)curl -s -X POST "$API/sources/$SRC/batch" \  -H "$AUTH" -H "$JSON" -H "Idempotency-Key: $KEY" \  -d @items-1.json

The JavaScript runs on Node 18 or later with no library. Add ?dry_run=true to any write to see the answer without storing anything.

Order, retries and deletes

When the list has a version field, every write carries it, and an older write than what mpulse has answers 409 stale_version and changes nothing. Treat it as done.

A delete leaves a marker with its version, so a late retry can't bring the item back.

Send an Idempotency-Key header with every write (your event id works well). A retry with the same key gets the same answer.

Personal details

mpulse never stores a buyer's name, phone, email or personal number. Fields like buyer_phone are dropped, and the answer warns personal_dropped. The owner can choose to refuse them instead.

Leads

GET /leads lists where each customer came from, one item per signal: an ad, a link, a tagged visit to the business's website, or a source its team set by hand. It needs a live key that may read (read, or read and write) with Leads switched on. A test key gets 403 live_key_required, because leads are real customers; any other key gets 403 scope_missing. GET /me lists the key's scopes.

Each item is {"object": "lead", "id", "at", "stored_at", "kind", "channel", "conversation_id", "contact": {"id", "name", "phone", "email"}, "source": {"key", "name", "source", "medium"}, "campaign": {"id", "name"}, "adset": {"id", "name"}, "ad": {"id", "name", "title"}, "utm", "clicks", "role", "clicked_at", "referrer", "landing", "page", "ref", "manual", "handoff"}. at is the signal's own time (a referral's, the message a web visit came with, the moment a source was set by hand), so it does not follow the feed's order; stored_at is when mpulse stored the lead, the order of the feed. kind is ad, link, web or manual. A web lead carries role (first: the visit the site kept as the person's first; last: their latest) and clicked_at, when that visit was; other leads have null there. manual holds a source the team set by hand, with its reason and who set it; manual.overrides is the id of the automatic lead it replaced, which a sync should then no longer count. handoff is set on a lead a WhatsApp chat took over from the website chat when the visitor pressed Continue on WhatsApp: {"from": the id of the website chat's lead it repeats, or null when that chat had none, "conversation_id": the website chat}. It is the same customer going on, which a sync should not count again; other leads have null there. source.name is in the language of the call's Accept-Language (en, ka or ru), else English.

?limit=1..100 (50), ?cursor= or ?since= with an earlier answer's next_cursor (since=0 starts from the beginning), ?created_since= an ISO 8601 date-time with its offset (2026-11-01T00:00:00Z or 2026-11-01T00:00:00+04:00: what mpulse stored from then on), ?kind= and ?source= (google, or google:cpc with its medium). Any other parameter is refused with 400 unknown_param. The answer is {"object": "list", "data", "has_more", "next_cursor"}, in the order mpulse stored the leads: send next_cursor back for the next page, and keep the last one to ask later for what came after it. A lead still being saved waits for a later call, so a kept cursor never skips one.

The feed only adds. Each lead comes once, as it stood when you read it, and what changes afterwards is not sent again: a Meta ad's names that arrive once the owner lets mpulse read the business's ads, two people joined into one, a source set by hand that is taken back, a chat or a customer deleted. To pick those up, read a recent window again with ?created_since= (for example the last 7 days, once a day) and update what you keep by id; a lead that no longer comes back in that window was deleted.

A lead carries the customer's name, phone and email as the inbox has them. Keep the key on your server, and what you read as carefully as mpulse does.

Errors

Every refusal is {"error": {"type", "code", "message", "request_id", "doc_url", "details"}}. details names each field that didn't fit and why; doc_url leads to the code's line below.

401 the key; 403 what the key may do; 404 no such list or item; 409 stale_version or a full list; 413 too big; 415 not JSON; 422 the item didn't fit; 429 slow down (Retry-After).

The code of a refusal (error.code), or of a warning in a write's answer (warnings[].code).

missing_key401. No key came with the call. Send it in the header: Authorization: Bearer mpk_…
invalid_key401. The key is not one of ours. Check that it was copied whole, with its mpk_live_ or mpk_test_ start.
key_revoked401. The owner switched the key off. Ask them for a new one.
key_expired401. The key's time ran out. Ask the owner for a new one.
key_in_url400. The key was in the address, where servers and proxies log it. A live key sent this way is switched off at once: ask for a new one and send it only in the header.
key_in_body400. A key was inside the body (in a value, a field name or an id), where it would have been stored and shown. Nothing was written, and a live key sent this way is switched off at once: ask for a new one and send keys only in the Authorization header.
api_not_enabled403. The data API is not switched on for this workspace yet.
write_only_key403. The key may only write. Reading needs a key with read access.
read_only_key403. The key may only read.
source_not_allowed403. The key may not touch that list. The owner can add the list to the key.
not_found404. No list has that id in this workspace.
item_not_found404. No item has that id. A merge (PATCH) changes only an item that exists; POST /items?mode=merge creates it.
source_not_api409. The list is read from an address or a file. Only a list your system sends can be written to.
json_only415. Send the body as JSON with Content-Type: application/json.
bad_json400. The body is not valid JSON.
too_large413. Over 64 KB for one item or 1 MB for a batch. Split it.
too_many_operations422. More than 500 operations in one batch.
bad_mode400. mode is replace or merge.
bad_limit400. limit is 1 to 100.
bad_cursor400. cursor and since take a value from an earlier answer's next_cursor; updated_since an ISO 8601 date-time.
bad_idempotency_key400. Idempotency-Key is 1 to 255 printable characters.
idempotency_mismatch422. This Idempotency-Key went with a different request in the last 24 hours. Use a new key for a new request.
idempotency_in_progress409. The first request with this Idempotency-Key is still running. Retry after Retry-After.
rate_limited429. 300 requests a minute per key, 600 per workspace. Wait the Retry-After seconds.
invalid_item422. Values did not match the list's fields. details names each one: param, code, message.
stale_version409. mpulse already has a newer version of this item, so nothing changed. Treat it as done.
source_full409. The list holds 5,000 items, the most it keeps (500 on the test side).
id_required422. The item needs its id, in the list's id field or in the address.
bad_id422. An id is a string or an integer, 1 to 200 characters.
id_mismatch422. The id in the body is not the one in the address.
personal_id422. The id looks like a person's details (an email, a phone number, a personal number), which mpulse never keeps. Use your own item id; an 11-digit product code passes once the owner marks the field not personal.
version_required422. The list orders writes by its version field: every write carries it, a delete as ?version=.
bad_version422. A version is a number (a counter, epoch milliseconds) or an ISO 8601 date-time.
personal_data422. A field holds a person's details and the owner chose to refuse them rather than leave them out.
not_an_object422. An item is a JSON object.
bad_key422. A field name is 1 to 64 characters, with no dots, not starting with $ or _mp.
too_deep422. Objects nest three levels at most.
not_supported422. A list of objects is not taken yet: send each row's values as fields of their own.
too_many_values422. A list of values holds 50 at most.
bad_value422. A value JSON cannot carry as text, a number or true/false.
too_long422. A value is 500 characters at most.
unknown_field422. The owner locked the fields, and this one is not among them.
too_many_fields422. A list keeps 50 fields at most.
not_a_number422. The field holds numbers: send 128000, not "128 000", or add ?typecast=true.
ambiguous_number422. "1.250" or "1,250" reads two ways, so it is never guessed, even with typecast. Send a JSON number.
not_a_boolean422. The field is true or false; with ?typecast=true also yes, no, 1 and 0.
not_a_date422. A date is 2026-11-14, or an ISO 8601 date-time with Z or an offset.
not_a_link422. A link starts with http:// or https://.
not_text422. The field holds text: send a string, or add ?typecast=true.
new_fieldWarning. A field the list did not have. From a live key it is kept, and switched off until the owner looks at it: the agent doesn't read it, and a key's reads leave it out of data. From a test key it is stored on the test side only, and the list's fields do not change.
new_valueWarning. A value the field had not had (status "B"): stored, and the owner is asked what it means.
personal_droppedWarning. Fields with a person's details were left out; the rest was written. The keys are named, never the values. When a field's name was itself a person's details (a phone number sent as a key), param is empty: such a name is never repeated.
encodingWarning. A value carried the � character: the text was probably sent in another encoding than UTF-8.
internal500. Something went wrong on our side. Retry with the same Idempotency-Key, and send us the request_id if it repeats.
live_key_required403. Leads are real customers' details, which a test key never reads. Use a live key with Leads switched on.
scope_missing403. The key may not read leads. The owner switches on Leads for a live key that may read.
bad_created_since400. created_since is an ISO 8601 date-time with its offset, such as 2026-11-01T00:00:00Z or 2026-11-01T00:00:00+04:00: one without an offset is never guessed.
unknown_param400. /leads takes limit, cursor (or since), created_since, kind and source; any other parameter is refused, so a misspelt one never reads as the whole list.
bad_filter400. kind is ad, link, web or manual; source names a source (google) or a source and its medium (google:cpc).

Limits

300 requests a minute per key, 5,000 items a list, 500 operations and 1 MB a batch, 64 KB an item, 500 characters a value. Numbers are strict: send 128000, not "128 000" (or add typecast=true).

A Georgian platform for customer conversations.

info@mpulse.ge
Tbilisi, Georgia

Product

  • One inbox
  • Where every lead came from
  • Auto-replies
  • Reports
  • Bookings
  • Phone app
  • Webhooks and calendar
  • Pricing
  • Custom builds

Channels

  • Channels
  • WhatsApp
  • Instagram
  • Messenger
  • Website chat

Industries

  • Industries
  • Real estate and developers
  • Clinics and dentists
  • Beauty and salons
  • Car dealers
  • Online shops
  • Restaurants and delivery
  • Hotels and guesthouses
  • Fitness and studios
  • Schools and courses
  • Repair and services

Compare

  • Compare
  • mpulse or the WhatsApp Business app
  • mpulse or a spreadsheet and three phones
  • mpulse or Bitrix24
  • mpulse or FollowUP

Company

  • Log in
© 2026 mpulse
PrivacyTermsDelete your data