API Documentation

Everything you need to integrate with Mediavox APIs.

Authentication

Server-to-server authentication via API Key header.

API Key

curl -H "X-API-Key: vxk_your_key_here" https://mediavox.co/mvvixo/api/v1/clients

Generate API keys from the Developer Portal dashboard. Keys don't expire; rotate manually when needed.

Base URLs

Product	URL
Vixo API	`https://mediavox.co/mvvixo/api/v1/`
mediaAPI	`https://mediavox.co/mvapi/api/v1/`
Turing AI	`https://mediavox.co/mvai/api/v1/`
HealthPower	`https://mediavox.co/mvai/api/v1/health/`

Rate Limiting & Quotas

Vixo API

Plan	Requests/month	Rate limit
Trial	50	30/min
Starter ($69)	500	60/min
Business ($149)	5K	120/min
Enterprise	20K	300/min

mediaAPI

Plan	API calls/month	Recognition included	Rate limit
Free	100	20	20/min
Developer ($49)	5K	1K	60/min
Growth ($99)	15K	0	90/min
Scale ($199)	50K	10K	120/min

Turing AI

Plan	Messages/month	Rate limit
Agent ($49)	2K	30/min
Expert ($149)	15K	60/min
Pro ($299)	30K	120/min
Empire ($499)	50K	120/min

Exceeding rate limit returns 429 Too Many Requests. Exceeding monthly quota returns 429 Monthly quota exceeded. Plans without overage have a hard cap.

Scopes

API keys have scopes that control access. Format: entity.action

Scope	Description
`*`	Full access to all entities and actions
`clients.*`	All actions on clients
`clients.read`	Read-only access to clients
`budgets.write`	Create/update budgets

Pagination

GET /api/v1/clients?page=1&pageSize=20

Response:

{ "data": [...], "pagination": { "page": 1, "pageSize": 20, "totalCount": 142, "totalPages": 8 } }

Read Endpoints (GET)

Sales

Endpoint	Description
`GET /clients`	Search clients
`GET /clients/{id}`	Get client by ID
`GET /contracts`	Search contracts
`GET /contracts/{id}`	Get contract by ID
`GET /contracts/{id}/projects`	Projects for a contract
`GET /projects`	Search projects
`GET /projects/{id}`	Get project by ID
`GET /projects/{id}/budgets`	Budgets for a project
`GET /opportunities`	Search opportunities
`GET /opportunities/{id}`	Get opportunity by ID
`GET /requests`	Search requests

Operations

Endpoint	Description
`GET /budgets`	Search budgets
`GET /budgets/{id}`	Get budget by ID
`GET /budgets/{id}/items`	Budget line items
`GET /purchase-orders`	Search purchase orders
`GET /production-orders`	Search production orders
`GET /advances`	Search advances
`GET /legalizations`	Search legalizations

People

Endpoint	Description
`GET /employees`	Search employees
`GET /employees/{id}`	Get employee by ID
`GET /payroll`	Search payroll periods
`GET /novelties`	Search novelties

Other

Endpoint	Description
`GET /tasks`	Search tasks
`GET /tasks/{id}`	Get task by ID
`GET /products`	Search products
`GET /products/{id}`	Get product by ID
`GET /suppliers`	Search suppliers
`GET /invoices`	Search invoices
`GET /invoices/{id}`	Get invoice by ID
`GET /invoices/{id}/lines`	Invoice line items
`GET /credit-notes`	Search credit notes
`GET /companies`	List companies
`GET /states`	List states by type

Write Endpoints (POST/PUT/DELETE)

Method	Endpoint	Description
POST	`/clients`	Create client
PUT	`/clients/{id}`	Update client
DELETE	`/clients/{id}`	Delete client
POST	`/contracts`	Create contract
POST	`/projects`	Create project
POST	`/opportunities`	Create opportunity
POST	`/requests`	Create request
PUT	`/requests/{id}`	Update request
POST	`/budgets`	Create budget
PUT	`/budgets/{id}`	Update budget
POST	`/purchase-orders`	Create purchase order
POST	`/production-orders`	Create production order
POST	`/advances`	Create advance
POST	`/legalizations`	Create legalization
POST	`/tasks`	Create task
PUT	`/tasks/{id}`	Update task
PUT	`/products/{id}`	Update product
PUT	`/suppliers/{id}`	Update supplier

