Developers and integrations
Qanas finds leads on Google Maps and pushes them straight into your system. This page covers the three ways to connect, and what you need to know before writing a line.
Three ways to connect
The simplest route: one JSON POST to an endpoint you choose, per event. Works with any system.
Available nowA native two-way connection, set up with one click from inside Odoo, no code.
Available nowFull control: request a search from your own system, follow it, take the results.
Available nowHubSpot and Zoho receive leads today through Zapier or Make - we do not call their APIs directly. A native connector for each is on our roadmap and coming soon.
Webhook
You add the URL and a secret on the Integrations page, and we start sending one request per event. Works with Zapier, Make, n8n, or an endpoint you write yourself.
Events
| Event | When it is sent |
|---|---|
lead.created | A new lead has been found |
lead.updated | A lead's status or details changed |
test | You pressed Test connection |
Headers
| Header | Meaning |
|---|---|
X-Qanas-Event | The event type, the same value as `event` in the body |
X-Qanas-Delivery | Unique per delivery. A retry of the same delivery reuses the id, so you can drop a duplicate. |
X-Qanas-Timestamp | Send time, unix seconds |
X-Qanas-Signature-256 | The signature to use: it covers the timestamp as well as the body, so a captured request cannot be replayed later. |
X-Qanas-Signature | The older signature, over the body alone. Kept for anyone already using it; use the one above for new work. |
Request body
POST https://your-endpoint.example/qanas
Content-Type: application/json
X-Qanas-Event: lead.created
X-Qanas-Delivery: 7f3c1e9a-...
X-Qanas-Timestamp: 1790000000
X-Qanas-Signature-256: sha256=...
{
"event": "lead.created",
"lead": {
"id": 10492,
"name": "...",
"mobile": "+9665...",
"phone": "+96611...",
"email": "...",
"website": "https://...",
"address": "...",
"city": "...",
"country": "...",
"country_code": "SA",
"rating": 4.6,
"review_count": 214,
"status": "new",
"notes": "",
"keywords": "...",
"project": "...",
"google_maps_url": "https://www.google.com/maps/..."
}
}
Empty fields are sent as an empty string, not null. A lead.updated event also carries a `changes` object holding only what changed.
When a lead changes
A lead.updated event sends the whole lead, plus a changes object holding only the fields that changed, each as [before, after].
{
"event": "lead.updated",
"lead": { "...": "the full lead, as above" },
"changes": { "status": ["new", "contacted"] }
}
Verifying the signature
Compute HMAC-SHA256 over the timestamp, a dot, then the raw body, using your secret, and compare it with the header.
import hmac, hashlib, time
MAX_AGE = 300 # seconds
def valid(secret, timestamp, raw_body, header):
if abs(time.time() - int(timestamp)) > MAX_AGE:
return False # too old to accept
expected = "sha256=" + hmac.new(
secret.encode(),
timestamp.encode() + b"." + raw_body,
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(expected, header)
Use the raw body exactly as received, not a re-serialised copy: any difference in whitespace or key order breaks the signature. Reject the request if the timestamp is too old.
What your reply does
| Your reply | What we do |
|---|---|
2xx | The delivery counts as successful and we record your id for it. |
400, 422 | That one lead was refused. We do not retry it, and it appears on the Integrations page. |
409 | Treated as a conflict on one record, retried with backoff. |
| Anything else, or no response | We assume the problem is general rather than about this one lead, so we pause with a growing delay and the job keeps its attempts. |
Retries and failures
Nothing is sent from the request path. Every event goes into a queue and one worker sends them, one at a time, so two pushes can never race each other into one record.
- If your system is unreachable or refuses everything alike, we pause with a growing delay and the job keeps its attempts - no lead is lost during your outage.
- A 400 or 422 means that one lead was refused, so we do not retry it. Anything else is retried with backoff.
- What fails for good appears on the Integrations page with a Retry button, so nothing disappears quietly.
Lead fields
The same fields are sent by the webhook and returned by the API. A field with no value is sent as an empty string, except rating and review_count which are null.
| Field | Type | Notes |
|---|---|---|
name | string | The business name as it appears on Google Maps |
mobile | string | A mobile number in E.164. This or the email is what makes a lead chargeable. |
phone | string | A landline, if there is one. On its own it does not make a lead chargeable. |
email | string | Extracted from the business website when that option is on; generic and placeholder addresses are rejected. |
website | string | The website as Google reports it. It may be a social page. |
address | string | The full address as a single string |
city, country | string | The city and country the search used |
country_code | string | Two-letter country code, ISO 3166-1 |
rating | number / null | From 1 to 5, or null when the business has no rating |
review_count | integer / null | Number of reviews, or null |
status | string | new on creation. It changes from Qanas or from your system. |
keywords | string | The keyword that found this lead |
google_maps_url | string | A link to the business on Google Maps |
REST API
Use this when you want your own system to ask for a search. Authenticate with a Bearer token issued when you connect; we store it as a SHA-256 hash, so a leaked database does not leak it.
Authentication
Every call carries a Bearer token. The token is issued when you connect: your system sends the customer's browser to Qanas, they approve, and you get back a one-time code which your server exchanges for an access token. No long-lived secret passes through the browser, and the code is valid for ten minutes, once.
Authorization: Bearer qat_...
We store the token as a SHA-256 hash, so a leaked database does not leak it. We cannot show it again after issuing it, so keep your copy. To revoke it, call disconnect.
Endpoints
| Endpoint | What it does |
|---|---|
POST /api/v1/lead-requests | Starts a search and returns a request id |
GET /api/v1/lead-requests/<id> | Progress, and the leads once it has finished |
POST /api/v1/lead-requests/<id>/ack | Tells us which record each lead became in your system |
POST /api/v1/enrich | Looks businesses you already have up on Google Maps and fills in their details |
GET /api/v1/account | Who is connected, the credit balance, and prices |
POST /api/v1/purchase-link | A link to buy credits without signing in |
POST /api/v1/disconnect | Revokes this token |
Requesting a search
One call starts the search and returns a request id immediately. The search runs in the background, so the call does not block until it finishes.
curl -X POST https://qanas.jawab.sa/api/v1/lead-requests \
-H "Authorization: Bearer qat_..." \
-H "Content-Type: application/json" \
-d '{
"lead_number": 50,
"keywords": ["car spare parts", "auto parts"],
"country_code": "SA",
"areas": ["Riyadh", "Jeddah"],
"find_emails": true,
"external_ref": "odoo-campaign-18"
}'
| Field | Type | Notes |
|---|---|---|
lead_number | integer | How many new leads you want. Duplicates do not count towards it. |
keywords | string[] | A list of strings, not one string. Every keyword is searched in every area. |
country_code | string | Two-letter country code. Or send country_name instead. |
areas | string[] | Cities or districts. Leave it out and we search the whole country. |
find_emails | boolean | Turn on email extraction from the businesses' websites. An email that is found is charged. |
external_ref | string | Your own id for the request. Repeating it returns the first request instead of starting a second search. |
lang | string | ar or en. Sets the language of result names and messages. |
The response
201 Created
{
"request": {
"id": 412,
"external_ref": "odoo-campaign-18",
"state": "running",
"lead_number": 50,
"progress": { "done": 0, "total": 0, "step": "..." },
"new_count": 0,
"credits_charged": 0,
"error": "",
"created_at": "...",
"finished_at": null
},
"balance": 1840,
"estimate": 50
}
Follow the request with a GET on its id. While the state is running there is no leads field; it appears with the first final state.
state | Meaning |
|---|---|
running | The search is running. Follow progress. |
done | Finished. The leads field holds the results and credits_charged what was charged. |
cancelled | Cancelled; whatever was found before that is kept and charged. |
error | Failed. The error field says why, and only what was found is charged. |
Once you have created the records on your side, send ack with each record id, so we know what each lead became and never push it a second time.
Limits
| Limit | Value |
|---|---|
| Calls per client | 120 / minute |
| Most leads in one request | 200 |
| Most keywords | 10 |
| Most areas | 10 |
| Requests running at once | 3 |
| Most businesses in one enrich call | 50 |
Errors
Every error comes back in the same shape: a stable code to branch on, a message in the request's language to show, and extra fields where they help.
{
"error": {
"code": "insufficient_credits",
"message": "...",
"balance": 3,
"need": 50
}
}
code | HTTP | Meaning |
|---|---|---|
bad_request | 400 | A missing field or an unacceptable value. The field key names it. |
unauthorized | 401 | The token is missing, wrong or revoked. |
insufficient_credits | 402 | Not enough credit. Comes with balance and need. |
account_suspended | 403 | The account is suspended. |
not_found | 404 | No request with that id for this client. |
rate_limited | 429 | You passed the calls-per-minute limit. Retry after a pause. |
too_many_running | 429 | You already have the maximum number of requests running. Wait for one to finish. |
daily_limit | 429 | You passed the daily enrich limit. |
service_unavailable | 503 | The service is temporarily unavailable. Retry later. |
What you are charged for
Nothing is reserved up front. One credit per new lead that carries a real way to reach the business - a mobile number or an email. Duplicates are free, a lead with no way to reach it is free, and a search that finds nothing costs nothing. The integrations, the webhook and the API carry no extra fee.
- One credit per new lead that carries a mobile number or an email.
- Duplicates are free, a lead with no way to reach it is free, and a search that finds nothing costs nothing.
- The integrations, the webhook and the API carry no extra fee.
Getting started
Create an account, open the Integrations page, and pick Webhook or Odoo. You can test before committing anything, and registration includes free credits - enough to try the integration end to end.