MiVida ↔ In4Suite Integration API

01Terminology

The two systems use the same words for different things. In this guide, “lead” and “opportunity” always mean In4Suite’s terms unless stated otherwise.

02Quick start

Three calls: get a token, push the customer, push their opportunity.

# 1. Get an access token (valid 24 hours)
curl -X POST https://<mivida-host>/api/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"client_id": "<your client id>", "client_secret": "<your client secret>"}'
# → {"token": "eyJ0eXAiOiJKV1Qi..."}

# 2. Push a lead (customer profile)
curl -X POST https://<mivida-host>/api/in4suite/leads \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1Qi...' \
  -H 'Content-Type: application/json' \
  -d '{
        "lead_id": "LD-000123",
        "customer_name": "Aisha Rahman",
        "customer_phone": "+971501234567",
        "customer_country_code": "AE",
        "customer_email": "aisha.rahman@example.com",
        "created_at": "2024-03-14T10:22:00+04:00"
      }'

# 3. Push an opportunity for that lead
curl -X POST https://<mivida-host>/api/in4suite/opportunities \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1Qi...' \
  -H 'Content-Type: application/json' \
  -d '{
        "opportunity_id": "OP-004567",
        "lead_id": "LD-000123",
        "customer_name": "Aisha Rahman",
        "customer_phone": "+971501234567",
        "customer_country_code": "AE",
        "project_id": "PRJ-104",
        "area": "0192a1b2-55aa-7b31-8c12-44ab77cd1200",
        "unit_type": "2 BHK Type B",
        "budget": "1500000-1800000",
        "source_category": "Digital",
        "source": "Facebook",
        "assigned_agent_id": "USR-0042",
        "created_at": "2024-03-14T10:25:00+04:00"
      }'

03Authentication

MiVida uses the OAuth2 client-credentials grant. MiVida issues you a client_id and client_secret through a secure channel, never in plain-text email.