Write response:

{ "success": true, "message": "Client created", "id": 123 }

State Changes

Change the state of an entity (e.g., approve, reject, close):

POST /api/v1/clients/{id}/change-state Content-Type: application/json { "newStateId": 5, "comments": "Approved" }

Available for: clients, contracts, projects, opportunities, requests, budgets, purchase-orders, production-orders, advances, legalizations, tasks

Error Responses

{ "error": { "code": "VALIDATION_ERROR", "message": "...", "correlationId": "abc-123" } }

Status	Code	Description
400	VALIDATION_ERROR	Invalid request body or parameters
401	MISSING_API_KEY	X-API-Key header not provided
401	INVALID_API_KEY	Key invalid or expired
403	SCOPE_NOT_AUTHORIZED	Key doesn't have required scope
403	MODULE_NOT_ENABLED	Module not enabled for this company
404	NOT_FOUND	Resource not found
429	RATE_LIMITED	Too many requests per minute
429	QUOTA_EXCEEDED	Monthly quota exceeded
500	INTERNAL_ERROR	Server error (check correlationId)

All inputs are automatically sanitized server-side: extra spaces, control characters, and repeated characters are normalized before processing. You don't need to pre-clean your data. Send it as-is and the API handles it.

SDK & Code Examples

Quick start examples for popular languages.

curl

curl -X GET \ -H "X-API-Key: YOUR_KEY" \ "https://mediavox.co/mvvixo/api/v1/clients?page=1&pageSize=5"

C# / .NET

// Install: dotnet add package System.Net.Http.Json using var client = new HttpClient(); client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_KEY"); // GET var clients = await client.GetFromJsonAsync<JsonElement>( "https://mediavox.co/mvvixo/api/v1/clients?page=1&pageSize=5"); // POST (mediaAPI) var response = await client.PostAsJsonAsync( "https://mediavox.co/mvapi/api/v1/datatools/names/standardize", new { text = "carlos alberto", country = "CO" }); var result = await response.Content.ReadFromJsonAsync<JsonElement>();

Python

# Install: pip install requests import requests headers = {"X-API-Key": "YOUR_KEY"} # GET clients = requests.get( "https://mediavox.co/mvvixo/api/v1/clients?page=1&pageSize=5", headers=headers).json() # POST (mediaAPI) result = requests.post( "https://mediavox.co/mvapi/api/v1/datatools/names/standardize", headers=headers, json={"text": "carlos alberto", "country": "CO"}).json()

JavaScript / Node.js

// Install: npm install node-fetch (Node.js) or use native fetch (browser) const headers = { "X-API-Key": "YOUR_KEY" }; // GET const clients = await fetch( "https://mediavox.co/mvvixo/api/v1/clients?page=1&pageSize=5", { headers }).then(r => r.json()); // POST (mediaAPI) const result = await fetch( "https://mediavox.co/mvapi/api/v1/datatools/names/standardize", { method: "POST", headers: { ...headers, "Content-Type": "application/json" }, body: JSON.stringify({ text: "carlos alberto", country: "CO" }) }).then(r => r.json());

Turing AI Endpoints

Embeddable AI assistant API. Base URL: https://mediavox.co/mvai/api/v1/

Endpoint	Description
`POST /api/v1/chat`	Send a question. Requires `key` (Turing API key). Optional: `user_context`, `geo` (lat/lng), `mobile_token`, `file` (base64) + `file_name` (attach document for analysis). Supports PDF, Excel, Word, CSV, images. Enables 110+ dynamic ERP tools. Multi-provider AI with automatic fallback.
`POST /api/v1/transcribe`	Voice-to-text. Send audio file (multipart), get transcript. Triple fallback across multiple AI providers. Rate limit: 5/min. Header: `X-Turing-Key`.
`POST /api/v1/extract-entities`	NER extraction from document (PDF, Excel, CSV, Word, TXT) or plain text. Supports `is_base64` + `file_name` for binary files. Returns structured entities + `integrity` field with: `score` (0-100), `level` (high/medium/low), and alerts. Multi-layer analysis (file structure + visual for images). Multi-provider fallback.
`POST /api/v1/feedback`	Submit feedback on a response. Requires `key`, `id_conversation`, `feedback` (1 or -1).
`POST /api/v1/clear`	Clear chat history for a session. Requires `key`, `sessionId`.
`POST /api/v1/index`	Index content into RAG. Supports `type`: text, url, file (PDF/Excel/CSV/TXT/MD).
`GET /api/v1/branding`	Get widget branding (name, color) for a tenant. Query param: `key`.
`GET /health`	Health check.
`GET /openapi/v1.json`	OpenAPI 3.x specification (machine-readable).

