New Your free digital business card from QCards, shared with an NFC tap or a QR code Create your free card
Qanas Market testing and lead generation platform

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

Webhook

The simplest route: one JSON POST to an endpoint you choose, per event. Works with any system.

Available now
Odoo and Jawab

A native two-way connection, set up with one click from inside Odoo, no code.

Available now
REST API

Full control: request a search from your own system, follow it, take the results.

Available now

HubSpot 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

EventWhen it is sent
lead.createdA new lead has been found
lead.updatedA lead's status or details changed
testYou pressed Test connection

Headers

HeaderMeaning
X-Qanas-EventThe event type, the same value as `event` in the body
X-Qanas-DeliveryUnique per delivery. A retry of the same delivery reuses the id, so you can drop a duplicate.
X-Qanas-TimestampSend time, unix seconds
X-Qanas-Signature-256The signature to use: it covers the timestamp as well as the body, so a captured request cannot be replayed later.
X-Qanas-SignatureThe 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 replyWhat we do
2xxThe delivery counts as successful and we record your id for it.
400, 422That one lead was refused. We do not retry it, and it appears on the Integrations page.
409Treated as a conflict on one record, retried with backoff.
Anything else, or no responseWe 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.

FieldTypeNotes
namestringThe business name as it appears on Google Maps
mobilestringA mobile number in E.164. This or the email is what makes a lead chargeable.
phonestringA landline, if there is one. On its own it does not make a lead chargeable.
emailstringExtracted from the business website when that option is on; generic and placeholder addresses are rejected.
websitestringThe website as Google reports it. It may be a social page.
addressstringThe full address as a single string
city, countrystringThe city and country the search used
country_codestringTwo-letter country code, ISO 3166-1
ratingnumber / nullFrom 1 to 5, or null when the business has no rating
review_countinteger / nullNumber of reviews, or null
statusstringnew on creation. It changes from Qanas or from your system.
keywordsstringThe keyword that found this lead
google_maps_urlstringA 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

EndpointWhat it does
POST /api/v1/lead-requestsStarts 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>/ackTells us which record each lead became in your system
POST /api/v1/enrichLooks businesses you already have up on Google Maps and fills in their details
GET  /api/v1/accountWho is connected, the credit balance, and prices
POST /api/v1/purchase-linkA link to buy credits without signing in
POST /api/v1/disconnectRevokes 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"
          }'
FieldTypeNotes
lead_numberintegerHow many new leads you want. Duplicates do not count towards it.
keywordsstring[]A list of strings, not one string. Every keyword is searched in every area.
country_codestringTwo-letter country code. Or send country_name instead.
areasstring[]Cities or districts. Leave it out and we search the whole country.
find_emailsbooleanTurn on email extraction from the businesses' websites. An email that is found is charged.
external_refstringYour own id for the request. Repeating it returns the first request instead of starting a second search.
langstringar 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.

stateMeaning
runningThe search is running. Follow progress.
doneFinished. The leads field holds the results and credits_charged what was charged.
cancelledCancelled; whatever was found before that is kept and charged.
errorFailed. 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

LimitValue
Calls per client120 / minute
Most leads in one request200
Most keywords10
Most areas10
Requests running at once3
Most businesses in one enrich call50

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
      }
    }
codeHTTPMeaning
bad_request400A missing field or an unacceptable value. The field key names it.
unauthorized401The token is missing, wrong or revoked.
insufficient_credits402Not enough credit. Comes with balance and need.
account_suspended403The account is suspended.
not_found404No request with that id for this client.
rate_limited429You passed the calls-per-minute limit. Retry after a pause.
too_many_running429You already have the maximum number of requests running. Wait for one to finish.
daily_limit429You passed the daily enrich limit.
service_unavailable503The 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.