{ "openapi": "3.0.3", "info": { "title": "HelloCRM API", "version": "1.0.0", "description": "HelloCRM **documented public API** for integrators: conversations, messaging (live chat, email, SMS, WhatsApp, bulk), templates, contacts, companies, products, deals, and quotes.\n\n**Messaging — two modes (both supported):** **In conversation** — pass `conversationId` (from Conversations APIs or your CRM). **Standalone** — omit `conversationId`; pass `to` (phone or email) or `contactId` and the API finds or creates the contact and conversation. `providerId` = provider id or sending phone/email on file.\n\n**Authentication:** `x-api-key` (team API key) or `Authorization: Bearer ` on protected routes.\n\n**Standard success envelope** (target contract; some handlers may omit fields):\n`{\"success\":true,\"message\":\"string\",\"data\":{},\"meta\":{}}`\n\n**Idempotency:** Send `Idempotency-Key` on creates and sensitive sends when you retry.\n\n**Bulk outbound:** `POST /api/messages/sendBulkNewMessages` — comma-separated `to`, `channel` one of `email`, `sms`, `whatsapp` (see Bulk Email / Bulk SMS / Bulk WhatsApp folders).\n\nRegenerated by `hellocrm-backend/scripts/generate-postman-collection.mjs` (documented routes only).\n\n---\n\nThis specification is generated from the Postman collection. Import the collection from `/hello-crm.postman_collection.json` on the docs site, or from the repository `postman/` folder.\n\nHosted API reference: https://developers.hellocrm.ai" }, "servers": [ { "url": "https://api.hellocrm.ai", "description": "Production API host" }, { "url": "https://{environmentHost}", "description": "Custom or staging host (set `environmentHost` when using OpenAPI tooling)", "variables": { "environmentHost": { "default": "api.hellocrm.ai", "description": "API hostname without scheme or path" } } } ], "tags": [ { "name": "Conversations", "description": "Obtain or create a `conversationId` for **in-conversation** messaging.\n\n**Three options:** (1) `POST /api/conversations/getConversationByPhoneAndEmail` — find or create contact + conversation from phone/email. (2) `POST /api/contacts/create-new-conversation` — create contact (if needed) and conversation in one request. (3) `POST /api/conversations` — create conversation when you already have a `contactId`.\n\n**Optional:** you can skip these and send standalone messages with `to` / `recipientId` — the send APIs auto-resolve contact and conversation.\n" }, { "name": "Send Live Chat", "description": "Send live chat on channel `chat`. **Two ways to target the recipient:** (1) **In conversation** — pass `conversationId` (and optionally `contactId`). (2) **Standalone** — omit `conversationId`; pass `contactId` or `to` (phone). (`recipientId` is accepted as an alias for `contactId`.)\n" }, { "name": "Send Email", "description": "Send email on channel `email`. **In conversation:** `conversationId` + `recipientIds`. **Standalone:** omit `conversationId`; use `to` (email) and/or `recipientIds`. `providerId` = provider id or provider email.\n" }, { "name": "Send SMS", "description": "Send SMS via `POST /api/messages/sendMessage` (`channel: \"sms\"`). **In conversation:** `conversationId` (+ optional `contactId`). **Standalone:** `to` (phone) — contact/conversation created if needed. `providerId` = provider id or sending number.\n" }, { "name": "Send WhatsApp", "description": "Send WhatsApp via `POST /api/messages/sendMessage` (`channel: \"whatsapp\"`). Same targeting as SMS: **in conversation** (`conversationId`) or **standalone** (`to`). Template fields for approved templates.\n" }, { "name": "Bulk Email", "description": "Bulk email campaign. Endpoint: `POST /api/messages/sendBulkNewMessages` with `channel: \"email\"` and comma-separated emails in `to`.\n" }, { "name": "Bulk SMS", "description": "Bulk SMS campaign. Endpoint: `POST /api/messages/sendBulkNewMessages` with `channel: \"sms\"` and comma-separated phone numbers in `to`.\n" }, { "name": "Bulk WhatsApp", "description": "Bulk WhatsApp campaign. Endpoint: `POST /api/messages/sendBulkNewMessages` with `channel: \"whatsapp\"` and comma-separated phone numbers in `to`.\n" }, { "name": "Templates", "description": "CRUD for message templates. **Create** endpoints are split by channel (SMS, email, WhatsApp). WhatsApp create/update often uses `multipart/form-data` when a header media `file` is required; SMS and email use JSON.\n" }, { "name": "Contacts", "description": "Create, update, upsert, and delete contacts." }, { "name": "Companies", "description": "Public API: `POST /api/companies/create`, `PUT /api/companies/edit/{companyId}`, `DELETE /api/companies/delete/{companyId}`." }, { "name": "Products", "description": "Create, update, and delete products." }, { "name": "Deals", "description": "Public API: `POST /api/deals/create`, `PUT /api/deals/edit/{dealId}`, `DELETE /api/deals/delete/{dealId}`." }, { "name": "Quotes", "description": "Create, update, delete quotes. `signatureOption`: no-signature, written-signature. `status`: draft, published, expired. `template`: default-basic.\n" } ], "x-tagGroups": [ { "name": "Conversations", "tags": [ "Conversations" ] }, { "name": "Messaging", "tags": [ "Send Live Chat", "Send Email", "Send SMS", "Send WhatsApp", "Bulk Email", "Bulk SMS", "Bulk WhatsApp" ] }, { "name": "Templates", "tags": [ "Templates" ] }, { "name": "CRM", "tags": [ "Contacts", "Companies", "Products", "Deals", "Quotes" ] } ], "paths": { "/api/conversations/getConversationByPhoneAndEmail": { "post": { "tags": [ "Conversations" ], "summary": "Resolve conversation by phone or email (find or create)", "description": "**Resolve conversation by phone or email (find or create)**\n\nReturns `{ data: { _id: conversationId, contactId: { ... } } }`. Creates contact/conversation if missing.\n\n\nUse the returned `data._id` as `conversationId` when you need it. You can skip this call if you send messages with `to` (phone/email) instead.", "operationId": "Resolve_conversation_by_phone_or_email_find_or_create", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Find or create contact and conversation by email and/or phone.", "required": [], "properties": { "email": { "type": "string", "format": "email", "description": "Contact email (optional if `phone` provided)." }, "phone": { "type": "string", "description": "Contact phone in E.164 format (optional if `email` provided)." } }, "additionalProperties": false }, "example": { "email": "john.doe@example.com", "phone": "+1234567890" } } } }, "responses": { "200": { "description": "Conversation and contact found or created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Found", "data": { "_id": "64f91a7d28ae948d8e9e8430", "teamId": "64f91a7d28ae948d8e9e8400", "contactId": { "_id": "64f91a7d28ae948d8e9e8432", "name": "John Doe", "email": "john.doe@example.com", "phoneNumber": "+1234567890" }, "createdAt": "2025-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Resolve conversation by phone or email (find or create)", "source": "curl -X POST https://api.hellocrm.ai/api/conversations/getConversationByPhoneAndEmail \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\"\n }'" } ] } }, "/api/contacts/create-new-conversation": { "post": { "tags": [ "Conversations" ], "summary": "Create contact and conversation", "description": "**Create contact and conversation**\n\nCreates contact if missing, then creates conversation. Returns `data._id` as `conversationId`. Reuses existing contact/conversation when phone or email matches.\n\n\nOne call when you do not have a `contactId` yet. Returns populated conversation; use `data._id` as `conversationId`.", "operationId": "Create_contact_and_conversation", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create contact when missing, then create conversation. At least one of `email` or `phone` recommended.", "required": [ "firstName", "lastName" ], "properties": { "firstName": { "type": "string", "description": "Contact first name." }, "lastName": { "type": "string", "description": "Contact last name." }, "email": { "type": "string", "format": "email", "description": "Contact email." }, "phone": { "type": "string", "description": "Contact phone (E.164)." }, "lifecycleStage": { "type": "string", "description": "e.g. Lead, Customer. Defaults to Lead when omitted." }, "groupId": { "type": "string", "description": "Optional contact group id." } }, "additionalProperties": false }, "example": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+1234567890", "lifecycleStage": "Lead", "groupId": "64f91a7d28ae948d8e9e8435" } } } }, "responses": { "200": { "description": "Contact and conversation found or created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Found", "data": { "_id": "64f91a7d28ae948d8e9e8430", "teamId": "64f91a7d28ae948d8e9e8400", "contactId": { "_id": "64f91a7d28ae948d8e9e8432", "name": "John Doe", "email": "john.doe@example.com", "phoneNumber": "+1234567890" }, "createdAt": "2025-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Create contact and conversation", "source": "curl -X POST https://api.hellocrm.ai/api/contacts/create-new-conversation \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\",\n \"lifecycleStage\": \"Lead\",\n \"groupId\": \"64f91a7d28ae948d8e9e8435\"\n }'" } ] } }, "/api/conversations": { "post": { "tags": [ "Conversations" ], "summary": "Create conversation (by contactId)", "description": "**Create conversation (by contactId)**\n\n`POST /api/conversations` — requires an existing `contactId`. Returns `201` with new conversation or `200` if one already exists for that contact.\n\n\nUse when the contact already exists. Same team-scoped uniqueness: one conversation per contact.", "operationId": "Create_conversation_by_contactId", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create a conversation for an existing contact (one per contact per team).", "required": [ "contactId" ], "properties": { "contactId": { "type": "string", "description": "Existing contact id." } }, "additionalProperties": false }, "example": { "contactId": "64f91a7d28ae948d8e9e8430" } } } }, "responses": { "200": { "description": "Conversation already exists", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Conversation already exist.", "data": { "_id": "64f91a7d28ae948d8e9e8430", "teamId": "64f91a7d28ae948d8e9e8400", "contactId": { "_id": "64f91a7d28ae948d8e9e8432", "name": "John Doe", "email": "john.doe@example.com", "phoneNumber": "+1234567890" }, "createdAt": "2025-01-15T10:00:00.000Z" } } } } }, "201": { "description": "Conversation created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Conversation created successfully.", "data": { "_id": "64f91a7d28ae948d8e9e8430", "teamId": "64f91a7d28ae948d8e9e8400", "contactId": { "_id": "64f91a7d28ae948d8e9e8432", "name": "John Doe", "email": "john.doe@example.com", "phoneNumber": "+1234567890" }, "createdAt": "2025-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Create conversation (by contactId)", "source": "curl -X POST https://api.hellocrm.ai/api/conversations \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"contactId\": \"64f91a7d28ae948d8e9e8430\"\n }'" } ] } }, "/api/conversations/{conversationId}": { "get": { "tags": [ "Conversations" ], "summary": "Get conversation by id", "description": "**Get conversation by id**\n\nFetch a single conversation with populated contact.\n", "operationId": "Get_conversation_by_id", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } } ], "responses": { "200": { "description": "Conversation found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Conversation Found.", "data": { "_id": "64f91a7d28ae948d8e9e8430", "teamId": "64f91a7d28ae948d8e9e8400", "contactId": { "_id": "64f91a7d28ae948d8e9e8432", "name": "John Doe", "email": "john.doe@example.com", "phoneNumber": "+1234567890" }, "createdAt": "2025-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Get conversation by id", "source": "curl -X GET https://api.hellocrm.ai/api/conversations/CONVERSATION_ID_HERE \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } }, "/api/conversations/getAllConversationsOfContact/{contactId}": { "get": { "tags": [ "Conversations" ], "summary": "List conversations for a contact", "description": "**List conversations for a contact**\n\nAll conversations linked to a contact id.\n", "operationId": "List_conversations_for_a_contact", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } } ], "responses": { "200": { "description": "Conversations listed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Conversations found.", "data": [ { "_id": "64f91a7d28ae948d8e9e8430", "teamId": "64f91a7d28ae948d8e9e8400", "contactId": { "_id": "64f91a7d28ae948d8e9e8432", "name": "John Doe", "email": "john.doe@example.com", "phoneNumber": "+1234567890" }, "createdAt": "2025-01-15T10:00:00.000Z" } ] } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "List conversations for a contact", "source": "curl -X GET https://api.hellocrm.ai/api/conversations/getAllConversationsOfContact/CONTACT_ID_HERE \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } }, "/api/messages/{conversationId}": { "get": { "tags": [ "Conversations" ], "summary": "List messages in a conversation", "description": "**List messages in a conversation**\n\nPaginated message history for a conversation (`?page=1&limit=10`, optional `channel`).\n", "operationId": "List_messages_in_a_conversation", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } } ], "responses": { "200": { "description": "Messages grouped by date", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Messages Found.", "data": [ { "date": "2025-01-15", "messages": [ { "_id": "64e90fa89e24f248d9a36e5b", "channel": "sms", "direction": "outgoing", "content": "Hello Jane, your appointment is scheduled.", "status": "sent", "conversationId": "64e93841f54d7026b53bb6a1", "contactId": "64e93829d0911c7392069abc", "createdAt": "2025-01-15T10:05:00.000Z" } ] } ], "pagination": { "total": 1, "currentPage": 1, "totalPages": 1, "hasMore": false } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "List messages in a conversation", "source": "curl -X GET \"https://api.hellocrm.ai/api/messages/CONVERSATION_ID_HERE?page=1&limit=10\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } }, "/api/messages/sendLiveMessage": { "post": { "tags": [ "Send Live Chat" ], "summary": "Send a live chat message", "description": "**Send a live chat message**\n\nSupports **in-conversation** (`conversationId`) or **standalone** (`contactId` or `to`). `channel` must be `chat`. Attachment `mediaType`: image, video, audio, file, or empty string.\n\n\n**In conversation:** `conversationId` (+ optional `contactId`). **Standalone:** `contactId` or `to` (phone). `recipientId` works as an alias for `contactId`. `channel` must be `chat`.", "operationId": "Send_a_live_chat_message", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Send live chat message", "description": "**Targeting (pick one mode):** In conversation — `conversationId` (optional `contactId`). Standalone — `to` (phone) or `contactId`. **Also accepted:** `recipientId` (same value as `contactId`, legacy alias). **Always send:** `channel: chat`, `content`.", "required": [ "channel", "content" ], "properties": { "conversationId": { "type": "string", "description": "In-conversation mode." }, "contactId": { "type": "string", "description": "HelloCRM contact id (who receives the message)." }, "to": { "type": "string", "description": "Standalone mode — recipient phone (E.164)." }, "content": { "type": "string", "description": "Message text. Merge fields supported." }, "channel": { "type": "string", "enum": [ "chat" ], "description": "Must be `chat`." }, "mediaUrl": { "type": "string", "nullable": true, "description": "Top-level media URL (optional)." }, "mediaType": { "type": "string", "nullable": true, "description": "Top-level media type (optional)." }, "source": { "type": "string", "description": "e.g. `widget`, `web`." }, "attachments": { "type": "array", "items": { "type": "object", "description": "File attachment metadata (URL must be reachable by HelloCRM).", "properties": { "fileName": { "type": "string", "description": "Display file name." }, "fileSize": { "type": "string", "description": "Human-readable size, e.g. `120 KB`." }, "mimeType": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "mediaUrl": { "type": "string", "description": "Public HTTPS URL of the file." }, "mediaType": { "type": "string", "enum": [ "image", "video", "audio", "file", "" ], "description": "Attachment kind for UI/channel handling." } } }, "description": "Optional file attachments." } }, "additionalProperties": false }, "example": { "conversationId": "64f91a7d28ae948d8e9e8430", "contactId": "64f91a7d28ae948d8e9e8432", "content": "Hello, {{contact.name}}! Please find the attached file.", "channel": "chat", "mediaUrl": null, "mediaType": null, "source": "widget", "attachments": [ { "fileName": "document.pdf", "fileSize": "120 KB", "mimeType": "application/pdf", "mediaUrl": "https://your-s3-bucket.s3.amazonaws.com/document.pdf", "mediaType": "file" }, { "fileName": "image.jpg", "fileSize": "450 KB", "mimeType": "image/jpeg", "mediaUrl": "https://your-s3-bucket.s3.amazonaws.com/image.jpg", "mediaType": "image" } ] } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Message sent successfully", "data": { "_id": "64e90fa89e24f248d9a36e5b", "channel": "chat", "direction": "outgoing", "content": "Hello Jane, your appointment is scheduled.", "status": "sent", "conversationId": "64e93841f54d7026b53bb6a1", "contactId": "64e93829d0911c7392069abc", "createdAt": "2025-01-15T10:05:00.000Z" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "In conversation", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendLiveMessage \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"conversationId\": \"64f91a7d28ae948d8e9e8430\",\n \"contactId\": \"64f91a7d28ae948d8e9e8432\",\n \"content\": \"Hello, {{contact.name}}! Please find the attached file.\",\n \"channel\": \"chat\",\n \"mediaUrl\": null,\n \"mediaType\": null,\n \"source\": \"widget\",\n \"attachments\": []\n }'" }, { "lang": "curl", "label": "Standalone (no conversationId)", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendLiveMessage \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"to\": \"+15551234567\",\n \"content\": \"Hello! Thanks for reaching out via chat.\",\n \"channel\": \"chat\",\n \"mediaUrl\": null,\n \"mediaType\": null,\n \"source\": \"widget\",\n \"attachments\": []\n }'" } ] } }, "/api/messages/sendEmailMessage": { "post": { "tags": [ "Send Email" ], "summary": "Send an email message", "description": "**Send an email message**\n\n**In conversation** or **standalone** — see folder description. `providerId` = provider id or provider email.\n\n\n**In conversation:** `conversationId` + `recipientIds`. **Standalone:** `to` (email) and/or `recipientIds` without `conversationId`.", "operationId": "Send_an_email_message", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "title": "Send email message", "description": "**Targeting:** In conversation — `conversationId` + `recipientIds`. Standalone — `to` (email) and/or `recipientIds` without `conversationId`. **Required:** `channel`, `subject`, `content`, `providerId`.", "required": [ "channel", "subject", "content", "providerId" ], "properties": { "conversationId": { "type": "string", "description": "In-conversation mode." }, "recipientIds": { "type": "array", "items": { "type": "string" }, "description": "Contact ids to receive the email." }, "to": { "type": "string", "format": "email", "description": "Standalone — recipient email address." }, "channel": { "type": "string", "enum": [ "email" ], "description": "Must be `email`." }, "subject": { "type": "string", "description": "Email subject line." }, "content": { "type": "string", "description": "HTML email body." }, "mediaUrl": { "type": "string", "description": "Optional." }, "mediaType": { "type": "string", "description": "Optional." }, "source": { "type": "string", "description": "e.g. `web`, `HelloCRM`." }, "providerId": { "type": "string", "description": "Provider id or provider email." }, "attachments": { "type": "array", "items": { "type": "object", "description": "File attachment metadata (URL must be reachable by HelloCRM).", "properties": { "fileName": { "type": "string", "description": "Display file name." }, "fileSize": { "type": "string", "description": "Human-readable size, e.g. `120 KB`." }, "mimeType": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "mediaUrl": { "type": "string", "description": "Public HTTPS URL of the file." }, "mediaType": { "type": "string", "enum": [ "image", "video", "audio", "file", "" ], "description": "Attachment kind for UI/channel handling." } } } }, "replyToMessageId": { "type": "string", "description": "Reply threading — HelloCRM message id." }, "quotedMessageId": { "type": "string", "description": "External Message-Id for threading." }, "threadId": { "type": "string", "description": "Provider thread id (e.g. Gmail)." } }, "additionalProperties": false }, "example": { "conversationId": "64d82f8f90b04f2b9c343b7a", "recipientIds": [ "64c1e942d0911c73920693bd" ], "channel": "email", "subject": "Test Email Subject", "content": "

Hello {{contact.firstName}}, this is a test email.

", "mediaUrl": "", "mediaType": "", "source": "web", "providerId": "64db8124cb0a330f257cb0c2", "attachments": [ { "fileName": "document.pdf", "fileSize": "120 KB", "mimeType": "application/pdf", "mediaUrl": "https://your-s3-bucket.s3.amazonaws.com/document.pdf", "mediaType": "file" } ], "replyToMessageId": "64e90fa89e24f248d9a36e5b", "quotedMessageId": "", "threadId": "" } } } }, "responses": { "200": { "description": "Messages sent successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Messages sent successfully", "data": { "_id": "64e90fa89e24f248d9a36e5b", "channel": "email", "direction": "outgoing", "content": "Hello Jane, your appointment is scheduled.", "status": "sent", "conversationId": "64e93841f54d7026b53bb6a1", "contactId": "64e93829d0911c7392069abc", "createdAt": "2025-01-15T10:05:00.000Z", "subject": "Test Email Subject" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "In conversation", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendEmailMessage \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"conversationId\": \"64d82f8f90b04f2b9c343b7a\",\n \"recipientIds\": [\"64c1e942d0911c73920693bd\"],\n \"channel\": \"email\",\n \"subject\": \"Test Email Subject\",\n \"content\": \"

Hello {{contact.firstName}}, this is a test email.

\",\n \"mediaUrl\": \"\",\n \"mediaType\": \"\",\n \"source\": \"web\",\n \"providerId\": \"64db8124cb0a330f257cb0c2\",\n \"attachments\": [],\n \"replyToMessageId\": \"64e90fa89e24f248d9a36e5b\",\n \"quotedMessageId\": \"\",\n \"threadId\": \"\"\n }'" }, { "lang": "curl", "label": "Standalone (no conversationId)", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendEmailMessage \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"jane.doe@example.com\",\n \"channel\": \"email\",\n \"subject\": \"Hello from HelloCRM\",\n \"content\": \"

Hi Jane, this email was sent without a prior conversation id.

\",\n \"mediaUrl\": \"\",\n \"mediaType\": \"\",\n \"source\": \"HelloCRM\",\n \"providerId\": \"64db8124cb0a330f257cb0c2\",\n \"attachments\": []\n }'" } ] } }, "/api/messages/sendMessage": { "post": { "tags": [ "Send SMS", "Send WhatsApp" ], "summary": "Send an SMS message (and variants)", "description": "**Send an SMS message**\n\n**Standalone example** in body; see docs for **in-conversation** variant with `conversationId`. `channel` must be `sms`.\n\n\n**In conversation:** `conversationId` (+ optional `contactId`). **Standalone:** `to` (phone) — contact/conversation auto-resolved. `providerId` = provider id or sending number.\n\n---\n\n**Send a WhatsApp message**\n\n**Standalone example** in body; see docs for **in-conversation** variant. Template fields optional when using approved templates.\n\n\nSame targeting as SMS. Template fields optional when using approved WhatsApp templates.", "operationId": "Send_an_SMS_message_or_Send_a_WhatsApp_message", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Send SMS", "type": "object", "description": "**Targeting:** `conversationId` **or** `to` (phone) **or** `contactId`. (`recipientId` is accepted as an alias for `contactId`.) **Required:** `channel`, `content`, `providerId`.", "required": [ "channel", "content", "providerId" ], "properties": { "conversationId": { "type": "string", "description": "In-conversation mode." }, "contactId": { "type": "string", "description": "HelloCRM contact id (who receives the SMS)." }, "to": { "type": "string", "description": "Standalone — recipient E.164 phone." }, "channel": { "type": "string", "enum": [ "sms" ], "description": "Must be `sms`." }, "content": { "type": "string", "description": "SMS body text." }, "mediaUrl": { "type": "string", "description": "Optional MMS media URL." }, "mediaType": { "type": "string", "description": "Optional media type." }, "source": { "type": "string", "description": "Source label." }, "providerId": { "type": "string", "description": "Provider id or sending phone number." } }, "additionalProperties": false, "example": { "to": "+15551234567", "channel": "sms", "content": "Hello {{contact.firstName}}, your appointment is scheduled.", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "+15559876543" } }, { "title": "Send WhatsApp", "type": "object", "description": "Same targeting rules as SMS. Template fields required for template/marketing sends.", "required": [ "channel", "content", "providerId" ], "properties": { "conversationId": { "type": "string", "description": "In-conversation mode." }, "contactId": { "type": "string", "description": "HelloCRM contact id (who receives the message)." }, "to": { "type": "string", "description": "Standalone — recipient E.164 phone." }, "channel": { "type": "string", "enum": [ "whatsapp" ], "description": "Must be `whatsapp`." }, "content": { "type": "string", "description": "Message body or template fallback text." }, "mediaUrl": { "type": "string", "description": "Optional." }, "mediaType": { "type": "string", "description": "Optional." }, "source": { "type": "string", "description": "Source label." }, "providerId": { "type": "string", "description": "Provider id or WhatsApp sending number." }, "templateId": { "type": "string", "description": "HelloCRM WhatsApp template id." }, "headerParameters": { "type": "array", "description": "WhatsApp template parameter objects (Meta format).", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Parameter type." }, "text": { "type": "string", "description": "Substitution value." } } } }, "bodyParameters": { "type": "array", "description": "WhatsApp template parameter objects (Meta format).", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Parameter type." }, "text": { "type": "string", "description": "Substitution value." } } } } }, "additionalProperties": false, "example": { "to": "+15551234567", "channel": "whatsapp", "content": "Hello {{contact.firstName}}, your appointment is scheduled.", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "+15559876543", "templateId": "646b8124cb0a330f257cb010", "headerParameters": [ { "type": "text", "text": "Hey" } ], "bodyParameters": [ { "type": "text", "text": "Hey body" } ] } } ], "description": "Multiple request shapes share this endpoint. Expand a variant below for **required vs optional** fields." }, "examples": { "Send_an_SMS_message": { "summary": "Send an SMS message", "value": { "to": "+15551234567", "channel": "sms", "content": "Hello {{contact.firstName}}, your appointment is scheduled.", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "+15559876543" } }, "Send_a_WhatsApp_message": { "summary": "Send a WhatsApp message", "value": { "to": "+15551234567", "channel": "whatsapp", "content": "Hello {{contact.firstName}}, your appointment is scheduled.", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "+15559876543", "templateId": "646b8124cb0a330f257cb010", "headerParameters": [ { "type": "text", "text": "Hey" } ], "bodyParameters": [ { "type": "text", "text": "Hey body" } ] } } } } } }, "responses": { "200": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "Send_an_SMS_message": { "summary": "Send an SMS message", "value": { "success": true, "message": "Message sent successfully", "data": { "_id": "64e90fa89e24f248d9a36e5b", "channel": "sms", "direction": "outgoing", "content": "Hello Jane, your appointment is scheduled.", "status": "sent", "conversationId": "64e93841f54d7026b53bb6a1", "contactId": "64e93829d0911c7392069abc", "createdAt": "2025-01-15T10:05:00.000Z" } } }, "Send_a_WhatsApp_message": { "summary": "Send a WhatsApp message", "value": { "success": true, "message": "Message sent successfully", "data": { "_id": "64e90fa89e24f248d9a36e5b", "channel": "whatsapp", "direction": "outgoing", "content": "Hello Jane, your appointment is scheduled.", "status": "sent", "conversationId": "64e93841f54d7026b53bb6a1", "contactId": "64e93829d0911c7392069abc", "createdAt": "2025-01-15T10:05:00.000Z" } } } } } } }, "201": { "description": "Message sent successfully", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "Send_an_SMS_message": { "summary": "Send an SMS message", "value": { "success": true, "message": "Message sent successfully", "data": { "_id": "64e90fa89e24f248d9a36e5b", "channel": "sms", "direction": "outgoing", "content": "Hello Jane, your appointment is scheduled.", "status": "sent", "conversationId": "64e93841f54d7026b53bb6a1", "contactId": "64e93829d0911c7392069abc", "createdAt": "2025-01-15T10:05:00.000Z" } } }, "Send_a_WhatsApp_message": { "summary": "Send a WhatsApp message", "value": { "success": true, "message": "Message sent successfully", "data": { "_id": "64e90fa89e24f248d9a36e5b", "channel": "whatsapp", "direction": "outgoing", "content": "Hello Jane, your appointment is scheduled.", "status": "sent", "conversationId": "64e93841f54d7026b53bb6a1", "contactId": "64e93829d0911c7392069abc", "createdAt": "2025-01-15T10:05:00.000Z" } } } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "In conversation", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendMessage \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"conversationId\": \"64f91a7d28ae948d8e9e8430\",\n \"contactId\": \"64f91a7d28ae948d8e9e8432\",\n \"channel\": \"sms\",\n \"content\": \"Hello {{contact.firstName}}, your appointment is scheduled.\",\n \"mediaUrl\": \"\",\n \"mediaType\": \"\",\n \"source\": \"HelloCRM\",\n \"providerId\": \"+15559876543\"\n }'" }, { "lang": "curl", "label": "Standalone (no conversationId)", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendMessage \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"+15551234567\",\n \"channel\": \"sms\",\n \"content\": \"Hello {{contact.firstName}}, your appointment is scheduled.\",\n \"mediaUrl\": \"\",\n \"mediaType\": \"\",\n \"source\": \"HelloCRM\",\n \"providerId\": \"+15559876543\"\n }'" }, { "lang": "curl", "label": "In conversation", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendMessage \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"conversationId\": \"64f91a7d28ae948d8e9e8430\",\n \"contactId\": \"64f91a7d28ae948d8e9e8432\",\n \"channel\": \"whatsapp\",\n \"content\": \"Hello {{contact.firstName}}, your appointment is scheduled.\",\n \"mediaUrl\": \"\",\n \"mediaType\": \"\",\n \"source\": \"HelloCRM\",\n \"providerId\": \"+15559876543\",\n \"templateId\": \"646b8124cb0a330f257cb010\",\n \"headerParameters\": [{ \"type\": \"text\", \"text\": \"Hey\" }],\n \"bodyParameters\": [{ \"type\": \"text\", \"text\": \"Hey body\" }]\n }'" }, { "lang": "curl", "label": "Standalone (no conversationId)", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendMessage \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"+15551234567\",\n \"channel\": \"whatsapp\",\n \"content\": \"Hello {{contact.firstName}}, your appointment is scheduled.\",\n \"mediaUrl\": \"\",\n \"mediaType\": \"\",\n \"source\": \"HelloCRM\",\n \"providerId\": \"+15559876543\",\n \"templateId\": \"646b8124cb0a330f257cb010\",\n \"headerParameters\": [{ \"type\": \"text\", \"text\": \"Hey\" }],\n \"bodyParameters\": [{ \"type\": \"text\", \"text\": \"Hey body\" }]\n }'" } ] } }, "/api/messages/sendBulkNewMessages": { "post": { "tags": [ "Bulk Email", "Bulk SMS", "Bulk WhatsApp" ], "summary": "Bulk send email (and variants)", "description": "**Bulk send email**\n\nQueues a bulk email campaign. `to` is comma-separated emails; requires `providerId`.\n\n\n---\n\n**Bulk send SMS**\n\nQueues bulk SMS. `to` is comma-separated phone numbers; `channel` must be `sms`.\n\n\n---\n\n**Bulk send WhatsApp**\n\nQueues bulk WhatsApp. Same endpoint as bulk SMS; set `channel` to `whatsapp`.\n", "operationId": "Bulk_send_email_or_Bulk_send_SMS_or_Bulk_send_WhatsApp", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Bulk email", "type": "object", "description": "Queue a bulk email campaign to comma-separated addresses in `to`.", "required": [ "to", "channel", "content", "providerId", "subject" ], "properties": { "to": { "type": "string", "description": "Comma-separated recipients (emails or E.164 phones depending on `channel`)." }, "channel": { "type": "string", "enum": [ "email" ], "description": "Must be `email`." }, "content": { "type": "string", "description": "Message body. Supports merge fields like `{{contact.firstName}}`." }, "mediaUrl": { "type": "string", "description": "Optional media URL." }, "mediaType": { "type": "string", "description": "Optional media type when `mediaUrl` is set." }, "source": { "type": "string", "description": "Source label for reporting, e.g. `HelloCRM`." }, "providerId": { "type": "string", "description": "Sending provider id, phone number, or email (must match channel)." }, "attachments": { "type": "array", "items": { "type": "object", "description": "File attachment metadata (URL must be reachable by HelloCRM).", "properties": { "fileName": { "type": "string", "description": "Display file name." }, "fileSize": { "type": "string", "description": "Human-readable size, e.g. `120 KB`." }, "mimeType": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "mediaUrl": { "type": "string", "description": "Public HTTPS URL of the file." }, "mediaType": { "type": "string", "enum": [ "image", "video", "audio", "file", "" ], "description": "Attachment kind for UI/channel handling." } } }, "description": "Optional attachments." }, "scheduleType": { "type": "string", "enum": [ "now", "scheduled" ], "description": "`now` sends immediately; `scheduled` uses `scheduleTime`." }, "scheduleTime": { "type": "object", "description": "Used when `scheduleType` is `scheduled`.", "properties": { "date": { "type": "string", "description": "Date string (team timezone)." }, "time": { "type": "string", "description": "Time string (team timezone)." } } }, "templateId": { "type": "string", "description": "HelloCRM template id (WhatsApp / some SMS flows)." }, "headerParameters": { "type": "array", "description": "WhatsApp template parameter objects (Meta format).", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Parameter type." }, "text": { "type": "string", "description": "Substitution value." } } } }, "bodyParameters": { "type": "array", "description": "WhatsApp template parameter objects (Meta format).", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Parameter type." }, "text": { "type": "string", "description": "Substitution value." } } } }, "subject": { "type": "string", "description": "Email subject for all recipients." }, "preheader": { "type": "string", "description": "Optional inbox preheader." } }, "additionalProperties": false, "example": { "to": "alice@example.com,bob@example.com", "channel": "email", "subject": "Bulk campaign subject", "preheader": "", "content": "

Hello {{contact.firstName}}, this is a bulk email.

", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "64db8124cb0a330f257cb0c2", "attachments": [], "scheduleType": "now", "scheduleTime": { "date": "", "time": "" } } }, { "title": "Bulk SMS", "type": "object", "description": "Queue bulk SMS to comma-separated E.164 numbers in `to`.", "required": [ "to", "channel", "content", "providerId" ], "properties": { "to": { "type": "string", "description": "Comma-separated recipients (emails or E.164 phones depending on `channel`)." }, "channel": { "type": "string", "enum": [ "sms" ], "description": "Must be `sms`." }, "content": { "type": "string", "description": "Message body. Supports merge fields like `{{contact.firstName}}`." }, "mediaUrl": { "type": "string", "description": "Optional media URL." }, "mediaType": { "type": "string", "description": "Optional media type when `mediaUrl` is set." }, "source": { "type": "string", "description": "Source label for reporting, e.g. `HelloCRM`." }, "providerId": { "type": "string", "description": "Sending provider id, phone number, or email (must match channel)." }, "attachments": { "type": "array", "items": { "type": "object", "description": "File attachment metadata (URL must be reachable by HelloCRM).", "properties": { "fileName": { "type": "string", "description": "Display file name." }, "fileSize": { "type": "string", "description": "Human-readable size, e.g. `120 KB`." }, "mimeType": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "mediaUrl": { "type": "string", "description": "Public HTTPS URL of the file." }, "mediaType": { "type": "string", "enum": [ "image", "video", "audio", "file", "" ], "description": "Attachment kind for UI/channel handling." } } }, "description": "Optional attachments." }, "scheduleType": { "type": "string", "enum": [ "now", "scheduled" ], "description": "`now` sends immediately; `scheduled` uses `scheduleTime`." }, "scheduleTime": { "type": "object", "description": "Used when `scheduleType` is `scheduled`.", "properties": { "date": { "type": "string", "description": "Date string (team timezone)." }, "time": { "type": "string", "description": "Time string (team timezone)." } } }, "templateId": { "type": "string", "description": "HelloCRM template id (WhatsApp / some SMS flows)." }, "headerParameters": { "type": "array", "description": "WhatsApp template parameter objects (Meta format).", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Parameter type." }, "text": { "type": "string", "description": "Substitution value." } } } }, "bodyParameters": { "type": "array", "description": "WhatsApp template parameter objects (Meta format).", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Parameter type." }, "text": { "type": "string", "description": "Substitution value." } } } } }, "additionalProperties": false, "example": { "to": "+15551234567,+15559876543", "channel": "sms", "content": "Hello {{contact.firstName}}, your appointment is scheduled.", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "64db8124cb0a330f257cb0c2", "attachments": [], "scheduleType": "now", "scheduleTime": { "date": "", "time": "" } } }, { "title": "Bulk WhatsApp", "type": "object", "description": "Queue bulk WhatsApp. Use `templateId` and parameter arrays for template messages.", "required": [ "to", "channel", "content", "providerId" ], "properties": { "to": { "type": "string", "description": "Comma-separated recipients (emails or E.164 phones depending on `channel`)." }, "channel": { "type": "string", "enum": [ "whatsapp" ], "description": "Must be `whatsapp`." }, "content": { "type": "string", "description": "Message body. Supports merge fields like `{{contact.firstName}}`." }, "mediaUrl": { "type": "string", "description": "Optional media URL." }, "mediaType": { "type": "string", "description": "Optional media type when `mediaUrl` is set." }, "source": { "type": "string", "description": "Source label for reporting, e.g. `HelloCRM`." }, "providerId": { "type": "string", "description": "Sending provider id, phone number, or email (must match channel)." }, "attachments": { "type": "array", "items": { "type": "object", "description": "File attachment metadata (URL must be reachable by HelloCRM).", "properties": { "fileName": { "type": "string", "description": "Display file name." }, "fileSize": { "type": "string", "description": "Human-readable size, e.g. `120 KB`." }, "mimeType": { "type": "string", "description": "MIME type, e.g. `application/pdf`." }, "mediaUrl": { "type": "string", "description": "Public HTTPS URL of the file." }, "mediaType": { "type": "string", "enum": [ "image", "video", "audio", "file", "" ], "description": "Attachment kind for UI/channel handling." } } }, "description": "Optional attachments." }, "scheduleType": { "type": "string", "enum": [ "now", "scheduled" ], "description": "`now` sends immediately; `scheduled` uses `scheduleTime`." }, "scheduleTime": { "type": "object", "description": "Used when `scheduleType` is `scheduled`.", "properties": { "date": { "type": "string", "description": "Date string (team timezone)." }, "time": { "type": "string", "description": "Time string (team timezone)." } } }, "templateId": { "type": "string", "description": "HelloCRM template id (WhatsApp / some SMS flows)." }, "headerParameters": { "type": "array", "description": "WhatsApp template parameter objects (Meta format).", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Parameter type." }, "text": { "type": "string", "description": "Substitution value." } } } }, "bodyParameters": { "type": "array", "description": "WhatsApp template parameter objects (Meta format).", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "Parameter type." }, "text": { "type": "string", "description": "Substitution value." } } } } }, "additionalProperties": false, "example": { "to": "+15551234567,+15559876543", "channel": "whatsapp", "content": "Hello {{contact.firstName}}, your appointment is scheduled.", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "64db8124cb0a330f257cb0c2", "templateId": "646b8124cb0a330f257cb010", "headerParameters": [ { "type": "text", "text": "Hey" } ], "bodyParameters": [ { "type": "text", "text": "Hey body" } ], "attachments": [], "scheduleType": "now", "scheduleTime": { "date": "", "time": "" } } } ], "description": "Multiple request shapes share this endpoint. Expand a variant below for **required vs optional** fields." }, "examples": { "Bulk_send_email": { "summary": "Bulk send email", "value": { "to": "alice@example.com,bob@example.com", "channel": "email", "subject": "Bulk campaign subject", "preheader": "", "content": "

Hello {{contact.firstName}}, this is a bulk email.

", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "64db8124cb0a330f257cb0c2", "attachments": [], "scheduleType": "now", "scheduleTime": { "date": "", "time": "" } } }, "Bulk_send_SMS": { "summary": "Bulk send SMS", "value": { "to": "+15551234567,+15559876543", "channel": "sms", "content": "Hello {{contact.firstName}}, your appointment is scheduled.", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "64db8124cb0a330f257cb0c2", "attachments": [], "scheduleType": "now", "scheduleTime": { "date": "", "time": "" } } }, "Bulk_send_WhatsApp": { "summary": "Bulk send WhatsApp", "value": { "to": "+15551234567,+15559876543", "channel": "whatsapp", "content": "Hello {{contact.firstName}}, your appointment is scheduled.", "mediaUrl": "", "mediaType": "", "source": "HelloCRM", "providerId": "64db8124cb0a330f257cb0c2", "templateId": "646b8124cb0a330f257cb010", "headerParameters": [ { "type": "text", "text": "Hey" } ], "bodyParameters": [ { "type": "text", "text": "Hey body" } ], "attachments": [], "scheduleType": "now", "scheduleTime": { "date": "", "time": "" } } } } } } }, "responses": { "200": { "description": "Bulk send queued", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "Bulk_send_email": { "summary": "Bulk send email", "value": { "success": true, "message": "Send successfully" } }, "Bulk_send_SMS": { "summary": "Bulk send SMS", "value": { "success": true, "message": "Send successfully" } }, "Bulk_send_WhatsApp": { "summary": "Bulk send WhatsApp", "value": { "success": true, "message": "Send successfully" } } } } } }, "201": { "description": "Bulk send queued", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "Bulk_send_email": { "summary": "Bulk send email", "value": { "success": true, "message": "Send successfully" } }, "Bulk_send_SMS": { "summary": "Bulk send SMS", "value": { "success": true, "message": "Send successfully" } }, "Bulk_send_WhatsApp": { "summary": "Bulk send WhatsApp", "value": { "success": true, "message": "Send successfully" } } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Bulk send email", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendBulkNewMessages \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"alice@example.com,bob@example.com\",\n \"channel\": \"email\",\n \"subject\": \"Bulk campaign subject\",\n \"preheader\": \"\",\n \"content\": \"

Hello {{contact.firstName}}, this is a bulk email.

\",\n \"mediaUrl\": \"\",\n \"mediaType\": \"\",\n \"source\": \"HelloCRM\",\n \"providerId\": \"64db8124cb0a330f257cb0c2\",\n \"attachments\": [],\n \"scheduleType\": \"now\",\n \"scheduleTime\": { \"date\": \"\", \"time\": \"\" }\n }'" }, { "lang": "curl", "label": "Bulk send SMS", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendBulkNewMessages \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"+15551234567,+15559876543\",\n \"channel\": \"sms\",\n \"content\": \"Hello {{contact.firstName}}, your appointment is scheduled.\",\n \"mediaUrl\": \"\",\n \"mediaType\": \"\",\n \"source\": \"HelloCRM\",\n \"providerId\": \"64db8124cb0a330f257cb0c2\",\n \"attachments\": [],\n \"scheduleType\": \"now\",\n \"scheduleTime\": { \"date\": \"\", \"time\": \"\" }\n }'" }, { "lang": "curl", "label": "Bulk send WhatsApp", "source": "curl -X POST https://api.hellocrm.ai/api/messages/sendBulkNewMessages \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"to\": \"+15551234567,+15559876543\",\n \"channel\": \"whatsapp\",\n \"content\": \"Hello {{contact.firstName}}, your appointment is scheduled.\",\n \"mediaUrl\": \"\",\n \"mediaType\": \"\",\n \"source\": \"HelloCRM\",\n \"providerId\": \"64db8124cb0a330f257cb0c2\",\n \"templateId\": \"646b8124cb0a330f257cb010\",\n \"headerParameters\": [{ \"type\": \"text\", \"text\": \"Hey\" }],\n \"bodyParameters\": [{ \"type\": \"text\", \"text\": \"Hey body\" }],\n \"attachments\": [],\n \"scheduleType\": \"now\",\n \"scheduleTime\": { \"date\": \"\", \"time\": \"\" }\n }'" } ] } }, "/api/templates": { "get": { "tags": [ "Templates" ], "summary": "List templates", "description": "**List templates**\n\nPaginated list. Agents see only their templates; admins see team templates.\n\n\nQuery `types` and `statuses` filter results. Agents see only their templates.", "operationId": "List_templates", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "string", "example": "1" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size", "schema": { "type": "string", "example": "20" } }, { "name": "types", "in": "query", "required": false, "description": "Filter: sms, email, whatsapp (repeat or array per server)", "schema": { "type": "string", "example": "sms" } }, { "name": "statuses", "in": "query", "required": false, "description": "Filter: pending, approved, rejected", "schema": { "type": "string", "example": "approved" } } ], "responses": { "200": { "description": "Paginated template list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Found.", "data": [ { "_id": "646b8124cb0a330f257cb010", "templateType": "sms", "name": "Appointment reminder", "uniqueName": "appointment_reminder_sms", "content": "Hello {{contact.firstName}}, your appointment is on {{appointment.date}}.", "status": "approved", "category": "UTILITY", "language": "en" } ], "pagination": { "totalResults": 1, "totalPages": 1, "currentPage": 1, "limit": 20, "hasMore": false } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "List templates", "source": "curl -X GET \"https://api.hellocrm.ai/api/templates?page=1&limit=20&types=sms&statuses=approved\" \\\n -H \"Accept: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] }, "post": { "tags": [ "Templates" ], "summary": "Create SMS template (and variants)", "description": "**Create SMS template**\n\n`templateType` must be `sms`. Returns `data._id` — use as `templateId` when sending messages.\n\n\nUse `data._id` from the response as `templateId` in message send APIs.\n\n---\n\n**Create email template**\n\n`templateType` must be `email`. Include `subject` and HTML `content`.\n\n\nUse `data._id` as `templateId` when referencing this template in sends.\n\n---\n\n**Create WhatsApp template**\n\n`templateType` must be `whatsapp`. Submitted to Meta for approval. For image/video/document headers, send `multipart/form-data` with a `file` field (see schema notes).\n\n\nFor image/video/document headers, use `multipart/form-data` with field `file` plus the same text fields. Status is often `pending` until Meta approves.", "operationId": "Create_SMS_template_or_Create_email_template_or_Create_WhatsApp_template", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Create SMS template", "type": "object", "description": "`POST /api/templates` with `templateType: sms`. Response `data._id` is the template id for send APIs.", "required": [ "templateType", "name", "uniqueName", "content", "provider" ], "properties": { "templateType": { "type": "string", "enum": [ "sms" ], "description": "Must be `sms`." }, "name": { "type": "string", "description": "Display name in HelloCRM." }, "uniqueName": { "type": "string", "description": "Unique slug / DLT id." }, "content": { "type": "string", "description": "SMS body with merge fields." }, "category": { "type": "string", "description": "Optional category label." }, "language": { "type": "string", "description": "BCP-47 code, e.g. `en`." }, "provider": { "type": "string", "description": "SMS provider id." }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Merge field keys referenced in content." } }, "additionalProperties": false, "example": { "templateType": "sms", "name": "Appointment reminder", "uniqueName": "appointment_reminder_sms", "content": "Hello {{contact.firstName}}, your appointment is on {{appointment.date}}.", "category": "UTILITY", "language": "en", "provider": "64db8124cb0a330f257cb0c2", "variables": [ "contact.firstName", "appointment.date" ] } }, { "title": "Create email template", "type": "object", "description": "`POST /api/templates` with `templateType: email`.", "required": [ "templateType", "name", "uniqueName", "subject", "content", "provider" ], "properties": { "templateType": { "type": "string", "enum": [ "email" ], "description": "Must be `email`." }, "name": { "type": "string", "description": "Display name in HelloCRM." }, "uniqueName": { "type": "string", "description": "Unique slug." }, "subject": { "type": "string", "description": "Email subject line." }, "content": { "type": "string", "description": "HTML email body." }, "preheader": { "type": "string", "description": "Inbox preheader (optional)." }, "language": { "type": "string", "description": "BCP-47 code, e.g. `en`." }, "provider": { "type": "string", "description": "Email provider id." }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Merge field keys referenced in subject/body." } }, "additionalProperties": false, "example": { "templateType": "email", "name": "Welcome email", "uniqueName": "welcome_email", "subject": "Welcome to {{company.name}}", "content": "

Hello {{contact.firstName}}, welcome aboard.

", "language": "en", "provider": "64db8124cb0a330f257cb0c2", "variables": [ "contact.firstName", "company.name" ], "preheader": "We're glad you're here" } }, { "title": "Create WhatsApp template", "type": "object", "description": "`POST /api/templates` with `templateType: whatsapp`. JSON shown below; use `multipart/form-data` when uploading header media (`file`). Status is usually `pending` until Meta approves.", "required": [ "templateType", "name", "uniqueName", "content", "category", "language", "provider" ], "properties": { "templateType": { "type": "string", "enum": [ "whatsapp" ], "description": "Must be `whatsapp`." }, "name": { "type": "string", "description": "Display name in HelloCRM." }, "uniqueName": { "type": "string", "description": "Meta template name (snake_case)." }, "content": { "type": "string", "description": "Template body with {{1}} style placeholders." }, "category": { "type": "string", "enum": [ "UTILITY", "MARKETING", "AUTHENTICATION" ], "description": "Meta template category." }, "language": { "type": "string", "description": "BCP-47 code, e.g. `en`." }, "provider": { "type": "string", "description": "WhatsApp provider id." }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Body variable placeholders." }, "bodyVariableSampleValues": { "type": "array", "items": { "type": "string" }, "description": "Sample values for Meta review." }, "headerVariables": { "type": "array", "items": { "type": "string" }, "description": "Header placeholders when header is text." }, "headerVariableSampleValues": { "type": "array", "items": { "type": "string" } }, "isHeader": { "type": "boolean", "description": "Whether template includes a header." }, "headerType": { "type": "string", "enum": [ "text", "image", "video", "document" ], "description": "Header format; non-text headers need `file` upload." }, "headerText": { "type": "string", "description": "Header text when `headerType` is `text`." }, "footer": { "type": "string", "description": "Optional footer line." }, "templateButtons": { "type": "array", "description": "Quick reply, URL, or phone buttons (JSON string in multipart)." }, "file": { "type": "string", "description": "Multipart only — header media file." } }, "additionalProperties": false, "example": { "templateType": "whatsapp", "name": "Appointment reminder", "uniqueName": "appointment_reminder_wa", "content": "Hello {{1}}, your appointment is on {{2}}.", "category": "UTILITY", "language": "en", "provider": "64db8124cb0a330f257cb0c2", "variables": [ "{{1}}", "{{2}}" ], "bodyVariableSampleValues": [ "Jane", "May 20" ], "isHeader": false, "headerType": "text", "footer": "Reply STOP to opt out" } } ], "description": "Multiple request shapes share this endpoint. Expand a variant below for **required vs optional** fields." }, "examples": { "Create_SMS_template": { "summary": "Create SMS template", "value": { "templateType": "sms", "name": "Appointment reminder", "uniqueName": "appointment_reminder_sms", "content": "Hello {{contact.firstName}}, your appointment is on {{appointment.date}}.", "category": "UTILITY", "language": "en", "provider": "64db8124cb0a330f257cb0c2", "variables": [ "contact.firstName", "appointment.date" ] } }, "Create_email_template": { "summary": "Create email template", "value": { "templateType": "email", "name": "Welcome email", "uniqueName": "welcome_email", "subject": "Welcome to {{company.name}}", "content": "

Hello {{contact.firstName}}, welcome aboard.

", "language": "en", "provider": "64db8124cb0a330f257cb0c2", "variables": [ "contact.firstName", "company.name" ], "preheader": "We're glad you're here" } }, "Create_WhatsApp_template": { "summary": "Create WhatsApp template", "value": { "templateType": "whatsapp", "name": "Appointment reminder", "uniqueName": "appointment_reminder_wa", "content": "Hello {{1}}, your appointment is on {{2}}.", "category": "UTILITY", "language": "en", "provider": "64db8124cb0a330f257cb0c2", "variables": [ "{{1}}", "{{2}}" ], "bodyVariableSampleValues": [ "Jane", "May 20" ], "isHeader": false, "headerType": "text", "footer": "Reply STOP to opt out" } } } } } }, "responses": { "200": { "description": "SMS template created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "Create_SMS_template": { "summary": "Create SMS template", "value": { "success": true, "message": "Template created.", "data": { "_id": "646b8124cb0a330f257cb010", "templateType": "sms", "name": "Appointment reminder", "status": "approved" } } }, "Create_email_template": { "summary": "Create email template", "value": { "success": true, "message": "Template created.", "data": { "_id": "646b8124cb0a330f257cb011", "templateType": "email", "name": "Welcome email", "subject": "Welcome to Acme", "status": "approved" } } }, "Create_WhatsApp_template": { "summary": "Create WhatsApp template", "value": { "success": true, "message": "Template created.", "data": { "_id": "646b8124cb0a330f257cb012", "templateType": "whatsapp", "name": "Appointment reminder", "status": "pending" } } } } } } }, "201": { "description": "SMS template created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "Create_SMS_template": { "summary": "Create SMS template", "value": { "success": true, "message": "Template created.", "data": { "_id": "646b8124cb0a330f257cb010", "templateType": "sms", "name": "Appointment reminder", "status": "approved" } } }, "Create_email_template": { "summary": "Create email template", "value": { "success": true, "message": "Template created.", "data": { "_id": "646b8124cb0a330f257cb011", "templateType": "email", "name": "Welcome email", "subject": "Welcome to Acme", "status": "approved" } } }, "Create_WhatsApp_template": { "summary": "Create WhatsApp template", "value": { "success": true, "message": "Template created.", "data": { "_id": "646b8124cb0a330f257cb012", "templateType": "whatsapp", "name": "Appointment reminder", "status": "pending" } } } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Create SMS template", "source": "curl -X POST https://api.hellocrm.ai/api/templates \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"templateType\": \"sms\",\n \"name\": \"Appointment reminder\",\n \"uniqueName\": \"appointment_reminder_sms\",\n \"content\": \"Hello {{contact.firstName}}, your appointment is on {{appointment.date}}.\",\n \"category\": \"UTILITY\",\n \"language\": \"en\",\n \"provider\": \"64db8124cb0a330f257cb0c2\",\n \"variables\": [\"contact.firstName\", \"appointment.date\"]\n }'" }, { "lang": "curl", "label": "Create email template", "source": "curl -X POST https://api.hellocrm.ai/api/templates \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"templateType\": \"email\",\n \"name\": \"Welcome email\",\n \"uniqueName\": \"welcome_email\",\n \"subject\": \"Welcome to {{company.name}}\",\n \"content\": \"

Hello {{contact.firstName}}, welcome aboard.

\",\n \"language\": \"en\",\n \"provider\": \"64db8124cb0a330f257cb0c2\",\n \"variables\": [\"contact.firstName\", \"company.name\"],\n \"preheader\": \"We are glad you are here\"\n }'" }, { "lang": "curl", "label": "Create WhatsApp template", "source": "curl -X POST https://api.hellocrm.ai/api/templates \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"templateType\": \"whatsapp\",\n \"name\": \"Appointment reminder\",\n \"uniqueName\": \"appointment_reminder_wa\",\n \"content\": \"Hello {{1}}, your appointment is on {{2}}.\",\n \"category\": \"UTILITY\",\n \"language\": \"en\",\n \"provider\": \"64db8124cb0a330f257cb0c2\",\n \"variables\": [\"{{1}}\", \"{{2}}\"],\n \"bodyVariableSampleValues\": [\"Jane\", \"May 20\"],\n \"isHeader\": false,\n \"footer\": \"Reply STOP to opt out\"\n }'" } ] } }, "/api/templates/{templateId}": { "get": { "tags": [ "Templates" ], "summary": "Get template by id", "description": "**Get template by id**\n\nFetch one template by id.\n", "operationId": "Get_template_by_id", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "646b8124cb0a330f257cb010" } } ], "responses": { "200": { "description": "Single template", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Template retrieved successfully", "data": { "_id": "646b8124cb0a330f257cb010", "templateType": "sms", "name": "Appointment reminder", "uniqueName": "appointment_reminder_sms", "content": "Hello {{contact.firstName}}, your appointment is on {{appointment.date}}.", "status": "approved" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Get template by id", "source": "curl -X GET https://api.hellocrm.ai/api/templates/646b8124cb0a330f257cb010 \\\n -H \"Accept: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] }, "put": { "tags": [ "Templates" ], "summary": "Update template", "description": "**Update template**\n\nUpdates template by id. WhatsApp templates sync to Meta when edited.\n\n\nWhatsApp templates sync to Meta on update.", "operationId": "Update_template", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "646b8124cb0a330f257cb010" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "templateType" ], "properties": { "templateType": { "type": "string", "enum": [ "sms", "email", "whatsapp" ] }, "name": { "type": "string" }, "content": { "type": "string" }, "category": { "type": "string" }, "language": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "example": { "templateType": "sms", "name": "Appointment reminder (updated)", "content": "Hi {{contact.firstName}}, reminder: appointment on {{appointment.date}}.", "category": "UTILITY", "language": "en", "variables": [ "contact.firstName", "appointment.date" ] } } } }, "responses": { "200": { "description": "Template updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Template updated successfully", "data": { "_id": "646b8124cb0a330f257cb010", "templateType": "sms", "name": "Appointment reminder (updated)" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Update template", "source": "curl -X PUT https://api.hellocrm.ai/api/templates/646b8124cb0a330f257cb010 \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"templateType\": \"sms\",\n \"name\": \"Appointment reminder (updated)\",\n \"content\": \"Hi {{contact.firstName}}, reminder: appointment on {{appointment.date}}.\",\n \"category\": \"UTILITY\",\n \"language\": \"en\",\n \"variables\": [\"contact.firstName\", \"appointment.date\"]\n }'" } ] }, "delete": { "tags": [ "Templates" ], "summary": "Delete template", "description": "**Delete template**\n\nDeletes template by id. WhatsApp templates are removed from Meta when applicable.\n", "operationId": "Delete_template", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "646b8124cb0a330f257cb010" } } ], "responses": { "200": { "description": "Template deleted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Template deleted successfully" } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Delete template", "source": "curl -X DELETE https://api.hellocrm.ai/api/templates/646b8124cb0a330f257cb010 \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } }, "/api/contacts": { "post": { "tags": [ "Contacts" ], "summary": "Create a new contact", "description": "**Create a new contact**\n\n`status`: open, in-progress, closed. `lifecycleStage`: Form, Live Chat, Ads, Event, CRM, Other.\n\n\n`status`: open, in-progress, closed. `lifecycleStage`: Form, Live Chat, Ads, Event, CRM, Other.", "operationId": "Create_a_new_contact", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "firstName", "lastName" ], "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "description": "E.164 recommended." }, "status": { "type": "string", "enum": [ "open", "in-progress", "closed" ], "description": "Contact status." }, "source": { "type": "string", "description": "Lead source label." }, "lifecycleStage": { "type": "string", "description": "Form, Live Chat, Ads, Event, CRM, Other, Lead, Customer, etc." }, "groupIds": { "type": "array", "items": { "type": "string" }, "description": "Group ids." }, "additionalFields": { "type": "object", "additionalProperties": true, "description": "Custom field key/value map." } }, "additionalProperties": false }, "example": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+1234567890", "status": "open", "source": "Website", "lifecycleStage": "Lead", "groupIds": [ "64f91a7d28ae948d8e9e8435" ], "additionalFields": { "job_title": "Marketing Manager", "city": "New York" } } } } }, "responses": { "201": { "description": "Contact created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Contact created successfully.", "data": { "_id": "64f91a7d28ae948d8e9e8430", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+1234567890", "status": "open", "lifecycleStage": "Lead", "teamId": "64f91a7d28ae948d8e9e8400", "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Create a new contact", "source": "curl -X POST https://api.hellocrm.ai/api/contacts \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\",\n \"status\": \"open\",\n \"source\": \"Website\",\n \"lifecycleStage\": \"Lead\",\n \"groupIds\": [\"64f91a7d28ae948d8e9e8435\"],\n \"additionalFields\": {\n \"job_title\": \"Marketing Manager\",\n \"city\": \"New York\"\n }\n }'" } ] } }, "/api/contacts/{contactId}": { "put": { "tags": [ "Contacts" ], "summary": "Update an existing contact", "description": "**Update an existing contact**\n\nUpdates a contact by id.\n", "operationId": "Update_an_existing_contact", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "in-progress", "closed" ] }, "source": { "type": "string" }, "lifecycleStage": { "type": "string" }, "groupIds": { "type": "array", "items": { "type": "string" } }, "company": { "type": "string", "description": "Company id." }, "additionalFields": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "example": { "firstName": "Jane", "lastName": "Doe", "email": "jane.doe@example.com", "phone": "+19876543210", "status": "open", "source": "LinkedIn", "lifecycleStage": "Customer", "groupIds": [ "64f91a7d28ae948d8e9e8435" ], "company": "64f91a7d28ae948d8e9e9999", "additionalFields": { "job_title": "CTO", "location": "San Francisco" } } } } }, "responses": { "200": { "description": "Contact updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Contact updated successfully.", "data": { "_id": "64f91a7d28ae948d8e9e8430", "firstName": "Jane", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+1234567890", "status": "open", "lifecycleStage": "Customer", "teamId": "64f91a7d28ae948d8e9e8400", "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Update an existing contact", "source": "curl -X PUT https://api.hellocrm.ai/api/contacts/CONTACT_ID_HERE \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"email\": \"jane.doe@example.com\",\n \"phone\": \"+19876543210\",\n \"status\": \"open\",\n \"source\": \"LinkedIn\",\n \"lifecycleStage\": \"Customer\",\n \"groupIds\": [\"64f91a7d28ae948d8e9e8435\"],\n \"company\": \"64f91a7d28ae948d8e9e9999\",\n \"additionalFields\": {\n \"job_title\": \"CTO\",\n \"location\": \"San Francisco\"\n }\n }'" } ] }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact by id", "description": "**Delete a contact by id**\n\nDeletes a contact.\n", "operationId": "Delete_a_contact_by_id", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } } ], "responses": { "200": { "description": "Contact deleted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Contact and associated data deleted successfully.", "data": { "_id": "64f91a7d28ae948d8e9e8430", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+1234567890", "status": "open", "lifecycleStage": "Lead", "teamId": "64f91a7d28ae948d8e9e8400", "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Delete a contact by id", "source": "curl -X DELETE https://api.hellocrm.ai/api/contacts/CONTACT_ID_HERE \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } }, "/api/contacts/createOrUpdateContact": { "post": { "tags": [ "Contacts" ], "summary": "Upsert a contact by matching rules (email/phone)", "description": "**Upsert a contact by matching rules (email/phone)**\n\nUse `Content-Type: application/json` (not `text/plain`).\n\n\nUse `Content-Type: application/json` (not `text/plain`).", "operationId": "Upsert_a_contact_by_matching_rules_email_phone", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "firstName", "lastName" ], "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "lifecycleStage": { "type": "string" }, "additionalFields": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "example": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+1234567890", "status": "open", "source": "CRM", "lifecycleStage": "Lead", "additionalFields": { "job_title": "Marketing Manager", "city": "New York" } } } } }, "responses": { "200": { "description": "Contact created or updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Contact created successfully.", "data": { "_id": "64f91a7d28ae948d8e9e8430", "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+1234567890", "status": "open", "lifecycleStage": "Lead", "teamId": "64f91a7d28ae948d8e9e8400", "createdAt": "2025-01-15T10:00:00.000Z", "updatedAt": "2025-01-15T10:00:00.000Z" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Upsert a contact by matching rules (email/phone)", "source": "curl -X POST https://api.hellocrm.ai/api/contacts/createOrUpdateContact \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\",\n \"status\": \"open\",\n \"source\": \"CRM\",\n \"lifecycleStage\": \"Lead\",\n \"additionalFields\": {\n \"job_title\": \"Marketing Manager\",\n \"city\": \"New York\"\n }\n }'" } ] } }, "/api/contacts/deleteContactsByEmail": { "delete": { "tags": [ "Contacts" ], "summary": "Delete contacts matching an email address", "description": "**Delete contacts matching an email address**\n\nDeletes contacts for the given `email` query parameter.\n", "operationId": "Delete_contacts_matching_an_email_address", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "email", "in": "query", "required": false, "description": "(Required) ", "schema": { "type": "string", "example": "test@gmail.com" } } ], "responses": { "200": { "description": "Contacts deleted by email", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Deleted 1 contact(s) and associated data successfully." } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Delete contacts matching an email address", "source": "curl -X DELETE \"https://api.hellocrm.ai/api/contacts/deleteContactsByEmail?email=test@gmail.com\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } }, "/api/companies/create": { "post": { "tags": [ "Companies" ], "summary": "Create company", "description": "**Create company**\n\nCreates a company.\n", "operationId": "Create_company", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "industry": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } }, "additionalProperties": false }, "example": { "name": "Acme Corporation", "domain": "acme.com", "industry": "Technology", "email": "info@acme.com", "phoneNumber": "+1234567890", "logoUrl": "https://logo.clearbit.com/acme.com", "address": "123 Main St", "city": "San Francisco", "state": "CA", "postalCode": "94105", "country": "USA", "employeeCount": 200, "annualRevenue": 5000000, "contacts": [ "64f91a7d28ae948d8e9e8431" ], "additionalFields": { "founded": "2005", "website": "https://www.acme.com" } } } } }, "responses": { "201": { "description": "Company created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Company created successfully", "data": { "_id": "64f91a7d28ae948d8e9e9999", "name": "Acme Corporation", "domain": "acme.com", "teamId": "64f91a7d28ae948d8e9e8400" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Create company", "source": "curl -X POST https://api.hellocrm.ai/api/companies/create \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"name\": \"Acme Corporation\",\n \"domain\": \"acme.com\",\n \"industry\": \"Technology\",\n \"email\": \"info@acme.com\",\n \"phoneNumber\": \"+1234567890\",\n \"logoUrl\": \"https://logo.clearbit.com/acme.com\",\n \"address\": \"123 Main St\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postalCode\": \"94105\",\n \"country\": \"USA\",\n \"employeeCount\": 200,\n \"annualRevenue\": 5000000,\n \"contacts\": [\"64f91a7d28ae948d8e9e8431\"],\n \"additionalFields\": {\n \"founded\": \"2005\",\n \"website\": \"https://www.acme.com\"\n }\n }'" } ] } }, "/api/companies/edit/{companyId}": { "put": { "tags": [ "Companies" ], "summary": "Update company", "description": "**Update company**\n\nUpdates a company by id.\n", "operationId": "Update_company", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "companyId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "industry": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } }, "additionalProperties": false }, "example": { "name": "Acme Corp International", "domain": "acme.com", "industry": "Enterprise Software", "additionalFields": { "updated_by": "Admin" } } } } }, "responses": { "200": { "description": "Company updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Company updated successfully", "data": { "_id": "64f91a7d28ae948d8e9e9999", "name": "Acme Corp International", "domain": "acme.com", "teamId": "64f91a7d28ae948d8e9e8400" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Update company", "source": "curl -X PUT https://api.hellocrm.ai/api/companies/edit/COMPANY_ID_HERE \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"name\": \"Acme Corp International\",\n \"domain\": \"acme.com\",\n \"industry\": \"Enterprise Software\",\n \"additionalFields\": {\n \"updated_by\": \"Admin\"\n }\n }'" } ] } }, "/api/companies/delete/{companyId}": { "delete": { "tags": [ "Companies" ], "summary": "Delete company", "description": "**Delete company**\n\nDeletes a company by id.\n", "operationId": "Delete_company", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "companyId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } } ], "responses": { "200": { "description": "Company deleted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Company deleted successfully" } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Delete company", "source": "curl -X DELETE https://api.hellocrm.ai/api/companies/delete/COMPANY_ID_HERE \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } }, "/api/products": { "post": { "tags": [ "Products" ], "summary": "Create a product", "description": "**Create a product**\n\n`billingFrequency`: one-time, weekly, every-two-weeks, monthly, quarterly, semi-annually, annually, etc.\n\n\n`billingFrequency`: one-time, weekly, every-two-weeks, monthly, quarterly, semi-annually, annually, every-two-years, every-three-years, every-four-years, every-five-years.", "operationId": "Create_a_product", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "unitPrice" ], "properties": { "name": { "type": "string" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unitPrice": { "type": "number", "description": "Sell price." }, "unitCost": { "type": "number", "description": "Cost basis." }, "billingFrequency": { "type": "string", "enum": [ "one_time", "monthly", "quarterly", "annually" ], "description": "Billing cadence." } }, "additionalProperties": false }, "example": { "name": "Pro CRM Subscription", "sku": "PRO-CRM-001", "description": "Advanced CRM plan with automation and reporting", "billingFrequency": "monthly", "term": "12 months", "productType": "subscription", "imageUrl": "https://example.com/images/product.png", "url": "https://example.com/products/pro-crm", "unitCost": 20, "unitPrice": 50 } } } }, "responses": { "201": { "description": "Product created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Product created successfully", "data": { "_id": "64f91a7d28ae948d8e9e8430", "name": "Pro CRM Subscription", "sku": "PRO-CRM-001", "unitPrice": 50, "unitCost": 20 } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Create a product", "source": "curl -X POST https://api.hellocrm.ai/api/products \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"name\": \"Pro CRM Subscription\",\n \"sku\": \"PRO-CRM-001\",\n \"description\": \"Advanced CRM plan with automation and reporting\",\n \"billingFrequency\": \"monthly\",\n \"term\": \"12 months\",\n \"productType\": \"subscription\",\n \"imageUrl\": \"https://example.com/images/product.png\",\n \"url\": \"https://example.com/products/pro-crm\",\n \"unitCost\": 20,\n \"unitPrice\": 50\n }'" } ] } }, "/api/products/{productId}": { "put": { "tags": [ "Products" ], "summary": "Update a product", "description": "**Update a product**\n\nUpdates a product by id.\n", "operationId": "Update_a_product", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "sku": { "type": "string" }, "description": { "type": "string" }, "unitPrice": { "type": "number" }, "unitCost": { "type": "number" }, "billingFrequency": { "type": "string", "enum": [ "one_time", "monthly", "quarterly", "annually" ] } }, "additionalProperties": false }, "example": { "name": "Pro CRM Plus", "sku": "PRO-CRM-002", "description": "Updated plan with more integrations", "billingFrequency": "monthly", "term": "12 months", "productType": "subscription", "imageUrl": "https://example.com/images/pro-crm-plus.png", "url": "https://example.com/products/pro-crm-plus", "unitCost": 25, "unitPrice": 60 } } } }, "responses": { "200": { "description": "Product updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Product updated successfully", "data": { "_id": "64f91a7d28ae948d8e9e8430", "name": "Pro CRM Plus", "sku": "PRO-CRM-001", "unitPrice": 60, "unitCost": 20 } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Update a product", "source": "curl -X PUT https://api.hellocrm.ai/api/products/PRODUCT_ID_HERE \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"name\": \"Pro CRM Plus\",\n \"sku\": \"PRO-CRM-002\",\n \"description\": \"Updated plan with more integrations\",\n \"billingFrequency\": \"monthly\",\n \"term\": \"12 months\",\n \"productType\": \"subscription\",\n \"imageUrl\": \"https://example.com/images/pro-crm-plus.png\",\n \"url\": \"https://example.com/products/pro-crm-plus\",\n \"unitCost\": 25,\n \"unitPrice\": 60\n }'" } ] }, "delete": { "tags": [ "Products" ], "summary": "Delete a product", "description": "**Delete a product**\n\nDeletes a product.\n", "operationId": "Delete_a_product", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } } ], "responses": { "200": { "description": "Product deleted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Product deleted successfully" } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Delete a product", "source": "curl -X DELETE https://api.hellocrm.ai/api/products/PRODUCT_ID_HERE \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } }, "/api/deals/create": { "post": { "tags": [ "Deals" ], "summary": "Create deal", "description": "**Create deal**\n\nCreates a deal.\n", "operationId": "Create_deal", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "pipeline", "stage" ], "properties": { "name": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string", "description": "ISO 4217, e.g. USD." }, "pipeline": { "type": "string", "description": "Pipeline id." }, "stage": { "type": "string", "description": "Stage id." }, "contactId": { "type": "string" }, "companyId": { "type": "string" }, "closeDate": { "type": "string", "description": "ISO date string." } }, "additionalProperties": false }, "example": { "name": "Enterprise CRM Deal", "description": "Annual CRM contract", "amount": 50000, "currency": "USD", "pipeline": "PIPELINE_ID_HERE", "stage": "STAGE_ID_HERE", "closeDate": "2025-08-30", "contacts": [ "CONTACT_ID_1", "CONTACT_ID_2" ], "company": "COMPANY_ID_HERE", "owner": "USER_ID_HERE" } } } }, "responses": { "200": { "description": "Deal created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Deal created successfully", "data": { "_id": "64f91a7d28ae948d8e9e8888", "name": "Enterprise CRM Deal", "amount": 50000, "currency": "USD", "stage": "STAGE_ID_HERE", "pipeline": "PIPELINE_ID_HERE" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Create deal", "source": "curl -X POST https://api.hellocrm.ai/api/deals/create \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"name\": \"Enterprise CRM Deal\",\n \"description\": \"Annual CRM contract\",\n \"amount\": 50000,\n \"currency\": \"USD\",\n \"pipeline\": \"PIPELINE_ID_HERE\",\n \"stage\": \"STAGE_ID_HERE\",\n \"closeDate\": \"2025-08-30\",\n \"contacts\": [\"CONTACT_ID_1\", \"CONTACT_ID_2\"],\n \"company\": \"COMPANY_ID_HERE\",\n \"owner\": \"USER_ID_HERE\"\n }'" } ] } }, "/api/deals/edit/{dealId}": { "put": { "tags": [ "Deals" ], "summary": "Update deal", "description": "**Update deal**\n\nUpdates a deal by id.\n", "operationId": "Update_deal", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "dealId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "pipeline": { "type": "string" }, "stage": { "type": "string" }, "contactId": { "type": "string" }, "companyId": { "type": "string" }, "closeDate": { "type": "string" } }, "additionalProperties": false }, "example": { "name": "Updated CRM Enterprise Deal", "description": "Updated description for annual enterprise deal", "amount": 60000, "currency": "USD", "pipeline": "PIPELINE_ID_HERE", "stage": "STAGE_ID_HERE", "closeDate": "2025-12-31", "contacts": [ "CONTACT_ID_1", "CONTACT_ID_3" ], "company": "COMPANY_ID_HERE", "owner": "USER_ID_HERE" } } } }, "responses": { "200": { "description": "Deal updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Saved successfully", "data": { "_id": "64f91a7d28ae948d8e9e8888", "name": "Enterprise CRM Deal", "amount": 60000, "currency": "USD", "stage": "STAGE_ID_HERE", "pipeline": "PIPELINE_ID_HERE" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Update deal", "source": "curl -X PUT https://api.hellocrm.ai/api/deals/edit/DEAL_ID_HERE \\\n -H \"Content-Type: application/json\" \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -d '{\n \"name\": \"Updated CRM Enterprise Deal\",\n \"description\": \"Updated description for annual enterprise deal\",\n \"amount\": 60000,\n \"currency\": \"USD\",\n \"pipeline\": \"PIPELINE_ID_HERE\",\n \"stage\": \"STAGE_ID_HERE\",\n \"closeDate\": \"2025-12-31\",\n \"contacts\": [\"CONTACT_ID_1\", \"CONTACT_ID_3\"],\n \"company\": \"COMPANY_ID_HERE\",\n \"owner\": \"USER_ID_HERE\"\n }'" } ] } }, "/api/deals/delete/{dealId}": { "delete": { "tags": [ "Deals" ], "summary": "Delete deal", "description": "**Delete deal**\n\nDeletes a deal (`DELETE /api/deals/delete/{dealId}`).\n", "operationId": "Delete_deal", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "dealId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "64f91a7d28ae948d8e9e8430" } } ], "responses": { "200": { "description": "Deal deleted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Deal and associated data deleted successfully" } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Delete deal", "source": "curl -X DELETE https://api.hellocrm.ai/api/deals/delete/DEAL_ID_HERE \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } }, "/api/quotes": { "post": { "tags": [ "Quotes" ], "summary": "Create a quote from a deal", "description": "**Create a quote from a deal**\n\nCreates a quote for a deal.\n", "operationId": "Create_a_quote_from_a_deal", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dealId" ], "properties": { "dealId": { "type": "string", "description": "Deal id." }, "template": { "type": "string", "description": "Quote template key, e.g. default-basic." }, "name": { "type": "string", "description": "Quote title override." } }, "additionalProperties": false }, "example": { "dealId": "YOUR_DEAL_ID" } } } }, "responses": { "201": { "description": "Quote created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Quote created successfully", "data": { "_id": "YOUR_QUOTE_ID", "dealId": "YOUR_DEAL_ID", "name": "Enterprise CRM Deal", "status": "draft", "template": "default-basic" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Create a quote from a deal", "source": "curl -X POST https://api.hellocrm.ai/api/quotes \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"dealId\": \"YOUR_DEAL_ID\"\n }'" } ] } }, "/api/quotes/{quoteId}": { "put": { "tags": [ "Quotes" ], "summary": "Update quote presentation and terms", "description": "**Update quote presentation and terms**\n\nUpdates quote fields.\n\n\n`signatureOption`: no-signature, written-signature. `status`: draft, published, expired. `template`: default-basic.", "operationId": "Update_quote_presentation_and_terms", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "YOUR_QUOTE_ID" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for safe retries on creates and message sends.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "accepted", "declined" ] }, "template": { "type": "string" }, "terms": { "type": "string" }, "notes": { "type": "string" } }, "additionalProperties": false }, "example": { "signatureOption": "written-signature", "name": "Updated Quote Name", "url": "https://quotes.example.com/q-123", "template": "default-basic", "expirationDate": "2025-10-10T00:00:00Z", "commentsToBuyer": "Please review this quote.", "purchaseTerms": "Net 30", "status": "published", "acceptOnlinePayment": true } } } }, "responses": { "200": { "description": "Quote updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Quote updated successfully", "data": { "_id": "YOUR_QUOTE_ID", "dealId": "YOUR_DEAL_ID", "name": "Enterprise CRM Deal", "status": "published", "template": "default-basic" } } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Update quote presentation and terms", "source": "curl -X PUT https://api.hellocrm.ai/api/quotes/YOUR_QUOTE_ID \\\n -H \"x-api-key: YOUR_API_KEY_HERE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"signatureOption\": \"written-signature\",\n \"name\": \"Updated Quote Name\",\n \"url\": \"https://quotes.example.com/q-123\",\n \"template\": \"default-basic\",\n \"expirationDate\": \"2025-10-10T00:00:00Z\",\n \"commentsToBuyer\": \"Please review this quote.\",\n \"purchaseTerms\": \"Net 30\",\n \"status\": \"published\",\n \"acceptOnlinePayment\": true\n }'" } ] }, "delete": { "tags": [ "Quotes" ], "summary": "Delete a quote", "description": "**Delete a quote**\n\nDeletes a quote.\n", "operationId": "Delete_a_quote", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "description": "(Required) ", "schema": { "type": "string", "example": "YOUR_QUOTE_ID" } } ], "responses": { "200": { "description": "Quote deleted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": true, "message": "Quote deleted successfully" } } } }, "400": { "description": "Bad request — missing or invalid fields", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "At least one recipientId is required" } } } }, "401": { "description": "Missing or invalid API key or token", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Unauthorized" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Resource not found" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "success": false, "message": "Internal server error" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "Delete a quote", "source": "curl -X DELETE https://api.hellocrm.ai/api/quotes/YOUR_QUOTE_ID \\\n -H \"x-api-key: YOUR_API_KEY_HERE\"" } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Team API key from HelloCRM settings." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Optional: some routes accept `Authorization: Bearer ` instead of an API key." } } }, "security": [ { "ApiKeyAuth": [] } ] }