WhatsApp Integration

Connect your WhatsApp Business account to Turing AI. Your customers chat via WhatsApp, Turing responds with full context (tools, RAG, history). Multi-tenant: each company configures its own WhatsApp number.

Endpoint	Description
`GET /api/v1/whatsapp`	Meta webhook verification (challenge-response). Configure this URL in your Meta WhatsApp Business dashboard. Query params: `hub.mode`, `hub.verify_token`, `hub.challenge`.
`POST /api/v1/whatsapp`	Receives incoming WhatsApp messages from Meta Cloud API. Resolves tenant by `phone_number_id`, processes text/audio messages through Turing AI, and responds automatically via Meta Send API. Supports: text messages, audio transcription (coming soon). Always returns 200 to Meta.

Setup: Configure $.whatsapp in your Turing tenant: enabled, verifyToken, metaToken, phoneNumberId. Then set webhook URL in Meta Business: https://mediavox.co/mvai/api/v1/whatsapp.

Embed in your site

Attributes: data-key (required), data-theme (light/dark), data-position (bottom-right/bottom-left), data-lang (es/en).

DocumentPower (Document Analysis + La Bóveda)

Upload any document. AI extracts structured data, detects type, verifies integrity, and persists in La Bóveda for cross-document search. Deduplication by SHA256. Storage per plan quota.

Endpoint	Description
`POST /api/v1/documents/analyze`	Full analysis: type detection + integrity score + template NER + entities. Persists in La Bóveda by default (`persist: false` for stateless). Returns `vault.document_id`. Supports PDF, Word, Excel, CSV, images.
`POST /api/v1/documents/ask`	Follow-up question about a previously analyzed document. Requires `session_id` from /analyze response.
`GET /api/v1/documents/types`	List 18+ supported document types. Pass as `tipo` hint to skip auto-classification.

La Bóveda (Document Vault)

Every document analyzed is automatically stored with full-text search (FTS Spanish). Search across thousands of documents by keyword, entity, or type — months later. Deduplication prevents re-analysis of the same file ($0 if duplicate).

Endpoint	Description
`GET /api/v1/documents/vault/browse`	Paginated list of all documents. Params: `page`, `page_size` (max 100), `type` (filter by document_type). Returns: file_name, type, summary, entity_count, integrity_score, date.
`GET /api/v1/documents/vault/search`	Full-text search across all documents. Params: `q` (search query), `type` (optional filter), `limit` (max 50). Spanish stemming + metadata JSONB search. Returns relevance-ranked results.
`GET /api/v1/documents/vault/{id}`	Get full document details + all extracted entities. Returns: text_extracted, metadata (template NER fields), integrity_score, entity list.
`DELETE /api/v1/documents/vault/{id}`	Soft-delete a document (removes from browse/search, frees storage quota).

Turing Personal (User Auth)

Endpoint	Description
`POST /personal/api/signup`	Register a personal user. Body: `email`, `password`, optional `nombre`, `pais`.
`POST /personal/api/login`	Authenticate. Returns `id_user`, `email`, `nombre`.

HealthPower (Clinical Data Intelligence)

Process medical service records (RIPS), extract clinical data from PDFs, detect anomalies, and score patient risk. Base URL: https://mediavox.co/mvai/api/v1/health/. Requires X-API-Key header.

