Partner API

The Partner API lets your CRM, your own software or an automation tool work with the leads your organization can see in Smartify Pro: leads you own and leads Smartify shares with you. You can read them, move them through the pipeline, add notes, activities, tasks, reminders and files, unlock shared leads, and refer customers to Smartify. For real-time updates, add a webhook.

Base URL

https://api.pro.smartify.in/v1

The paths below are relative to this base URL. Every request is over HTTPS and uses JSON.

API keys

1. An owner or admin of your organization opens Settings → Integrations in Smartify Pro and creates a key, choosing the scopes it needs.
2. The key (spk_live_…) is shown once. Store it in your secret manager; Smartify keeps only a hash of it.
3. Send it on every request: Authorization: Bearer spk_live_…

export SMARTIFY_API_KEY="spk_live_your_key_here"
curl -s -H "Authorization: Bearer $SMARTIFY_API_KEY" https://api.pro.smartify.in/v1/me

• A key belongs to your organization, not to a person, and sees exactly what your team sees in the app, never more.
• Up to 10 active keys per organization. A revoked key stops working within about a minute.
• A key cannot manage keys. It can manage webhook endpoints only with the webhooks:manage scope, and only the ones it created.
• A key never sees partnership, dealership, Smartify Pro or support inquiries, even if one was shared with you.

Scopes

Each key has one or more scopes. A request that needs a scope the key lacks gets 403 insufficient_scope.

Give a key only the scopes its job needs. GET /me works with any key and lists the key's scopes.

Endpoints

Read

Lists return data, next_cursor and has_more. Pass next_cursor back as after until has_more is false or data is empty. A cursor only resumes the listing that issued it.

Write

The catalog endpoints are on their own page.

How writes behave

• A key acts as your organization in the app, never as an admin. A write succeeds only when the same action would succeed for your team in Smartify Pro.
• A lead your organization cannot see answers 404 lead_not_found, the same as a lead that does not exist. A shared lead you have not unlocked answers 403 lead_locked to anything that touches its details.
• Every successful write returns the lead's new ETag header. Create calls return 201 with the new item in data. Deletes return 204 with no body.
• Writes show up in your webhook feed with an origin naming your key, so you can ignore your own echoes.

Keep your CRM in step

Store the updated_at of the newest lead you processed, and ask for changes from that time:

curl -s -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  "https://api.pro.smartify.in/v1/leads?updated_since=2026-11-13T00:00:00Z&limit=100"

The boundary is inclusive, so you can see the same lead twice: upsert by lead_id. With webhooks set up, use this feed only to catch up after downtime.

What a lead shows

You get the same fields the app shows your organization. A lead shared with you but not yet unlocked is a preview ("masked": true, no contact details), and its history answers 403 lead_locked until you unlock it.

In history, your own team's entries show their names. Everything else, including work Smartify's team did before sharing the lead, is credited to Smartify (created_by: "smartify").

Edit a lead

PATCH /leads/{leadId}

Only leads your organization added by hand can be edited. A lead Smartify shared or assigned to you answers 403 not_editable.

Send any of these fields; the rest stay as they are.

curl -s -X PATCH https://api.pro.smartify.in/v1/leads/CRM-1794550000000-123 \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: W/"2026-11-13T10:15:02.874Z"' \
  -d '{ "city": "Pune", "requirements_text": "3 BHK, wants curtain motors" }'

The response is { "data": { …the lead… } } with the new ETag. A body with no editable fields is 400 invalid_parameter.

Change a lead's stage

POST /leads/{leadId}/stage

curl -s -X POST https://api.pro.smartify.in/v1/leads/CRM-1794550000000-123/stage \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-8841" \
  -d '{ "to": "WON", "deal_value": 150000, "note": "Signed today" }'

The response is { "data": { …the lead… } } with the new ETag.

Stage moves follow the same rules as the app:

CUSTOMER_ACCEPTED is set by Smartify when a customer accepts a quote on the public quote page. You cannot move a lead into it.

Moving to LOST also needs a reason of price_too_high, chose_competitor, project_postponed, no_response or other. Moving to NOT_INTERESTED needs declined_before_quote, wrong_contact, project_cancelled or other.

A move the rules do not allow answers 422 stage_transition_not_allowed, and tells you what is allowed from where the lead is now:

{
  "type": "about:blank",
  "title": "Unprocessable request",
  "status": 422,
  "detail": "A lead can't move from NEW to WON.",
  "code": "stage_transition_not_allowed",
  "from": "NEW",
  "allowed_transitions": [{ "to": "UNLOCKED", "requires_reason": false }]
}

requires_reason is true when the move needs a reason. For LOST and NOT_INTERESTED the entry also has a reasons array with the values you may send; for moves backwards or re-opening the reason is free text. A missing or invalid reason or deal_value answers 400 invalid_parameter with detail saying what to fix.

Notes, activities, tasks and reminders

All four are added with a POST on the lead and return 201 with the new item in data. Tasks, reminders and activities can then be changed with PATCH (send only the fields to change) and removed with DELETE.

Notes

curl -s -X POST https://api.pro.smartify.in/v1/leads/CRM-1794550000000-123/notes \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-note-5521" \
  -d '{ "note": "Customer asked for a site visit on Saturday." }'

note is required, up to 2000 characters.

Activities

Any other field is refused with 400 invalid_parameter.

curl -s -X POST https://api.pro.smartify.in/v1/leads/CRM-1794550000000-123/activities \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-call-9917" \
  -d '{ "type": "call", "content": "Walked through the quote.", "direction": "outbound", "outcome": "connected", "duration_seconds": 420 }'

Tasks

curl -s -X POST https://api.pro.smartify.in/v1/leads/CRM-1794550000000-123/tasks \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Send curtain motor quote", "due_date": "2026-11-20" }'

Reminders

Ids and legacy items

Every item has an id. Items written before ids existed get ids like legacy_<16 hex characters>. Use them like any other id in PATCH and DELETE paths.

An item that does not exist answers 404 not_found. Editing two different items on one lead at the same time is safe: both changes land. In the rare case two writes hit the same lead at the very same instant, one can answer 409 conflict; send it again.

Files

Attaching a file takes two requests. Files can be PDFs, images (PNG, JPEG, WebP, GIF, HEIC), Word and Excel files, CSV, plain text and DWG or DXF drawings, up to 15 MB each, and a lead holds up to 50 files (the 51st answers 409).

1. Ask for an upload URL:

curl -s -X POST https://api.pro.smartify.in/v1/leads/CRM-1794550000000-123/attachments/upload-url \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "floor-plan.pdf", "file_type": "application/pdf", "file_size": 482113 }'

The response is { "data": { "upload_url": "…", "file_url": "…" } }. The upload_url is valid for 15 minutes.

2. PUT the file to upload_url with the same Content-Type and a Content-Length equal to file_size.

3. Record it on the lead, using the file_url from step 1:

curl -s -X POST https://api.pro.smartify.in/v1/leads/CRM-1794550000000-123/attachments \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "floor-plan.pdf", "file_type": "application/pdf", "file_url": "FILE_URL_FROM_STEP_1", "file_size": 482113 }'

Smartify checks that the file exists, its type and its real size before recording it.

Unlock a shared lead

curl -s -X POST https://api.pro.smartify.in/v1/leads/CRM-1794550000000-123/unlock \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H "Idempotency-Key: unlock-CRM-1794550000000-123"

The response is { "data": { …the unlocked lead… } } with the new ETag. Unlocking needs the leads:unlock scope and spends credits exactly as unlocking in the app does. If your organization cannot pay for it, the answer is 402 payment_required and carries a subscription_url, where you can unlock without credits:

{
  "type": "about:blank",
  "title": "Payment required",
  "status": 402,
  "detail": "…",
  "code": "payment_required",
  "subscription_url": "https://pro.smartify.in/settings/billing"
}

Always send an Idempotency-Key on unlock, so a retry after a timeout cannot spend credits twice.

Refer a customer to Smartify

POST /referrals

Needs the referrals:write scope. Smartify contacts the customer on WhatsApp to confirm, and you earn the referral commission if the referral converts.

curl -s -X POST https://api.pro.smartify.in/v1/referrals \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: referral-2026-11-13-001" \
  -d '{
    "name": "Test Customer",
    "phone": "+910000000000",
    "city": "Pune",
    "reason": "Wants a smart home setup for a new 3 BHK",
    "notes": "Prefers calls after 6 pm"
  }'

{
  "data": {
    "message": "Referral submitted. Customer will receive a WhatsApp verification.",
    "lead_id": "REF-1794550000000-123",
    "whatsapp_delivery": "SENT"
  }
}

whatsapp_delivery is SENT when the verification went out and FAILED when it could not be confirmed. The referral is created either way.

A customer who is already known to Smartify answers 409 conflict. A referral that your organization sharing has been suspended for answers 403 forbidden.

Idempotency

Send an Idempotency-Key header on any POST to make it safe to retry. It must be 1 to 255 printable characters, or the answer is 400 invalid_parameter. Use a value that is unique for each thing you mean to do, such as an id from your own system.

• The same key with the same request within 48 hours replays the first response, without doing the work again.
• The same key with a different request (a different body, lead or endpoint) answers 422 idempotency_key_reused.
• The same key while the first request is still running answers 409 idempotency_in_progress. Wait a moment and retry.
• Server errors (5xx) are not stored, so retry them with the same key. Other answers, including refusals such as 422 or 403, are stored and replayed: after fixing the request, use a new key.
• Keys are scoped to the API key that sent them.
• This holds for notes and activities too: a retry with the same key never adds a second note or activity.
• Catalog submissions do not take an Idempotency-Key; a submission is keyed by your SKU (see the Partner Catalog API).

PATCH and DELETE are naturally safe to repeat, so they do not take the header. They do take If-Match (below).

Conditional writes with ETag

Every read and write of a lead returns ETag: W/"<updated_at>". Send that value back in an If-Match header on a PATCH, a DELETE or a stage change to make the write conditional: if the lead changed in the meantime, the write is refused with 412 precondition_failed and nothing changes. Fetch the lead again and decide what to do.

curl -s -X DELETE https://api.pro.smartify.in/v1/leads/CRM-1794550000000-123/tasks/task_123 \
  -H "Authorization: Bearer $SMARTIFY_API_KEY" \
  -H 'If-Match: W/"2026-11-13T10:15:02.874Z"'

If-Match is optional. It works on lead edits, stage changes and on PATCH and DELETE of activities, tasks, reminders and attachments. Without it a write goes ahead on whatever the lead looks like now.

Errors

Errors from the API are RFC 9457 application/problem+json with a stable code. Some add fields, such as allowed_transitions or subscription_url.

Some errors come from the gateway before the API sees the request. They are plain JSON with a message and no code:

Branch on the HTTP status first, then on code.

Limits

• 120 requests a minute per key. Over the limit you get 429 rate_limited with a Retry-After header; wait that many seconds.
• Up to 10 active keys per organization, and 25 webhook endpoints.

The machine-readable contract is the OpenAPI 3.1 document.

Other ways to connect

• Connect an AI assistant to Smartify Pro with Smartify Connect (sign in and approve; no key).
• Connect Zapier or Make with a webhook and an HTTP step.