CRM

Contacts, opportunities/deals, activities — core customer data.

9 endpoints · base /api/v1/crm

GET/api/v1/crm/contactsTry it ▶

Search/list contacts.

MCP tool: search_contactsScope: crm.contacts.viewAPI key / app

Parameter

Parameter	Type	In	Required	Description
`q`	string	query	no	Search keyword
`pageNumber`	int	query	no	Page (starts at 1)
`pageSize`	int	query	no	Rows per page (default 20 for CRM and Sales orders/customers; 50 for Sales products)

Example

curl https://api.nextx.vn/api/v1/crm/contacts?q=...&pageNumber=1&pageSize=1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Sample response

{
  "items": [
    {
      "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "code": "string",
      "contactType": "string",
      "fullName": "string",
      "email": "string",
      "phone": "string",
      "jobTitle": "string",
      "companyName": "string",
      "avatarUrl": "string",
      "tier": "string",
      "hasCustomerProfile": false,
      "tags": [
        null
      ],
      "createdAt": "2026-10-27T09:00:00+07:00",
      "lifecycleStage": "string",
      "address": "string",
      "city": "string",
      "ward": "string",
      "assigneeName": "string",
      "assigneeId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "pipelineStageName": "string",
      "pipelineStageColor": "string",
      "orderCount": 0,
      "dealCount": 0,
      "topDealValue": 0,
      "topDealStage": "string",
      "topDealStageColor": "string",
      "topDealCloseDate": "2026-10-27",
      "topDealId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "provinceCode": "string",
      "customerStatus": "string",
      "groupName": "string",
      "lastActivityAt": "2026-10-27T09:00:00+07:00",
      "groupIcon": "string",
      "groupColor": "string",
      "statusLabel": "string",
      "statusIcon": "string",
      "statusColor": "string",
      "customFields": {},
      "sourceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "assignedAt": "2026-10-27T09:00:00+07:00",
      "leadScore": 0,
      "leadTier": "string",
      "latestCommentText": "string",
      "latestCommentAt": "2026-10-27T09:00:00+07:00",
      "notes": "string",
      "sourceName": "string",
      "phone2": "string",
      "phone3": "string",
      "dob": "2026-10-27",
      "channelOrigin": {
        "channelType": null,
        "channelAccountName": null,
        "otherAccountCount": null
      },
      "chatSummary": {
        "openCount": null,
        "totalCount": null,
        "unreadCount": null,
        "lastMessageAt": null,
        "lastMessagePreview": null,
        "lastMessageDirection": null,
        "lastChannelType": null,
        "awaitingReplyMinutes": null,
        "slaBreached": null,
        "botHandling": null,
        "linkedOrderCodes": null,
        "conversationTags": null
      },
      "nextActivityAt": "2026-10-27T09:00:00+07:00",
      "nextActivityKind": "string",
      "nextActivityTitle": "string",
      "contactStatusId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "branchId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "branchName": "string",
      "slaStage": 0,
      "slaContactedAt": "2026-10-27T09:00:00+07:00"
    }
  ],
  "totalCount": 0,
  "page": 0,
  "pageSize": 0,
  "totalPages": 0,
  "hasNextPage": false,
  "hasPreviousPage": false
}

GET/api/v1/crm/contacts/{id}Try it ▶

Details of one contact.

MCP tool: get_contactScope: crm.contacts.viewAPI key / app

Parameter

Parameter	Type	In	Required	Description
`id`	GUID	path	yes	Contact id

Example

curl https://api.nextx.vn/api/v1/crm/contacts/<id> \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Sample response

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "code": "string",
  "contactType": "string",
  "fullName": "string",
  "email": "string",
  "phone": "string",
  "jobTitle": "string",
  "companyName": "string",
  "website": "string",
  "avatarUrl": "string",
  "gender": "string",
  "dob": "2026-10-27",
  "address": "string",
  "city": "string",
  "country": "string",
  "identityNumber": "string",
  "identityIssuedDate": "2026-10-27",
  "identityIssuedPlace": "string",
  "ward": "string",
  "phone2": "string",
  "phone3": "string",
  "linkedinUrl": "string",
  "tier": "string",
  "isDecisionMaker": false,
  "customFields": {},
  "sourceRef": "string",
  "tags": [
    {
      "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "name": "string",
      "color": "string"
    }
  ],
  "customerProfile": {
    "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "tier": "string",
    "customerStatus": "string",
    "lifetimeValue": 0,
    "createdAt": "2026-10-27T09:00:00+07:00"
  },
  "supplierInfo": {
    "supplierId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "supplierName": "string",
    "supplierCode": "string"
  },
  "createdAt": "2026-10-27T09:00:00+07:00",
  "updatedAt": "2026-10-27T09:00:00+07:00",
  "lifecycleStage": "string",
  "industryId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "sourceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "customerGroupId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "contactPersonName": "string",
  "contactPersonPhone": "string",
  "contactPersonRelationship": "string",
  "provinceCode": "string",
  "districtCode": "string",
  "wardCode": "string",
  "notes": "string",
  "groupName": "string",
  "groupIcon": "string",
  "groupColor": "string",
  "assigneeId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "assigneeName": "string",
  "assignedAt": "2026-10-27T09:00:00+07:00",
  "statusLabel": "string",
  "statusIcon": "string",
  "statusColor": "string",
  "contactStatusId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "branchId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "branchName": "string",
  "taxCode": "string",
  "bankAccountNumber": "string",
  "bankName": "string",
  "bankBranch": "string",
  "leadScore": 0,
  "leadTier": "string",
  "referralCodeId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "referralCodeKind": "string",
  "referralCode": "string",
  "firstTouch": {
    "intakeEventId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "receivedAt": "2026-10-27T09:00:00+07:00",
    "doorType": "string",
    "doorName": "string",
    "sourceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "sourceRaw": "string",
    "utmSource": "string",
    "utmMedium": "string",
    "utmCampaign": "string",
    "landingUrl": "string",
    "referralRaw": "string",
    "referralMatch": "string"
  }
}

POST/api/v1/crm/contactsTry it ▶

Create a new contact.

MCP tool: create_contactScope: crm.contacts.createAPI key / app

Parameter

Parameter	Type	In	Required	Description
`Idempotency-Key` New	string	header	no	A value you generate for EACH write (e.g. a UUID), up to 200 characters. Resending the same value within 24 hours returns the original result instead of creating a second record. Same value with a different body ⇒ 422.
`contactType`	string	body	yes	INDIVIDUAL or BUSINESS; cannot be changed after creation
`fullName`	string	body	yes	—
`email`	string	body	no	—
`phone`	string	body	no	—
`companyName`	string	body	no	—
`jobTitle`	string	body	no	—
`customFields`	object	body	no	Keys are custom field codes

Example

curl -X POST https://api.nextx.vn/api/v1/crm/contacts \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Idempotency-Key: 7f3c2a90-…" \
  -H "Content-Type: application/json" \
  -d '{
    "contactType": "...",
    "fullName": "...",
    "email": "...",
    "phone": "...",
    "companyName": "...",
    "jobTitle": "...",
    "customFields": {}
  }'

Sample response

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "code": "string",
  "contactType": "string",
  "fullName": "string",
  "email": "string",
  "phone": "string",
  "jobTitle": "string",
  "companyName": "string",
  "website": "string",
  "avatarUrl": "string",
  "gender": "string",
  "dob": "2026-10-27",
  "address": "string",
  "city": "string",
  "country": "string",
  "identityNumber": "string",
  "identityIssuedDate": "2026-10-27",
  "identityIssuedPlace": "string",
  "ward": "string",
  "phone2": "string",
  "phone3": "string",
  "linkedinUrl": "string",
  "tier": "string",
  "isDecisionMaker": false,
  "customFields": {},
  "sourceRef": "string",
  "tags": [
    {
      "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "name": "string",
      "color": "string"
    }
  ],
  "customerProfile": {
    "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "tier": "string",
    "customerStatus": "string",
    "lifetimeValue": 0,
    "createdAt": "2026-10-27T09:00:00+07:00"
  },
  "supplierInfo": {
    "supplierId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "supplierName": "string",
    "supplierCode": "string"
  },
  "createdAt": "2026-10-27T09:00:00+07:00",
  "updatedAt": "2026-10-27T09:00:00+07:00",
  "lifecycleStage": "string",
  "industryId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "sourceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "customerGroupId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "contactPersonName": "string",
  "contactPersonPhone": "string",
  "contactPersonRelationship": "string",
  "provinceCode": "string",
  "districtCode": "string",
  "wardCode": "string",
  "notes": "string",
  "groupName": "string",
  "groupIcon": "string",
  "groupColor": "string",
  "assigneeId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "assigneeName": "string",
  "assignedAt": "2026-10-27T09:00:00+07:00",
  "statusLabel": "string",
  "statusIcon": "string",
  "statusColor": "string",
  "contactStatusId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "branchId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "branchName": "string",
  "taxCode": "string",
  "bankAccountNumber": "string",
  "bankName": "string",
  "bankBranch": "string",
  "leadScore": 0,
  "leadTier": "string",
  "referralCodeId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "referralCodeKind": "string",
  "referralCode": "string",
  "firstTouch": {
    "intakeEventId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "receivedAt": "2026-10-27T09:00:00+07:00",
    "doorType": "string",
    "doorName": "string",
    "sourceId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "sourceRaw": "string",
    "utmSource": "string",
    "utmMedium": "string",
    "utmCampaign": "string",
    "landingUrl": "string",
    "referralRaw": "string",
    "referralMatch": "string"
  }
}

GET/api/v1/crm/opportunitiesTry it ▶

Opportunity/deal pipeline.

MCP tool: get_deal_pipelineScope: crm.opportunities.viewAPI key / app

Parameter

Parameter	Type	In	Required	Description
`q`	string	query	no	Keyword by opportunity name/code
`status`	string	query	no	Opportunity status
`stageId`	GUID	query	no	Filter by pipeline stage
`pageNumber`	int	query	no	Page (starts at 1)
`pageSize`	int	query	no	Rows per page (default 20 for CRM and Sales orders/customers; 50 for Sales products)

Example

curl https://api.nextx.vn/api/v1/crm/opportunities?q=...&status=...&stageId=%3CstageId%3E&pageNumber=1&pageSize=1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Sample response

{
  "items": [
    {
      "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "code": "string",
      "name": "string",
      "contactId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "contactName": "string",
      "contactCompanyName": "string",
      "pipelineStageId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "pipelineStageName": "string",
      "pipelineStageColor": "string",
      "estimatedValue": 0,
      "probability": 0,
      "expectedCloseDate": "2026-10-27",
      "assigneeId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "assigneeName": "string",
      "description": "string",
      "status": "string",
      "wonReason": "string",
      "lostReason": "string",
      "lostToCompetitor": "string",
      "wonAt": "2026-10-27T09:00:00+07:00",
      "createdAt": "2026-10-27T09:00:00+07:00",
      "isOverdue": false,
      "daysOverdue": 0,
      "quotationCount": 0,
      "contractCount": 0,
      "latestCommentText": "string",
      "latestCommentAt": "2026-10-27T09:00:00+07:00",
      "reopenCount": 0,
      "contactPhone": "string",
      "campaignName": "string",
      "nextCallAt": "2026-10-27T09:00:00+07:00",
      "callCount": 0,
      "lastDisposition": "string",
      "lastCalledAt": "2026-10-27T09:00:00+07:00",
      "tags": [
        null
      ]
    }
  ],
  "totalCount": 0,
  "page": 0,
  "pageSize": 0,
  "totalPages": 0,
  "hasNextPage": false,
  "hasPreviousPage": false
}

GET/api/v1/crm/opportunities/{id}Try it ▶

Deal details.

MCP tool: get_dealScope: crm.opportunities.viewAPI key / app

Parameter

Parameter	Type	In	Required	Description
`id`	GUID	path	yes	—

Example

curl https://api.nextx.vn/api/v1/crm/opportunities/<id> \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Sample response

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "code": "string",
  "name": "string",
  "contactId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "contactName": "string",
  "leadId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "leadName": "string",
  "pipelineStageId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "pipelineStageName": "string",
  "pipelineStageColor": "string",
  "estimatedValue": 0,
  "probability": 0,
  "expectedCloseDate": "2026-10-27",
  "assigneeId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "assigneeName": "string",
  "description": "string",
  "customFields": {},
  "status": "string",
  "wonReason": "string",
  "lostReason": "string",
  "lostToCompetitor": "string",
  "actualValue": 0,
  "actualCloseDate": "2026-10-27",
  "wonAt": "2026-10-27T09:00:00+07:00",
  "createdAt": "2026-10-27T09:00:00+07:00",
  "updatedAt": "2026-10-27T09:00:00+07:00",
  "reopenCount": 0,
  "lastReopenReason": "string",
  "reopenedAt": "2026-10-27T09:00:00+07:00"
}

PATCH/api/v1/crm/opportunities/{id}/stageTry it ▶

Change a deal's stage. Not allowed once the deal is Won or Lost.

MCP tool: update_deal_stageScope: crm.opportunities.manageAPI key / app

Parameter

Parameter	Type	In	Required	Description
`Idempotency-Key` New	string	header	no	A value you generate for EACH write (e.g. a UUID), up to 200 characters. Resending the same value within 24 hours returns the original result instead of creating a second record. Same value with a different body ⇒ 422.
`id`	GUID	path	yes	—
`pipelineStageId`	GUID	body	yes	Target stage id in the pipeline

Example

curl -X PATCH https://api.nextx.vn/api/v1/crm/opportunities/<id>/stage \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Idempotency-Key: 7f3c2a90-…" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineStageId": "<pipelineStageId>"
  }'

Sample response

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "code": "string",
  "name": "string",
  "contactId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "contactName": "string",
  "leadId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "leadName": "string",
  "pipelineStageId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "pipelineStageName": "string",
  "pipelineStageColor": "string",
  "estimatedValue": 0,
  "probability": 0,
  "expectedCloseDate": "2026-10-27",
  "assigneeId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "assigneeName": "string",
  "description": "string",
  "customFields": {},
  "status": "string",
  "wonReason": "string",
  "lostReason": "string",
  "lostToCompetitor": "string",
  "actualValue": 0,
  "actualCloseDate": "2026-10-27",
  "wonAt": "2026-10-27T09:00:00+07:00",
  "createdAt": "2026-10-27T09:00:00+07:00",
  "updatedAt": "2026-10-27T09:00:00+07:00",
  "reopenCount": 0,
  "lastReopenReason": "string",
  "reopenedAt": "2026-10-27T09:00:00+07:00"
}

GET/api/v1/crm/opportunities/statsTry it ▶

Opportunity overview: open/won/lost totals, expected revenue, forecast, win rate, new in the last N days, breakdown by stage.

MCP tool: get_sales_summaryScope: crm.opportunities.viewAPI key / app

Parameter

Parameter	Type	In	Required	Description
`periodDays`	int	query	no	Most recent days, 1 to 365; default 30

Example

curl https://api.nextx.vn/api/v1/crm/opportunities/stats?periodDays=1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Sample response