Endpoint	Description
`POST /rips/upload`	Upload RIPS CSV file (Colombia AC/AP/AH/AU pipe-separated). Multipart form: `file` (CSV), `api_key`. Returns: records processed, duplicates skipped, errors. Batch 10K with binary COPY protocol.
`GET /patients/{tipoId}/{id}/timeline`	Patient clinical timeline. All services ordered by date. Params: `tipoId` (document type: CC, TI, CE, PA), `id` (document number). Returns: procedures, diagnoses, providers, dates.
`GET /patients/{tipoId}/{id}/risk-score`	Patient risk score (0-100). Weighs: chronic diagnoses, service frequency, cost history, care gaps. High score = high projected cost.
`GET /analytics/dashboard`	Aggregated KPIs: total services, unique patients, top diagnoses (ICD-10), top providers, services by type. Query: `period` (YYYY-MM, default current month).
`GET /catalogs/{country}`	Procedure code catalog by country. Supported: `CO` (CUPS), `MX` (CAUSES), `PE` (CPT-PE), `CL` (Fonasa), `EC` (IESS). Returns: code, description, group.
`GET /analytics/anomalies`	Detected anomalies: duplicate procedures (same patient+code in configurable window), overbilling (provider charges >2x average). Returns: type, patient, provider, amount, evidence.
`GET /appointments`	List appointments with filters (date, specialist, status, patient). PII masked server-side. Paginated.
`POST /appointments`	Create appointment. Requires: id_especialista, fecha, paciente_tipo_id, paciente_id.
`PUT /appointments/{id}`	Reschedule appointment (change date, specialist, or reason).
`PUT /appointments/{id}/status`	Change status: confirmada, cancelada, completada, pendiente.
`GET /specialists`	Medical specialist directory. Filters: specialty, location, active. Paginated.
`POST /specialists`	Register specialist (`nombre`, `especialidad`, `documento_id`, `registro_medico`, `sede`, `telefono`).
`PUT /specialists/{id}`	Update specialist information.
`DELETE /specialists/{id}`	Deactivate specialist (soft delete).
`GET /patients`	Patient list with risk scores. PII masked. Filters: exact ID, min_score. Paginated.
`GET /services`	Search clinical services. Filters: date range, provider, diagnosis, patient, catalog. Paginated.
`POST /patients/sync`	Bulk sync affiliate/patient master data from insurer systems.
`POST /consent/grant`	Register Habeas Data patient consent (Ley 1581). Required before exposing data to third-party portals.
`GET /consent/status`	Check if patient has active consent for data sharing.
`GET /reconciliation`	Cross-reference services vs invoices. Identifies orphan items in both directions. Query: `period` (YYYY-MM).
`GET/PUT /alerts/config`	Get or update alert thresholds (chronic gap days, anomaly threshold, channels).
`POST /documents/ingest`	Upload clinical PDF → auto-classify → NER → persist in salud tables. Dedup by file hash. Confidence threshold configurable per empresa. Optional `tipo` parameter skips classification (see GET /documents/types).
`GET /patients/template`	Download Excel import template (Patients + Specialists + Instructions bilingual). Upload to POST /patients/sync.
`GET /documents/types`	List all available document types (18+). Use as `tipo` hint in /documents/analyze or /health/documents/ingest to skip auto-classification and save latency.
`POST /treatments`	Register treatment/prescription for adherence monitoring. Params: `paciente_id`, `medicamento`, `frecuencia_horas`, `cuidador_telefono`.
`GET /treatments`	List active treatments for empresa with pagination.
`GET /adherence/status`	Adherence compliance: cumplidas, incumplidas, pendientes, total, compliance_percent. Optional patient filter.
`POST /adherence/mark`	Mark a dose as taken (cumplido) or missed (incumplido). Params: id_adherencia, estado.
`POST /authorize`	Validate service against local authorization rules. Returns: decision (auto_approve/manual_review/rejected), copago, cuota_max_mes.
`GET /authorization/rules`	List configured authorization rules per empresa (categoria, decision, copago, cuota).
`GET /audit/rules`	List configured audit rules (7 active + 3 roadmap). Returns: codigo, nombre, tipo, parametros, activo.
`POST /audit/rules`	Create or update audit rule. Body: `codigo`, `nombre`, `tipo`, `activo`, `parametros` (JSONB thresholds).
`GET /audit/findings`	List audit findings with filters. Params: `estado`, `severidad`, `tipo`, `page`, `pageSize`. Returns: findings with total count.
`PUT /audit/findings/{id}`	Change finding status. Body: `estado` (confirmado/descartado/respondido). Ownership validated server-side.
`GET /audit/summary`	Audit KPIs: pendientes, confirmados, descartados, monto_pendiente, monto_confirmado, nuevos_semana, tasa_confirmacion.

Example: Upload RIPS

curl -X POST https://mediavox.co/mvai/api/v1/health/rips/upload \ -H "X-API-Key: vxk_your_key" \ -F "file=@rips_consultas.csv" \ -F "api_key=vxk_your_key"

Response: {"processed": 8542, "duplicates": 23, "errors": 0}

Example: Patient Risk Score

curl https://mediavox.co/mvai/api/v1/health/patients/CC/1032456789/risk-score \ -H "X-API-Key: vxk_your_key"

Response: {"score": 73, "risk_level": "high", "factors": ["diabetes_type_2", "hypertension", "gap_90_days"]}

Example: Anomalies

curl https://mediavox.co/mvai/api/v1/health/analytics/anomalies \ -H "X-API-Key: vxk_your_key"

Response: {"anomalies": [{"type": "duplicate", "patient": "CC-***6789", "code": "890302", "count": 3, "amount": 450000}]}

Interactive Docs (Swagger)

Full interactive API documentation with try-it-out:

Vixo API: mediavox.co/mvvixo/swagger

mediaAPI: mediavox.co/mvapi/swagger

Turing AI: mediavox.co/mvai/swagger

mediaAPI Endpoints

REST API across 5 domains. Base URL: https://mediavox.co/mvapi/api/v1/

DataTools: Data Quality

Endpoint	Description
`POST /datatools/names/standardize`	Standardize person or company name. 3-layer matching: exact → phonetic fingerprint + trigram similarity → AI. Accent-insensitive, firstName/lastName split (LATAM convention 2+2), gender detection, person vs company classification. extensive canonical name database.
`POST /datatools/names/batch`	Batch name standardization (up to 1K names per request)
`POST /datatools/addresses/standardize`	Parse and standardize addresses. Typo dictionary (56+ variants), accuracy score (high/medium/low), Google cache. Multi-country: CO, MX, PE, CL, EC. Returns `accuracy` + `confidence`.
`POST /datatools/addresses/batch`	Batch address standardization (up to 1K per request)
`POST /datatools/addresses/resolve`	Resolve colloquial references to formal addresses using POIs. "al lado del Ara" → lat/lng + address. Requires `text`, optional `lat`/`lng` for proximity. Returns best match + alternatives.
`POST /datatools/geocode/reverse`	Convert GPS coordinates to human-readable address. Cached permanently (same coordinates = instant response). Params: `lat`, `lng`. Returns address, city, department, country.
`POST /datatools/emails/validate`	Validate email: RFC 5322 syntax, disposable detection (118+ providers), typo correction (6K+ known typos from BD), MX record verification, domain brand identification, role account detection, free provider flagging. Returns suggested_correction and domain_brand.
`POST /datatools/emails/validate/batch`	Batch validate up to 1K emails in a single request. Same checks as single validation. Request: {"emails":["[email protected]",...]}
`POST /datatools/domains/validate`	Validate domain: DNS resolution, SSL certificate (issuer, expiry, days remaining), IPv6 support, overall scoring.

Recognition: Document Processing (AI Vision)

Endpoint	Description
`POST /recognition/documents/classify`	Classify document type from image (ID card, invoice, receipt, driver license). Powered by AI Vision.
`POST /recognition/id-documents/extract`	Extract structured data from ID documents: cédula CO, INE MX, DNI PE, CI CL. Returns name, ID number, dates, photo region.
`POST /recognition/invoices/extract`	Extract data from electronic invoices. Multi-country electronic invoice formats.
`POST /recognition/receipts/extract`	Extract data from purchase receipts: merchant, items with SKU, quantities, prices, totals, payment method.
`POST /recognition/upload`	Upload document via multipart/form-data (max 10MB). Stores in GCP, optional AI extraction. TTL: 30 days ID docs, 90 days invoices/receipts.

Finance: LATAM Financial Tools

Endpoint	Description
`POST /finance/tax-id/validate`	Validate tax ID with check digit: NIT CO (módulo 11), CC CO, RUT CL, RFC MX, CURP MX, RUC PE, DNI PE. 7 document types.
`POST /finance/tax/calculate`	Calculate taxes: retención en la fuente CO (with UVT), IVA, ICA (CO), ISR (MX), IGV (PE). Country-specific rules and brackets.
`POST /finance/invoice/format`	Format electronic invoice: Multi-country electronic invoice formatting.
`POST /finance/bank-account/validate`	Validate bank account: 50+ LATAM banks with SWIFT codes, account format validation by country.
`POST /finance/categorize-transaction`	AI-powered transaction categorization from bank statement descriptions. Returns category, subcategory, merchant, confidence.
`GET /finance/dian/validate/{nit}`	Look up Colombian NIT in business registry. Returns company name, tax regime, city.
`GET /finance/rues/search/{query}`	Search Colombian business registry by company name. Returns matching companies with NIT.

Security: Threat Intelligence

Endpoint	Description
`POST /security/threats/analyze`	Analyze any message (SMS, WhatsApp, email) for phishing, scam, or fraud: resolves ALL shortened URLs in cascade, compares final domain vs brand trusted domains, homoglyph detection, phishing pattern analysis, weighted scoring.
`POST /security/urls/analyze`	Analyze URL: follows up to 10 redirects, homoglyph detection, domain age check, SSL verification, threat database lookup.
`GET /security/threats/feed`	Shared threat intelligence feed. Paginated. Every analysis contributes to the database (network effect).
`POST /security/pin/generate`	Generate secure PIN/OTP: SHA-256 hashed, configurable length (4-8 digits), configurable expiration.
`POST /security/pin/validate`	Validate PIN: attempt tracking (max 5), automatic expiration, secure hash comparison.
`POST /security/breach/check`	Check if email/domain appears in known data breaches.
`POST /security/password/strength`	Analyze password strength: entropy, common patterns, dictionary check, scoring.
`POST /security/sanctions/check`	Sanctions list screening against 4 official lists: OFAC SDN (US Treasury, 18K+), UN Security Council (1K+), EU Financial Sanctions (6K+), PEP OpenSanctions (39K+). Fuzzy name matching + ID lookup. 65K+ total entries. Updated weekly. Note: this is a screening tool; it does not replace a full compliance program (KYC, due diligence, transaction monitoring).

Brand Intelligence: Enterprise Brand Protection

Real-time monitoring of brand impersonation across SMS, WhatsApp, email, and web. Proactive detection via Certificate Transparency 24/7 + domain scanner (3,000+ variants). Content Forensics analyzes HTML for credential harvesting and exfiltration. Interactive Threat Graph reveals organized campaigns. Average detection: under 5 minutes.

Endpoint	Description
`POST /security/brands/register`	Register a brand for protection. Provide brand name, trusted domains, alert email. Returns brand ID and verification instructions.
`POST /security/brands/verify`	Verify domain ownership via DNS TXT record or meta tag. Required before monitoring activates.
`GET /security/brands`	List all registered brands for this developer with verification status.
`PUT /security/brands/{id}/channels`	Configure monitoring channels (SMS, WhatsApp, email, web), countries, alert delivery (email, webhook, Slack), escalation rules, keywords, and trusted assets.
`GET /security/brands/{id}/channels`	Retrieve current channel and alert configuration.
`GET /security/brands/{id}/alerts`	List impersonation alerts with severity, channel, country, domain, indicators, and campaign info. Paginated, filterable by severity and status.
`POST /security/brands/{id}/alerts/{alertId}/action`	Take action: confirm_threat, dismiss, escalate, request_takedown, block_sender. Improves ML accuracy.
`GET /security/brands/{id}/dashboard`	Real-time dashboard: risk score, KPIs, threats by channel/country, active campaigns, top fraudulent domains, activity timeline.
`GET /security/brand-report`	Comprehensive intelligence report: threats detected, domain analysis, trend analysis, risk score, geographic distribution.
`GET /security/bi/summary`	CISO Dashboard KPIs. Returns: threats (30d), active threats, takedowns sent/success, avg detection time, source breakdown (scanner/ct_logs/mfd), top attack techniques. Params: `brand` (optional), `days` (default 30). Multi-tenant: only shows threats for your brands.
`GET /security/bi/timeline`	Threats per day chart data. Returns array of {date, threats, takedowns} for the last N days. Params: `brand` (optional), `days` (default 30, max 90).
`GET /security/bi/graph`	Threat Graph (vis.js-ready). Returns nodes (brands, domains, IPs, registrars, IOCs) and edges (impersonates, hosted_on, registered_at). Max 200 nodes. Params: `brand` (optional). Use for interactive force-directed visualization of campaigns.

