CRM V4

Overview

Overview of V4MOS.AI CRM V4 API

The V4MOS.AI CRM V4 API exposes lead, opportunity, company, contact, and pipeline data synced from the V4 CRM (mars-sales) connected to your organization. Endpoints share the /v1/crm-v4 prefix and use the same authentication, pagination, and metadata envelope as every other V4MOS.AI integration.

Available Endpoints

Authentication

All endpoints require the organizationId query parameter. The lead, opportunity, company, contact, and pipeline endpoints use the x-client-id and x-client-secret headers. The retention endpoints (/v1/crm-v4/retention and /v1/crm-v4/retention/cohort) do not accept that pair: they require Authorization: Bearer {token} with a user or oaclient token. See Authentication.

Common Parameters

  • organizationId (required) – Organization that owns the CRM V4 integration
  • integrationId – Integration scope
  • page – Page number (default: 1)
  • limit – Records per page (default: 500, max: 5000)

Resource-Specific Filters

Leads (/v1/crm-v4/leads)

  • boardId, columnId, phaseType – Pipeline and stage filters
  • temperature, ownerId
  • createdStart / createdEnd – Creation date range

Opportunities (/v1/crm-v4/opportunities)

  • boardId, columnId, phaseType – Pipeline and stage filters
  • type – Board type (OPPORTUNITY, EXPANSION, ACQUISITION)
  • ownerId
  • createdStart / createdEnd – Creation date range

Companies (/v1/crm-v4/companies)

  • segment, tierType, ownerId
  • lastActivityStart / lastActivityEnd – Last activity range

Contacts (/v1/crm-v4/contacts)

  • companyId, ownerId

Retention (/v1/crm-v4/retention)

  • startDate / endDate (required, YYYY-MM-DD, UTC, up to 366 days); no pagination
  • Monthly customer churn and gross revenue retention (GRR) by CNPJ, for the months of the period and as many months right before it

Contract cohort (/v1/crm-v4/retention/cohort)

  • startDate / endDate (required, YYYY-MM-DD, UTC, up to 366 days); no pagination
  • Per contract start month, how many CNPJs keep billing in each following month, up to the month of endDate

The two retention routes are made for the audit: they only accept a Bearer token of kind user or oaclient issued for the V4MOS application; the x-client-id / x-client-secret pair and customer service accounts get 403.

Pipelines (/v1/crm-v4/pipelines)

  • boardId
  • boardType – Board type (LEAD, OPPORTUNITY, EXPANSION, ACQUISITION)

Working With Stages

A card's stage is described by column_id + column_title + phase_type. Use phase_type for business logic — it is the stable, language-independent marker, while column_title is free text organizations can rename at any time. Join cards to /v1/crm-v4/pipelines on board_id + column_id to resolve stage ordering (column_order).

Pagination

Responses return meta.page, meta.limit, meta.hasNextPage, and meta.hasPreviousPage. Iterate while hasNextPage is true.

On this page