• Tokens are valid for 24 hours. Request a new one before expiry, or when a call returns 401.
• The /api/in4suite/* endpoints accept only tokens issued to the In4Suite client. Any other token, including a MiVida user’s login token, gets 403.
• Invalid credentials on /auth/token return 403 Invalid client credentials.

04Conventions

Your IDs are the keys

Every record is addressed by your ID (lead_id, opportunity_id). You never need to store MiVida’s IDs, though responses include them (mivida_customer_id, mivida_opportunity_id, mivida_lead_id, mivida_project_id) for support conversations. IDs are strings of up to 64 characters and may contain anything except /.

Projects and agents are addressed by your IDs too: MiVida stores your project id and agent id on its own project and employee records (fields, agent assignment).

Create-or-update with POST is safe to retry

POST creates the record if MiVida doesn’t know the ID yet, and updates it if it does. Re-sending the same payload never creates duplicates, so retrying after a timeout or network error is always safe.

PUT and PATCH on /…/{id} only update. They return 404 if MiVida doesn’t know the ID.

Partial updates

On update, only the fields you send change. Fields you omit keep their current value.

• “Required” fields are required to create. On update you may omit them, but you can’t blank them: "" or null gives 422.
• created_at is used on create only and ignored on update.
• Unknown fields are ignored, so extra fields won’t break a call.

Dates and times

• Send ISO 8601 with a UTC offset, e.g. 2024-03-14T10:22:00+04:00 or 2024-03-14T06:22:00Z. A value without an offset is read in MiVida’s business timezone.
• Received timestamps are always UTC, e.g. 2024-03-14T06:22:00Z.
• created_at may not be in the future. Five minutes of clock skew are tolerated.

Response shapes

Single write (POST, PUT, PATCH). warnings lists non-fatal notes. The record was saved (example).

{ "result": "created", "warnings": [], "data": { ...record... } }

Lookup (GET):

{ "data": { ...record... } }

Validation failure (HTTP 422). Every problem is listed, by field name:

{
  "errors": [
    { "field": "customer_country_code", "message": "customer_country_code \"ZZ\" is not a known ISO2 country code or dial code." },
    { "field": "created_at", "message": "created_at cannot be in the future." }
  ],
  "code": 422
}

Other errors (400, 401, 403, 404, 500):

{ "errors": { "name": "Not Found", "message": "No record with lead_id \"LD-9\" exists in MiVida.", "status": 404 }, "code": 404 }

HTTP status summary

05Endpoints

Base URL: https://<mivida-host>/api

06Leads (customer profiles)

Fields

Behaviour

• Matching existing customers. If MiVida doesn’t know your lead_id yet but already has a customer with the same email (checked first) or phone, that customer is linked to your lead_id (result: "linked") and updated with your fields. No duplicate is created.
• Conflict. If that email or phone belongs to a customer already linked to a different lead_id, you get 422 naming the other lead. Two In4Suite leads can’t share an email or phone in MiVida.
• Copies stay in sync. MiVida keeps a copy of the customer’s name, phone, email and country on each of their opportunities and leads. Updating the lead updates those copies too.

Example: update one field

PATCH /api/in4suite/leads/LD-000123
Content-Type: application/json

{ "customer_phone": "+971509999999" }

{
  "result": "updated",
  "warnings": [],
  "data": {
    "lead_id": "LD-000123",
    "mivida_customer_id": "0192a1b2-7c44-7e9a-bf21-2b1c9d4e5f60",
    "customer_name": "Aisha Rahman",
    "customer_phone": "+971509999999",
    "customer_country_code": "AE",
    "customer_email": "aisha.rahman@example.com",
    "salutation": null,
    "customer_category": null,
    "customer_location": null,
    "preferred_contact_method": null,
    "preferred_contact_time": null,
    "created_at": "2024-03-14T06:22:00Z",
    "updated_at": "2026-10-07T08:15:31Z"
  }
}

07Opportunities

Fields

Fields marked master data are sent as your In4Suite names (e.g. 2 BHK Type B, Walk-In). MiVida keeps its lists in sync with In4Suite’s and matches names ignoring case, spaces and separators. area is the exception: a MiVida unit size id from the MiVida Master Data sheet. The customer’s email isn’t sent with the opportunity; MiVida takes it from the lead.

Agent assignment

Agents are identified by your In4Suite id for them, matched exactly against the In4Suite ID set on each MiVida employee. Employee codes are not accepted.

{
  "result": "created",
  "warnings": ["Employee USR-0222 has no MiVida user account; the opportunity is left unassigned. It can be assigned once the account exists."],
  "data": { "opportunity_id": "OP-004568", "status": "unassigned", "is_agent_assigned": false, "assigned_agent_id": "USR-0222", "...": "..." }
}

Response fields

Rules to know

• One customer, many opportunities. A lead may have any number of opportunities. MiVida doesn’t treat them as duplicates.
• Changing project_id without area is rejected if the stored area belongs to the old project. Send the new project’s area with it.
• Changing source_category without source is rejected if the stored source belongs to the old category. Send a source from the new category, or "source": "" to clear it.
• A lead deleted in MiVida. If a MiVida user deletes the lead, In4Suite updates still apply to the opportunity, and the response carries a warning saying so.
• An opportunity deleted in MiVida can’t be re-created with the same opportunity_id (422). Contact MiVida if this happens.

08Historical records

An opportunity whose created_at falls before today, in MiVida’s business timezone, is historical. MiVida decides this once, when the record is created; updates never change it.

Historical records:

• keep their original dates (created, assigned, stage), so reports place them in the right period;
• are archived: kept out of agents’ work lists, dashboards, funnel reports, automatic lead scoring and reminders;
• trigger no notifications to agents or customers, and are not synced back to In4Suite;
• are never auto-assigned;
• stay searchable in MiVida (filter “Historical: Yes”). A MiVida admin can un-archive one, for example when the customer comes back.

09Batches and the initial load

Batch endpoints

POST /api/in4suite/opportunities/batch
Content-Type: application/json

{ "items": [ { ...opportunity... }, { ...opportunity... } ] }

• Up to 100 items per request. More returns 400.
• Each item has the same fields as the single endpoint and is created or updated independently. A failing item doesn’t affect the others, even when MiVida hits an internal error on it: that item is reported as failed with an “internal error” message and the rest of the batch still runs.
• The response is 200 whenever the body is well formed. Check each item’s result. index is the item’s position in your items array.

{
  "summary": { "total": 2, "created": 0, "updated": 1, "linked": 0, "failed": 1 },
  "results": [
    { "index": 0, "opportunity_id": "OP-1", "result": "updated", "warnings": [],
      "mivida_opportunity_id": "...", "mivida_lead_id": "...", "is_historical": true },
    { "index": 1, "opportunity_id": "OP-3", "result": "failed",
      "errors": [ { "field": "lead_id", "message": "In4Suite lead \"LD-404\" has not been pushed to MiVida yet. Push the lead first, then retry this opportunity." } ] }
  ]
}

Loading about 200,000 historical records

1. All leads first, through POST /in4suite/leads/batch. An opportunity is rejected if its lead hasn’t arrived yet.
2. Then all opportunities, through POST /in4suite/opportunities/batch.
3. Send 100 items per request, with at most 4 requests in parallel.
4. Collect the failed items, fix them and re-send only those. Re-sending items that already succeeded is harmless.
5. A failure reading “This record was being written by another request at the same time” means two parallel requests raced for the same ID. Retry it.
6. Start with a dry run on MiVida’s staging environment using a few thousand records, to check the master-data mapping and throughput.

After the initial load, push changes as they happen through the single endpoints or batches.

10Changes sent back to In4Suite

MiVida notifies In4Suite when a MiVida user changes a record that came from In4Suite. Changes In4Suite sent itself are not echoed back, and historical records aren’t synced.

Delivery

• POST <your URL> with a JSON body.
• Headers: Content-Type: application/json, Authorization: Bearer <token you give us>, Idempotency-Key: <event_id>.
• Any 2xx response counts as delivered. Anything else, or a 15-second timeout, is retried up to 8 times, about a minute apart.
• Delivery is at-least-once: use event_id to discard duplicates. Order isn’t guaranteed; compare occurred_at if order matters.

Envelope

{
  "event_id": "0192a1c0-1d2e-7f30-8a41-5b6c7d8e9f00",
  "event": "opportunity.assigned",
  "occurred_at": "2026-10-07T08:15:31Z",
  "data": { ... }
}

Events

MiVida pipeline statuses, in order

1. opportunity
2. site_visited
3. booked
4. sold
5. loo_executed
6. min_deposit_paid
7. afl_requested
8. afl_issued
9. afl_executed

LOO is the Letter of Offer; AFL is the Agreement for Lease.

11Error messages

12Go-live checklist

• MiVida provides client_id / client_secret for each environment (staging, production).
• MiVida sets the In4Suite Project ID on every project In4Suite will send opportunities for.
• MiVida sets the In4Suite ID on every employee In4Suite assigns opportunities to.
• In4Suite verifies the master data mapping (unit sizes, unit types, source categories and sources) against the MiVida Master Data sheet.
• Dry run of the historical load on staging; review the failed items.
• In4Suite provides the sync-back URL and token.
• Production historical load: leads, then opportunities.
• Switch to live pushes.

Coming next

• Bookings (next phase): In4Suite bookings will update MiVida pipeline stages, including for historical records.
• Activity history (calls, notes, site visits) is out of scope for this phase.

13Changes in 1.1

What changed since version 1.0. The first three rows change what you send or receive.