Compliance: KYC & Batch Intelligence (NEW)

Endpoint	Description
`POST /compliance/kyc`	KYC Bundle 4 validations in 1 call: sanctions screening (OFAC/EU/UN/PEP, 65K+ entities), identity validation (NIT/RUT/RFC check digit), name standardization (AI + phonetic matching), risk score (0-100). Returns: PROCEED, REVIEW_RECOMMENDED, MANUAL_REVIEW_REQUIRED, or BLOCK. Params: `name`, `documentType` (NIT/CC/RUT/RFC), `documentNumber`, `country` (CO/CL/MX/PE).
`GET /stats`	Usage Intelligence Real-time analytics: dictionary hit rate, unique names resolved, AI calls saved, estimated savings vs competition. Shows flywheel effect: API improves with usage.
`POST /batch/upload`	Batch Processing Upload CSV/Excel (up to 10MB, 50K rows) with operations: `standardize_name`, `validate_tax_id`, `sanctions_check`, `validate_email`, `kyc`. Returns `batch_id` for async results. Max 3 concurrent batches.
`GET /batch/results/{batchId}`	Poll batch processing status and retrieve results when complete. Returns progress percentage and partial results.
`POST /execute`	RPC Gateway Execute any registered method by name. Generic gateway for custom operations. Requires specific scope per method.
`GET /methods`	List all methods available for your API key based on assigned scopes.

Verify: Content Verification

Endpoint	Description
`POST /verify/check`	AI content verification: detect phishing, fraud, spam, manipulated content. Returns verdict (legitimate/suspicious/fraudulent) with confidence and analysis.
`GET /verify/webhook`	Webhook challenge verification for WhatsApp/Twilio integration.
`POST /verify/webhook`	Incoming message processing: receives WhatsApp/Twilio messages, processes with AI, auto-replies.

AI: AI Services

Endpoint	Description
`POST /ai/chat/completions`	Chat completions. Multi-provider ready (swap AI providers without API changes).
`POST /ai/text/analyze`	Text analysis optimized for LATAM Spanish: sentiment, entities, intent detection. Understands regional slang.
`POST /ai/text/summarize`	Text summarization via AI.

Sales Copilot Integration API

Synchronize your ERP/CRM with Sales Copilot. Auth: X-API-Key header with scope salescopilot.write.

`POST /api/v1/sc/clients`	Bulk upsert clients. Body: `{"records": [{"codigo","nombre","telefono","zona","segment"}]}`. Max 1000/request.
`POST /api/v1/sc/products`	Bulk upsert products. Body: `{"records": [{"codigo","nombre","precio","unidad","categoria"}]}`. Max 1000/request.
`POST /api/v1/sc/assignments`	Bulk upsert client-rep assignments. Body: `{"records": [{"codigo_cliente","codigo_rep"}]}`. Max 5000/request.
`GET /api/v1/sc/orders?since=YYYY-MM-DD`	Get orders created since date. Returns vendor, client, items, total, status.
`GET /api/v1/sc/sync-status`	Last 20 sync operations with status, timing, and error details.

Webhook Validation (HMAC-SHA256)

When MV sends webhooks to your endpoint, validate the X-MV-Signature header to ensure authenticity.

using System.Security.Cryptography;
using System.Text;

bool ValidateWebhook(string body, string signature, string secret)
{
    var key = Encoding.UTF8.GetBytes(secret);
    var hash = HMACSHA256.HashData(key, Encoding.UTF8.GetBytes(body));
    var expected = "sha256=" + Convert.ToHexStringLower(hash);
    return signature == expected;
}
// Usage: ValidateWebhook(requestBody, Request.Headers["X-MV-Signature"], yourSecret);

Python

import hmac, hashlib

def validate_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)
# Usage: validate_webhook(request.body, request.headers["X-MV-Signature"], your_secret)

Node.js

const crypto = require('crypto');

function validateWebhook(body, signature, secret) {
    const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex');
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
// Usage: validateWebhook(req.body, req.headers['x-mv-signature'], yourSecret);