\n
\n\nHello lemlist Team! 😎
I joined lemlist last Monday, and I am humbly offering you the chance to meet me (and probably my cat, Megatron 😽🤖) through a 15-minute call at your convenience! You can book it [here](https://app.lemcal.com/@alex-doe/quick-meeting?leadId=lea_tmOgcDHB5wWwStNtN).
See you soon!
Alex DOE
\n I joined lemlist last Monday, and I am humbly offering you the chance to meet me (and probably my cat, Megatron 😽🤖) through a 15-minute call at your convenience! You can book it [here](https://app.lemcal.com/@alex-doe/quick-meeting?leadId=lea_tmOgcDHB5wWwStNtN).
See you soon!
Alex DOE
\n \n \n
\n Haha Welcome Jordan, j'adore cette campagne !
A très vite,
A très vite,
Alex
On Tue, Dec 3, 2024 at 10:52 AM Jordan DOE <jordan.doe@example.com> wrote:
\n\n\n\nHey Alex ,
I hope this email finds you well!
Have you ever heard about Jordan Doe?
🇫🇷 He was a member of the French Parliament during the French Revolution,
🏘️ He has a street named after him
📙 He authored the famous "Beurre frais épuré, et conservant longtemps ses bonnes qualités, sans devenir rance".
Unfortunately, this brilliant man died ages ago...
But wait, there's another Jordan Doe you might be interested in meeting—one who is very much alive and well! Yes, that's me. I've just joined Lemlist, and I'm looking forward to meeting everyone for a quick chat.
☑️ Book an appointment on 📅 my lemcal !
Feel free to reach out and get to know me better. I'm excited to be part of the team and eager to contribute to our collective success.
Looking forward to seeing you all soon!
Best regards, as your contemporary, Jordan Doe\n\n\n \n\n
\n \n
\n\nHey Alex ,
I hope this email finds you well!
Have you ever heard about Jordan Doe?
🇫🇷 He was a member of the French Parliament during the French Revolution,
🏘️ He has a street named after him
📙 He authored the famous \"Beurre frais épuré, et conservant longtemps ses bonnes qualités, sans devenir rance\".![](\"https://zr0.lemlst.org/api/files/Files/fil_3WlQwHwsxgZZCRnu3.png\")
Unfortunately, this brilliant man died ages ago...
But wait, there's another Jordan Doe you might be interested in meeting—one who is very much alive and well! Yes, that's me. I've just joined Lemlist, and I'm looking forward to meeting everyone for a quick chat.
☑️ Book an appointment on 📅 my lemcal !
Feel free to reach out and get to know me better. I'm excited to be part of the team and eager to contribute to our collective success.
Looking forward to seeing you all soon!
Best regards, as your contemporary, Jordan Doe
\n \n \n
\n Hello,
Following up on our conversation...
", "cc": [], "replyToActivityId": "latest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "True when the email was sent." }, "contactId": { "type": "string", "description": "The contact the email was sent to (resolved from leadId when only a lead was provided)." } }, "additionalProperties": true }, "example": { "ok": true, "contactId": "ctc_JgrwGbHKgFoEnunBA" } } } }, "400": { "description": "Possible errors: Bad team / Invalid sendUserId / Invalid sendUserEmail / Invalid sendUserMailboxId / contactId or leadId is required / Invalid leadId / Lead not found / Failed to send email", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } }, "parameters": [] } }, "/inbox/linkedin": { "post": { "summary": "Send LinkedIn Message", "tags": [ "Inbox" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sendUserId": { "type": "string", "description": "Sender user ID" }, "leadId": { "type": "string", "description": "Lead ID" }, "contactId": { "type": "string", "description": "Contact ID" }, "message": { "type": "string", "description": "Message content" } }, "required": [ "sendUserId", "leadId", "contactId", "message" ] }, "example": { "sendUserId": "usr_FU6yAd3UdBFel0UDy", "leadId": "lea_wadZOcDDSFWSbFaCf", "contactId": "ctc_ei6zVayP9B2ugwUPN", "message": "Hi, I wanted to follow up..." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "400": { "description": "Possible errors: Bad team / Invalid sendUserId / contactId or leadId is required / Invalid leadId / Lead not found / Invalid contactId / Failed to send message", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } }, "parameters": [] } }, "/inbox/whatsapp": { "post": { "summary": "Send WhatsApp Message", "tags": [ "Inbox" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sendUserId": { "type": "string", "description": "Sender user ID" }, "sendUserWhatsappAccountId": { "type": "string", "description": "WhatsApp account ID" }, "contactId": { "type": "string", "description": "Contact ID" }, "leadId": { "type": "string", "description": "Lead ID" }, "message": { "type": "string", "description": "Message content" } }, "required": [ "sendUserId", "sendUserWhatsappAccountId", "contactId", "leadId", "message" ] }, "example": { "sendUserId": "usr_FU6yAd3UdBFel0UDy", "sendUserWhatsappAccountId": "wha_ABC123", "contactId": "ctc_ei6zVayP9B2ugwUPN", "leadId": "lea_wadZOcDDSFWSbFaCf", "message": "Hi, following up on our conversation" } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Possible errors: Bad team / Invalid sendUserId / Invalid sendUserWhatsappAccountId / contactId or leadId is required / Invalid leadId / Lead not found / Failed to send whatsapp message", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } }, "parameters": [] } }, "/inbox/labels": { "get": { "summary": "Get Many Labels", "description": "List all labels available to your team.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success - Returns array of labels", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Label" } }, "example": [ { "_id": "lbl_uPAAgsi4oi9juBHfW", "name": "Interested", "color": "#F9A2A2", "createdAt": "2025-11-26T15:49:23.470Z", "createdBy": "john.doe@example.com" } ] } } }, "400": { "description": "Bad team", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } } }, "parameters": [] }, "post": { "summary": "Create Label", "description": "Creates a new label available to the team.", "tags": [ "Inbox" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "labelName": { "type": "string", "description": "Name of the label to create" } }, "required": [ "labelName" ] }, "example": { "labelName": "Interested" } } } }, "responses": { "200": { "description": "Success - Label created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" }, "example": { "_id": "lbl_uPAAgsi4oi9juBHfW", "name": "Interested", "color": "#F9A2A2", "createdAt": "2025-11-26T15:49:23.470Z" } } } }, "400": { "description": "Possible errors: Bad team / labelName is required / Failed to create label", "content": { "text/plain": { "example": "labelName is required" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "409": { "description": "Label with this name already exists", "content": { "text/plain": { "example": "Label with this name already exists" } } }, "405": { "description": "Method not allowed" } }, "parameters": [] } }, "/inbox/labels/{labelId}": { "get": { "summary": "Get Label", "description": "Get info of a specific label.", "tags": [ "Inbox" ], "parameters": [ { "name": "labelId", "in": "path", "required": true, "description": "Label ID", "example": "lbl_uPAAgsi4oi9juBHfW", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" }, "example": { "_id": "lbl_uPAAgsi4oi9juBHfW", "name": "Interested", "color": "#F9A2A2", "createdAt": "2025-11-26T15:49:23.470Z", "createdBy": "john.doe@example.com" } } } }, "400": { "description": "Bad team", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Label not found", "content": { "text/plain": { "example": "Label not found" } } }, "405": { "description": "Method not allowed" } } } }, "/inbox/conversations/labels/{contactId}": { "post": { "summary": "Attach Labels to Conversations", "description": "Attaches one or more labels to one or more conversations.", "tags": [ "Inbox" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "Contact ID", "example": "ctc_ei6zVayP9B2ugwUPN", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "labelIds": { "type": "array", "description": "Array of label IDs to attach", "items": { "type": "string" } }, "appendLabels": { "type": "boolean", "description": "If true, appends labels to existing ones. If false, replaces all labels." } }, "required": [ "labelIds", "appendLabels" ] }, "example": { "labelIds": [ "lbl_uPAAgsi4oi9juBHfW", "lbl_oZCShmPCP2L43b8qf" ], "appendLabels": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "400": { "description": "Possible errors: Bad team / Invalid request body: labelIds must be an array and appendLabels must be a boolean", "content": { "text/plain": { "example": "Invalid request body: labelIds must be an array and appendLabels must be a boolean" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Possible errors: Inbox not found / Label not found", "content": { "text/plain": { "example": "Label not found" } } }, "405": { "description": "Method not allowed" } } }, "delete": { "summary": "Remove Labels from Conversation", "description": "Removes one or more labels from one conversation.", "tags": [ "Inbox" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "Contact ID", "example": "ctc_ei6zVayP9B2ugwUPN", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "labelIds": { "type": "array", "description": "Array of label IDs to remove", "items": { "type": "string" } } }, "required": [ "labelIds" ] }, "example": { "labelIds": [ "lbl_uPAAgsi4oi9juBHfW" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "400": { "description": "Possible errors: Bad team / Invalid request body: labelIds must be an array", "content": { "text/plain": { "example": "Invalid request body: labelIds must be an array" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Possible errors: Inbox not found / Label not found", "content": { "text/plain": { "example": "Label not found" } } }, "405": { "description": "Method not allowed" } } } }, "/inbox/{contactId}/drafts": { "get": { "summary": "List Drafts", "description": "Lists all non-deleted drafts for a specific contact.", "tags": [ "Inbox" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "Contact ID", "example": "ctc_ei6zVayP9B2ugwUPN", "schema": { "type": "string" } }, { "name": "draftOwner", "in": "query", "required": true, "description": "Draft owner identifier. Accepts either a userId (e.g., `usr_abc123def456789`) or a login email (e.g., `john@acme.com`).", "example": "usr_abc123def456789", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "drafts": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique draft identifier" }, "channel": { "type": "string", "enum": [ "email", "linkedin", "whatsapp", "sms" ], "description": "Communication channel" }, "subject": { "type": "string", "description": "Draft subject" }, "contentPreview": { "type": "string", "description": "Content preview (max 100 chars)" }, "source": { "type": "string", "enum": [ "api", "ui" ], "description": "Draft creation source" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date" } } } } } }, "example": { "drafts": [ { "_id": "drf_abc123def456789", "channel": "email", "subject": "Follow up on our meeting", "contentPreview": "Hi John, I wanted to follow up on our conversation from last week...", "source": "api", "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:30:00.000Z" } ] } } } }, "400": { "description": "Possible errors: Missing draftOwner / User not found", "content": { "text/plain": { "example": "User not found: neither a valid email nor a valid user id for this team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } }, "post": { "summary": "Create Draft", "description": "Creates a new draft for a specific contact. The source is automatically set to \"api\".", "tags": [ "Inbox" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "Contact ID", "example": "ctc_ei6zVayP9B2ugwUPN", "schema": { "type": "string" } }, { "name": "draftOwner", "in": "query", "required": true, "description": "Draft owner identifier. Accepts either a userId (e.g., `usr_abc123def456789`) or a login email (e.g., `john@acme.com`).", "example": "usr_abc123def456789", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "linkedin", "whatsapp", "sms" ], "description": "Communication channel" }, "content": { "type": "string", "description": "Draft content (max 30KB)" }, "subject": { "type": "string", "description": "Draft subject (optional)" }, "cc": { "type": "array", "items": { "type": "string" }, "description": "CC email addresses (optional)" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "Attachment URL" }, "size": { "type": "integer", "description": "File size in bytes" }, "type": { "type": "string", "description": "MIME type" } } }, "description": "File attachments (optional)" }, "replyToActivityId": { "type": "string", "description": "Activity ID to reply to (optional)" }, "sourceMetadata": { "type": "object", "description": "Additional metadata (optional)" } }, "required": [ "channel", "content" ] }, "example": { "channel": "email", "content": "Hello John, I wanted to follow up on our conversation.
", "subject": "Follow up on our meeting", "cc": [], "attachments": [] } } } }, "responses": { "201": { "description": "Draft created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "draftId": { "type": "string", "description": "ID of the created draft" } } }, "example": { "draftId": "drf_abc123def456789" } } } }, "400": { "description": "Possible errors: Missing draftOwner / Invalid channel / Content must not be empty / Content too large / Draft limit reached (max 10 per conversation) / User not found", "content": { "text/plain": { "example": "Content must not be empty" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } } }, "/inbox/{contactId}/drafts/{draftId}": { "get": { "summary": "Get Draft", "description": "Retrieves a single draft with its full content, including attachments.", "tags": [ "Inbox" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "Contact ID", "example": "ctc_ei6zVayP9B2ugwUPN", "schema": { "type": "string" } }, { "name": "draftId", "in": "path", "required": true, "description": "Draft ID", "example": "drf_abc123def456789", "schema": { "type": "string" } }, { "name": "draftOwner", "in": "query", "required": true, "description": "Draft owner identifier. Accepts either a userId (e.g., `usr_abc123def456789`) or a login email (e.g., `john@acme.com`).", "example": "usr_abc123def456789", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique draft identifier" }, "channel": { "type": "string", "enum": [ "email", "linkedin", "whatsapp", "sms" ], "description": "Communication channel" }, "subject": { "type": "string", "description": "Draft subject" }, "cc": { "type": "array", "items": { "type": "string" }, "description": "CC email addresses" }, "content": { "type": "string", "description": "Full draft content" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size": { "type": "integer" }, "type": { "type": "string" } } }, "description": "File attachments" }, "source": { "type": "string", "enum": [ "api", "ui" ], "description": "Draft creation source" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date" } } } } }, "example": { "draft": { "_id": "drf_abc123def456789", "channel": "email", "subject": "Follow up on our meeting", "cc": [], "content": "Hello John, I wanted to follow up on our conversation.
", "attachments": [], "source": "api", "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:30:00.000Z" } } } } }, "400": { "description": "Possible errors: Missing draftOwner / User not found", "content": { "text/plain": { "example": "User not found: neither a valid email nor a valid user id for this team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Draft not found", "content": { "text/plain": { "example": "Draft not found" } } }, "405": { "description": "Method not allowed" } } }, "patch": { "summary": "Update Draft", "description": "Partially updates an existing draft. Only the provided fields will be updated.", "tags": [ "Inbox" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "Contact ID", "example": "ctc_ei6zVayP9B2ugwUPN", "schema": { "type": "string" } }, { "name": "draftId", "in": "path", "required": true, "description": "Draft ID", "example": "drf_abc123def456789", "schema": { "type": "string" } }, { "name": "draftOwner", "in": "query", "required": true, "description": "Draft owner identifier. Accepts either a userId (e.g., `usr_abc123def456789`) or a login email (e.g., `john@acme.com`).", "example": "usr_abc123def456789", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Draft subject" }, "cc": { "type": "array", "items": { "type": "string" }, "description": "CC email addresses" }, "content": { "type": "string", "description": "Draft content (max 30KB)" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Attachment file name" }, "url": { "type": "string", "description": "Attachment URL" }, "size": { "type": "integer", "description": "File size in bytes" }, "type": { "type": "string", "description": "MIME type" } } }, "description": "File attachments" }, "replyToActivityId": { "type": "string", "description": "Activity ID to reply to" } } }, "example": { "subject": "Updated subject", "content": "Updated content for the draft.
" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique draft identifier" }, "channel": { "type": "string", "enum": [ "email", "linkedin", "whatsapp", "sms" ], "description": "Communication channel" }, "subject": { "type": "string", "description": "Draft subject" }, "cc": { "type": "array", "items": { "type": "string" }, "description": "CC email addresses" }, "content": { "type": "string", "description": "Full draft content" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size": { "type": "integer" }, "type": { "type": "string" } } }, "description": "File attachments" }, "source": { "type": "string", "enum": [ "api", "ui" ], "description": "Draft creation source" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update date" } } } } }, "example": { "draft": { "_id": "drf_abc123def456789", "channel": "email", "subject": "Updated subject", "cc": [], "content": "Updated content for the draft.
", "attachments": [], "source": "api", "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T11:00:00.000Z" } } } } }, "400": { "description": "Possible errors: Missing draftOwner / Content must not be empty / Content too large / User not found", "content": { "text/plain": { "example": "Content must not be empty" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Draft not found", "content": { "text/plain": { "example": "Draft not found" } } }, "405": { "description": "Method not allowed" } } }, "delete": { "summary": "Delete Draft", "description": "Soft-deletes a draft by setting its deletedAt timestamp.", "tags": [ "Inbox" ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "Contact ID", "example": "ctc_ei6zVayP9B2ugwUPN", "schema": { "type": "string" } }, { "name": "draftId", "in": "path", "required": true, "description": "Draft ID", "example": "drf_abc123def456789", "schema": { "type": "string" } }, { "name": "draftOwner", "in": "query", "required": true, "description": "Draft owner identifier. Accepts either a userId (e.g., `usr_abc123def456789`) or a login email (e.g., `john@acme.com`).", "example": "usr_abc123def456789", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "400": { "description": "Possible errors: Missing draftOwner / User not found", "content": { "text/plain": { "example": "User not found: neither a valid email nor a valid user id for this team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Draft not found", "content": { "text/plain": { "example": "Draft not found" } } }, "405": { "description": "Method not allowed" } } } }, "/contacts": { "get": { "summary": "Get Many Contacts", "description": "Retrieves contacts by IDs/emails, or searches/lists contacts by name, email, contact list, campaign membership, or company link.\n\nWhen using `idsOrEmails`, returns an array of matching contacts directly.\n\nWhen using `search`, `email`, `listId`, `notInAnyCampaign`, any of the `company*` filters, or no filter at all, returns a paginated response with `data`, `total`, `limit`, and `offset` fields. You can combine filters together to narrow results (e.g. `listId` with `search`, or `notInAnyCampaign` with `companyId`). Calling the endpoint without any filter returns all contacts of the team, paginated.\n\nThe `company*` filters (`companyId`, `companyDomain`, `companyLinkedinUrl`, `companySalesnavUrl`) are mutually exclusive — use only one at a time. `companyDomain` / `companyLinkedinUrl` / `companySalesnavUrl` are resolved to a `companyId` through the Companies collection; if no matching company exists, the endpoint returns an empty list with `total: 0` (not an error), which keeps automation flows simple.", "tags": [ "Contacts" ], "parameters": [ { "name": "idsOrEmails", "in": "query", "required": false, "description": "A comma separated string of either valid contact IDs (MongoDB ObjectId) or valid email addresses. Optional — when omitted, returns the paginated list of all contacts of the team.", "example": "ctc_xW8Ou6C03Csv8vatp,riley@example.com", "schema": { "type": "string" }, "style": "form", "explode": false }, { "name": "search", "in": "query", "required": false, "description": "Search contacts by name or other text fields. Must be at least 2 characters.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Search contacts by exact email address.", "schema": { "type": "string", "format": "email" } }, { "name": "listId", "in": "query", "required": false, "description": "Filter contacts by contact list ID (`clt_xxx` format). Can be combined with `search` or `email`, or used alone to list all contacts in a list. Get valid IDs from `GET /contacts/lists`.", "example": "clt_abc123def456ghi78", "schema": { "type": "string", "pattern": "^clt_[a-zA-Z0-9]+$" } }, { "name": "notInAnyCampaign", "in": "query", "required": false, "description": "When set to `true`, only returns contacts that are not part of any campaign (orphan contacts). Can be used alone or combined with other filters such as `search`, `email`, or `listId`.", "schema": { "type": "boolean" } }, { "name": "companyId", "in": "query", "required": false, "description": "Filter contacts by attached company ID (`cpn_xxx` format). Use this when you already know the lemlist company id (for example after fetching `GET /companies?crmSyncStatus=unique_index_error_company`). Mutually exclusive with `companyDomain`, `companyLinkedinUrl`, and `companySalesnavUrl`.", "example": "cpn_A1B2C3D4E5F6G7H8I", "schema": { "type": "string", "pattern": "^cpn_[a-zA-Z0-9]+$" } }, { "name": "companyDomain", "in": "query", "required": false, "description": "Filter contacts by their company's website domain. Resolved to a `companyId` against the Companies collection. If no company matches, the endpoint returns an empty list (`total: 0`). Mutually exclusive with the other `company*` filters.", "example": "acme.com", "schema": { "type": "string" } }, { "name": "companyLinkedinUrl", "in": "query", "required": false, "description": "Filter contacts by their company's LinkedIn URL. Resolved to a `companyId` against the Companies collection. If no company matches, the endpoint returns an empty list (`total: 0`). Mutually exclusive with the other `company*` filters.", "example": "https://www.linkedin.com/company/acme", "schema": { "type": "string" } }, { "name": "companySalesnavUrl", "in": "query", "required": false, "description": "Filter contacts by their company's LinkedIn Sales Navigator URL. Resolved to a `companyId` against the Companies collection. If no company matches, the endpoint returns an empty list (`total: 0`). Mutually exclusive with the other `company*` filters.", "example": "https://www.linkedin.com/sales/company/12345678", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of contacts to return (1–500). Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of contacts to skip for pagination. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success. When using `idsOrEmails`, returns an array of contacts. Otherwise, returns a paginated object with `data`, `total`, `limit`, and `offset`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "data", "total", "limit", "offset" ] } ] }, "example": [ { "_id": "ctc_xW8Ou6C03Csv8vatp", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "fullName": "John Doe", "email": "support@lemlist.com", "fields": { "firstName": "John", "jobTitle": "Growth Engineer", "lastName": "Doe", "industry": "Technology", "isActiveInCampaigns": false, "lastCampaign": "NEW TO DELETE", "lastLeadMarkedAsInterestedDate": "2025-10-28T02:12:31.971Z", "leadStatus": "Marked as not Interested by api" }, "campaigns": [ { "campaignId": "cam_bSn8EORHQxbWPjHvu", "campaignState": "running", "leadState": "review", "leadId": "lea_fiDpiGV585wy3Oii2" } ], "ownerId": "usr_ahfFktBBHUIxbVG5P", "createdAt": "2025-10-28T00:40:37.917Z", "createdBy": "usr_ahfFktBBHUIxbVG5P", "unsubscribed": false }, { "_id": "ctc_a9RxJNa7pmMd85H9b", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "fullName": "Casey", "email": "riley@example.com", "fields": { "firstName": "Casey", "isActiveInCampaigns": false }, "campaigns": [ { "campaignId": "cam_jwm7THjgGFE3ylR85", "campaignState": "running", "leadState": "done", "leadId": "lea_XKjAytuJhBKZhxhWh" }, { "campaignId": "cam_eF4DlNERV0CW1TwRd", "campaignState": "running", "leadState": "done", "leadId": "lea_fJcS9D3UtEqZcDcAG" }, { "campaignId": "cam_UBbMt30jHq0vNJKJr", "campaignState": "running", "leadState": "done", "leadId": "lea_GlaMfjxlUYuwEDL0w" }, { "campaignId": "cam_pijDVnytN5S7frriD", "campaignState": "running", "leadState": "review", "leadId": "lea_Bs9aMGCcjdzTDvixY" } ], "ownerId": "usr_Emu1g29BMtBixhMSP", "createdAt": "2024-10-01T09:00:13.831Z", "createdBy": "usr_Emu1g29BMtBixhMSP", "unsubscribed": true } ] } } }, "400": { "description": "Possible errors: Bad team / search query too short / invalid listId format", "content": { "text/plain": { "example": "Search query must be at least 2 characters" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } }, "post": { "summary": "Add and update contact", "description": "Creates a new contact or updates an existing one (upsert). If a contact with the same email, LinkedIn URL, or Sales Navigator URL already exists, it will be updated with the provided non-empty fields. Null or empty values are ignored during updates to preserve existing data. You can target an existing contact directly by providing `contactId`, bypassing email/LinkedIn matching. You can optionally link the contact to a company by providing `companyId`, `companyDomain`, or `companyLinkedinUrl`.", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string", "description": "Existing contact ID. Updates a specific contact by ID, bypassing email/LinkedIn matching. Can only be used to update an existing contact, not to create a new one. When provided, `email` and `linkedinUrl` are not required. At least one of `contactId`, `email`, `linkedinUrl`, or `linkedinUrlSalesNav` is required." }, "email": { "type": "string", "description": "Contact email address. Used as a unique key for upsert matching. At least one of `contactId`, `email`, `linkedinUrl`, or `linkedinUrlSalesNav` is required." }, "linkedinUrl": { "type": "string", "description": "LinkedIn profile URL. Used as an alternative unique key for upsert matching. At least one of `contactId`, `email`, `linkedinUrl`, or `linkedinUrlSalesNav` is required." }, "linkedinUrlSalesNav": { "type": "string", "description": "LinkedIn Sales Navigator profile URL. Used as an alternative unique key for upsert matching." }, "additionalEmails": { "type": "array", "items": { "type": "string" }, "description": "Additional email addresses for the contact. Each must be a valid email address." }, "firstName": { "type": "string", "description": "Contact first name." }, "lastName": { "type": "string", "description": "Contact last name." }, "phone": { "type": "string", "description": "Contact phone number." }, "jobTitle": { "type": "string", "description": "Contact job title. If a company is linked, this is saved as part of the job data." }, "jobDescription": { "type": "string", "description": "Contact job description. If a company is linked, this is saved as part of the job data." }, "picture": { "type": "string", "description": "URL of the contact's profile picture." }, "timezone": { "type": "string", "description": "Contact timezone." }, "industry": { "type": "string", "description": "Contact industry." }, "languages": { "type": "string", "description": "Contact languages." }, "location": { "type": "string", "description": "Contact location." }, "skills": { "type": "string", "description": "Contact skills." }, "summary": { "type": "string", "description": "Contact summary or bio." }, "tagline": { "type": "string", "description": "Contact tagline." }, "contactOwner": { "type": "string", "description": "Owner of the contact. Can be a user ID (e.g. `usr_...`) or a team member's email address. If the provided value does not match a team member, the owner defaults to the API key owner." }, "source": { "type": "string", "description": "Origin of the contact record. Set on creation only and cannot be updated afterwards. Defaults to `api`.", "default": "api" }, "companyId": { "type": "string", "description": "ID of a company already existing in lemlist to link to this contact. Takes priority over `companyDomain` and `companyLinkedinUrl`." }, "companyDomain": { "type": "string", "description": "Domain of a company already existing in lemlist to link to this contact (e.g. `lemlist.com`). Used if `companyId` is not provided." }, "companyLinkedinUrl": { "type": "string", "description": "LinkedIn URL of a company already existing in lemlist to link to this contact. Used if `companyId` and `companyDomain` are not provided." } }, "additionalProperties": { "description": "Any additional key is treated as a custom field. Custom fields must be registered in the team's CRM field registry beforehand." } }, "example": { "email": "jane.smith@example.com", "firstName": "Jane", "lastName": "Smith", "linkedinUrl": "https://linkedin.com/in/janesmith", "jobTitle": "Product Manager", "companyDomain": "acme.com" } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique contact identifier" }, "teamId": { "type": "string", "description": "Team ID" }, "emails": { "type": "array", "description": "Contact email addresses", "items": { "type": "object", "properties": { "value": { "type": "string" } } } }, "linkedinUrl": { "type": "string", "description": "LinkedIn profile URL" }, "linkedinUrlSalesNav": { "type": "string", "description": "LinkedIn Sales Navigator URL" }, "fields": { "type": "object", "description": "Key/value fields (firstName, lastName, phone, jobTitle, custom fields, etc.)", "additionalProperties": true }, "ownerId": { "type": "string", "description": "Owner user ID" }, "companyId": { "type": "string", "description": "Linked company ID (present only when a company was linked)" }, "source": { "type": "string", "description": "Record origin" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "createdBy": { "type": "string", "description": "User ID who created the record" }, "unsubscribed": { "type": "boolean", "description": "Whether the contact is unsubscribed" }, "created": { "type": "boolean", "description": "`true` when a new contact was created, `false` when an existing contact was updated." }, "updated": { "type": "boolean", "description": "Present and set to `true` only when an existing contact was updated (i.e. `created` is `false`)." }, "companyLinked": { "type": "boolean", "description": "Whether a company was successfully linked to the contact." } } }, "warnings": { "type": "array", "description": "Optional warnings (e.g. company resolution issues).", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "success": true, "data": { "_id": "ctc_xW8Ou6C03Csv8vatp", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "emails": [ { "value": "jane.smith@example.com" } ], "linkedinUrl": "https://www.linkedin.com/in/janesmith", "fields": { "firstName": "Jane", "lastName": "Smith", "jobTitle": "Product Manager" }, "ownerId": "usr_ahfFktBBHUIxbVG5P", "source": "api", "createdAt": "2025-10-28T00:40:37.917Z", "createdBy": "usr_ahfFktBBHUIxbVG5P", "unsubscribed": false, "created": true, "companyLinked": true, "companyId": "cpn_gG7PsmZFpEAnpMCHO" } } } } }, "200": { "description": "Existing contact updated (upsert matched by email or LinkedIn URL)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "Same shape as the 201 response, with `created: false` and `updated: true`." } } }, "example": { "success": true, "data": { "_id": "ctc_xW8Ou6C03Csv8vatp", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "emails": [ { "value": "jane.smith@example.com" } ], "fields": { "firstName": "Jane", "lastName": "Smith", "jobTitle": "Product Manager" }, "ownerId": "usr_ahfFktBBHUIxbVG5P", "source": "api", "createdAt": "2025-10-28T00:40:37.917Z", "createdBy": "usr_ahfFktBBHUIxbVG5P", "unsubscribed": false, "created": false, "updated": true, "companyLinked": false } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code: `MISSING_IDENTIFIER`, `INVALID_CONTACT_ID`, `CONTACT_NOT_FOUND_BY_ID`, `INVALID_EMAIL`, `INVALID_ADDITIONAL_EMAILS`, `INVALID_LINKEDIN_URL`, `INVALID_FIELD`, or `CONTACT_VALIDATION_FAILED`." }, "message": { "type": "string" } } } } }, "example": { "success": false, "error": { "code": "MISSING_IDENTIFIER", "message": "At least one identifier is required: email, linkedinUrl or contactId" } } } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } } }, "parameters": [] } }, "/contacts/{idOrEmail}": { "parameters": [ { "name": "idOrEmail", "in": "path", "required": true, "description": "The unique identifier or email of the contact", "example": "ctc_XXBXpAxmxwg24IzBI", "schema": { "type": "string" } } ], "get": { "summary": "Get Contact", "tags": [ "Contacts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" }, "example": { "_id": "ctc_xW8Ou6C03Csv8vatp", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "fullName": "John Doe", "email": "support@lemlist.com", "fields": { "firstName": "John", "jobTitle": "Growth Engineer", "lastName": "Doe", "industry": "Technology", "isActiveInCampaigns": false, "lastCampaign": "NEW TO DELETE", "lastLeadMarkedAsInterestedDate": "2025-10-28T02:12:31.971Z", "leadStatus": "Marked as not Interested by api" }, "campaigns": [ { "campaignId": "cam_bSn8EORHQxbWPjHvu", "campaignState": "running", "leadState": "review", "leadId": "lea_fiDpiGV585wy3Oii2" } ], "ownerId": "usr_ahfFktBBHUIxbVG5P", "createdAt": "2025-10-28T00:40:37.917Z", "createdBy": "usr_ahfFktBBHUIxbVG5P", "unsubscribed": false } } } }, "400": { "description": "Bad team", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } }, "parameters": [] } }, "/contacts/lists": { "get": { "summary": "Get Contact Lists", "description": "Retrieves all static and dynamic contact lists for the team. Optionally filter by name.", "tags": [ "Contacts" ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Filter lists by name (case-insensitive partial match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique list ID (`clt_xxx` format)" }, "name": { "type": "string", "description": "Name of the contact list" }, "dynamic": { "type": "boolean", "description": "Whether the list is dynamic (auto-populated by filters) or static (manually managed)" } } } }, "example": [ { "_id": "clt_abc123def456ghi78", "name": "Nurturing", "dynamic": false }, { "_id": "clt_xyz789uvw012rst34", "name": "Enterprise Prospects", "dynamic": true } ] } } }, "400": { "description": "Bad team", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } }, "post": { "summary": "Create Contact List", "description": "Creates a new static contact list. After creating the list, use `POST /contacts/lists/{listId}/entities` to add contacts to it.", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 200, "description": "Name of the contact list to create (max 200 characters)." } } }, "example": { "name": "Nurturing" } } } }, "responses": { "201": { "description": "Contact list created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "list": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique list ID (`clt_xxx` format)" }, "name": { "type": "string", "description": "Name of the created list" } } } } }, "example": { "message": "Contact list created successfully", "list": { "id": "clt_abc123def456ghi78", "name": "Nurturing" } } } } }, "400": { "description": "Possible errors: Bad team / name is required / name too long", "content": { "text/plain": { "example": "name is required and must be a non-empty string" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } } }, "/contacts/lists/{listId}/entities": { "parameters": [ { "name": "listId", "in": "path", "required": true, "description": "The unique identifier of the contact list (`clt_xxx` format). Must be a **static** contact list.", "example": "clt_xxxxxxxxxxxxxxxxx", "schema": { "type": "string", "pattern": "^clt_[a-zA-Z0-9]+$" } } ], "post": { "summary": "Add or Remove Contacts in a List", "description": "Adds existing CRM contacts to a static contact list, or removes them when `?action=remove` is set.\n\n- **Add** (default): send a `POST` with a `contactIds` body. Contacts already in the list are silently skipped (no duplicates) and reported in `alreadyInList`.\n- **Remove**: send a `POST` with `?action=remove` and a `contactIds` body. Contacts that are not in the list are silently skipped; `removedCount` reflects the associations actually removed. This only affects list membership, the contacts are not deleted from your CRM.\n\nThe list must be a **static** contact list (`clt_xxx`). Dynamic lists (auto-populated by filter rules) and company lists are rejected.\n\n**Removal uses `POST ?action=remove` on purpose:** a `DELETE` request body is dropped by our stack, so `DELETE` on this path is **not supported** and returns `405 Method Not Allowed`.", "tags": [ "Contacts" ], "parameters": [ { "name": "action", "in": "query", "required": false, "description": "Omit to **add** the contacts to the list. Set to `remove` to **remove** them from the list.", "example": "remove", "schema": { "type": "string", "enum": [ "remove" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contactIds" ], "properties": { "contactIds": { "type": "array", "items": { "type": "string", "pattern": "^ctc_[a-zA-Z0-9]+$" }, "minItems": 1, "maxItems": 1000, "description": "Array of contact IDs (`ctc_xxx` format) to add to or remove from the list. Required, non-empty, maximum 1,000 per request." } } }, "example": { "contactIds": [ "ctc_xxxxxxxxxxxxxxxxx", "ctc_yyyyyyyyyyyyyyyyy" ] } } } }, "responses": { "200": { "description": "Contacts added to or removed from the list successfully. The response body depends on `action`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "addedCount": { "type": "integer", "description": "Number of contacts added to the list (add only)." }, "alreadyInList": { "type": "integer", "description": "Number of contacts that were already in the list and therefore skipped (add only)." }, "removedCount": { "type": "integer", "description": "Number of list associations actually removed (remove only). Contacts that were not in the list are not counted." } } }, "examples": { "add": { "summary": "Add contacts (no action)", "value": { "message": "Contacts added to list successfully", "addedCount": 2, "alreadyInList": 0 } }, "remove": { "summary": "Remove contacts (action=remove)", "value": { "message": "Contacts removed from list successfully", "removedCount": 2 } } } } } }, "400": { "description": "Possible errors: Bad team / Invalid listId format (expected clt_xxx) / contactIds is required and must be a non-empty array / Maximum 1,000 contacts per request / All contactIds must be in ctc_xxx format / List is not a contact list / Cannot manually add contacts to a dynamic list / Cannot manually remove contacts from a dynamic list.", "content": { "text/plain": { "example": "contactIds is required and must be a non-empty array" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Contact list not found", "content": { "text/plain": { "example": "Contact list not found" } } }, "405": { "description": "Method not allowed. `DELETE` on this path is not supported because the request body is dropped by our stack. Use `POST ?action=remove` to remove contacts.", "content": { "text/plain": { "example": "Method not allowed" } } }, "500": { "description": "Internal error while updating the list", "content": { "text/plain": { "example": "Failed to add contacts to list" } } } } } }, "/contacts/export": { "get": { "summary": "Export Contact List", "description": "Exports contacts or companies from a CRM list as a CSV file. The response is streamed as `text/csv` with a `Content-Disposition: attachment` header.\n\nThe exported columns depend on the `entity` type:\n- **contact**: firstName, lastName, email, linkedinUrl, companyName, jobTitle, phone, status, owner, campaigns, contactLists, and more.\n- **company**: name, domain, linkedinUrl, industry, website, status, size, owner, numberOfContacts, companyLists, and more.\n\nCustom fields are included as additional columns.", "tags": ["Contacts"], "parameters": [ { "name": "listId", "in": "query", "required": true, "description": "The contact list ID to export (`clt_xxx` format), or `\"all\"` to export all contacts.", "example": "clt_abc123def456ghi78", "schema": { "type": "string" } }, { "name": "entity", "in": "query", "required": false, "description": "The type of entities to export. Defaults to `\"contact\"`.", "schema": { "type": "string", "enum": ["contact", "company"], "default": "contact" } } ], "responses": { "200": { "description": "CSV file download", "content": { "text/csv": { "example": "firstName,lastName,email,companyName,jobTitle,status\nJohn,Doe,john@example.com,Acme Inc,CEO,interested" } } }, "400": { "description": "Bad team", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "Unauthorized" } } } }, "/lemwarm/{userMailboxId}/start": { "parameters": [ { "name": "userMailboxId", "in": "path", "required": true, "description": "The unique identifier of the user mailbox", "example": "usm_2mkqJNUjnJQiyVBht", "schema": { "type": "string" } } ], "post": { "summary": "Start lemwarm", "tags": [ "lemwarm" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "400": { "description": "Possible errors: Bad team / Error from warmupToggle (invalid-usermailbox, invalid-sender, mailbox-deleted, emailWarmedByAnotherAccount, billing-error, etc.)", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } } }, "/lemwarm/{userMailboxId}/pause": { "parameters": [ { "name": "userMailboxId", "in": "path", "required": true, "description": "The unique identifier of the user mailbox", "example": "usm_2mkqJNUjnJQiyVBht", "schema": { "type": "string" } } ], "post": { "summary": "Pause lemwarm", "tags": [ "lemwarm" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "400": { "description": "Possible errors: Bad team / Error from warmupToggle", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } } }, "/lemwarm/{userMailboxId}/settings": { "parameters": [ { "name": "userMailboxId", "in": "path", "required": true, "description": "The unique identifier of the user mailbox", "example": "usm_2mkqJNUjnJQiyVBht", "schema": { "type": "string" } } ], "get": { "summary": "Get lemwarm Settings", "tags": [ "lemwarm" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LemwarmSettings" }, "example": { "warmEmailRampup": 5, "warmEmailMax": 5, "activeAt": "2025-04-10T07:38:31.530Z", "deliverability": { "score": 70, "lastAt": "2025-04-09T13:34:43.998Z" } } } } }, "400": { "description": "Possible errors: Bad team / Error retrieving settings", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } }, "patch": { "summary": "Update lemwarm Settings", "tags": [ "lemwarm" ], "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "warmEmailMax": { "type": "integer", "description": "Maximum number of warm emails per day" }, "warmEmailRampup": { "type": "integer", "description": "Daily increase in warm email count" } } }, "example": { "warmEmailMax": 30, "warmEmailRampup": 5 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "400": { "description": "Possible errors: Bad team / Error updating settings (warmEmailMax, warmEmailRampup)", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } } }, "/companies": { "get": { "summary": "Get Many Companies", "tags": [ "Companies" ], "parameters": [ { "name": "idsOrDomains", "in": "query", "required": false, "description": "Comma-separated list of company IDs or domains to fetch. When provided, returns only matching companies (no pagination). Each value is classified as a company ID (e.g. `cpn_xxx`) or a domain (e.g. `example.com`). URLs are normalized automatically (e.g. `https://example.com/path` → `example.com`). Invalid values are silently skipped. Maximum 100 values.", "example": "cpn_gG7PsmZFpEAnpMCHO,persana.ai", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "description": "Number of companies to skip for pagination. Defaults to 0. Ignored when `idsOrDomains` is provided.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "sortBy", "in": "query", "required": false, "description": "The field by which to sort. Currently, only 'createdAt' is supported.", "example": "createdAt", "schema": { "type": "string", "enum": [ "createdAt" ] } }, { "name": "sortOrder", "in": "query", "required": false, "description": "The sort direction. Use 'desc' for descending order; any other value (or omission) will sort in ascending order.", "example": "desc", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "required": false, "description": "Search by company name (case insensitive)", "example": "lemlist", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "required": false, "description": "Returns selected fields. Returns all fields if empty. Each field is separated by a comma (e.g., '_id,fields.name,domain')", "example": "_id,fields.name,domain", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of companies to retrieve. Default: 100. Maximum: 500", "example": "10", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "crmSyncStatus", "in": "query", "required": false, "description": "Filter companies by their CRM sync state against the team's active CRM provider. Requires a CRM (Hubspot, Salesforce, or Pipedrive) to be connected — otherwise the request returns `400 NO_CRM_CONNECTED`. Common values:\n- `synced` — the company has a CRM record and no sync errors.\n- `not_synced` — the company has no CRM record yet.\n- `error` — at least one sync error is currently raised.\n- A specific error reason (lowercase form), to filter by root cause: `unique_index_error_company`, `property_doesnt_exist`, `required_field_missing`, `company_already_exists_with_name`, `company_already_exists_with_linkedin_url`.\n\nFor each returned company, see `crmSync.errors[].metadata.alreadyExistingCompanyId` to identify the lemlist company that already occupies the conflicting CRM record (useful to remap contacts before deleting the duplicate).", "example": "unique_index_error_company", "schema": { "type": "string", "enum": [ "synced", "not_synced", "error", "unique_index_error_company", "property_doesnt_exist", "required_field_missing", "company_already_exists_with_name", "company_already_exists_with_linkedin_url" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "data", "total", "limit", "offset" ] }, "example": { "data": [ { "_id": "cpn_gG7PsmZFpEAnpMCHO", "createdAt": "2025-10-26T11:54:27.387Z", "createdBy": "usr_iGBmhLaxZmL0s7k1G", "domain": "persana.ai", "fields": { "name": "Persana AI", "picture": "https://example.com/logos/company-1.png" }, "ownerId": "usr_iGBmhLaxZmL0s7k1G" }, { "_id": "cpn_FEWCjzMWXo5StjpDa", "createdAt": "2025-10-26T11:45:18.773Z", "createdBy": "usr_iGBmhLaxZmL0s7k1G", "domain": "duno.ai", "fields": { "industry": "IT Services and IT Consulting", "name": "Duno.ai", "picture": "https://example.com/logos/company-2.png" }, "ownerId": "usr_iGBmhLaxZmL0s7k1G" }, { "_id": "cpn_2STz8x5Bexmd0nvIz", "createdAt": "2025-10-25T21:37:45.741Z", "createdBy": "usr_iGBmhLaxZmL0s7k1G", "domain": "tally.so", "fields": { "industry": "Computer Software", "name": "lemlist family", "picture": "https://example.com/logos/lemlist.png" }, "ownerId": "usr_iGBmhLaxZmL0s7k1G" }, { "_id": "cpn_Qf4CJuUrNUNmHm6uZ", "createdAt": "2025-10-24T07:26:34.956Z", "createdBy": "usr_ahfFktBBHUIxbVG5P", "domain": "example.com", "fields": { "name": "Growth & GTM Engineering" }, "ownerId": "usr_ahfFktBBHUIxbVG5P" }, { "_id": "cpn_A1B2C3D4E5F6G7H8I", "createdAt": "2025-11-02T09:14:08.512Z", "createdBy": "usr_A1B2C3D4E5F6G7H8I", "domain": "acme.com", "fields": { "name": "Acme Inc" }, "ownerId": "usr_A1B2C3D4E5F6G7H8I", "crmSync": { "provider": "hubspot", "crmRecordId": null, "syncDisabled": false, "errors": [ { "type": "CONNECT_FAILED", "reason": "UNIQUE_INDEX_ERROR_COMPANY", "raisedAt": "2025-11-02T09:14:12.034Z", "metadata": { "alreadyExistingCompanyId": "cpn_J1K2L3M4N5O6P7Q8R" } } ] } } ], "total": 59310, "limit": 100, "offset": 0 } } } }, "400": { "description": "Bad team", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "405": { "description": "Method not allowed" } } }, "post": { "summary": "Add and update company", "description": "Creates a new company or updates an existing one (upsert). If a company with the same domain, LinkedIn URL, or Sales Navigator URL already exists, it will be updated with the provided non-empty fields. Null or empty values are ignored during updates to preserve existing data. You can target an existing company directly by providing `companyId`, bypassing domain/LinkedIn matching — in that case `name` and `domain` become optional.", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "description": "Existing company ID. Updates a specific company by ID, bypassing domain/LinkedIn matching. Can only be used to update an existing company, not to create a new one. When provided, `name` and `domain` become optional." }, "name": { "type": "string", "description": "Company name. Required unless `companyId` is provided." }, "domain": { "type": "string", "description": "Company website domain (e.g. `lemlist.com`). Used as a unique key for upsert matching. Required unless `companyId` is provided." }, "linkedinUrl": { "type": "string", "description": "LinkedIn company page URL. Used as an alternative unique key for upsert matching." }, "linkedinUrlSalesNav": { "type": "string", "description": "LinkedIn Sales Navigator company URL. Used as an alternative unique key for upsert matching." }, "companyOwner": { "type": "string", "description": "Owner of the company. Can be a user ID (e.g. `usr_...`) or a team member's email address. If the provided value does not match a team member, the owner defaults to the API key owner." }, "industry": { "type": "string", "description": "Industry sector of the company." }, "location": { "type": "string", "description": "Geographic location of the company." }, "size": { "type": "string", "description": "Company size." }, "specialties": { "type": "string", "description": "Company specialties." }, "tagline": { "type": "string", "description": "Company tagline." }, "type": { "type": "string", "description": "Company type." }, "description": { "type": "string", "description": "Company description." }, "foundedOn": { "type": "string", "description": "Company founding date." }, "headquarters": { "type": "string", "description": "Company headquarters location." }, "picture": { "type": "string", "description": "URL of the company logo or picture." }, "source": { "type": "string", "description": "Origin of the company record. Set on creation only and cannot be updated afterwards. Defaults to `api`.", "default": "api" } }, "additionalProperties": { "description": "Any additional key is treated as a custom field. Custom fields must be registered in the team's CRM field registry beforehand." } }, "example": { "name": "Acme Corp", "domain": "acme.com", "linkedinUrl": "https://linkedin.com/company/acme", "industry": "Technology", "location": "San Francisco, CA" } } } }, "responses": { "201": { "description": "Company created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique company identifier" }, "teamId": { "type": "string", "description": "Team ID" }, "domain": { "type": "string", "description": "Company domain" }, "linkedinUrl": { "type": "string", "description": "LinkedIn URL" }, "fields": { "type": "object", "description": "Key/value fields (name, picture, industry, location, custom fields, etc.)", "additionalProperties": true }, "ownerId": { "type": "string", "description": "Owner user ID" }, "source": { "type": "string", "description": "Record origin" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "createdBy": { "type": "string", "description": "User ID who created the record" }, "created": { "type": "boolean", "description": "`true` when a new company was created, `false` when an existing company was updated." }, "updated": { "type": "boolean", "description": "Present and set to `true` only when an existing company was updated (i.e. `created` is `false`)." } } }, "warnings": { "type": "array", "description": "Optional warnings (e.g. owner resolution issues).", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "success": true, "data": { "_id": "cpn_gG7PsmZFpEAnpMCHO", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "domain": "acme.com", "linkedinUrl": "https://www.linkedin.com/company/acme", "fields": { "name": "Acme Corp", "industry": "Technology", "location": "San Francisco, CA" }, "ownerId": "usr_ahfFktBBHUIxbVG5P", "source": "api", "createdAt": "2025-10-28T00:40:37.917Z", "createdBy": "usr_ahfFktBBHUIxbVG5P", "created": true } } } } }, "200": { "description": "Existing company updated (upsert matched by domain or LinkedIn URL)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "Same shape as the 201 response, with `created: false` and `updated: true`." } } }, "example": { "success": true, "data": { "_id": "cpn_gG7PsmZFpEAnpMCHO", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "domain": "acme.com", "fields": { "name": "Acme Corp", "industry": "Technology", "location": "San Francisco, CA" }, "ownerId": "usr_ahfFktBBHUIxbVG5P", "source": "api", "createdAt": "2025-10-28T00:40:37.917Z", "createdBy": "usr_ahfFktBBHUIxbVG5P", "created": false, "updated": true } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code: `MISSING_REQUIRED_FIELD`, `INVALID_COMPANY_ID`, `COMPANY_NOT_FOUND_BY_ID`, `INVALID_DOMAIN`, `INVALID_LINKEDIN_URL`, or `INVALID_FIELD`." }, "message": { "type": "string" } } } } }, "example": { "success": false, "error": { "code": "MISSING_REQUIRED_FIELD", "message": "Missing required field: name" } } } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } } }, "parameters": [] } }, "/companies/{companyId}": { "delete": { "summary": "Delete Company", "description": "Deletes a lemlist company. Refuses by default when contacts are still attached — pass `force=true` to detach them (the `companyId` field is unset on each contact) before deleting the company.\n\n**No CRM-side propagation:** only the lemlist record is removed. Designed for the contact-to-company remapping workflow: after reassigning the contacts of a duplicate company to the canonical one (via `POST /contacts/{idOrEmail}`), call this endpoint to drop the now-empty duplicate.", "tags": [ "Companies" ], "parameters": [ { "name": "companyId", "in": "path", "required": true, "description": "The lemlist company ID to delete.", "example": "cpn_A1B2C3D4E5F6G7H8I", "schema": { "type": "string", "pattern": "^cpn_[a-zA-Z0-9]+$" } }, { "name": "force", "in": "query", "required": false, "description": "When `true`, detaches contacts attached to this company (unsets their `companyId`) before deleting it. When omitted or `false`, the request fails with `400 COMPANY_HAS_CONTACTS` if any contact is still attached.", "example": "true", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Company deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deletedCompanyId": { "type": "string", "description": "ID of the deleted lemlist company." }, "unlinkedContacts": { "type": "integer", "description": "Number of contacts whose `companyId` was unset before deletion. Only present when `force=true`." } }, "required": [ "success", "deletedCompanyId" ] }, "examples": { "no contacts attached": { "value": { "success": true, "deletedCompanyId": "cpn_A1B2C3D4E5F6G7H8I" } }, "force=true with attached contacts": { "value": { "success": true, "deletedCompanyId": "cpn_A1B2C3D4E5F6G7H8I", "unlinkedContacts": 3 } } } } } }, "400": { "description": "Invalid request. Possible error codes: `INVALID_COMPANY_ID` (malformed ID), `COMPANY_HAS_CONTACTS` (contacts still attached and `force` not set).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "contactCount": { "type": "integer", "description": "Only on `COMPANY_HAS_CONTACTS` — how many contacts are still attached." } } } } }, "example": { "success": false, "error": { "code": "COMPANY_HAS_CONTACTS", "message": "Company still has contacts attached. Pass ?force=true to detach them before deletion. (3 contacts attached)", "contactCount": 3 } } } } }, "401": { "description": "The authentication you supplied is incorrect.", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Company not found (`COMPANY_NOT_FOUND_BY_ID`).", "content": { "application/json": { "example": { "success": false, "error": { "code": "COMPANY_NOT_FOUND_BY_ID", "message": "Company not found by ID" } } } } }, "405": { "description": "Method not allowed." } } } }, "/companies/{companyId}/notes": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "description": "The unique identifier of the company", "example": "cmp_ABC123", "schema": { "type": "string" } } ], "get": { "summary": "Get Company Notes", "tags": [ "Companies" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of notes to retrieve. Default: 100. Maximum: 100", "example": "2", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number to retrieve", "example": "1", "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "required": false, "description": "The field by which to sort. Currently, only 'createdAt' is supported.", "example": "createdAt", "schema": { "type": "string", "enum": [ "createdAt" ] } }, { "name": "sortOrder", "in": "query", "required": false, "description": "The sort direction. Use 'desc' for descending order; any other value (or omission) will sort in ascending order.", "example": "desc", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyNote" } }, "total": { "type": "integer" } }, "required": [ "data", "total" ] }, "example": { "data": [ { "_id": "act_j0NrG6rYEPP9TMmWC", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "companyId": "cpn_Qf4CJuUrNUNmHm6uZ", "createdAt": "2025-10-28T04:25:00.653Z", "note": "could help our GTM team be more productive", "userId": "usr_ahfFktBBHUIxbVG5P" }, { "_id": "act_BYF2j06u0wgeLncub", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "companyId": "cpn_Qf4CJuUrNUNmHm6uZ", "createdAt": "2025-10-24T12:42:40.605Z", "note": "Note created from the API!", "userId": "usr_ahfFktBBHUIxbVG5P" } ], "total": 2 } } } }, "400": { "description": "Bad team", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Company not found", "content": { "text/plain": { "example": "Company not found" } } }, "405": { "description": "Method not allowed" } } }, "post": { "summary": "Create Company Note", "tags": [ "Companies" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "The note content" } }, "required": [ "note" ] }, "example": { "note": "Note created from the API!" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyNote" }, "example": { "_id": "act_j0NrG6rYEPP9TMmWC", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "companyId": "cpn_Qf4CJuUrNUNmHm6uZ", "type": "annotated", "createdAt": "2025-10-28T04:25:00.653Z", "note": "could help our GTM team be more productive", "sendUserId": "usr_ahfFktBBHUIxbVG5P", "userId": "usr_ahfFktBBHUIxbVG5P" } } } }, "400": { "description": "Bad team", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "The authentication you supplied is incorrect", "content": { "text/plain": { "example": "The authentication you supplied is incorrect" } } }, "404": { "description": "Company not found", "content": { "text/plain": { "example": "Company not found" } } }, "405": { "description": "Method not allowed" } }, "parameters": [] } }, "/activities": { "get": { "summary": "Get Many Activities", "tags": [ "Activities" ], "parameters": [ { "name": "version", "in": "query", "required": true, "description": "API version. v2 is mandatory", "example": "v2", "schema": { "type": "string", "enum": [ "v2" ] } }, { "name": "type", "in": "query", "required": false, "description": "Filter by activity type (e.g., paused)", "example": "paused", "schema": { "type": "string" } }, { "name": "campaignId", "in": "query", "required": false, "description": "Filter by campaign ID", "example": "cam_123", "schema": { "type": "string" } }, { "name": "isFirst", "in": "query", "required": false, "description": "Filter for first activity", "example": "true", "schema": { "type": "boolean" } }, { "name": "offset", "in": "query", "required": false, "description": "Number of records to skip. Note: This is not traditional cursor-based pagination. To retrieve all activities, increment offset by the limit value on each request (e.g., offset=0, then offset=100, then offset=200, etc.).", "example": "0", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of activities to retrieve. Default: 100. Maximum: 100", "example": "2", "schema": { "type": "integer" } }, { "name": "leadId", "in": "query", "required": false, "description": "Filter by lead ID", "example": "lea_123", "schema": { "type": "string" } }, { "name": "minDate", "in": "query", "required": false, "description": "Filter activities by `createdAt >= minDate`. Accepts either a Unix timestamp in seconds (e.g. `1715385600`) or an ISO 8601 datetime (e.g. `2026-05-11T00:00:00Z`). `minDate` is the primary name; `startDate` is accepted as an alias and `minDate` takes precedence when both are provided.", "example": "2026-05-01T00:00:00Z", "schema": { "type": "string" } }, { "name": "maxDate", "in": "query", "required": false, "description": "Filter activities by `createdAt <= maxDate`. Accepts either a Unix timestamp in seconds (e.g. `1715385600`) or an ISO 8601 datetime (e.g. `2026-05-11T00:00:00Z`). Must be strictly greater than `minDate` when both are provided. `maxDate` is the primary name; `endDate` is accepted as an alias and `maxDate` takes precedence when both are provided.", "example": "2026-05-31T23:59:59Z", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "description": "Alias for `minDate`, provided for consistency with sibling endpoints (e.g. `/campaigns/{campaignId}/stats`). Accepts either a Unix timestamp in seconds or an ISO 8601 datetime. Ignored when `minDate` is also provided.", "example": "2026-05-01T00:00:00Z", "schema": { "type": "string" } }, { "name": "endDate", "in": "query", "required": false, "description": "Alias for `maxDate`, provided for consistency with sibling endpoints (e.g. `/campaigns/{campaignId}/stats`). Accepts either a Unix timestamp in seconds or an ISO 8601 datetime. Ignored when `maxDate` is also provided.", "example": "2026-05-31T23:59:59Z", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" } }, "example": [ { "_id": "act_PbKqTGpQqSlPcoOZ5", "type": "manualDone", "userId": "usr_Emu1g29BMtBixhMSP", "userName": "Guillaume Moubeche", "bot": false, "createdAt": "2025-10-28T08:07:38.375Z", "leadFirstName": "John", "leadLastName": "Doe", "leadEmail": "support@lemlist.com", "leadCompanyName": "Acme Inc", "leadId": "lea_fiDpiGV585wy3Oii2", "contactId": "ctc_xW8Ou6C03Csv8vatp", "campaignId": "cam_bSn8EORHQxbWPjHvu", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "opportunityId": "opp_LyXDV8KHzctQdLFpG", "metaData": { "teamId": "tea_8QvkOiBfPdb2ZRhHi", "campaignId": "cam_bSn8EORHQxbWPjHvu", "leadId": "lea_fiDpiGV585wy3Oii2", "type": "manualDone" }, "lead": { "_id": "lea_fiDpiGV585wy3Oii2", "isPaused": false, "state": "manualNotInterested", "personalized": false, "source": "api", "variables": { "firstName": "John", "lastName": "Doe", "companyName": "Acme Inc", "jobTitle": "Growth Engineer", "companyDomain": "example.com", "email": "support@lemlist.com", "preferredContactMethod": "email", "industry": "Technology", "Company name": "John Doe" }, "contactId": "ctc_xW8Ou6C03Csv8vatp", "enrichment": { "emailStatus": "deliverable" } }, "campaignName": "NEW TO DELETE", "sequenceTested": "B" }, { "_id": "act_j0NrG6rYEPP9TMmWC", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "companyId": "cpn_Qf4CJuUrNUNmHm6uZ", "type": "annotated", "createdAt": "2025-10-28T04:25:00.653Z", "note": "could help our GTM team be more productive", "sendUserId": "usr_ahfFktBBHUIxbVG5P", "userId": "usr_ahfFktBBHUIxbVG5P" }, { "_id": "act_WeKrlIaQlBnM3LZ6G", "type": "manualNotInterested", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "userName": "api", "isFirst": false, "bot": false, "createdAt": "2025-10-28T02:14:34.834Z", "name": "NEW TO DELETE", "leadFirstName": "John", "leadLastName": "Doe", "leadEmail": "support@lemlist.com", "leadCompanyName": "Acme Inc", "leadId": "lea_fiDpiGV585wy3Oii2", "contactId": "ctc_xW8Ou6C03Csv8vatp", "campaignId": "cam_bSn8EORHQxbWPjHvu", "metaData": { "teamId": "tea_8QvkOiBfPdb2ZRhHi", "campaignId": "cam_bSn8EORHQxbWPjHvu", "leadId": "lea_fiDpiGV585wy3Oii2", "type": "manualNotInterested" }, "lead": { "_id": "lea_fiDpiGV585wy3Oii2", "isPaused": false, "state": "manualNotInterested", "personalized": false, "source": "api", "variables": { "firstName": "John", "lastName": "Doe", "companyName": "Acme Inc", "jobTitle": "Growth Engineer", "companyDomain": "example.com", "email": "support@lemlist.com", "preferredContactMethod": "email", "industry": "Technology", "Company name": "John Doe" }, "contactId": "ctc_xW8Ou6C03Csv8vatp", "enrichment": { "emailStatus": "deliverable" } }, "campaignName": "NEW TO DELETE", "sequenceTested": "B" }, { "_id": "act_zktTG4HXXXSOQya5U", "type": "paused", "userName": "api", "bot": false, "createdAt": "2025-10-28T01:54:56.099Z", "name": "NEW TO DELETE", "leadFirstName": "John", "leadLastName": "Doe", "leadEmail": "support@lemlist.com", "leadCompanyName": "Acme Inc", "leadId": "lea_fiDpiGV585wy3Oii2", "contactId": "ctc_xW8Ou6C03Csv8vatp", "campaignId": "cam_bSn8EORHQxbWPjHvu", "teamId": "tea_8QvkOiBfPdb2ZRhHi", "metaData": { "teamId": "tea_8QvkOiBfPdb2ZRhHi", "campaignId": "cam_bSn8EORHQxbWPjHvu", "leadId": "lea_fiDpiGV585wy3Oii2", "type": "paused" }, "lead": { "_id": "lea_fiDpiGV585wy3Oii2", "isPaused": false, "state": "manualNotInterested", "personalized": false, "source": "api", "variables": { "firstName": "John", "lastName": "Doe", "companyName": "Acme Inc", "jobTitle": "Growth Engineer", "companyDomain": "example.com", "email": "support@lemlist.com", "preferredContactMethod": "email", "industry": "Technology", "Company name": "John Doe" }, "contactId": "ctc_xW8Ou6C03Csv8vatp", "enrichment": { "emailStatus": "deliverable" } }, "campaignName": "NEW TO DELETE", "sequenceTested": "B" }, { "_id": "act_x6esGLhoPa2SMHCZ7", "type": "emailsOpened", "isFirst": false, "stopped": false, "createdAt": "2025-10-27T20:20:59.696Z", "bot": false, "teamId": "tea_8QvkOiBfPdb2ZRhHi", "leadId": "lea_wj47uWhDbbN6Qq6oT", "campaignId": "cam_oxeGg6paG3ZVxjHkH", "sequenceId": "seq_ODjsLXkxXiySRw6dK", "sequenceStep": 1, "emailTemplateId": "etp_z3nAbjdHuewVEjIl5", "createdBy": "usr_EvXz6JqPSJJL9lHkp", "sendUserId": "usr_EvXz6JqPSJJL9lHkp", "name": "Unicorn campaign", "leadFirstName": "Sam", "leadLastName": "Taylor", "leadEmail": "sam@example.com", "leadCompanyName": "lemlist", "contactId": "ctc_FkeUdQHEfhqG2HMbK", "relatedSentAt": "2020-12-07T11:49:14.830Z", "metaData": { "teamId": "tea_8QvkOiBfPdb2ZRhHi", "campaignId": "cam_oxeGg6paG3ZVxjHkH", "leadId": "lea_wj47uWhDbbN6Qq6oT", "type": "emailsOpened", "createdBy": "usr_EvXz6JqPSJJL9lHkp", "taskId": "tsk_namMcIQnA6gxQIupP" }, "lead": { "_id": "lea_wj47uWhDbbN6Qq6oT", "isPaused": false, "state": "emailsUnsubscribed", "personalized": false, "source": "manually", "variables": { "firstName": "Sam ", "lastName": "Taylor", "email": "sam@example.com", "companyName": "lemlist", "linkedinUrl": "https://www.linkedin.com/in/sam-doe" }, "contactId": "ctc_FkeUdQHEfhqG2HMbK", "enrichment": {} }, "campaignName": "Unicorn campaign", "sequenceTested": "A", "emailTemplateName": "Blank" }, { "_id": "act_q4tnlXNdXsBeQceYW", "type": "emailsOpened", "isFirst": false, "stopped": false, "createdAt": "2025-10-27T20:17:24.119Z", "bot": false, "teamId": "tea_8QvkOiBfPdb2ZRhHi", "leadId": "lea_wj47uWhDbbN6Qq6oT", "campaignId": "cam_oxeGg6paG3ZVxjHkH", "sequenceId": "seq_ODjsLXkxXiySRw6dK", "sequenceStep": 1, "emailTemplateId": "etp_z3nAbjdHuewVEjIl5", "createdBy": "usr_EvXz6JqPSJJL9lHkp", "sendUserId": "usr_EvXz6JqPSJJL9lHkp", "name": "Unicorn campaign", "leadFirstName": "Sam", "leadLastName": "Taylor", "leadEmail": "sam@example.com", "leadCompanyName": "lemlist", "contactId": "ctc_FkeUdQHEfhqG2HMbK", "relatedSentAt": "2020-12-07T11:49:14.830Z", "metaData": { "teamId": "tea_8QvkOiBfPdb2ZRhHi", "campaignId": "cam_oxeGg6paG3ZVxjHkH", "leadId": "lea_wj47uWhDbbN6Qq6oT", "type": "emailsOpened", "createdBy": "usr_EvXz6JqPSJJL9lHkp", "taskId": "tsk_namMcIQnA6gxQIupP" }, "lead": { "_id": "lea_wj47uWhDbbN6Qq6oT", "isPaused": false, "state": "emailsUnsubscribed", "personalized": false, "source": "manually", "variables": { "firstName": "Sam ", "lastName": "Taylor", "email": "sam@example.com", "companyName": "lemlist", "linkedinUrl": "https://www.linkedin.com/in/sam-doe" }, "contactId": "ctc_FkeUdQHEfhqG2HMbK", "enrichment": {} }, "campaignName": "Unicorn campaign", "sequenceTested": "A", "emailTemplateName": "Blank" } ] } } }, "400": { "description": "Bad team", "content": { "text/plain": { "example": "Bad team" } } }, "401": { "description": "Unauthorized" } } } }, "/activities/{activityId}/recording-transcript": { "delete": { "summary": "Delete Activity Recording & Transcript", "tags": [ "Activities" ], "parameters": [ { "name": "activityId", "in": "path", "required": true, "description": "Unique activity ID", "example": "act_123", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Activity not found or has no recording", "content": { "text/plain": { "example": "Activity not found" } } }, "405": { "description": "Method not allowed" }, "500": { "description": "Error while deleting recording or transcript" } } } }, "/v2/campaigns/{campaignId}/stats": { "get": { "summary": "Get Campaign Stats", "tags": [ "Campaigns" ], "description": "Retrieve detailed statistics for a specific campaign, with filtering options by date, user, A/B testing, and communication channels.", "parameters": [ { "name": "campaignId", "in": "path", "required": true, "description": "Unique campaign ID", "example": "cam_123", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": true, "description": "Start date in ISO 8601 format", "example": "2024-01-07T22:00:00.000Z", "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "required": true, "description": "End date in ISO 8601 format", "example": "2025-07-10T21:59:59.999Z", "schema": { "type": "string", "format": "date-time" } }, { "name": "sendUser", "in": "query", "required": false, "description": "Filter stats by send user. Format: `sendUserId|sendUserEmail`. The sendUserId should begin with 'usr_' and the sendUserEmail should be a valid sender email. If the param is specified, both sendUserId and sendUserEmail are mandatory.", "example": "usr_OcIHizJyIeaDxicQP|email@example.com", "schema": { "type": "string" } }, { "name": "ABSelected", "in": "query", "required": false, "description": "A/B version filter", "example": "A", "schema": { "type": "string", "enum": [ "A", "B" ] } }, { "name": "channels", "in": "query", "required": false, "description": "JSON array of channels to include. Possible values: 'email', 'linkedin', 'others'", "example": "[\"others\", \"linkedin\", \"email\"]", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "nbLeads": { "type": "integer", "description": "Total number of leads in the campaign" }, "nbLeadsLaunched": { "type": "integer", "description": "Number of leads launched in the campaign" }, "nbLeadsReached": { "type": "integer", "description": "Number of leads that were successfully reached" }, "nbLeadsOpened": { "type": "integer", "description": "Number of leads that opened messages" }, "nbLeadsInteracted": { "type": "integer", "description": "Number of leads that interacted with messages (clicked, replied)" }, "nbLeadsAnswered": { "type": "integer", "description": "Number of leads that answered" }, "nbLeadsInterested": { "type": "integer", "description": "Number of leads marked as interested" }, "nbLeadsNotInterested": { "type": "integer", "description": "Number of leads marked as not interested" }, "nbLeadsUnsubscribed": { "type": "integer", "description": "Number of leads that unsubscribed" }, "nbLeadsInterrupted": { "type": "integer", "description": "Number of leads with interrupted sequences" }, "messagesSent": { "type": "integer", "description": "Total number of messages sent" }, "messagesNotSent": { "type": "integer", "description": "Number of messages that failed to send" }, "messagesBounced": { "type": "integer", "description": "Number of messages that bounced" }, "delivered": { "type": "integer", "description": "Number of messages successfully delivered" }, "opened": { "type": "integer", "description": "Number of messages opened" }, "clicked": { "type": "integer", "description": "Number of messages with clicks" }, "replied": { "type": "integer", "description": "Number of messages that received replies" }, "invitationAccepted": { "type": "integer", "description": "Number of LinkedIn invitations accepted" }, "meetingBooked": { "type": "integer", "description": "Number of meetings booked" }, "steps": { "type": "array", "description": "Detailed metrics for each step in the campaign", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Step index in the sequence" }, "sequenceId": { "type": "string", "description": "ID of the sequence" }, "sequenceStep": { "type": "integer", "description": "Step number within the sequence" }, "abTest": { "type": "string", "description": "A/B test variant (if applicable)" }, "taskType": { "type": "string", "description": "Type of task", "enum": [ "email", "linkedinVisit", "linkedinInvite", "linkedinSend", "phone", "manual", "conditional" ] }, "conditionLabel": { "type": "string", "description": "Label for conditional steps" }, "invited": { "type": "integer", "description": "Number of LinkedIn invitations sent" }, "sent": { "type": "integer", "description": "Number of messages sent" }, "delivered": { "type": "integer", "description": "Number of messages delivered" }, "opened": { "type": "integer", "description": "Number of messages opened" }, "clicked": { "type": "integer", "description": "Number of clicks from a message from this step" }, "replied": { "type": "integer", "description": "Number of replies" }, "notDelivered": { "type": "integer", "description": "Number of messages not delivered" }, "bounced": { "type": "integer", "description": "Number of messages bounced" }, "unsubscribed": { "type": "integer", "description": "Number of unsubscribes from this step" } } } } } }, "example": { "nbLeads": 32, "nbLeadsLaunched": 32, "nbLeadsReached": 32, "nbLeadsOpened": 31, "nbLeadsInteracted": 4, "nbLeadsAnswered": 16, "nbLeadsInterested": 1, "nbLeadsNotInterested": 0, "nbLeadsUnsubscribed": 1, "nbLeadsInterrupted": 1, "messagesSent": 72, "messagesNotSent": 0, "messagesBounced": 0, "delivered": 72, "opened": 47, "clicked": 4, "replied": 16, "invitationAccepted": 0, "meetingBooked": 0, "steps": [ { "index": 1, "sequenceId": "seq_rH5RD3fMkkt2gM3YC", "sequenceStep": 0, "taskType": "linkedinSend", "invited": 0, "sent": 32, "delivered": 32, "opened": 15, "clicked": 0, "replied": 15, "notDelivered": 0, "bounced": 0, "unsubscribed": 1 }, { "index": 2, "sequenceId": "seq_rH5RD3fMkkt2gM3YC", "sequenceStep": 1, "invited": 0, "sent": 20, "delivered": 20, "opened": 17, "clicked": 1, "replied": 1, "notDelivered": 0, "bounced": 0, "unsubscribed": 0 }, { "index": 3, "sequenceId": "seq_rH5RD3fMkkt2gM3YC", "sequenceStep": 2, "invited": 0, "sent": 20, "delivered": 20, "opened": 15, "clicked": 3, "replied": 0, "notDelivered": 0, "bounced": 0, "unsubscribed": 0 } ] } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "text/plain": { "examples": { "badTeam": { "summary": "Bad team", "value": "Bad team" }, "missingDates": { "summary": "Missing dates", "value": "Bad params: startDate and endDate are required" }, "invalidChannels": { "summary": "Invalid channels format", "value": "Bad params: channels must be a valid array" }, "invalidChannelValues": { "summary": "Invalid channel values", "value": "Bad params: channels must be empty or contain \"others\", \"email\" or \"linkedin\"" }, "invalidAB": { "summary": "Invalid A/B selection", "value": "Bad params: ABSelected must be A or B" }, "invalidSendUserFormat": { "summary": "Invalid send user format", "value": "Bad param format: sendUser must be formatted as follow: