{ "openapi": "3.0.3", "info": { "title": "Grinfi.io API", "description": "Complete API reference for Grinfi.io — the all-in-one LinkedIn & email outreach platform.\nUse this API to manage your CRM contacts, run outreach automations, send messages, and integrate Grinfi with your own tools.\n\n## Authentication\nAll requests require a Bearer token in the `Authorization` header.\n1. Log in at [leadgen.grinfi.io](https://leadgen.grinfi.io/)\n2. Go to [Settings → API Keys](https://leadgen.grinfi.io/settings/api-keys)\n3. Copy your key and pass it as:\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\n\n\n## Pagination\nList endpoints support `limit` (default 20) and `offset` (default 0) query parameters. Responses include `total` count and `has_more` boolean.\n\n## Filtering\nMost list endpoints accept a `filter` object. Supported value types:\n| Type | Example | SQL equivalent | |------|---------|----------------| | Scalar | `\"status\": \"ok\"` | `= 'ok'` | | Array | `\"status\": [\"ok\", \"pending\"]` | `IN ('ok', 'pending')` | | Object | `\"created_at\": {\">=\": \"2024-01-01\"}` | `>= '2024-01-01'` | | `\"is_null\"` | `\"email\": \"is_null\"` | `IS NULL` | | `\"is_not_null\"` | `\"email\": \"is_not_null\"` | `IS NOT NULL` |\nSupported operators: `=`, `!=`, `<`, `<=`, `>`, `>=`, `<>`\n\n## Rate Limits\nAPI requests are rate-limited to **300 requests per minute** per API key. If you exceed the limit, you'll receive a `429` response. Use exponential backoff when retrying.\n\n## Contact Deduplication\nWhen creating contacts via upsert, the system checks for duplicates using the following field priority (first match wins):\n1. `ln_member_id` (LinkedIn member ID)\n2. `ln_id` (LinkedIn public ID)\n3. `sn_id` (Sales Navigator ID)\n4. LinkedIn nickname\n5. `work_email`\n6. `personal_email`\n7. `name` + `company_name` combination\n", "version": "2.0.0", "contact": { "name": "Grinfi.io Support", "url": "https://grinfi.io", "email": "support@grinfi.io" }, "license": { "name": "Copyright", "url": "https://grinfi.io/terms" } }, "x-tagGroups": [ { "name": "Account", "tags": [ "User", "Teams" ] }, { "name": "CRM", "tags": [ "Contacts", "Companies", "Lists", "Tags", "Pipeline", "Custom Fields", "Notes", "Activities", "Data Sources" ] }, { "name": "Outreach", "tags": [ "Automations", "Tasks", "Sender Profiles" ] }, { "name": "Messaging", "tags": [ "LinkedIn Messages", "Emails", "Mailboxes", "Attachments" ] }, { "name": "Browsers", "tags": [ "LinkedIn Browsers" ] }, { "name": "Integrations", "tags": [ "Webhooks" ] } ], "tags": [ { "name": "User", "description": "Get current authenticated user profile.\n" }, { "name": "Teams", "description": "Manage workspaces (teams). Each team has its own contacts, automations, and sender profiles.\n" }, { "name": "LinkedIn Browsers", "description": "Manage LinkedIn browser profiles used for automation. Browsers run in the cloud and execute LinkedIn actions on behalf of sender profiles.\n" }, { "name": "Data Sources", "description": "Manage LinkedIn import jobs. Data sources represent automated imports from LinkedIn searches, Sales Navigator, and other LinkedIn data.\n" }, { "name": "Contacts", "description": "Manage your CRM contacts (leads). Search, create, update, and organize contacts across lists and pipeline stages.\n\n**Mass action types** for `PUT /leads/api/leads/mass-action`: `contact_add_tags`, `contact_remove_tags`, `contact_replace_tags`, `contact_change_list`, `contact_change_pipeline_stage`, `contact_change_custom_field`, `contact_add_to_flow`, `contact_cancel_from_flows`, `contact_delete`, `contact_export_csv`, `contact_mark_read`.\n" }, { "name": "Companies", "description": "Manage company records in your CRM. Companies can be linked to contacts and enriched with additional data from LinkedIn.\n" }, { "name": "Lists", "description": "Organize contacts into lists. Every contact must belong to a list. Use lists to segment your audience for outreach campaigns.\n" }, { "name": "Tags", "description": "Label contacts and companies with custom tags for easy filtering and segmentation.\n" }, { "name": "Pipeline", "description": "Define and manage pipeline stages to track where each contact stands in your sales or outreach process.\n\n**Stage categories:** `cold` (not yet contacted), `engaging` (outreach in progress), `positive` (showing interest / converted), `negative` (rejected / lost).\n" }, { "name": "Custom Fields", "description": "Extend contact and company records with custom data fields. Store any additional information relevant to your workflow.\n\n**Limits:** Maximum 100 custom fields per object type (`lead` or `company`). Field names must start with a letter or underscore, and contain only alphanumeric characters and underscores.\n" }, { "name": "Notes", "description": "Add internal notes to contacts or companies for your team's reference.\n" }, { "name": "Activities", "description": "Track events and interactions on contacts and companies, such as messages sent, emails opened, and status changes.\n" }, { "name": "Automations", "description": "Manage outreach automation sequences. Automations define multi-step workflows that send LinkedIn messages, emails, and perform other actions on a schedule.\n\n**Flow statuses:** `on` (active), `off` (paused), `draft`, `archived`.\n" }, { "name": "Tasks", "description": "Create and manage outreach tasks such as sending LinkedIn messages or emails. Tasks can be created manually or generated by automations.\n\n**Task types:** `linkedin_send_message`, `linkedin_send_connection_request`, `linkedin_send_inmail`, `linkedin_like_latest_post`, `linkedin_endorse_skills`, `email_send_message`, `trigger_linkedin_connection_request_accepted`.\n\n**Task statuses:** `in_progress`, `closed`, `canceled`, `failed`, `skipped`.\n" }, { "name": "Sender Profiles", "description": "Sender profiles represent the LinkedIn and email accounts used to send outreach messages. Each profile links a LinkedIn browser and/or email mailbox.\n" }, { "name": "LinkedIn Messages", "description": "Send and retrieve LinkedIn messages through your connected sender profiles.\n\n**LinkedIn message types:** `connection_note`, `message`, `InMail`.\n\n**Message statuses:** `new`, `in_progress`, `done`, `failed`.\n\n**Automation field:** `auto` (sent by automation), `manual` (sent by user), `synced` (incoming message synced from LinkedIn).\n" }, { "name": "Emails", "description": "Send and retrieve emails through your connected mailboxes.\n\n**Email types:** `inbox` (received), `outbox` (sent).\n" }, { "name": "Mailboxes", "description": "Manage email mailboxes (SMTP/IMAP, Gmail, Outlook) used for sending and receiving emails in outreach campaigns.\n" }, { "name": "Attachments", "description": "Upload files (images, PDFs, documents) to your team's attachment storage. Uploaded attachments can be referenced by UUID when sending LinkedIn messages or emails via the `attachments` field in the request body.\n" }, { "name": "Webhooks", "description": "Configure real-time HTTP callbacks for events in your account. Webhooks send a POST (or custom method) request to your target URL whenever a specified event occurs — such as a contact replying, being enriched, or exported.\n" } ], "servers": [ { "url": "https://leadgen.grinfi.io", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/id/api/users/current": { "get": { "summary": "Get current user", "description": "Retrieve the authenticated user's profile and configuration.", "operationId": "getCurrentUser", "tags": [ "User" ], "responses": { "200": { "description": "Current user profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user" } } } } } } }, "/id/api/teams": { "get": { "summary": "List teams", "description": "List all teams (workspaces) the authenticated user has access to.", "operationId": "listTeams", "tags": [ "Teams" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Paginated list of teams.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/team" } }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 }, "has_more": { "type": "boolean" } } } } } } } } }, "/id/api/teams/{id}": { "get": { "summary": "Get a team", "description": "Get details of a specific team by ID.", "operationId": "getTeam", "tags": [ "Teams" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "Team ID." } ], "responses": { "200": { "description": "Team details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/team" } } } }, "404": { "description": "Team not found." } } } }, "/leads/api/leads/lookup-one": { "post": { "summary": "Find a contact", "description": "Look up a single contact by LinkedIn ID, email address, or name + company combination. At least one identifier must be provided. This is useful for checking if a contact already exists before creating a new one.\n", "operationId": "findOneContact", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "linkedin_id": { "type": "string", "nullable": true, "description": "LinkedIn profile URL or member ID.", "example": "john-doe-123456" }, "email": { "type": "string", "nullable": true, "description": "Email address to search by.", "example": "john@example.com" }, "name": { "type": "string", "nullable": true, "description": "Full name of the contact.", "example": "John Doe" }, "company_name": { "type": "string", "nullable": true, "description": "Company name (required when searching by name).", "example": "Acme Inc" }, "disable_aggregation": { "type": "boolean", "description": "Skip enrichment data aggregation in the response." } }, "anyOf": [ { "required": [ "linkedin_id" ] }, { "required": [ "email" ] }, { "required": [ "name", "company_name" ] } ] }, "example": { "linkedin_id": "john-doe-123456" } } } }, "responses": { "200": { "description": "Contact found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lead" } } } }, "404": { "description": "No matching contact found." }, "422": { "description": "Validation error — provide at least one identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/leads/api/leads/search": { "post": { "summary": "Search contacts", "description": "Search contacts using advanced filters with pagination and sorting. Use this to find contacts by any combination of fields — name, company, email status, pipeline stage, tags, and more.\n", "operationId": "searchContacts", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "type": "object", "description": "Filter criteria. Supports scalar values (equals), arrays (IN), objects with operators (`>=`, `<=`, etc.), `\"is_null\"`, `\"is_not_null\"`.\n", "example": { "company_name": "Acme Inc", "email_status": "ok" } }, "limit": { "type": "integer", "minimum": 1, "default": 20, "description": "Number of results to return.", "example": 20 }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Number of results to skip.", "example": 0 }, "order_field": { "type": "string", "default": "created_at", "description": "Field to sort by.", "example": "name" }, "order_type": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction.", "example": "asc" }, "disable_aggregation": { "type": "boolean", "default": false, "description": "Skip enrichment data aggregation." } } }, "example": { "filter": { "company_name": "Acme Inc", "email_status": "ok" }, "limit": 20, "offset": 0, "order_field": "created_at", "order_type": "desc" } } } }, "responses": { "200": { "description": "Paginated list of matching contacts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/lead" } }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 142 } } } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/leads/api/leads/{uuid}": { "get": { "summary": "Get a contact", "description": "Retrieve full details of a contact by their UUID.", "operationId": "getLead", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Contact details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lead" } } } }, "404": { "description": "Contact not found." } } }, "put": { "summary": "Update a contact", "description": "Update one or more fields on an existing contact. Only include the fields you want to change.\n\n**Important:** this endpoint only accepts the standard contact fields listed below. Custom field values are **silently ignored**. To set custom fields use [`POST /leads/api/custom-field-values`](#tag/Custom-Fields/operation/upsertCustomFieldValue). Alternatively, the [Upsert endpoint](#tag/Contacts/operation/upsertContact) supports `custom_fields` in a single request.\n", "operationId": "updateLead", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "company_name": { "type": "string", "example": "Acme Inc" }, "ln_id": { "type": "string", "nullable": true, "description": "LinkedIn member ID.", "example": "ACoAAAB6GuQBOXo75numqJfM9u08uHgjOSo4p9U" }, "sn_id": { "type": "string", "nullable": true, "description": "Sales Navigator ID.", "example": "ACwAAAB6GuQBEz2TMHbG4sa7Nw5wSi7cJXMQkPI" }, "linkedin": { "type": "string", "nullable": true, "description": "LinkedIn profile handle.", "example": "john-doe-123456" }, "email": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "about": { "type": "string", "description": "Bio or description." }, "domain": { "type": "string", "description": "Company domain (used for email discovery).", "example": "acme.com" }, "headline": { "type": "string", "nullable": true, "example": "VP of Sales at Acme Inc" }, "position": { "type": "string", "nullable": true, "example": "VP of Sales" }, "raw_address": { "type": "string", "nullable": true, "example": "San Francisco, CA, USA" } } } } } }, "responses": { "200": { "description": "Updated contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lead" } } } }, "404": { "description": "Contact not found." } } }, "delete": { "summary": "Delete a contact", "description": "Permanently delete a contact by UUID. This creates a background deletion job.", "operationId": "deleteLead", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Contact deleted." }, "422": { "description": "Unable to process deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/leads/api/leads/upsert": { "post": { "summary": "Create or update a contact", "description": "Create a new contact in a list, or update an existing one if found. The contact is identified by `linkedin_id`. If the contact already exists and `update_if_exists` is true, their data will be updated. Optionally move the contact to the specified list with `move_to_list`.\n\n**Tip:** Unlike `PUT /leads/api/leads/{uuid}`, this endpoint accepts `custom_fields` so you can set standard and custom fields in a single request.\n", "operationId": "upsertContact", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead", "list_uuid" ], "properties": { "lead": { "allOf": [ { "$ref": "#/components/schemas/create-lead-fields" }, { "type": "object", "required": [ "linkedin_id" ] } ] }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values as key-value pairs.", "example": { "field_position": "CTO", "field_experience": "10 years" } }, "list_uuid": { "type": "string", "description": "Target list UUID.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "update_if_exists": { "type": "boolean", "default": true, "description": "Update the contact if it already exists." }, "move_to_list": { "type": "boolean", "default": false, "description": "Move existing contact to the specified list." } } }, "example": { "lead": { "linkedin_id": "john-doe-123456", "first_name": "John", "last_name": "Doe", "company_name": "Acme Inc", "email": "john@acme.com" }, "list_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "update_if_exists": true } } } }, "responses": { "200": { "description": "Contact created or updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lead" } } } }, "422": { "description": "Validation or duplicate error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/leads/api/leads/mass-action": { "put": { "summary": "Mass action on contacts", "description": "Perform a bulk action on contacts matching a filter.\n\n**Supported action types:**\n| Type | Payload | Description | |------|---------|-------------| | `contact_add_tags` | `{tag_uuid}` | Add a tag | | `contact_remove_tags` | `{tag_uuid}` | Remove a tag | | `contact_replace_tags` | `{tag_uuids: [...]}` | Replace all tags | | `contact_change_list` | `{list_uuid}` | Move to a different list | | `contact_change_pipeline_stage` | `{pipeline_stage_uuid}` | Change pipeline stage | | `contact_change_custom_field` | `{custom_field_uuid, value}` | Set custom field value | | `contact_add_to_flow` | `{flow_uuid}` | Add to automation | | `contact_cancel_from_flows` | `{flow_uuids: [...]}` | Cancel from automations | | `contact_delete` | — | Delete contacts | | `contact_export_csv` | — | Export to CSV | | `contact_mark_read` | — | Mark conversations as read |\n", "operationId": "leadsMassAction", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "filter" ], "properties": { "type": { "type": "string", "description": "Action type.", "enum": [ "contact_add_tags", "contact_remove_tags", "contact_replace_tags", "contact_change_list", "contact_change_pipeline_stage", "contact_change_custom_field", "contact_add_to_flow", "contact_cancel_from_flows", "contact_delete", "contact_export_csv", "contact_mark_read" ], "example": "contact_add_tags" }, "filter": { "type": "object", "additionalProperties": true, "description": "Filter to select contacts. Use `{ids: [\"uuid1\", \"uuid2\"]}` for specific contacts or `{all: true}` for all matching contacts.\n" }, "payload": { "type": "object", "additionalProperties": true, "description": "Action-specific payload (see table above)." } } }, "example": { "type": "contact_add_tags", "filter": { "ids": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "payload": { "tag_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } } } } }, "responses": { "200": { "description": "Action executed." }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/leads/api/companies": { "get": { "summary": "List companies", "description": "Retrieve a paginated list of companies in your CRM. Supports filtering by name, domain, industry, and other fields.\n", "operationId": "listCompanies", "tags": [ "Companies" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "filter", "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Search query." } } }, "description": "Filters for company search." } ], "responses": { "200": { "description": "Paginated list of companies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/company" } }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 58 } } } } } } } }, "post": { "summary": "Create companies", "description": "Create one or more company records. Optionally assign them to lists and a data source.\n", "operationId": "createCompanies", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companies" ], "properties": { "companies": { "type": "array", "description": "Array of company objects to create.", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Acme Inc" }, "domain": { "type": "string", "example": "acme.com" }, "website": { "type": "string", "example": "https://acme.com" }, "linkedin": { "type": "string", "example": "acme-inc" }, "industry": { "type": "string", "example": "Technology" }, "employees_range": { "type": "string", "example": "51-200" }, "hq_raw_address": { "type": "string", "example": "San Francisco, CA" } } } }, "list_uuids": { "type": "array", "items": { "type": "string" }, "description": "List UUIDs to assign companies to." }, "data_source_uuid": { "type": "string" } } }, "example": { "companies": [ { "name": "Acme Inc", "domain": "acme.com", "industry": "Technology" } ], "list_uuids": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] } } } }, "responses": { "200": { "description": "Created companies.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/company" } } } } } } } }, "/leads/api/companies/{uuid}": { "get": { "summary": "Get a company", "description": "Retrieve full details of a company by UUID.", "operationId": "getCompany", "tags": [ "Companies" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Company details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/company" } } } }, "404": { "description": "Company not found." } } }, "put": { "summary": "Update a company", "description": "Update one or more fields on an existing company.", "operationId": "updateCompany", "tags": [ "Companies" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Acme Inc" }, "domain": { "type": "string", "example": "acme.com" }, "website": { "type": "string", "example": "https://acme.com" }, "linkedin": { "type": "string", "example": "acme-inc" }, "ln_id": { "type": "integer", "description": "LinkedIn company numeric ID." }, "industry": { "type": "string", "example": "Technology" }, "employees_range": { "type": "string", "example": "51-200" }, "hq_raw_address": { "type": "string", "example": "San Francisco, CA" }, "phone": { "type": "string" }, "about": { "type": "string" }, "lead_status_uuid": { "type": "string", "description": "Pipeline stage UUID." } } } } } }, "responses": { "200": { "description": "Updated company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/company" } } } }, "404": { "description": "Company not found." } } }, "delete": { "summary": "Delete a company", "description": "Permanently delete a company by UUID.", "operationId": "deleteCompany", "tags": [ "Companies" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Company deleted." }, "422": { "description": "Unable to process deletion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/leads/api/companies/lookup": { "post": { "summary": "Lookup companies", "description": "Find companies by LinkedIn ID, website URL, or name. Pass an array of lookup criteria — each item should contain at least one identifier.\n", "operationId": "lookupCompanies", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lookups" ], "properties": { "lookups": { "type": "array", "items": { "type": "object", "properties": { "ln_id": { "type": "string" }, "linkedin": { "type": "string" }, "website": { "type": "string" }, "name": { "type": "string" } } } } } }, "example": { "lookups": [ { "linkedin": "acme-inc" }, { "website": "acme.com" } ] } } } }, "responses": { "200": { "description": "Matching companies.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/company" } } } } } } } }, "/leads/api/companies/leads": { "post": { "summary": "Get contacts by companies", "description": "Retrieve all contacts belonging to the specified companies. Returns an object mapping company UUIDs to arrays of contacts.\n", "operationId": "getCompanyLeads", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "description": "Array of company UUIDs." } } }, "example": { "uuids": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] } } } }, "responses": { "200": { "description": "Contacts grouped by company UUID.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/lead" } } } } } } } } }, "/leads/api/companies/advanced-enrichment": { "put": { "summary": "Enrich companies", "description": "Queue advanced enrichment for companies. Provide either a filter to select companies or an array of specific company UUIDs. Enrichment uses credits from your account balance.\n", "operationId": "enrichCompanies", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "type": "object", "description": "Filter to select companies for enrichment." }, "uuids": { "type": "array", "items": { "type": "string" }, "description": "Specific company UUIDs to enrich." } } }, "example": { "uuids": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] } } } }, "responses": { "200": { "description": "Enrichment queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of companies queued." } } } } } }, "402": { "description": "Insufficient enrichment credits." } } } }, "/leads/api/companies/mass-action": { "put": { "summary": "Mass action on companies", "description": "Perform a bulk action on companies matching a filter.\n", "operationId": "companiesMassAction", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "filter" ], "properties": { "type": { "type": "string", "description": "Action type.", "enum": [ "company_add_tags", "company_remove_tags", "company_replace_tags", "company_change_pipeline_stage", "company_delete" ], "example": "company_add_tags" }, "filter": { "type": "object", "additionalProperties": true, "description": "Filter to select companies." }, "payload": { "type": "object", "additionalProperties": true, "description": "Action-specific payload." } } }, "example": { "type": "company_add_tags", "filter": { "ids": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }, "payload": { "tag_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } } } } }, "responses": { "200": { "description": "Action executed." }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/leads/api/lists": { "get": { "summary": "List all lists", "description": "Retrieve all contact lists in your account. Lists are used to organize contacts into groups for outreach campaigns.\n", "operationId": "listLists", "tags": [ "Lists" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "filter", "schema": { "type": "object", "properties": { "q": { "type": "string", "nullable": true, "description": "Search by list name." }, "uuid": { "$ref": "#/components/schemas/mixed-filter-type" }, "name": { "$ref": "#/components/schemas/mixed-filter-type" } } } } ], "responses": { "200": { "description": "List of contact lists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/list" } }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 12 } } } } } } } }, "post": { "summary": "Create a list", "description": "Create a new contact list.", "operationId": "createList", "tags": [ "Lists" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name for the new list.", "example": "CMO Germany" } } }, "example": { "name": "CMO Germany" } } } }, "responses": { "201": { "description": "List created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list" } } } } } } }, "/leads/api/lists/{uuid}": { "get": { "summary": "Get a list", "description": "Retrieve details of a specific contact list.", "operationId": "getList", "tags": [ "Lists" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "List details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list" } } } }, "404": { "description": "List not found." } } }, "put": { "summary": "Update a list", "description": "Rename an existing contact list.", "operationId": "updateList", "tags": [ "Lists" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Updated List Name" } } } } } }, "responses": { "200": { "description": "Updated list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list" } } } } } }, "delete": { "summary": "Delete a list", "description": "Permanently delete a contact list.", "operationId": "deleteList", "tags": [ "Lists" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "List deleted." } } } }, "/leads/api/lists/metrics": { "post": { "summary": "Get list metrics", "description": "Get lead counts for specified lists.", "operationId": "getListMetrics", "tags": [ "Lists" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "description": "Array of list UUIDs." } } }, "example": { "uuids": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] } } } }, "responses": { "200": { "description": "Metrics per list." } } } }, "/leads/api/tags": { "get": { "summary": "List tags", "description": "Retrieve all tags in your account.", "operationId": "listTags", "tags": [ "Tags" ], "responses": { "200": { "description": "List of tags.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/tag" } } } } } } } } }, "post": { "summary": "Create a tag", "description": "Create a new tag with optional color.", "operationId": "createTag", "tags": [ "Tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Hot Lead" }, "color": { "type": "string", "description": "Hex color code.", "example": "#ff5733" } } } } } }, "responses": { "201": { "description": "Tag created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tag" } } } } } } }, "/leads/api/tags/{uuid}": { "put": { "summary": "Update a tag", "description": "Update a tag's name or color.", "operationId": "updateTag", "tags": [ "Tags" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Warm Lead" }, "color": { "type": "string", "example": "#33ff57" } } } } } }, "responses": { "200": { "description": "Updated tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tag" } } } } } }, "delete": { "summary": "Delete a tag", "description": "Permanently delete a tag.", "operationId": "deleteTag", "tags": [ "Tags" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Tag deleted." } } } }, "/leads/api/tags/metrics": { "post": { "summary": "Get tag metrics", "description": "Get lead and company counts for specified tags.", "operationId": "getTagMetrics", "tags": [ "Tags" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids", "metrics" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "description": "Array of tag UUIDs." }, "metrics": { "type": "array", "items": { "type": "string", "enum": [ "leads_count", "companies_count" ] }, "description": "Which metrics to retrieve." } } }, "example": { "uuids": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ], "metrics": [ "leads_count", "companies_count" ] } } } }, "responses": { "200": { "description": "Metrics per tag." } } } }, "/leads/api/pipeline-stages": { "get": { "summary": "List pipeline stages", "description": "Retrieve all pipeline stages. Use the `filter` parameter (JSON string) to narrow results by object type or stage type.\n", "operationId": "listPipelineStages", "tags": [ "Pipeline" ], "parameters": [ { "in": "query", "name": "filter", "required": true, "schema": { "type": "string" }, "description": "JSON string with filter criteria. Supported keys:\n- `object` — `\"lead\"` or `\"company\"` (required)\n- `type` — `\"custom\"`, `\"new\"`, `\"approaching\"`, `\"engaging\"`, `\"replied\"`\nExample: `?filter={\"object\":\"lead\"}`\n" } ], "responses": { "200": { "description": "List of pipeline stages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/pipeline-stage" } } } } } } } } }, "post": { "summary": "Create a pipeline stage", "description": "Create a new custom pipeline stage.", "operationId": "createPipelineStage", "tags": [ "Pipeline" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "object", "category" ], "properties": { "name": { "type": "string", "example": "Demo Booked" }, "object": { "type": "string", "enum": [ "lead", "company" ], "example": "lead" }, "category": { "type": "string", "enum": [ "cold", "engaging", "positive", "negative" ], "description": "Visual category for the stage.", "example": "positive" }, "order": { "type": "integer", "description": "Display order.", "example": 5 } } } } } }, "responses": { "201": { "description": "Stage created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipeline-stage" } } } } } } }, "/leads/api/pipeline-stages/{uuid}": { "put": { "summary": "Update a pipeline stage", "description": "Update a pipeline stage's name, category, or order.", "operationId": "updatePipelineStage", "tags": [ "Pipeline" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string", "enum": [ "cold", "engaging", "positive", "negative" ] }, "order": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated stage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pipeline-stage" } } } } } }, "delete": { "summary": "Delete a pipeline stage", "description": "Delete a custom pipeline stage.", "operationId": "deletePipelineStage", "tags": [ "Pipeline" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Stage deleted." } } } }, "/leads/api/custom-fields": { "get": { "summary": "List custom fields", "description": "Retrieve all custom field definitions for contacts and companies.", "operationId": "listCustomFields", "tags": [ "Custom Fields" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" } ], "responses": { "200": { "description": "List of custom fields.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/custom-field" } } } } } } } } }, "post": { "summary": "Create a custom field", "description": "Define a new custom field for contacts or companies.", "operationId": "createCustomField", "tags": [ "Custom Fields" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "object" ], "properties": { "name": { "type": "string", "description": "Field name.", "example": "Industry Vertical" }, "object": { "type": "string", "enum": [ "lead", "company" ], "description": "Whether this field applies to contacts or companies.", "example": "lead" }, "order": { "type": "integer", "description": "Display order." } } } } } }, "responses": { "201": { "description": "Custom field created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-field" } } } } } } }, "/leads/api/custom-fields/{uuid}": { "put": { "summary": "Update a custom field", "description": "Update a custom field's name or order.", "operationId": "updateCustomField", "tags": [ "Custom Fields" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "order": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-field" } } } } } }, "delete": { "summary": "Delete a custom field", "description": "Permanently remove a custom field definition and all its values.", "operationId": "deleteCustomField", "tags": [ "Custom Fields" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Field deleted." } } } }, "/leads/api/custom-field-values": { "post": { "summary": "Set a custom field value", "description": "Set (or update) a custom field value on a contact or company. Pass `null` as value to clear the field.\n", "operationId": "upsertCustomFieldValue", "tags": [ "Custom Fields" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "custom_field_uuid", "object_type", "object_uuid" ], "properties": { "custom_field_uuid": { "type": "string", "description": "UUID of the custom field." }, "object_type": { "type": "string", "enum": [ "lead", "company" ] }, "object_uuid": { "type": "string", "description": "UUID of the contact or company." }, "value": { "type": "string", "nullable": true, "description": "Field value, or null to clear.", "example": "Enterprise" } } }, "example": { "custom_field_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "object_type": "lead", "object_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "value": "Enterprise" } } } }, "responses": { "201": { "description": "Value set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom-field-value" } } } } } } }, "/leads/api/notes": { "get": { "summary": "List notes", "description": "Retrieve notes with pagination.", "operationId": "listNotes", "tags": [ "Notes" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" } ], "responses": { "200": { "description": "List of notes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/note" } } } } } } } } }, "post": { "summary": "Create a note", "description": "Add a note to a contact or company.", "operationId": "createNote", "tags": [ "Notes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "object_uuid", "note" ], "properties": { "object": { "type": "string", "enum": [ "lead", "company" ], "example": "lead" }, "object_uuid": { "type": "string", "description": "UUID of the contact or company." }, "note": { "type": "string", "example": "Follow up after demo next week." } } } } } }, "responses": { "201": { "description": "Note created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/note" } } } } } } }, "/leads/api/notes/{uuid}": { "put": { "summary": "Update a note", "description": "Update the text of an existing note.", "operationId": "updateNote", "tags": [ "Notes" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "note" ], "properties": { "note": { "type": "string", "example": "Updated note content." } } } } } }, "responses": { "200": { "description": "Updated note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/note" } } } } } }, "delete": { "summary": "Delete a note", "description": "Permanently delete a note.", "operationId": "deleteNote", "tags": [ "Notes" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Note deleted." } } } }, "/leads/api/activities": { "get": { "summary": "List activities", "description": "List activity records for contacts or companies. Activities track events like messages sent, emails opened, pipeline stage changes, and more.\n\n**Known activity types:** `pipeline_stage_changed`, `linkedin_message_sent`, `linkedin_message_replied`, `linkedin_connection_request_sent`, `linkedin_connection_request_accepted`, `email_sent`, `email_replied`, `email_opened`, `email_clicked`, `email_bounced`, `contact_enriched`.\n\nFilter by type and date range to narrow results. The `payload` field contains event-specific data (e.g. `flow_origin`, `flow_uuid`, pipeline stage UUIDs).\n", "operationId": "listActivities", "tags": [ "Activities" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "filter", "required": true, "schema": { "type": "string" }, "description": "JSON string with filter criteria. Supported keys:\n- `type` — activity type (e.g. `\"pipeline_stage_changed\"`)\n- `lead_uuid` — filter by contact UUID\n- `company_uuid` — filter by company UUID\n- `created_at` — date filter with operators (`{\">=\": \"2026-01-01\"}`)\nExample: `?filter={\"type\":\"pipeline_stage_changed\",\"created_at\":{\">=\":\"2026-04-01\"}}`\n" } ], "responses": { "200": { "description": "List of activities.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/activity" } } } } } } } } }, "post": { "summary": "Create an activity", "description": "Create a new activity record for a contact or company.", "operationId": "createActivity", "tags": [ "Activities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "object_uuid", "object_type", "type" ], "properties": { "object_uuid": { "type": "string", "description": "UUID of the contact or company." }, "object_type": { "type": "string", "enum": [ "lead", "company" ] }, "type": { "type": "string", "description": "Activity type (e.g. `linkedin_message_sent`, `email_sent`).", "example": "linkedin_message_sent" }, "payload": { "type": "object", "additionalProperties": true, "description": "Activity-specific data." } } } } } }, "responses": { "201": { "description": "Activity created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/activity" } } } } } } }, "/leads/api/enrichment-queue": { "get": { "summary": "List enrichment queue", "description": "List entries in the enrichment processing queue.", "operationId": "listEnrichmentQueue", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" } ], "responses": { "200": { "description": "Enrichment queue entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/leads/api/data-sources": { "get": { "summary": "List data sources", "description": "List LinkedIn import jobs with pagination.", "operationId": "listDataSources", "tags": [ "Data Sources" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" } ], "responses": { "200": { "description": "Paginated list of data sources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/data-source" } }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 10 }, "has_more": { "type": "boolean" } } } } } } } }, "post": { "summary": "Create a data source", "operationId": "createDataSource", "tags": [ "Data Sources" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "list_uuid" ], "properties": { "type": { "type": "string", "enum": [ "csv_leads", "sn_leads_search", "sn_leads_saved_search", "sn_leads_list", "sn_accounts_search", "sn_accounts_saved_search", "sn_accounts_list", "ln_leads_search", "ln_accounts_search", "ln_my_network", "ln_my_messenger", "post_engagement", "recruiter_leads_search" ], "example": "sn_leads_search" }, "list_uuid": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "payload": { "type": "object", "description": "Import configuration specific to the data source type." }, "tags": { "type": "array", "nullable": true, "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Data source created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/data-source" } } } } } } }, "/leads/api/data-sources/{uuid}": { "get": { "summary": "Get a data source", "operationId": "getDataSource", "tags": [ "Data Sources" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Data source details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/data-source" } } } } } }, "put": { "summary": "Update a data source", "operationId": "updateDataSource", "tags": [ "Data Sources" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "list_uuid": { "type": "string" }, "payload": { "type": "object" }, "tags": { "type": "array", "nullable": true, "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Data source updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/data-source" } } } } } }, "delete": { "summary": "Delete a data source", "operationId": "deleteDataSource", "tags": [ "Data Sources" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Data source deleted." } } } }, "/flows/api/flows": { "get": { "summary": "List automations", "description": "Retrieve all outreach automations in your account. Automations are multi-step sequences that send LinkedIn messages, emails, and other actions on a schedule.\n", "operationId": "listFlows", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "filter", "schema": { "type": "object", "properties": { "q": { "type": "string", "nullable": true, "description": "Search by automation name." }, "status": { "$ref": "#/components/schemas/mixed-filter-type" } } }, "description": "Filters." } ], "responses": { "200": { "description": "Paginated list of automations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/flow" } }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 15 }, "has_more": { "type": "boolean" } } } } } } } } }, "/flows/api/flows/{flowUuid}": { "get": { "summary": "Get an automation", "description": "Retrieve full details of an automation by UUID.", "operationId": "getFlow", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/flowUuid-path" } ], "responses": { "200": { "description": "Automation details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flow" } } } }, "404": { "description": "Automation not found." } } }, "put": { "summary": "Update an automation", "description": "Update an automation's name, description, or schedule.", "operationId": "updateFlow", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/flowUuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Updated Campaign Name" }, "description": { "type": "string" }, "schedule": { "$ref": "#/components/schemas/schedule" } } } } } }, "responses": { "200": { "description": "Updated automation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flow" } } } } } }, "delete": { "summary": "Delete an automation", "description": "Permanently delete an automation. This cannot be undone.", "operationId": "deleteFlow", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/flowUuid-path" } ], "responses": { "204": { "description": "Automation deleted." } } } }, "/flows/api/flows/{flowUuid}/start": { "put": { "summary": "Start an automation", "description": "Activate an automation so it begins processing contacts and executing outreach steps on its schedule.\n", "operationId": "startFlow", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/flowUuid-path" } ], "responses": { "200": { "description": "Automation started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flow" } } } }, "422": { "description": "Cannot start (e.g., archived automation).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/flows/api/flows/{flowUuid}/stop": { "put": { "summary": "Stop an automation", "description": "Pause an automation. Contacts already in progress will finish their current step.", "operationId": "stopFlow", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/flowUuid-path" } ], "responses": { "200": { "description": "Automation stopped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flow" } } } } } } }, "/flows/api/flows/{flowUuid}/archive": { "put": { "summary": "Archive an automation", "description": "Archive an automation. Archived automations cannot be started.", "operationId": "archiveFlow", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/flowUuid-path" } ], "responses": { "200": { "description": "Automation archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flow" } } } } } } }, "/flows/api/flows/{flowUuid}/unarchive": { "put": { "summary": "Unarchive an automation", "description": "Restore an archived automation so it can be started again.", "operationId": "unarchiveFlow", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/flowUuid-path" } ], "responses": { "200": { "description": "Automation unarchived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flow" } } } } } } }, "/flows/api/flows/clone": { "post": { "summary": "Clone an automation", "description": "Create a copy of an existing automation with a new name. The cloned automation will be in a stopped state.\n", "operationId": "cloneFlow", "tags": [ "Automations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "flow_uuid", "name" ], "properties": { "flow_uuid": { "type": "string", "description": "UUID of the automation to clone." }, "name": { "type": "string", "example": "Campaign Q2 - Copy" }, "flow_workspace_uuid": { "type": "string" } } } } } }, "responses": { "201": { "description": "Cloned automation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flow" } } } } } } }, "/flows/api/flow-workspaces": { "get": { "summary": "List automation folders", "description": "List all automation folders (workspaces) for organizing automations.", "operationId": "listFlowWorkspaces", "tags": [ "Automations" ], "responses": { "200": { "description": "Paginated list of automation folders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/flow-workspace" } }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 5 }, "has_more": { "type": "boolean" } } } } } } } }, "post": { "summary": "Create automation folder", "operationId": "createFlowWorkspace", "tags": [ "Automations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Q2 Campaigns" }, "order": { "type": "integer", "example": 1 } } } } } }, "responses": { "201": { "description": "Automation folder created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flow-workspace" } } } } } } }, "/flows/api/flow-workspaces/{uuid}": { "put": { "summary": "Update automation folder", "operationId": "updateFlowWorkspace", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "order": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Automation folder updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flow-workspace" } } } } } }, "delete": { "summary": "Delete automation folder", "operationId": "deleteFlowWorkspace", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Automation folder deleted." } } } }, "/flows/api/flows/metrics": { "post": { "summary": "Get automation metrics", "description": "Retrieve performance metrics for one or more automations. Returns contact counts and task breakdowns per automation UUID.\n", "operationId": "getFlowMetrics", "tags": [ "Automations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "description": "List of automation UUIDs.", "items": { "type": "string" } } } }, "example": { "uuids": [ "e0280f7c-c2e9-4aec-a6bc-bc17ef028740" ] } } } }, "responses": { "200": { "description": "Metrics keyed by automation UUID. Each entry contains contact counts and task counts broken down by task type.\n", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "leads_count": { "type": "integer", "description": "Total contacts added to this automation." }, "in_progress_leads_count": { "type": "integer", "description": "Contacts currently in progress." }, "finished_leads_count": { "type": "integer", "description": "Contacts that completed the sequence." }, "failed_leads_count": { "type": "integer", "description": "Contacts that failed." }, "task_counts": { "type": "object", "description": "Task counts keyed by type (e.g. `linkedin_send_connection_request`, `email_send_message`).\n", "additionalProperties": { "type": "integer" } } } } }, "example": { "e0280f7c-c2e9-4aec-a6bc-bc17ef028740": { "leads_count": 150, "in_progress_leads_count": 42, "finished_leads_count": 95, "failed_leads_count": 13, "task_counts": { "linkedin_send_connection_request": 150, "email_send_message": 87 } } } } } } } } }, "/flows/api/flows/{flowUuid}/leads/{leadUuid}": { "post": { "summary": "Add a contact to an automation", "description": "Add an existing contact to an automation. The contact will enter the automation from the beginning of the sequence.\n", "operationId": "addLeadToFlow", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/flowUuid-path" }, { "in": "path", "name": "leadUuid", "required": true, "schema": { "type": "string" }, "description": "Contact UUID." } ], "responses": { "204": { "description": "Contact added." }, "404": { "description": "Automation or contact not found." } } } }, "/flows/api/flows/{flowUuid}/add-new-lead": { "post": { "summary": "Create a contact and add to automation", "description": "Create a new contact and immediately add them to an automation. The contact is created in the specified list and starts the automation sequence. If `skip_if_lead_exists` is true, existing contacts won't be added again.\n", "operationId": "addNewLeadToFlow", "tags": [ "Automations" ], "parameters": [ { "$ref": "#/components/parameters/flowUuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead", "list_uuid" ], "properties": { "lead": { "allOf": [ { "$ref": "#/components/schemas/create-lead-fields" }, { "type": "object", "required": [ "linkedin_id" ] } ] }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Custom field values.", "example": { "field_position": "CTO" } }, "list_uuid": { "type": "string", "description": "List UUID for the new contact." }, "update_lead_if_exists": { "type": "boolean", "default": true }, "move_to_list": { "type": "boolean", "default": false }, "flow_segment_id": { "type": "integer", "default": 1, "description": "Automation segment to enter." }, "skip_if_lead_exists": { "type": "boolean", "description": "Skip if contact already exists." } } }, "example": { "lead": { "linkedin_id": "john-doe-123456", "first_name": "John", "last_name": "Doe", "company_name": "Acme Inc" }, "list_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "skip_if_lead_exists": true } } } }, "responses": { "200": { "description": "Contact skipped (already exists).", "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "example": "skipped" } } } } } }, "204": { "description": "Contact created and added to automation." }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/flows/api/flows/leads/{leadUuid}/cancel": { "put": { "summary": "Cancel contact from specific automations", "description": "Remove a contact from specific automations. The contact's progress in those automations will be cancelled.\n", "operationId": "cancelLeadFromFlows", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "leadUuid", "required": true, "schema": { "type": "string" }, "description": "Contact UUID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "flow_uuids" ], "properties": { "flow_uuids": { "type": "array", "items": { "type": "string" }, "description": "Automation UUIDs to cancel from." } } } } } }, "responses": { "204": { "description": "Contact cancelled from specified automations." }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/flows/api/flows/leads/{leadUuid}/cancel-all": { "put": { "summary": "Cancel contact from all automations", "description": "Remove a contact from all active automations at once.", "operationId": "cancelLeadFromAllFlows", "tags": [ "Automations" ], "parameters": [ { "in": "path", "name": "leadUuid", "required": true, "schema": { "type": "string" }, "description": "Contact UUID." } ], "responses": { "204": { "description": "Contact cancelled from all automations." } } } }, "/flows/api/attachments": { "get": { "summary": "List attachments", "description": "List files uploaded to your team's attachment storage. Attachments can be referenced by UUID when sending LinkedIn messages, emails, or from automation message nodes.\n", "operationId": "listAttachments", "tags": [ "Attachments" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" } ], "responses": { "200": { "description": "Paginated list of attachments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/attachment" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "post": { "summary": "Upload an attachment", "description": "Upload a file (image, PDF, document) to attachment storage. Use `multipart/form-data`. Returns an attachment UUID that can be used in `attachments: [{ \"uuid\": \"...\" }]` when sending LinkedIn messages or emails. Supported types include images (JPG, PNG, GIF), documents (PDF, DOCX), and other common formats.\n", "operationId": "uploadAttachment", "tags": [ "Attachments" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "attachment", "payload" ], "properties": { "attachment": { "type": "string", "format": "binary", "description": "The file to upload." }, "payload": { "type": "object", "required": [ "name", "size", "type" ], "properties": { "name": { "type": "string", "description": "Original filename.", "example": "photo.png" }, "size": { "type": "string", "description": "File size in bytes (as string).", "example": "324274" }, "type": { "type": "string", "description": "MIME type.", "example": "image/png" } } } } } } } }, "responses": { "201": { "description": "Attachment uploaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/attachment" } } } } } } }, "/flows/api/attachments/{uuid}": { "get": { "summary": "Get an attachment", "operationId": "getAttachment", "tags": [ "Attachments" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Attachment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/attachment" } } } }, "404": { "description": "Attachment not found." } } }, "delete": { "summary": "Delete an attachment", "operationId": "deleteAttachment", "tags": [ "Attachments" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Attachment deleted." }, "404": { "description": "Attachment not found." } } } }, "/flows/api/tasks": { "get": { "summary": "List tasks", "description": "Retrieve outreach tasks with filtering. Tasks can be manual (created by you) or automatic (generated by automations). Filter by `automation` = `manual` or `auto`.\n", "operationId": "listTasks", "tags": [ "Tasks" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "automation", "schema": { "type": "string", "enum": [ "manual", "auto" ] }, "description": "Filter by task source." }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "in_progress", "closed", "canceled", "failed", "skipped" ] }, "description": "Filter by task status." }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "linkedin_send_message", "linkedin_send_connection_request", "linkedin_send_inmail", "linkedin_like_latest_post", "linkedin_endorse_skills", "email_send_message", "trigger_linkedin_connection_request_accepted" ] }, "description": "Filter by task type." }, { "in": "query", "name": "lead_uuid", "schema": { "type": "string" }, "description": "Filter by contact UUID." }, { "in": "query", "name": "sender_profile_uuid", "schema": { "type": "string" }, "description": "Filter by sender profile." }, { "in": "query", "name": "schedule_at_before", "schema": { "type": "string", "format": "date-time" }, "description": "Tasks scheduled before this date." }, { "in": "query", "name": "schedule_at_after", "schema": { "type": "string", "format": "date-time" }, "description": "Tasks scheduled after this date." } ], "responses": { "200": { "description": "Paginated list of tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/task" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }, "post": { "summary": "Create a task", "description": "Create a manual outreach task. Common types: `linkedin_send_message`, `linkedin_send_connection_request`, `linkedin_send_inmail`, `linkedin_like_latest_post`, `linkedin_endorse_skills`.\n", "operationId": "createTask", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead_uuid", "sender_profile_uuid", "text", "schedule_at" ], "properties": { "lead_uuid": { "type": "string" }, "sender_profile_uuid": { "type": "string" }, "type": { "type": "string", "default": "linkedin_send_message", "example": "linkedin_send_message" }, "text": { "type": "string", "example": "Hi John, I'd love to connect!" }, "note": { "type": "string" }, "schedule_at": { "type": "string", "format": "date-time", "example": "2026-03-01T10:00:00.000000Z" }, "timezone": { "type": "string", "default": "UTC" } } }, "example": { "lead_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "sender_profile_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "type": "linkedin_send_message", "text": "Hi John, I'd love to connect!", "schedule_at": "2026-03-01T10:00:00.000000Z" } } } }, "responses": { "201": { "description": "Task created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/task" } } } } } } }, "/flows/api/tasks/{uuid}": { "get": { "summary": "Get a task", "description": "Retrieve details of a specific task.", "operationId": "getTask", "tags": [ "Tasks" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Task details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/task" } } } }, "404": { "description": "Task not found." } } } }, "/flows/api/tasks/{uuid}/complete": { "put": { "summary": "Complete a task", "description": "Mark a manual task as completed. Only works for manual tasks.", "operationId": "completeTask", "tags": [ "Tasks" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Task completed." } } } }, "/flows/api/tasks/{uuid}/cancel": { "put": { "summary": "Cancel a task", "description": "Cancel a manual task. Only works for manual tasks.", "operationId": "cancelTask", "tags": [ "Tasks" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Task cancelled." } } } }, "/flows/api/tasks/{uuid}/fail": { "put": { "summary": "Mark a task as failed", "description": "Mark a manual task as failed. Only works for manual tasks.", "operationId": "failTask", "tags": [ "Tasks" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Task marked as failed." } } } }, "/flows/api/tasks/continue-automation": { "put": { "summary": "Continue automation for a contact", "description": "Resume a paused automation for a specific contact. The contact will continue from where they were paused in the automation sequence.\n", "operationId": "continueAutomation", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead_uuid" ], "properties": { "lead_uuid": { "type": "string", "description": "UUID of the contact to resume." } } } } } }, "responses": { "200": { "description": "Automation resumed." }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/flows/api/tasks/schedule": { "get": { "summary": "Get tasks schedule", "description": "Get the tasks schedule for a specific sender profile on a given date. Returns the timeline of scheduled tasks.\n", "operationId": "getTasksSchedule", "tags": [ "Tasks" ], "parameters": [ { "in": "query", "name": "sender_profile_uuid", "required": true, "schema": { "type": "string" }, "description": "UUID of the sender profile." }, { "in": "query", "name": "date", "required": true, "schema": { "type": "string", "format": "date" }, "description": "Date to view schedule for (YYYY-MM-DD).", "example": "2026-04-03" } ], "responses": { "200": { "description": "Schedule overview for the sender on the given date." } } } }, "/flows/api/tasks/mass-cancel": { "put": { "summary": "Mass cancel tasks", "description": "Cancel multiple manual tasks at once. Only works for manual tasks.", "operationId": "massCancelTasks", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "description": "Array of task UUIDs to cancel." } } } } } }, "responses": { "200": { "description": "Tasks cancelled." } } } }, "/flows/api/tasks/mass-complete": { "put": { "summary": "Mass complete tasks", "description": "Mark multiple manual tasks as completed at once.", "operationId": "massCompleteTasks", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "description": "Array of task UUIDs to complete." } } } } } }, "responses": { "200": { "description": "Tasks completed." } } } }, "/flows/api/tasks/mass-retry": { "put": { "summary": "Mass retry tasks", "description": "Retry multiple failed manual tasks at once.", "operationId": "massRetryTasks", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "description": "Array of task UUIDs to retry." } } } } } }, "responses": { "200": { "description": "Tasks retried." } } } }, "/flows/api/tasks/mass-skip": { "put": { "summary": "Mass skip tasks", "description": "Skip multiple manual tasks at once.", "operationId": "massSkipTasks", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuids" ], "properties": { "uuids": { "type": "array", "items": { "type": "string" }, "description": "Array of task UUIDs to skip." } } } } } }, "responses": { "200": { "description": "Tasks skipped." } } } }, "/flows/api/sender-profiles": { "get": { "summary": "List sender profiles", "description": "Retrieve all sender profiles. A sender profile represents a person (with linked LinkedIn account and/or email mailbox) who sends outreach messages.\n", "operationId": "listSenderProfiles", "tags": [ "Sender Profiles" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "filter", "schema": { "type": "object", "properties": { "q": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/mixed-filter-type" } } }, "description": "Filters." } ], "responses": { "200": { "description": "Paginated list of sender profiles.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/sender-profile" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "post": { "summary": "Create a sender profile", "description": "Create a new sender profile with a name and optional label.", "operationId": "createSenderProfile", "tags": [ "Sender Profiles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "first_name", "last_name" ], "properties": { "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "label": { "type": "string", "example": "Sales Team - US" }, "assignee_user_id": { "type": "integer" } } }, "example": { "first_name": "John", "last_name": "Doe", "label": "Sales Team - US" } } } }, "responses": { "201": { "description": "Sender profile created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sender-profile" } } } } } } }, "/flows/api/sender-profiles/{uuid}": { "get": { "summary": "Get a sender profile", "description": "Retrieve details of a sender profile.", "operationId": "getSenderProfile", "tags": [ "Sender Profiles" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Sender profile details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sender-profile" } } } }, "404": { "description": "Not found." } } }, "put": { "summary": "Update a sender profile", "description": "Update a sender profile's name, label, or schedule.", "operationId": "updateSenderProfile", "tags": [ "Sender Profiles" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "label": { "type": "string" }, "schedule": { "type": "object" } } } } } }, "responses": { "200": { "description": "Updated sender profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/sender-profile" } } } } } }, "delete": { "summary": "Delete a sender profile", "description": "Permanently delete a sender profile.", "operationId": "deleteSenderProfile", "tags": [ "Sender Profiles" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Deleted." } } } }, "/flows/api/sender-profiles/{uuid}/enable": { "put": { "summary": "Enable a sender profile", "description": "Enable a sender profile so it can be used in automations.", "operationId": "enableSenderProfile", "tags": [ "Sender Profiles" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Enabled." } } } }, "/flows/api/sender-profiles/{uuid}/disable": { "put": { "summary": "Disable a sender profile", "description": "Disable a sender profile. It will no longer be used in automations.", "operationId": "disableSenderProfile", "tags": [ "Sender Profiles" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Disabled." } } } }, "/flows/api/linkedin-messages": { "get": { "summary": "List LinkedIn messages", "description": "Retrieve LinkedIn messages from your unified inbox. Filter by contact, sender profile, conversation, message type (inbox/outbox), and status.\n", "operationId": "listLinkedinMessages", "tags": [ "LinkedIn Messages" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "filter", "style": "deepObject", "explode": true, "schema": { "type": "object", "properties": { "q": { "type": "string", "nullable": true }, "lead_uuid": { "$ref": "#/components/schemas/mixed-filter-type" }, "sender_profile_uuid": { "$ref": "#/components/schemas/mixed-filter-type" }, "type": { "$ref": "#/components/schemas/mixed-filter-type" }, "status": { "$ref": "#/components/schemas/mixed-filter-type" } } } } ], "responses": { "200": { "description": "Paginated list of messages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/linkedin-message" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } } } }, "post": { "summary": "Send a LinkedIn message", "description": "Send a LinkedIn message to a contact through a sender profile. The message will be queued and sent via the linked LinkedIn account.\n", "operationId": "sendLinkedInMessage", "tags": [ "LinkedIn Messages" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sender_profile_uuid", "lead_uuid", "text" ], "properties": { "sender_profile_uuid": { "type": "string" }, "lead_uuid": { "type": "string" }, "text": { "type": "string", "example": "Hi John, thanks for connecting!" }, "template_uuid": { "type": "string", "description": "Optional AI template UUID." }, "attachments": { "type": "array", "description": "Files to attach to the message. Upload files first via `POST /flows/api/attachments`, then pass an array of `{ \"uuid\": \"...\" }` references here.\n", "items": { "$ref": "#/components/schemas/attachment-ref" } } } }, "example": { "sender_profile_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "lead_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "text": "Hi John, here's the deck we discussed.", "attachments": [ { "uuid": "e94a3b39-1242-4d70-8703-8b600d8960d6" } ] } } } }, "responses": { "201": { "description": "Message queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linkedin-message" } } } } } } }, "/flows/api/linkedin-messages/{uuid}": { "delete": { "summary": "Delete a LinkedIn message", "description": "Delete a LinkedIn message record.", "operationId": "deleteLinkedinMessage", "tags": [ "LinkedIn Messages" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Deleted." } } } }, "/flows/api/linkedin-messages/{uuid}/retry": { "put": { "summary": "Retry a failed LinkedIn message", "description": "Retry sending a LinkedIn message that previously failed.", "operationId": "retryLinkedinMessage", "tags": [ "LinkedIn Messages" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Message retry initiated." }, "404": { "description": "Message not found." } } } }, "/emails/api/emails": { "get": { "summary": "List emails", "description": "Retrieve emails from your unified inbox. Filter by contact, sender profile, mailbox, type (inbox/outbox), status, and date range.\n", "operationId": "listEmails", "tags": [ "Emails" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "filter", "schema": { "type": "object", "properties": { "q": { "type": "string", "nullable": true }, "lead_uuid": { "$ref": "#/components/schemas/mixed-filter-type" }, "sender_profile_uuid": { "$ref": "#/components/schemas/mixed-filter-type" }, "mailbox_uuid": { "$ref": "#/components/schemas/mixed-filter-type" }, "type": { "$ref": "#/components/schemas/mixed-filter-type" }, "status": { "$ref": "#/components/schemas/mixed-filter-type" } } } } ], "responses": { "200": { "description": "List of emails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/email" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } } } } } }, "/emails/api/emails/{uuid}": { "get": { "summary": "Get an email", "description": "Retrieve full details of an email by UUID.", "operationId": "getEmail", "tags": [ "Emails" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Email details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email" } } } }, "404": { "description": "Email not found." } } }, "delete": { "summary": "Delete an email", "description": "Delete an email record.", "operationId": "deleteEmail", "tags": [ "Emails" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Deleted." } } } }, "/emails/api/emails/send-email": { "post": { "summary": "Send an email", "description": "Send a new email to a contact through a connected mailbox.\n", "operationId": "sendEmail", "tags": [ "Emails" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sender_profile_uuid", "lead_uuid", "from_name", "from_email", "to_name", "to_email", "subject" ], "properties": { "sender_profile_uuid": { "type": "string", "format": "uuid" }, "lead_uuid": { "type": "string", "format": "uuid" }, "from_name": { "type": "string", "example": "John Doe" }, "from_email": { "type": "string", "example": "john@company.com" }, "to_name": { "type": "string", "example": "Jane Smith" }, "to_email": { "type": "string", "example": "jane@acme.com" }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string", "example": "Quick question about your outreach stack" }, "body": { "type": "string", "description": "Email body (HTML supported)." }, "attachments": { "type": "array", "description": "Files to attach to the email. Upload files first via `POST /flows/api/attachments`, then pass an array of `{ \"uuid\": \"...\" }` references here.\n", "items": { "$ref": "#/components/schemas/attachment-ref" } } } }, "example": { "sender_profile_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "lead_uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "from_name": "John Doe", "from_email": "john@company.com", "to_name": "Jane Smith", "to_email": "jane@acme.com", "subject": "Quick question about your outreach stack", "body": "

Hi Jane, attached is our deck.

", "attachments": [ { "uuid": "e94a3b39-1242-4d70-8703-8b600d8960d6" } ] } } } }, "responses": { "201": { "description": "Email sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailDomain": { "$ref": "#/components/schemas/email" }, "emailBodyDomain": { "$ref": "#/components/schemas/email-body" } } } } } } } } }, "/emails/api/mailboxes": { "get": { "summary": "List mailboxes", "description": "Retrieve all email mailboxes (SMTP/IMAP, Gmail, Outlook) configured in your account.\n", "operationId": "listMailboxes", "tags": [ "Mailboxes" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "filter", "schema": { "type": "object", "properties": { "q": { "type": "string" } } } } ], "responses": { "200": { "description": "List of mailboxes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/mailbox" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }, "post": { "summary": "Create a mailbox", "description": "Add a new SMTP/IMAP mailbox with connection settings.\n", "operationId": "createMailbox", "tags": [ "Mailboxes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "sender_name", "sender_profile_uuid" ], "properties": { "email": { "type": "string", "example": "outreach@company.com" }, "sender_name": { "type": "string", "example": "John from Company" }, "sender_profile_uuid": { "type": "string" }, "provider": { "type": "string" }, "connection_settings": { "type": "object", "properties": { "smtp_host": { "type": "string" }, "smtp_port": { "type": "integer" }, "smtp_username": { "type": "string" }, "smtp_password": { "type": "string" }, "imap_host": { "type": "string" }, "imap_port": { "type": "integer" }, "imap_username": { "type": "string" }, "imap_password": { "type": "string" } } }, "automation_daily_limit": { "type": "integer", "example": 50 }, "automation_task_interval": { "type": "integer", "example": 120 } } } } } }, "responses": { "201": { "description": "Mailbox created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mailbox" } } } } } } }, "/emails/api/mailboxes/{uuid}": { "get": { "summary": "Get a mailbox", "description": "Retrieve details of a specific mailbox.", "operationId": "getMailbox", "tags": [ "Mailboxes" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Mailbox details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mailbox" } } } }, "404": { "description": "Not found." } } }, "put": { "summary": "Update a mailbox", "description": "Update mailbox settings such as sender name, daily limits, or connection details.", "operationId": "updateMailbox", "tags": [ "Mailboxes" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sender_name": { "type": "string" }, "automation_daily_limit": { "type": "integer" }, "automation_task_interval": { "type": "integer" }, "connection_settings": { "type": "object" }, "custom_tracking_domain_uuid": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated mailbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mailbox" } } } } } }, "delete": { "summary": "Delete a mailbox", "description": "Delete a mailbox. Optionally reassign automations to another mailbox.\n", "operationId": "deleteMailbox", "tags": [ "Mailboxes" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "automation_reassign_mailboxes" ], "properties": { "automation_reassign_mailboxes": { "type": "boolean" }, "automation_mailbox_to_reassign": { "type": "string" } } } } } }, "responses": { "204": { "description": "Deleted." } } } }, "/emails/api/mailboxes/{uuid}/activate": { "put": { "summary": "Activate a mailbox", "description": "Enable a mailbox so it can send and sync emails.", "operationId": "activateMailbox", "tags": [ "Mailboxes" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Activated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mailbox" } } } } } } }, "/emails/api/mailboxes/{uuid}/deactivate": { "put": { "summary": "Deactivate a mailbox", "description": "Disable a mailbox. It will stop sending and syncing emails.", "operationId": "deactivateMailbox", "tags": [ "Mailboxes" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mailbox" } } } } } } }, "/emails/api/email-bodies": { "get": { "summary": "List email bodies", "description": "List email body records (HTML content, subject, attachments).", "operationId": "listEmailBodies", "tags": [ "Emails" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search email bodies." } ], "responses": { "200": { "description": "List of email bodies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/email-body" } } } } } } } } } }, "/emails/api/email-bodies/{uuid}": { "get": { "summary": "Get an email body", "description": "Get the HTML content, subject, and attachments of an email body.", "operationId": "getEmailBody", "tags": [ "Emails" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Email body details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/email-body" } } } }, "404": { "description": "Not found." } } } }, "/emails/api/emails/{uuid}/thread": { "get": { "summary": "Get email thread", "description": "Get the conversation thread for a reply email.", "operationId": "getEmailThread", "tags": [ "Emails" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Email thread content." } } } }, "/emails/api/emails/latest-by-leads": { "post": { "summary": "Get latest emails by leads", "description": "Get the most recent email for each of the specified contact UUIDs.", "operationId": "getLatestEmailsByLeads", "tags": [ "Emails" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lead_uuids" ], "properties": { "lead_uuids": { "type": "array", "items": { "type": "string" }, "description": "Array of contact UUIDs." } } } } } }, "responses": { "200": { "description": "Latest email per contact." } } } }, "/emails/api/emails/llm-thread": { "post": { "summary": "Get email thread for LLM", "description": "Get an email conversation thread formatted for LLM processing. Optimized for AI analysis and response generation.\n", "operationId": "getEmailLLMThread", "tags": [ "Emails" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sender_profile_uuid", "lead_uuid", "lead_name" ], "properties": { "sender_profile_uuid": { "type": "string" }, "lead_uuid": { "type": "string" }, "lead_name": { "type": "string", "description": "Name of the contact (for personalization)." }, "limit": { "type": "string" }, "sent_at_recency_in_days": { "type": "integer" } } } } } }, "responses": { "200": { "description": "LLM-formatted email thread." } } } }, "/emails/api/mailbox-errors": { "get": { "summary": "List mailbox errors", "description": "List mailbox send/sync errors for debugging. Shows errors with timestamps and details.\n", "operationId": "listMailboxErrors", "tags": [ "Mailboxes" ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/order-field" }, { "$ref": "#/components/parameters/order-type" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search errors." } ], "responses": { "200": { "description": "List of mailbox errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/mailbox-error" } } } } } } } } } }, "/browsers/api/linkedin-browsers/list": { "post": { "summary": "List LinkedIn browsers", "description": "List all LinkedIn browser profiles with pagination.", "operationId": "listLinkedInBrowsers", "tags": [ "LinkedIn Browsers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "default": 20, "example": 20 }, "offset": { "type": "integer", "default": 0, "example": 0 }, "order_field": { "type": "string", "default": "created_at", "example": "created_at" }, "order_type": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "example": "asc" } } } } } }, "responses": { "200": { "description": "Paginated list of LinkedIn browsers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/linkedin-browser" } }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 5 }, "has_more": { "type": "boolean" } } } } } } } } }, "/browsers/api/linkedin-browsers/{id}": { "get": { "summary": "Get a LinkedIn browser", "operationId": "getLinkedInBrowser", "tags": [ "LinkedIn Browsers" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "LinkedIn browser ID." } ], "responses": { "200": { "description": "LinkedIn browser details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linkedin-browser" } } } }, "404": { "description": "LinkedIn browser not found." } } }, "put": { "summary": "Update a LinkedIn browser", "operationId": "updateLinkedInBrowser", "tags": [ "LinkedIn Browsers" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "LinkedIn browser ID." } ], "responses": { "200": { "description": "LinkedIn browser updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linkedin-browser" } } } } } }, "delete": { "summary": "Delete a LinkedIn browser", "operationId": "deleteLinkedInBrowser", "tags": [ "LinkedIn Browsers" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "LinkedIn browser ID." } ], "responses": { "204": { "description": "LinkedIn browser deleted." } } } }, "/browsers/api/linkedin-browsers": { "post": { "summary": "Create a LinkedIn browser", "operationId": "createLinkedInBrowser", "tags": [ "LinkedIn Browsers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sender_profile_uuid" ], "properties": { "sender_profile_uuid": { "type": "string", "description": "UUID of the sender profile to link." }, "proxy_country_code": { "type": "string", "description": "Proxy country code (e.g., US, DE).", "example": "US" } } } } } }, "responses": { "201": { "description": "LinkedIn browser created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/linkedin-browser" } } } } } } }, "/browsers/api/linkedin-browsers/{id}/run": { "post": { "summary": "Start a browser session", "description": "Start the LinkedIn browser session. The browser will begin executing queued actions.", "operationId": "runLinkedInBrowser", "tags": [ "LinkedIn Browsers" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "LinkedIn browser ID." } ], "responses": { "204": { "description": "Browser session started." } } } }, "/browsers/api/linkedin-browsers/{id}/stop": { "post": { "summary": "Stop a browser session", "operationId": "stopLinkedInBrowser", "tags": [ "LinkedIn Browsers" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "LinkedIn browser ID." } ], "responses": { "204": { "description": "Browser session stopped." } } } }, "/browsers/api/linkedin-browsers/{id}/set-proxy": { "post": { "summary": "Set browser proxy", "description": "Change the proxy configuration for a LinkedIn browser.", "operationId": "setLinkedInBrowserProxy", "tags": [ "LinkedIn Browsers" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "LinkedIn browser ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proxy_country_code": { "type": "string", "example": "DE" } } } } } }, "responses": { "200": { "description": "Proxy configuration updated." } } } }, "/browsers/api/linkedin-browsers/{id}/share": { "post": { "summary": "Share browser profile", "description": "Share a LinkedIn browser profile with another team member.", "operationId": "shareLinkedInBrowser", "tags": [ "LinkedIn Browsers" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "LinkedIn browser ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipients" ], "properties": { "recipients": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Email addresses of team members to share with.", "example": [ "colleague@example.com" ] } } } } } }, "responses": { "200": { "description": "Browser profile shared." } } } }, "/integrations/api/webhooks": { "get": { "summary": "List webhooks", "description": "List all webhooks configured in your account. Webhooks send HTTP requests to your target URL when specified events occur.\n", "operationId": "listWebhooks", "tags": [ "Webhooks" ], "responses": { "200": { "description": "List of webhooks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/webhook" } }, "limit": { "type": "integer", "example": 20 }, "offset": { "type": "integer", "example": 0 }, "total": { "type": "integer", "example": 3 }, "has_more": { "type": "boolean" } } } } } } } }, "post": { "summary": "Create a webhook", "description": "Create a new webhook that fires on the specified event. Optionally add filters to narrow which contacts trigger the webhook.\n", "operationId": "createWebhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "event", "target_url" ], "properties": { "name": { "type": "string", "description": "Human-readable label.", "example": "New Reply Handler" }, "event": { "type": "string", "description": "Event that triggers the webhook. Supported events: `contact_replied_email`, `contact_replied_linkedin_message`, `contact_exported`, `contact_enriched`.\n", "enum": [ "contact_replied_email", "contact_replied_linkedin_message", "contact_exported", "contact_enriched" ], "example": "contact_replied_linkedin_message" }, "request_method": { "type": "string", "description": "HTTP method for the outgoing request.", "enum": [ "POST", "GET", "PUT", "PATCH", "DELETE" ], "default": "POST", "example": "POST" }, "target_url": { "type": "string", "format": "uri", "description": "URL that will receive the webhook payload.", "example": "https://hook.eu2.make.com/abc123" }, "filters": { "type": "object", "nullable": true, "description": "Optional filter object to narrow which contacts trigger the webhook. Uses a tree-based filter format with `jsonLogic` and `filter_tree_format` keys.\n" }, "status": { "type": "string", "enum": [ "on", "off" ], "default": "on" } } }, "example": { "name": "New Reply Handler", "event": "contact_replied_linkedin_message", "request_method": "POST", "target_url": "https://hook.eu2.make.com/abc123", "status": "on" } } } }, "responses": { "201": { "description": "Webhook created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } }, "/integrations/api/webhooks/{uuid}": { "get": { "summary": "Get a webhook", "description": "Retrieve full details of a webhook by UUID.", "operationId": "getWebhook", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "200": { "description": "Webhook details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" } } } }, "404": { "description": "Webhook not found." } } }, "put": { "summary": "Update a webhook", "description": "Update one or more fields on an existing webhook. Only include the fields you want to change.\n", "operationId": "updateWebhook", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "event": { "type": "string", "enum": [ "contact_replied_email", "contact_replied_linkedin_message", "contact_exported", "contact_enriched" ] }, "request_method": { "type": "string", "enum": [ "POST", "GET", "PUT", "PATCH", "DELETE" ] }, "target_url": { "type": "string", "format": "uri" }, "filters": { "type": "object", "nullable": true }, "status": { "type": "string", "enum": [ "on", "off" ] } } } } } }, "responses": { "200": { "description": "Webhook updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" } } } }, "404": { "description": "Webhook not found." }, "422": { "description": "Validation error." } } }, "delete": { "summary": "Delete a webhook", "description": "Permanently remove a webhook.", "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/uuid-path" } ], "responses": { "204": { "description": "Webhook deleted." }, "404": { "description": "Webhook not found." } } } }, "/integrations/api/webhooks/test": { "post": { "summary": "Test a webhook", "description": "Send a test payload to a webhook's target URL to verify connectivity and response handling.\n", "operationId": "testWebhook", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "uuid" ], "properties": { "uuid": { "type": "string", "description": "UUID of the webhook to test." } } }, "example": { "uuid": "b27f3cfc-84a0-4fb8-956b-91d032f9c523" } } } }, "responses": { "200": { "description": "Test payload sent. Returns the target response." }, "404": { "description": "Webhook not found." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "API key from [Settings -> API Keys](https://leadgen.grinfi.io/settings/api-keys).\n" } }, "schemas": { "error": { "type": "object", "description": "Error response envelope. Validation errors include field-level details in `error.data`.\n", "properties": { "error": { "type": "object", "properties": { "reason": { "type": "string", "description": "Machine-readable error code: `validation_error`, `bad_request`, `auth_exception`, `access_denied`, `payment_required`.\n", "example": "validation_error" }, "message": { "type": "string", "example": "The name field is required." }, "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field-level validation errors (field name → messages)." } } }, "message": { "type": "string", "example": "The given data was invalid." }, "code": { "type": "integer", "example": 422 } } }, "lead": { "type": "object", "description": "A contact (lead) in your CRM.", "properties": { "uuid": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer", "nullable": true }, "sender_profile_uuid": { "type": "string", "nullable": true }, "list_uuid": { "type": "string" }, "data_source_uuid": { "type": "string", "nullable": true }, "pipeline_stage_uuid": { "type": "string" }, "company_uuid": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true, "example": "John Doe" }, "first_name": { "type": "string", "nullable": true, "example": "John" }, "last_name": { "type": "string", "nullable": true, "example": "Doe" }, "company_name": { "type": "string", "nullable": true, "example": "Acme Inc" }, "company_ln_id": { "type": "string", "nullable": true }, "position": { "type": "string", "nullable": true, "example": "VP of Sales" }, "headline": { "type": "string", "nullable": true, "example": "VP of Sales at Acme Inc" }, "about": { "type": "string", "nullable": true }, "avatar_url": { "type": "string", "nullable": true }, "ln_id": { "type": "string", "nullable": true, "description": "LinkedIn member ID." }, "sn_id": { "type": "string", "nullable": true, "description": "Sales Navigator ID." }, "linkedin": { "type": "string", "nullable": true, "example": "john-doe-123456" }, "facebook": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true }, "work_email": { "type": "string", "nullable": true, "example": "john@acme.com" }, "personal_email": { "type": "string", "nullable": true }, "work_phone_number": { "type": "string", "nullable": true }, "personal_phone_number": { "type": "string", "nullable": true }, "connections_number": { "type": "integer", "nullable": true }, "followers_number": { "type": "integer", "nullable": true }, "primary_language": { "type": "string", "nullable": true }, "supported_languages": { "type": "array", "nullable": true, "items": { "type": "string" } }, "has_open_profile": { "type": "integer", "nullable": true }, "has_verified_profile": { "type": "integer", "nullable": true }, "has_premium": { "type": "integer", "nullable": true }, "experience": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "title": { "type": "string" }, "company": { "type": "string" }, "start_date": { "type": "string" }, "end_date": { "type": "string" } } } }, "posts": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "content": { "type": "string" }, "date": { "type": "string", "format": "date-time" } } } }, "educations": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "school": { "type": "string" }, "degree": { "type": "string" }, "field_of_study": { "type": "string" }, "start_year": { "type": "string" }, "end_year": { "type": "string" } } } }, "skills": { "type": "array", "nullable": true, "items": { "type": "string" } }, "raw_address": { "type": "string", "nullable": true, "example": "San Francisco, CA, USA" }, "location": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "address_string": { "type": "string" } } } }, "tags": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Tag UUIDs." }, "status": { "type": "string", "example": "ok" }, "linkedin_status": { "type": "string", "example": "active" }, "email_status": { "type": "string", "nullable": true }, "unread_counts": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "count": { "type": "integer" } } } }, "last_automation_approve_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "create-lead-fields": { "type": "object", "properties": { "linkedin_id": { "type": "string", "description": "LinkedIn profile URL or member ID.", "example": "john-doe-123456" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "company_name": { "type": "string", "example": "Acme Inc" }, "ln_id": { "type": "string", "nullable": true }, "sn_id": { "type": "string", "nullable": true }, "linkedin": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "example": "john@acme.com" }, "about": { "type": "string" }, "domain": { "type": "string", "description": "Company domain for email discovery.", "example": "acme.com" }, "headline": { "type": "string", "nullable": true }, "position": { "type": "string", "nullable": true }, "raw_address": { "type": "string", "nullable": true } } }, "company": { "type": "object", "description": "A company record in your CRM.", "properties": { "uuid": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer", "nullable": true }, "data_source_uuid": { "type": "string", "nullable": true }, "lead_status_uuid": { "type": "string", "nullable": true, "description": "Pipeline stage UUID." }, "name": { "type": "string", "example": "Acme Inc" }, "domain": { "type": "string", "nullable": true, "example": "acme.com" }, "website": { "type": "string", "nullable": true, "example": "https://acme.com" }, "ln_id": { "type": "integer", "nullable": true, "description": "LinkedIn company numeric ID." }, "linkedin": { "type": "string", "nullable": true, "example": "acme-inc" }, "facebook": { "type": "string", "nullable": true }, "twitter": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "hq_raw_address": { "type": "string", "nullable": true, "example": "San Francisco, CA, USA" }, "hq_location": { "type": "array", "nullable": true, "items": { "type": "object" } }, "logo_url": { "type": "string", "nullable": true }, "industry": { "type": "string", "nullable": true, "example": "Technology" }, "employees_range": { "type": "string", "nullable": true, "example": "51-200" }, "year_established": { "type": "integer", "nullable": true, "example": 2015 }, "about": { "type": "string", "nullable": true }, "lists": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "List UUIDs." }, "tags": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Tag UUIDs." }, "status": { "type": "string" }, "last_enrich_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "tag": { "type": "object", "properties": { "uuid": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "team_id": { "type": "integer" }, "name": { "type": "string", "example": "Hot Lead" }, "color": { "type": "string", "nullable": true, "example": "#ff5733" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "pipeline-stage": { "type": "object", "properties": { "uuid": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "team_id": { "type": "integer" }, "name": { "type": "string", "example": "Demo Booked" }, "object": { "type": "string", "enum": [ "lead", "company" ] }, "type": { "type": "string", "enum": [ "custom", "new", "approaching", "engaging", "replied" ] }, "category": { "type": "string", "enum": [ "cold", "engaging", "positive", "negative" ] }, "order": { "type": "integer" } } }, "custom-field": { "type": "object", "properties": { "uuid": { "type": "string" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "name": { "type": "string", "example": "Industry Vertical" }, "object": { "type": "string", "enum": [ "lead", "company" ] }, "order": { "type": "integer" } } }, "custom-field-value": { "type": "object", "properties": { "uuid": { "type": "string" }, "team_id": { "type": "integer" }, "custom_field_uuid": { "type": "string" }, "object_type": { "type": "string", "enum": [ "lead", "company" ] }, "object_uuid": { "type": "string" }, "value": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "note": { "type": "object", "properties": { "uuid": { "type": "string" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "object": { "type": "string", "enum": [ "lead", "company" ] }, "object_uuid": { "type": "string" }, "note": { "type": "string", "example": "Follow up after demo next week." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "list": { "type": "object", "properties": { "uuid": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "team_id": { "type": "integer" }, "name": { "type": "string", "example": "CMO Germany" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "flow": { "type": "object", "properties": { "uuid": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "public_uuid": { "type": "string", "nullable": true }, "team_id": { "type": "integer" }, "name": { "type": "string", "example": "DACH CTO Outreach" }, "flow_workspace_uuid": { "type": "string", "nullable": true }, "flow_version_uuid": { "type": "string" }, "use_sender_schedule": { "type": "boolean", "description": "When `true`, tasks use each sender profile's own schedule instead of the flow schedule." }, "schedule": { "$ref": "#/components/schemas/schedule" }, "description": { "type": "string", "nullable": true }, "priority": { "type": "integer" }, "status": { "type": "string", "description": "Flow status.", "enum": [ "on", "off", "draft", "archived" ], "example": "on" }, "is_public": { "type": "boolean" }, "user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "schedule": { "type": "object", "description": "Working hours schedule.", "properties": { "timezone": { "type": "string", "example": "Europe/Berlin" }, "use_lead_timezone": { "type": "boolean", "default": false }, "timeblocks": { "type": "array", "items": { "type": "object", "properties": { "dow": { "type": "integer", "description": "Day of week (0=Sunday)." }, "min": { "type": "integer", "description": "Start time in minutes from midnight.", "example": 540 }, "max": { "type": "integer", "description": "End time in minutes from midnight.", "example": 1080 } } } } }, "required": [ "timezone", "timeblocks" ] }, "task": { "type": "object", "properties": { "uuid": { "type": "string" }, "parent_task_pipeline_uuid": { "type": "string", "nullable": true, "description": "UUID of the parent task (for chained tasks)." }, "team_id": { "type": "integer" }, "assigned_to": { "type": "integer", "description": "User ID the task is assigned to." }, "user_id": { "type": "integer" }, "lead_uuid": { "type": "string" }, "company_uuid": { "type": "string", "nullable": true }, "sender_profile_uuid": { "type": "string" }, "mailbox_uuid": { "type": "string", "nullable": true }, "flow_uuid": { "type": "string", "nullable": true }, "flow_lead_uuid": { "type": "string", "nullable": true, "description": "UUID of the flow-lead record linking this contact to the automation." }, "flow_origin": { "type": "string", "description": "`automation` when created by a flow.", "example": "automation" }, "flow_node_id": { "type": "integer", "nullable": true, "description": "Node index within the automation that generated this task." }, "type": { "type": "string", "description": "Task type. Known values: `linkedin_send_message`, `linkedin_send_connection_request`, `email_send_message`.\n", "example": "linkedin_send_message" }, "automation": { "type": "string", "enum": [ "manual", "auto" ] }, "automation_error_code": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "in_progress", "closed", "canceled", "failed", "skipped" ] }, "fork_result": { "type": "integer", "nullable": true }, "payload": { "type": "object", "nullable": true, "description": "Task-specific data. For message tasks includes `template`, `rendered_text`, `attachments`, `stop_on_reply_level`, `last_message_at`.\n", "properties": { "template": { "type": "string", "nullable": true, "description": "Message template with variables." }, "rendered_text": { "type": "string", "nullable": true, "description": "Final message text after variable substitution." }, "attachments": { "type": "array", "nullable": true, "items": { "type": "object" } }, "stop_on_reply_level": { "type": "string", "nullable": true, "description": "When to stop the sequence on reply.", "example": "always" }, "last_message_at": { "type": "string", "format": "date-time", "nullable": true } } }, "attempts": { "type": "integer", "description": "Number of execution attempts." }, "error_msg": { "type": "string", "nullable": true, "description": "Error or skip reason." }, "priority": { "type": "integer", "description": "Task priority (lower = higher priority)." }, "number_in_line": { "type": "integer", "nullable": true }, "note": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "schedule_at": { "type": "string", "format": "date-time" }, "executed_at": { "type": "string", "format": "date-time", "nullable": true }, "taken_to_execute_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "sender-profile": { "type": "object", "properties": { "uuid": { "type": "string", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "team_id": { "type": "integer" }, "linkedin_browser_id": { "type": "integer", "nullable": true, "description": "ID of the linked LinkedIn browser." }, "linkedin_account_uuid": { "type": "string", "nullable": true }, "mailbox_uuid": { "type": "string", "nullable": true }, "assignee_user_id": { "type": "integer", "nullable": true }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "label": { "type": "string", "nullable": true, "example": "Sales Team - US" }, "avatar_url": { "type": "string", "nullable": true, "description": "Profile photo URL." }, "schedule": { "$ref": "#/components/schemas/schedule" }, "smart_limits_enabled": { "type": "boolean", "description": "Whether smart sending limits are active." }, "status": { "type": "string", "description": "Sender profile status.", "enum": [ "enabled", "disabled" ], "example": "enabled" }, "hold_tasks_till": { "type": "string", "format": "date-time", "nullable": true, "description": "Tasks are held until this time (set automatically during execution)." }, "last_automation_server_id": { "type": "integer", "nullable": true }, "notification_emails": { "type": "string", "nullable": true }, "user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "attachment": { "type": "object", "description": "A file uploaded to your team's attachment storage. Reference by UUID in the `attachments` array when sending LinkedIn messages or emails.\n", "properties": { "uuid": { "type": "string", "description": "Attachment UUID." }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "payload": { "type": "object", "properties": { "name": { "type": "string", "description": "Original filename.", "example": "photo.png" }, "path": { "type": "string", "description": "Internal storage path.", "example": "attachments/134/1ab98d82-cc1a-451b-918e-5b9c026a9d85.png" }, "size": { "type": "string", "description": "File size in bytes (as string).", "example": "324274" }, "type": { "type": "string", "description": "MIME type.", "example": "image/png" } } }, "body": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "attachment-ref": { "type": "object", "description": "Reference to an uploaded attachment by UUID.", "required": [ "uuid" ], "properties": { "uuid": { "type": "string", "description": "UUID returned from `POST /flows/api/attachments`.", "example": "e94a3b39-1242-4d70-8703-8b600d8960d6" } } }, "linkedin-message": { "type": "object", "properties": { "uuid": { "type": "string" }, "team_id": { "type": "integer" }, "sender_profile_uuid": { "type": "string" }, "linkedin_account_uuid": { "type": "string" }, "linkedin_conversation_uuid": { "type": "string" }, "lead_uuid": { "type": "string" }, "task_pipeline_uuid": { "type": "string", "nullable": true }, "template_uuid": { "type": "string", "nullable": true }, "message_hash": { "type": "string", "nullable": true }, "subject": { "type": "string", "nullable": true }, "text": { "type": "string", "example": "Hi John, thanks for connecting!" }, "custom_content": { "type": "array", "nullable": true }, "attachments": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/attachment-ref" } }, "type": { "type": "string", "description": "Message direction.", "enum": [ "inbox", "outbox" ], "example": "outbox" }, "automation": { "type": "string", "description": "Message origin: `auto` (sent by automation), `manual` (sent by user), `synced` (incoming message synced from LinkedIn).\n", "enum": [ "auto", "manual", "synced" ] }, "linkedin_type": { "type": "string", "description": "LinkedIn message type.", "enum": [ "connection_note", "message", "InMail" ], "example": "message" }, "status": { "type": "string", "enum": [ "new", "in_progress", "done", "failed" ], "example": "done" }, "fail_reason": { "type": "string", "nullable": true }, "read_at": { "type": "string", "format": "date-time", "nullable": true }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "email": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "sender_profile_uuid": { "type": "string", "format": "uuid" }, "mailbox_uuid": { "type": "string", "format": "uuid" }, "email_body_uuid": { "type": "string", "format": "uuid" }, "flow_uuid": { "type": "string", "format": "uuid", "nullable": true }, "lead_uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "type": { "type": "string", "description": "Message direction.", "enum": [ "inbox", "outbox" ] }, "from_name": { "type": "string" }, "from_email": { "type": "string" }, "to_name": { "type": "string" }, "to_email": { "type": "string" }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "replied_to_uuid": { "type": "string", "format": "uuid", "nullable": true }, "bounced_by_uuid": { "type": "string", "format": "uuid", "nullable": true }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "email-body": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "team_id": { "type": "integer" }, "body": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object" } }, "subject": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "mailbox": { "type": "object", "properties": { "uuid": { "type": "string" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "sender_profile_uuid": { "type": "string" }, "email": { "type": "string", "example": "outreach@company.com" }, "sender_name": { "type": "string", "example": "John from Company" }, "provider": { "type": "string" }, "status": { "type": "string" }, "automation_daily_limit": { "type": "integer", "example": 50 }, "automation_task_interval": { "type": "integer", "example": 120 }, "custom_tracking_domain_uuid": { "type": "string", "nullable": true }, "connection_settings": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "activity": { "type": "object", "description": "An activity record tracking an event on a contact or company.", "properties": { "uuid": { "type": "string" }, "team_id": { "type": "integer" }, "object_type": { "type": "string", "enum": [ "lead", "company" ] }, "object_uuid": { "type": "string" }, "type": { "type": "string", "example": "linkedin_message_sent" }, "payload": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "mailbox-error": { "type": "object", "description": "A mailbox send/sync error record.", "properties": { "uuid": { "type": "string" }, "team_id": { "type": "integer" }, "mailbox_uuid": { "type": "string" }, "error_type": { "type": "string" }, "message": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "webhook": { "type": "object", "description": "A webhook configuration.", "properties": { "uuid": { "type": "string", "example": "b27f3cfc-84a0-4fb8-956b-91d032f9c523" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "name": { "type": "string", "example": "New Reply Handler" }, "event": { "type": "string", "description": "Event that triggers the webhook. Supported events: `contact_replied_email`, `contact_replied_linkedin_message`, `contact_exported`, `contact_enriched`.\n", "enum": [ "contact_replied_email", "contact_replied_linkedin_message", "contact_exported", "contact_enriched" ], "example": "contact_replied_linkedin_message" }, "request_method": { "type": "string", "description": "HTTP method for the outgoing request.", "example": "POST" }, "target_url": { "type": "string", "format": "uri", "example": "https://hook.eu2.make.com/abc123" }, "filters": { "type": "object", "nullable": true, "description": "Optional filter criteria to narrow which contacts trigger the webhook. Uses `jsonLogic`, `elasticQuery`, and `filter_tree_format` keys.\n" }, "status": { "type": "string", "description": "Webhook status.", "enum": [ "on", "off" ], "example": "on" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "user": { "type": "object", "description": "Authenticated user profile.", "properties": { "uuid": { "type": "string" }, "id": { "type": "integer" }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "email_status": { "type": "string" }, "image_url": { "type": "string", "nullable": true }, "timezone": { "type": "string", "example": "Europe/Berlin" }, "config": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "team": { "type": "object", "description": "A team (workspace) in the system.", "properties": { "id": { "type": "integer" }, "cluster_id": { "type": "integer" }, "subscription_id": { "type": "integer", "nullable": true }, "license_uuid": { "type": "string", "nullable": true }, "name": { "type": "string", "example": "My Team" }, "color": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active" ], "example": "active" }, "features": { "type": "object", "properties": { "sender_profiles": { "type": "integer", "nullable": true }, "cloud_browsers": { "type": "integer", "nullable": true }, "contacts": { "type": "integer", "nullable": true }, "linkedin_accounts": { "type": "integer", "nullable": true }, "email_accounts": { "type": "integer", "nullable": true }, "users": { "type": "integer", "nullable": true } } }, "credits": { "type": "object", "properties": { "activities": { "type": "integer", "nullable": true }, "advanced_enrichment": { "type": "integer", "nullable": true }, "llm": { "type": "integer", "nullable": true } } }, "config": { "type": "object", "properties": { "is_onboarding_completed": { "type": "boolean" }, "is_cloud_browser_disabled": { "type": "boolean" } } }, "user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "flow-workspace": { "type": "object", "description": "An automation folder (workspace) for organizing automations.", "properties": { "uuid": { "type": "string" }, "team_id": { "type": "integer" }, "user_id": { "type": "integer" }, "name": { "type": "string", "example": "Q2 Campaigns" }, "order": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "data-source": { "type": "object", "description": "A LinkedIn import job (data source).", "properties": { "uuid": { "type": "string" }, "team_id": { "type": "integer" }, "sender_profile_uuid": { "type": "string", "nullable": true }, "list_uuid": { "type": "string" }, "payload": { "type": "object" }, "tags": { "type": "array", "nullable": true, "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "csv_leads", "sn_leads_search", "sn_leads_saved_search", "sn_leads_list", "sn_accounts_search", "sn_accounts_saved_search", "sn_accounts_list", "ln_leads_search", "ln_accounts_search", "ln_my_network", "ln_my_messenger", "post_engagement", "recruiter_leads_search" ] }, "status": { "type": "string", "enum": [ "not_started", "in_progress", "on_hold", "completed", "failed", "contacts_limit_achieved" ] }, "errors": { "type": "array", "items": { "type": "object" } }, "user_id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "linkedin-browser": { "type": "object", "description": "A LinkedIn browser profile used for automation.", "properties": { "id": { "type": "integer" }, "team_id": { "type": "integer" }, "sender_profile_uuid": { "type": "string" }, "linkedin_account_uuid": { "type": "string", "nullable": true }, "external_id": { "type": "string" }, "name": { "type": "string" }, "shared_emails": { "type": "array", "items": { "type": "string" } }, "linkedin_automation_server_id": { "type": "integer", "nullable": true }, "linkedin_proxy_id": { "type": "integer", "nullable": true }, "proxy_country_code": { "type": "string", "nullable": true }, "custom_proxy_config": { "type": "array", "items": { "type": "object" } }, "schedule": { "$ref": "#/components/schemas/schedule" }, "linkedin_login": { "type": "string", "nullable": true }, "linkedin_password": { "type": "string", "nullable": true }, "ln_code": { "type": "string", "nullable": true }, "browser_owner": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "stopped", "idle", "start_issue", "running_issue", "login_issue", "initializing" ] }, "error_reason": { "type": "string", "nullable": true }, "user_id": { "type": "integer" }, "last_start_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "mixed-filter-type": { "description": "Flexible filter value. Supports: scalar (equals), array (IN), object with operator, `\"is_null\"`, `\"is_not_null\"`.\n", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } }, { "type": "string", "enum": [ "is_null", "is_not_null" ] }, { "type": "string" }, { "type": "integer" } ] } }, "parameters": { "uuid-path": { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string" }, "description": "Resource UUID." }, "flowUuid-path": { "in": "path", "name": "flowUuid", "required": true, "schema": { "type": "string" }, "description": "Automation UUID." }, "limit": { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "format": "int32", "default": 20, "example": 20 }, "description": "Items per page (default 20)." }, "offset": { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "format": "int32", "default": 0, "example": 0 }, "description": "Items to skip (default 0)." }, "order-field": { "in": "query", "name": "order_field", "required": false, "schema": { "type": "string", "default": "created_at", "example": "created_at" }, "description": "Sort field (default `created_at`)." }, "order-type": { "in": "query", "name": "order_type", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "example": "asc" }, "description": "Sort direction." } } } }