{
  "totalOpen": 0,
  "totalWon": 0,
  "totalLost": 0,
  "totalEstimatedValue": 0,
  "totalWonValue": 0,
  "newInPeriod": 0,
  "winRate": 0,
  "forecast": {
    "weightedValue": 0,
    "openCount": 0,
    "totalOpenEstimatedValue": 0
  },
  "pipelineDistribution": [
    {
      "stageId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "stageName": "string",
      "stageColor": "string",
      "count": 0,
      "totalValue": 0
    }
  ]
}

GET/api/v1/crm/activitiesTry it ▶

Recent activity across the workspace, newest first.

MCP tool: get_recent_activitiesScope: crm.reports.viewAPI key / app

Parameter

Parameter	Type	In	Required	Description
`pageNumber`	int	query	no	Page (starts at 1)
`pageSize`	int	query	no	1–100; default 20
`activityType`	string	query	no	Filter by activity type
`fromDate`	date	query	no	ISO-8601
`toDate`	date	query	no	ISO-8601
`contactId`	GUID	query	no	—

Example

curl https://api.nextx.vn/api/v1/crm/activities?pageNumber=1&pageSize=1&activityType=...&fromDate=2026-06-01&toDate=2026-06-01&contactId=%3CcontactId%3E \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Sample response

{
  "items": [
    {
      "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "activityType": "string",
      "title": "string",
      "description": "string",
      "contactId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "contactName": "string",
      "sourceService": "string",
      "actorId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
      "occurredAt": "2026-10-27T09:00:00+07:00"
    }
  ],
  "totalCount": 0,
  "page": 0,
  "pageSize": 0,
  "totalPages": 0,
  "hasNextPage": false,
  "hasPreviousPage": false
}

POST/api/v1/crm/tasksTry it ▶

Create a task. It can be linked to only ONE of: contact, opportunity or ticket; otherwise 422 TASK_SINGLE_LINK_VIOLATION.

MCP tool: create_taskScope: crm.tasks.manageAPI key / app

Parameter

Parameter	Type	In	Required	Description
`Idempotency-Key` New	string	header	no	A value you generate for EACH write (e.g. a UUID), up to 200 characters. Resending the same value within 24 hours returns the original result instead of creating a second record. Same value with a different body ⇒ 422.
`title`	string	body	yes	Up to 500 characters
`status`	string	body	yes	TODO, IN_PROGRESS or DONE
`priority`	string	body	yes	LOW, MEDIUM or HIGH
`description`	string	body	no	—
`dueDate`	date	body	no	YYYY-MM-DD
`assigneeId`	GUID	body	no	—
`contactId`	GUID	body	no	Only one of contactId / opportunityId / ticketId
`opportunityId`	GUID	body	no	—
`ticketId`	GUID	body	no	—

Example

curl -X POST https://api.nextx.vn/api/v1/crm/tasks \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Idempotency-Key: 7f3c2a90-…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "...",
    "status": "...",
    "priority": "...",
    "description": "...",
    "dueDate": "2026-06-01",
    "assigneeId": "<assigneeId>",
    "contactId": "<contactId>",
    "opportunityId": "<opportunityId>",
    "ticketId": "<ticketId>"
  }'

Sample response

{
  "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "code": "string",
  "title": "string",
  "description": "string",
  "status": "string",
  "priority": "string",
  "startDate": "2026-10-27",
  "dueDate": "2026-10-27",
  "assigneeId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "assigneeName": "string",
  "contactId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "contactName": "string",
  "contactCode": "string",
  "opportunityId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "opportunityName": "string",
  "opportunityCode": "string",
  "ticketId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "ticketSubject": "string",
  "parentTaskId": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "parentTaskTitle": "string",
  "parentTaskCode": "string",
  "progress": 0,
  "customFields": "string",
  "createdAt": "2026-10-27T09:00:00+07:00",
  "updatedAt": "2026-10-27T09:00:00+07:00",
  "remindAt": "2026-10-27T09:00:00+07:00",
  "reminderSentAt": "2026-10-27T09:00:00+07:00"
}