{ "openapi": "3.1.0", "info": { "title": "Linnia API", "version": "1.0.0", "summary": "LinkedIn actions for AI agents and your own tools, paced safely.", "description": "The Linnia REST API. Every request needs `Authorization: Bearer lin_…` (an API key from the dashboard). Reads and writes become **jobs**: writes return at once and run later inside the account's working hours and budgets, so poll `GET /v1/jobs/{id}?wait=60` or subscribe to webhooks.\n\nGuides: https://docs.linnia.ai · Dashboard: https://app.linnia.ai", "contact": { "name": "Linnia", "email": "hello@linnia.ai", "url": "https://linnia.ai" } }, "servers": [ { "url": "https://api.linnia.ai", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Me", "description": "The caller." }, { "name": "Accounts", "description": "Connected LinkedIn accounts (seats): status, settings, limits, health." }, { "name": "Account connection", "description": "Endpoints behind the in-app LinkedIn sign-in. Most integrations only need `connectUrl` from `POST /v1/accounts/connect`." }, { "name": "Commands: read", "description": "Look things up on LinkedIn. Each returns a job." }, { "name": "Commands: write", "description": "Change something on LinkedIn. Each returns a job that the Governor paces; approve mode applies." }, { "name": "Jobs", "description": "Every command becomes a job. Poll with `?wait=`." }, { "name": "Workflows", "description": "Trees of actions in one job." }, { "name": "Approvals", "description": "Writes waiting for a person." }, { "name": "Automations", "description": "Follow-ups that stop when the person replies." }, { "name": "People", "description": "The organisation's shared history with one person." }, { "name": "Webhooks", "description": "Your endpoints for Linnia events." }, { "name": "API keys", "description": "Keys for integrations." }, { "name": "Webhook events", "description": "What Linnia POSTs to your endpoints." } ], "x-tagGroups": [ { "name": "Basics", "tags": [ "Me", "Jobs" ] }, { "name": "Accounts", "tags": [ "Accounts", "Account connection" ] }, { "name": "LinkedIn", "tags": [ "Commands: read", "Commands: write", "Workflows" ] }, { "name": "Workflow", "tags": [ "Approvals", "Automations", "People" ] }, { "name": "Integrations", "tags": [ "Webhooks", "Webhook events", "API keys" ] } ], "paths": { "/v1/me": { "get": { "tags": [ "Me" ], "operationId": "getMe", "summary": "Who am I", "description": "The organisation behind the credential. With an API key, `org` and `user` are null; with a signed-in session they describe the person.", "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "orgId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "key", "session" ] }, "keyName": { "type": "string" }, "org": { "type": [ "object", "null" ] }, "user": { "type": [ "object", "null" ] } } }, "example": { "ok": true, "orgId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "kind": "key", "keyName": "CRM sync", "org": null, "user": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts": { "get": { "tags": [ "Accounts" ], "operationId": "listAccounts", "summary": "List accounts", "description": "Every connected LinkedIn account in the organisation, with status, health, working hours and budgets left, plus seat usage.", "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "seats": { "$ref": "#/components/schemas/Seats" } } }, "example": { "ok": true, "accounts": [ { "id": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "label": "Emma (US SDR)", "status": "warming", "tier": "sales_nav", "products": [ "sales_navigator" ], "health": { "level": "green", "reason": null, "pausedUntil": null, "readsOnlyUntil": null }, "connections": 1840, "settings": { "minInviteQuality": 30, "autoWithdrawDays": 21 }, "warmup": { "day": 4, "of": 15 }, "workingHours": { "days": [ 1, 2, 3, 4, 5 ], "from": "09:00", "to": "17:30", "timezone": "America/New_York", "openNow": true, "nextOpening": null }, "offHoursPolicy": "queue", "mode": "approve", "budgets": { "invites": { "today": 9, "week": 41 }, "messages": { "today": 27, "week": null }, "profile_views": { "today": 52, "week": null } }, "pendingInvitations": 12, "reconnectUrl": null, "connectedAt": "2026-10-13T14:02:11.000Z" } ], "seats": { "used": 1, "pending": 0, "total": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/connect": { "post": { "tags": [ "Accounts" ], "operationId": "connectAccount", "summary": "Start connecting an account", "description": "Creates the account and returns `connectUrl`, a Linnia page where the rep signs in to LinkedIn. LinkedIn credentials never pass through your integration. Takes a seat; fails with `notAllowed` when every seat is in use.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 80, "description": "Usually the rep's name." }, "timezone": { "type": "string", "description": "IANA timezone. Default UTC.", "examples": [ "America/New_York" ] }, "workingHours": { "$ref": "#/components/schemas/WorkingHours" } } }, "example": { "label": "Emma (US SDR)", "timezone": "America/New_York" } } } }, "responses": { "201": { "description": "Created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" }, "connectUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "ok": true, "account": { "id": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "label": "Emma (US SDR)", "status": "connecting", "tier": "sales_nav", "products": [ "sales_navigator" ], "health": { "level": "green", "reason": null, "pausedUntil": null, "readsOnlyUntil": null }, "connections": 1840, "settings": { "minInviteQuality": 30, "autoWithdrawDays": 21 }, "warmup": { "day": 1, "of": 15 }, "workingHours": { "days": [ 1, 2, 3, 4, 5 ], "from": "09:00", "to": "17:30", "timezone": "America/New_York", "openNow": true, "nextOpening": null }, "offHoursPolicy": "queue", "mode": "approve", "budgets": null, "pendingInvitations": 12, "reconnectUrl": null, "connectedAt": null }, "connectUrl": "https://app.linnia.ai/accounts/6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44/connect", "expiresAt": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}": { "get": { "tags": [ "Accounts" ], "operationId": "getAccount", "summary": "Get an account", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" } } }, "example": { "ok": true, "account": { "id": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "label": "Emma (US SDR)", "status": "warming", "tier": "sales_nav", "products": [ "sales_navigator" ], "health": { "level": "green", "reason": null, "pausedUntil": null, "readsOnlyUntil": null }, "connections": 1840, "settings": { "minInviteQuality": 30, "autoWithdrawDays": 21 }, "warmup": { "day": 4, "of": 15 }, "workingHours": { "days": [ 1, 2, 3, 4, 5 ], "from": "09:00", "to": "17:30", "timezone": "America/New_York", "openNow": true, "nextOpening": null }, "offHoursPolicy": "queue", "mode": "approve", "budgets": { "invites": { "today": 9, "week": 41 }, "messages": { "today": 27, "week": null }, "profile_views": { "today": 52, "week": null } }, "pendingInvitations": 12, "reconnectUrl": null, "connectedAt": "2026-10-13T14:02:11.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Accounts" ], "operationId": "updateAccount", "summary": "Update account settings", "description": "Label, timezone, working hours, what happens to writes outside working hours (`queue` waits for the next opening, `reject` fails at once, `run` ignores hours), the invitation quality gate (0 disables), automatic withdrawal of stale invitations (days, or null to disable) and the operating mode.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 80 }, "timezone": { "type": "string" }, "workingHours": { "$ref": "#/components/schemas/WorkingHours" }, "offHoursPolicy": { "type": "string", "enum": [ "queue", "reject", "run" ] }, "minInviteQuality": { "type": "integer", "minimum": 0, "maximum": 100, "default": 30 }, "autoWithdrawDays": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 90, "default": 21 }, "mode": { "type": "string", "enum": [ "assist", "approve", "autopilot" ], "description": "`approve` (default): every write waits for a person, except withdrawing and declining invitations. `assist`: every write waits for a person. `autopilot`: writes run within policy." } } }, "example": { "mode": "autopilot", "workingHours": { "days": [ 1, 2, 3, 4, 5 ], "from": "08:30", "to": "17:00" } } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Accounts" ], "operationId": "deleteAccount", "summary": "Remove an account", "description": "Disconnects the account and frees its seat.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" }, "example": { "ok": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/health-report": { "get": { "tags": [ "Accounts" ], "operationId": "getHealthReport", "summary": "Health report", "description": "Network size, pending and stale invitations (older than 21 days) with a proposed cleanup, Social Selling Index when Sales Navigator is on, the warm-up plan and recommendations. Read it right after connecting.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "report": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" }, "network": { "type": "object", "properties": { "connections": { "type": [ "integer", "null" ] }, "size": { "type": "string", "enum": [ "small", "medium", "large", "unknown" ] }, "note": { "type": "string" } } }, "invitations": { "type": "object", "properties": { "pending": { "type": "integer" }, "stale": { "type": "integer" }, "proposedCleanup": { "type": [ "string", "null" ] } } }, "ssi": { "type": [ "object", "null" ] }, "warmup": { "type": [ "object", "null" ] }, "recommendations": { "type": "array", "items": { "type": "string" } } } } } }, "example": { "ok": true, "report": { "account": { "id": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "label": "Emma (US SDR)", "status": "warming", "tier": "sales_nav", "products": [ "sales_navigator" ], "health": { "level": "green", "reason": null, "pausedUntil": null, "readsOnlyUntil": null }, "connections": 1840, "settings": { "minInviteQuality": 30, "autoWithdrawDays": 21 }, "warmup": { "day": 4, "of": 15 }, "workingHours": { "days": [ 1, 2, 3, 4, 5 ], "from": "09:00", "to": "17:30", "timezone": "America/New_York", "openNow": true, "nextOpening": null }, "offHoursPolicy": "queue", "mode": "approve", "budgets": { "invites": { "today": 9, "week": 41 }, "messages": { "today": 27, "week": null }, "profile_views": { "today": 52, "week": null } }, "pendingInvitations": 12, "reconnectUrl": null, "connectedAt": "2026-10-13T14:02:11.000Z" }, "network": { "connections": 1840, "size": "large", "note": "Established network: full budgets apply after warm-up." }, "invitations": { "pending": 12, "stale": 3, "proposedCleanup": "Withdraw 3 invitations pending for more than 21 days." }, "ssi": null, "warmup": { "day": 4, "of": 15, "finishesOn": "2026-10-29", "todayInvites": 9, "note": "Budgets grow a little every day of the ramp. Warm, specific outreach during warm-up builds the account's standing; volume comes later." }, "recommendations": [ "During warm-up, prefer messages to existing connections and comments over new invitations." ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/brief": { "get": { "tags": [ "Accounts" ], "operationId": "getBrief", "summary": "Daily brief", "description": "The morning read for one rep: replies that need them in priority order (with triage class), new connections ready for a first message, queue, approvals waiting, budgets and working hours.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "hours", "in": "query", "required": false, "description": "Look back this many hours for replies.", "schema": { "type": "integer", "minimum": 1, "maximum": 168, "default": 24 } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "brief": { "type": "object", "properties": { "account": { "type": "object" }, "date": { "type": "string", "format": "date" }, "replies": { "type": "array", "items": { "type": "object", "properties": { "chatId": { "type": "string" }, "from": { "type": [ "string", "null" ] }, "class": { "type": "string", "enum": [ "interested", "meeting", "referral", "not_now", "not_interested", "objection", "out_of_office", "other" ] }, "text": { "type": [ "string", "null" ] }, "suggestedReply": { "type": [ "string", "null" ] }, "receivedAt": { "type": "string", "format": "date-time" } } } }, "readyForFirstMessage": { "type": "array", "items": { "type": "object" } }, "queue": { "type": "object", "properties": { "queued": { "type": "integer" }, "scheduled": { "type": "integer" }, "awaitingApproval": { "type": "integer" }, "byKind": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "approvals": { "type": "integer" }, "budgets": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/Budget" } }, "workingHours": { "type": "object", "properties": { "openNow": { "type": "boolean" }, "nextOpening": { "type": [ "string", "null" ], "format": "date-time" } } }, "headline": { "type": "string" } } } } }, "example": { "ok": true, "brief": { "account": { "id": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "label": "Emma (US SDR)", "health": "green", "mode": "approve", "warmupDay": 4 }, "date": "2026-10-18", "replies": [ { "chatId": "2-YjM4ZTQ1MjAtNzQ4ZC00", "from": "ACoAAA0003", "class": "meeting", "text": "Sure, Thursday at 3pm works.", "suggestedReply": null, "receivedAt": "2026-10-18T07:41:00.000Z" } ], "readyForFirstMessage": [ { "providerId": "ACoAAA0005", "name": "Leo Hart", "acceptedAt": "2026-10-17T16:20:00.000Z", "suggestedOpener": "Thanks for connecting, Leo. No pitch: I'd just like to hear what's on your plate this quarter." } ], "queue": { "queued": 2, "scheduled": 1, "awaitingApproval": 3, "byKind": { "connect": 4, "send_message": 2 } }, "approvals": 3, "budgets": { "invites": { "today": 9, "week": 41 } }, "workingHours": { "openNow": true, "nextOpening": null }, "headline": "1 reply needs you (one wants a meeting); 1 new connection is ready for a first message; 3 writes wait for approval; 3 queued for today." } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/invitations": { "get": { "tags": [ "Accounts" ], "operationId": "listInvitations", "summary": "List invitations Linnia knows about", "description": "Invitations sent from this account as Linnia recorded them (sent through Linnia, or seen when syncing), newest first, up to 200.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "accepted", "withdrawn", "declined", "unknown", "all" ], "default": "pending" } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "invitations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "providerId": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "withdrawn", "declined", "unknown" ] }, "source": { "type": "string", "examples": [ "linnia", "external" ] }, "sentAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "example": { "ok": true, "invitations": [ { "id": "8a9b0c1d-2e3f-4a5b-8c6d-7e8f9a0b1c2d", "providerId": "ACoAAA0001", "note": "Hi Jana, enjoyed your post on RevOps hiring.", "status": "pending", "source": "linnia", "sentAt": "2026-10-16T10:02:00.000Z", "resolvedAt": null } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/limits": { "get": { "tags": [ "Accounts" ], "operationId": "getLimits", "summary": "Get limits", "description": "Each limit in force next to Linnia's default and the ceiling for the account's tier.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "tier": { "type": "string", "enum": [ "free", "premium", "sales_nav", "recruiter" ] }, "limits": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "invites", "messages", "inmails", "profile_views", "company_views", "search_rows", "comments", "reactions", "posts", "endorsements", "invite_withdrawals", "list_polls" ] }, "period": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "default": { "type": "integer" }, "ceiling": { "type": "integer" }, "maxValue": { "type": "integer" }, "isEnabled": { "type": "boolean" }, "source": { "type": "string", "examples": [ "default", "user" ] } } } } } }, "example": { "ok": true, "tier": "sales_nav", "limits": [ { "category": "invites", "period": "daily", "default": 25, "ceiling": 40, "maxValue": 20, "isEnabled": true, "source": "user" }, { "category": "invites", "period": "weekly", "default": 100, "ceiling": 200, "maxValue": 100, "isEnabled": true, "source": "default" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": [ "Accounts" ], "operationId": "setLimits", "summary": "Set limits", "description": "Sets one or more limits. Lower is always fine; anything above the tier's ceiling is capped by the Governor. Warm-up and health still scale the limit down.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "limits" ], "properties": { "limits": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "category", "period", "maxValue" ], "properties": { "category": { "type": "string", "enum": [ "invites", "messages", "inmails", "profile_views", "company_views", "search_rows", "comments", "reactions", "posts", "endorsements", "invite_withdrawals", "list_polls" ] }, "period": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "maxValue": { "type": "integer", "minimum": 0 }, "isEnabled": { "type": "boolean" } } } } } }, "example": { "limits": [ { "category": "invites", "period": "daily", "maxValue": 20 } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/pause": { "post": { "tags": [ "Accounts" ], "operationId": "pauseAccount", "summary": "Pause an account", "description": "Stops all writes until a person resumes it.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" }, "example": { "ok": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/resume": { "post": { "tags": [ "Accounts" ], "operationId": "resumeAccount", "summary": "Resume an account", "description": "Resumes a paused or stopped account. After a LinkedIn restriction the account only reads for 7 days, then restarts warm-up at half its previous level.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "account": { "$ref": "#/components/schemas/Account" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/reconnect": { "post": { "tags": [ "Account connection" ], "operationId": "reconnectAccount", "summary": "Get a reconnect link", "description": "A Linnia page where the rep signs in to LinkedIn again.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "reconnectUrl": { "type": "string", "format": "uri" } } }, "example": { "ok": true, "reconnectUrl": "https://app.linnia.ai/accounts/6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44/connect" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/native-auth": { "post": { "tags": [ "Account connection" ], "operationId": "nativeAuth", "summary": "Sign in with LinkedIn email and password", "description": "For building your own connect screen. Linnia doesn't store the password; the session is held by Linnia's LinkedIn provider. Usually answers with a checkpoint (2FA, OTP, CAPTCHA, approval in the LinkedIn app…) to complete with `native-checkpoint`. Most teams use `connectUrl` instead.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "maxLength": 320 }, "password": { "type": "string", "maxLength": 200, "format": "password" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO country code of where the rep usually is." } } }, "example": { "username": "emma@example.com", "password": "••••••••", "country": "US" } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeConnectResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/accounts/{id}/native-cookie": { "post": { "tags": [ "Account connection" ], "operationId": "nativeCookie", "summary": "Connect with a LinkedIn session cookie", "description": "Connects with the `li_at` cookie (and `li_a` for Sales Navigator or Recruiter). Only when cookie connect is enabled for the workspace; otherwise `notAllowed`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accessToken" ], "properties": { "accessToken": { "type": "string", "maxLength": 8000, "description": "li_at" }, "premiumAccessToken": { "type": "string", "maxLength": 8000, "description": "li_a" }, "userAgent": { "type": "string", "maxLength": 512 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } } } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeConnectResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/accounts/{id}/native-checkpoint": { "post": { "tags": [ "Account connection" ], "operationId": "nativeCheckpoint", "summary": "Complete a checkpoint", "description": "Sends the code (or CAPTCHA token, selection, phone number) for the checkpoint. Send an empty `code` to wait on PAIRING_CODE or LOADING.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerAccountId" ], "properties": { "providerAccountId": { "type": "string" }, "code": { "type": "string", "maxLength": 8000, "default": "" } } }, "example": { "providerAccountId": "kL9xQ2mN", "code": "482913" } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeConnectResult" }, "example": { "ok": true, "kind": "connected", "providerAccountId": "kL9xQ2mN", "provider": "unipile-v1" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/accounts/{id}/native-checkpoint/resend": { "post": { "tags": [ "Account connection" ], "operationId": "nativeCheckpointResend", "summary": "Resend a checkpoint code", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerAccountId" ], "properties": { "providerAccountId": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" }, "example": { "ok": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/native-poll": { "post": { "tags": [ "Account connection" ], "operationId": "nativePoll", "summary": "Check an in-app approval", "description": "After the rep approves the sign-in in the LinkedIn app, returns `connected`; otherwise still the IN_APP_VALIDATION checkpoint.", "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providerAccountId" ], "properties": { "providerAccountId": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeConnectResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/hosted-auth": { "post": { "tags": [ "Account connection" ], "operationId": "hostedAuth", "summary": "Hosted sign-in link (legacy)", "description": "A fresh hosted LinkedIn sign-in URL from the provider. Prefer `connectUrl` or the native endpoints.", "deprecated": true, "parameters": [ { "$ref": "#/components/parameters/AccountId" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "provider": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/get_profile": { "post": { "tags": [ "Commands: read" ], "operationId": "command_get_profile", "summary": "Get a profile", "description": "A person's profile: headline, company, location, connection degree, shared connections. Cached for a week; a fresh fetch counts against `profile_views`. Each detail section is a heavier LinkedIn call, so ask only for what you need.\n\n**Read.** Runs as soon as possible. Budget category: `profile_views`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"get_profile\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "person" ], "properties": { "person": { "type": "string", "minLength": 1, "maxLength": 300, "description": "LinkedIn profile URL, public identifier (the part after /in/) or provider id.", "examples": [ "https://www.linkedin.com/in/jana-novak" ] }, "sections": { "type": "array", "maxItems": 8, "items": { "type": "string", "enum": [ "about", "experience", "education", "skills", "languages", "certifications", "projects", "recommendations_received" ] } }, "api": { "type": "string", "enum": [ "classic", "sales_navigator", "recruiter" ], "description": "Which LinkedIn product to use. Defaults to what the account has." } } }, "example": { "person": "jana-novak", "sections": [ "experience" ] } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "get_profile", "status": "queued", "approval": null, "input": { "person": "jana-novak", "sections": [ "experience" ] }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/get_company": { "post": { "tags": [ "Commands: read" ], "operationId": "command_get_company", "summary": "Get a company", "description": "A company page: industry, size, location, website.\n\n**Read.** Runs as soon as possible. Budget category: `company_views`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"get_company\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company" ], "properties": { "company": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Company page URL, public identifier or id." } } }, "example": { "company": "https://www.linkedin.com/company/northwind" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "get_company", "status": "queued", "approval": null, "input": { "company": "https://www.linkedin.com/company/northwind" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/search_people": { "post": { "tags": [ "Commands: read" ], "operationId": "command_search_people", "summary": "Search people", "description": "Searches LinkedIn for people. Charged per result row returned (`search_rows`), so prefer tighter filters over paging. Filters marked Sales Navigator need it on the account.\n\n**Read.** Runs as soon as possible. Budget category: `search_rows`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"search_people\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "keywords": { "type": "string", "maxLength": 300 }, "url": { "type": "string", "format": "uri", "description": "A LinkedIn or Sales Navigator search URL to run as is." }, "api": { "type": "string", "enum": [ "classic", "sales_navigator", "recruiter" ], "description": "Which LinkedIn product to use. Defaults to what the account has." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "cursor": { "type": [ "string", "null" ], "description": "Cursor from the previous page's result." }, "filters": { "type": "object", "properties": { "location": { "type": "array", "maxItems": 10, "items": { "type": "string" }, "description": "Place names or LinkedIn geo ids" }, "industry": { "type": "array", "maxItems": 10, "items": { "type": "string" } }, "company": { "type": "array", "maxItems": 10, "items": { "type": "string" }, "description": "Current company names or ids" }, "pastCompany": { "type": "array", "maxItems": 10, "items": { "type": "string" } }, "school": { "type": "array", "maxItems": 10, "items": { "type": "string" } }, "title": { "type": "string", "maxLength": 100, "description": "Job title keywords" }, "firstName": { "type": "string", "maxLength": 60 }, "lastName": { "type": "string", "maxLength": 60 }, "seniority": { "type": "array", "description": "Sales Navigator only", "items": { "type": "string", "enum": [ "owner_partner", "cxo", "vice_president", "director", "experienced_manager", "entry_level_manager", "strategic", "senior", "entry_level", "in_training" ] } }, "tenureAtRole": { "type": "object", "properties": { "min": { "type": "integer", "minimum": 0 }, "max": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "description": "Sales Navigator only: years in current role" }, "companyHeadcount": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "min": { "type": "integer", "minimum": 0 }, "max": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "description": "Sales Navigator only: employee count ranges such as {min: 51, max: 200}" }, "connectionDegree": { "type": "array", "items": { "type": "string", "enum": [ "first", "second", "third" ] } }, "changedJobs": { "type": "boolean", "description": "Sales Navigator only: changed jobs in the last 90 days" }, "postedRecently": { "type": "boolean", "description": "Sales Navigator only: posted on LinkedIn in the last 30 days" } } } } }, "example": { "keywords": "head of revops", "limit": 10, "filters": { "location": [ "London" ], "connectionDegree": [ "second" ] } } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "search_people", "status": "queued", "approval": null, "input": { "keywords": "head of revops", "limit": 10, "filters": { "location": [ "London" ], "connectionDegree": [ "second" ] } }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/search_companies": { "post": { "tags": [ "Commands: read" ], "operationId": "command_search_companies", "summary": "Search companies", "description": "Searches LinkedIn for companies. Charged per result row returned.\n\n**Read.** Runs as soon as possible. Budget category: `search_rows`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"search_companies\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "keywords": { "type": "string", "maxLength": 300 }, "url": { "type": "string", "format": "uri" }, "api": { "type": "string", "enum": [ "classic", "sales_navigator" ], "description": "Which LinkedIn product to use. Defaults to what the account has." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "cursor": { "type": [ "string", "null" ], "description": "Cursor from the previous page's result." }, "filters": { "type": "object", "properties": { "location": { "type": "array", "maxItems": 10, "items": { "type": "string" } }, "industry": { "type": "array", "maxItems": 10, "items": { "type": "string" } }, "headcount": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "min": { "type": "integer", "minimum": 0 }, "max": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "hasJobOffers": { "type": "boolean" }, "connectionDegree": { "type": "array", "items": { "type": "string", "enum": [ "first", "second", "third" ] } } } } } }, "example": { "keywords": "payments", "limit": 10, "filters": { "headcount": [ { "min": 51, "max": 200 } ] } } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "search_companies", "status": "queued", "approval": null, "input": { "keywords": "payments", "limit": 10, "filters": { "headcount": [ { "min": 51, "max": 200 } ] } }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/get_posts": { "post": { "tags": [ "Commands: read" ], "operationId": "command_get_posts", "summary": "Get posts", "description": "Recent posts by a person or a company page, newest first. Give a person or a company, not both. Not budgeted.\n\n**Read.** Runs as soon as possible. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"get_posts\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "person": { "type": "string", "minLength": 1, "maxLength": 300, "description": "LinkedIn profile URL, public identifier (the part after /in/) or provider id.", "examples": [ "https://www.linkedin.com/in/jana-novak" ] }, "company": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Company page URL, public identifier or numeric id" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "cursor": { "type": [ "string", "null" ], "description": "Cursor from the previous page's result." } } }, "example": { "person": "jana-novak", "limit": 5 } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "get_posts", "status": "queued", "approval": null, "input": { "person": "jana-novak", "limit": 5 }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/get_post": { "post": { "tags": [ "Commands: read" ], "operationId": "command_get_post", "summary": "Get a post", "description": "A post by URL or id: author, text, reaction and comment counts.\n\n**Read.** Runs as soon as possible. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"get_post\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "post" ], "properties": { "post": { "type": "string", "minLength": 1 } } }, "example": { "post": "urn:li:activity:7251234567890123456" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "get_post", "status": "queued", "approval": null, "input": { "post": "urn:li:activity:7251234567890123456" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/list_chats": { "post": { "tags": [ "Commands: read" ], "operationId": "command_list_chats", "summary": "List conversations", "description": "Recent conversations, newest first. Each carries the latest reply triage when there is one.\n\n**Read.** Runs as soon as possible. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"list_chats\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "unread": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "cursor": { "type": [ "string", "null" ], "description": "Cursor from the previous page's result." } } }, "example": { "unread": true, "limit": 20 } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "list_chats", "status": "queued", "approval": null, "input": { "unread": true, "limit": 20 }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/get_conversation": { "post": { "tags": [ "Commands: read" ], "operationId": "command_get_conversation", "summary": "Get a conversation", "description": "Messages in one conversation (chat id from `list_chats`), newest first.\n\n**Read.** Runs as soon as possible. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"get_conversation\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chat" ], "properties": { "chat": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "cursor": { "type": [ "string", "null" ], "description": "Cursor from the previous page's result." } } }, "example": { "chat": "2-YjM4ZTQ1MjAtNzQ4ZC00", "limit": 30 } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "get_conversation", "status": "queued", "approval": null, "input": { "chat": "2-YjM4ZTQ1MjAtNzQ4ZC00", "limit": 30 }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/list_invites": { "post": { "tags": [ "Commands: read" ], "operationId": "command_list_invites", "summary": "List invitations on LinkedIn", "description": "Sent or received invitations, read live from LinkedIn. Counts against `list_polls` (a few a day); for Linnia's own record use `GET /v1/accounts/{id}/invitations`.\n\n**Read.** Runs as soon as possible. Budget category: `list_polls`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"list_invites\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "sent", "received" ], "default": "sent" } } }, "example": { "direction": "received" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "list_invites", "status": "queued", "approval": null, "input": { "direction": "received" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/profile_viewers": { "post": { "tags": [ "Commands: read" ], "operationId": "command_profile_viewers", "summary": "Profile viewers", "description": "Who viewed the account's profile recently. Free LinkedIn shows only a few recent viewers.\n\n**Read.** Runs as soon as possible. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"profile_viewers\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "profile_viewers", "status": "queued", "approval": null, "input": {}, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/ssi": { "post": { "tags": [ "Commands: read" ], "operationId": "command_ssi", "summary": "Social Selling Index", "description": "The account's Social Selling Index (score out of 100 and four pillars). Needs Sales Navigator.\n\n**Read.** Runs as soon as possible. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"ssi\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": {} } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "ssi", "status": "queued", "approval": null, "input": {}, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/connect": { "post": { "tags": [ "Commands: write" ], "operationId": "command_connect", "summary": "Send a connection request", "description": "Sends a connection request with an optional note (max 300 characters, no links). Linnia checks the target first: already connected, pending invitation, do-not-contact, recently contacted by a colleague, duplicate text and a targeting quality gate (`minInviteQuality`).\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Budget category: `invites`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"connect\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "person" ], "properties": { "person": { "type": "string", "minLength": 1, "maxLength": 300, "description": "LinkedIn profile URL, public identifier (the part after /in/) or provider id.", "examples": [ "https://www.linkedin.com/in/jana-novak" ] }, "note": { "type": "string", "maxLength": 300 } } }, "example": { "person": "https://www.linkedin.com/in/jana-novak", "note": "Hi Jana, enjoyed your post on RevOps hiring. Would be glad to connect." } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "connect", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "person": "https://www.linkedin.com/in/jana-novak", "note": "Hi Jana, enjoyed your post on RevOps hiring. Would be glad to connect." }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/withdraw_invite": { "post": { "tags": [ "Commands: write" ], "operationId": "command_withdraw_invite", "summary": "Withdraw an invitation", "description": "Withdraws a pending invitation the account sent. Does not need approval in approve mode.\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Budget category: `invite_withdrawals`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"withdraw_invite\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "person" ], "properties": { "person": { "type": "string", "minLength": 1, "maxLength": 300, "description": "LinkedIn profile URL, public identifier (the part after /in/) or provider id.", "examples": [ "https://www.linkedin.com/in/jana-novak" ] } } }, "example": { "person": "jana-novak" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "withdraw_invite", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "person": "jana-novak" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/send_message": { "post": { "tags": [ "Commands: write" ], "operationId": "command_send_message", "summary": "Send a message", "description": "Sends a message to a 1st-degree connection (`person`) or into an existing conversation (`chat`). Set `inmail: true` for InMail (counts against `inmails`). The same text twice to one person, and more than 10 near-identical messages a day, are blocked.\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Budget category: `messages`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"send_message\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "person": { "type": "string", "minLength": 1, "maxLength": 300, "description": "LinkedIn profile URL, public identifier (the part after /in/) or provider id.", "examples": [ "https://www.linkedin.com/in/jana-novak" ] }, "chat": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1, "maxLength": 1900 }, "inmail": { "type": "boolean", "default": false }, "subject": { "type": "string", "maxLength": 200, "description": "InMail subject" } } }, "example": { "person": "sofia-reyes", "text": "Thanks for connecting, Sofia. Curious how Lumen is approaching outbound this quarter." } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "send_message", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "person": "sofia-reyes", "text": "Thanks for connecting, Sofia. Curious how Lumen is approaching outbound this quarter." }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/accept_invite": { "post": { "tags": [ "Commands: write" ], "operationId": "command_accept_invite", "summary": "Accept a received invitation", "description": "Accepts an invitation from the received list (`list_invites` with direction `received`).\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"accept_invite\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invitationId" ], "properties": { "invitationId": { "type": "string", "minLength": 1 }, "sharedSecret": { "type": "string" } } }, "example": { "invitationId": "7251234567890123456", "sharedSecret": "Xy12ab" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "accept_invite", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "invitationId": "7251234567890123456", "sharedSecret": "Xy12ab" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/decline_invite": { "post": { "tags": [ "Commands: write" ], "operationId": "command_decline_invite", "summary": "Decline a received invitation", "description": "Declines a received invitation. Does not need approval in approve mode.\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"decline_invite\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invitationId" ], "properties": { "invitationId": { "type": "string", "minLength": 1 }, "sharedSecret": { "type": "string" } } }, "example": { "invitationId": "7251234567890123456" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "decline_invite", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "invitationId": "7251234567890123456" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/endorse": { "post": { "tags": [ "Commands: write" ], "operationId": "command_endorse", "summary": "Endorse a skill", "description": "Endorses one skill on a connection's profile, by the skill name shown on the profile.\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Budget category: `endorsements`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"endorse\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "person", "skill" ], "properties": { "person": { "type": "string", "minLength": 1, "maxLength": 300, "description": "LinkedIn profile URL, public identifier (the part after /in/) or provider id.", "examples": [ "https://www.linkedin.com/in/jana-novak" ] }, "skill": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "example": { "person": "leo-hart", "skill": "Operations" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "endorse", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "person": "leo-hart", "skill": "Operations" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/save_lead": { "post": { "tags": [ "Commands: write" ], "operationId": "command_save_lead", "summary": "Save a Sales Navigator lead", "description": "Saves a person as a Sales Navigator lead, optionally into a lead list. Needs Sales Navigator.\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"save_lead\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "person" ], "properties": { "person": { "type": "string", "minLength": 1, "maxLength": 300, "description": "LinkedIn profile URL, public identifier (the part after /in/) or provider id.", "examples": [ "https://www.linkedin.com/in/jana-novak" ] }, "listId": { "type": "string", "minLength": 1, "description": "Sales Navigator lead list id" } } }, "example": { "person": "ida-lind" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "save_lead", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "person": "ida-lind" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/react": { "post": { "tags": [ "Commands: write" ], "operationId": "command_react", "summary": "React to a post", "description": "Reacts to a post.\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Budget category: `reactions`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"react\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "post" ], "properties": { "post": { "type": "string", "minLength": 1 }, "reaction": { "type": "string", "enum": [ "like", "celebrate", "support", "love", "insightful", "funny" ], "default": "like" } } }, "example": { "post": "urn:li:activity:7251234567890123456", "reaction": "insightful" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "react", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "post": "urn:li:activity:7251234567890123456", "reaction": "insightful" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/comment": { "post": { "tags": [ "Commands: write" ], "operationId": "command_comment", "summary": "Comment on a post", "description": "Comments on a post. Comments can't contain links.\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Budget category: `comments`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"comment\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "post", "text" ], "properties": { "post": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1, "maxLength": 1250 } } }, "example": { "post": "urn:li:activity:7251234567890123456", "text": "Great point about ramp time for new SDRs." } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "comment", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "post": "urn:li:activity:7251234567890123456", "text": "Great point about ramp time for new SDRs." }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/create_post": { "post": { "tags": [ "Commands: write" ], "operationId": "command_create_post", "summary": "Publish a post", "description": "Publishes a post from the account.\n\n**Write.** Paced by the Governor inside working hours and budgets; in approve or assist mode it waits for a person (status `awaiting_approval`). Budget category: `posts`. Returns a job; poll `GET /v1/jobs/{id}?wait=60` for the result. Same as `POST /v1/jobs` with `command: \"create_post\"`.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 3000 } } }, "example": { "text": "Three things we learned rebuilding our outbound motion this year…" } } } }, "responses": { "200": { "description": "Same request as before: the existing job (`created: false`)", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "create_post", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "text": "Three things we learned rebuilding our outbound motion this year…" }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/jobs": { "post": { "tags": [ "Jobs" ], "operationId": "createJob", "summary": "Run a command", "description": "The generic form of every command: `{ account, command, input }`. Same behaviour as `POST /v1/accounts/{id}/{command}`.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "command" ], "properties": { "account": { "type": "string", "format": "uuid" }, "command": { "type": "string", "enum": [ "get_profile", "get_company", "search_people", "search_companies", "get_posts", "get_post", "list_chats", "get_conversation", "list_invites", "profile_viewers", "ssi", "connect", "withdraw_invite", "send_message", "accept_invite", "decline_invite", "endorse", "save_lead", "react", "comment", "create_post" ] }, "input": { "type": "object", "default": {} }, "idempotencyKey": { "type": "string", "maxLength": 200 } } }, "example": { "account": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "command": "connect", "input": { "person": "jana-novak", "note": "Hi Jana, enjoyed your post on RevOps hiring." }, "idempotencyKey": "crm-lead-88412-connect" } } } }, "responses": { "200": { "description": "Existing job for this idempotency key", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "202": { "description": "Job created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "ok": true, "created": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "connect", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "person": "jana-novak", "note": "Hi Jana, enjoyed your post on RevOps hiring. Would be glad to connect." }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Jobs" ], "operationId": "listJobs", "summary": "List jobs", "description": "Recent jobs, newest first.", "parameters": [ { "$ref": "#/components/parameters/AccountFilter" }, { "$ref": "#/components/parameters/Limit200" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/jobs/{id}": { "get": { "tags": [ "Jobs" ], "operationId": "getJob", "summary": "Get a job (long-poll)", "description": "With `wait`, holds the request open up to that many seconds (max 600) and returns as soon as the job is completed, failed or cancelled. Otherwise returns the current snapshot.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13" }, { "name": "wait", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 600, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "job": { "$ref": "#/components/schemas/Job" } } }, "example": { "ok": true, "job": { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "connect", "status": "completed", "approval": null, "input": { "person": "jana-novak", "note": "Hi Jana, enjoyed your post on RevOps hiring. Would be glad to connect." }, "result": { "person": { "providerId": "ACoAAA0001", "name": "Jana Novak" }, "invitationId": "7251234567890123456", "note": "Hi Jana, enjoyed your post on RevOps hiring. Would be glad to connect.", "quality": { "score": 72, "reasons": [ "2nd-degree connection", "4 shared connections" ] } }, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": null, "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": "2026-10-18T10:41:27.000Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Jobs" ], "operationId": "cancelJob", "summary": "Cancel a job", "description": "Cancels a job that hasn't finished. Pending approvals for it are rejected. Anything already sent to LinkedIn is not undone.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "job": { "$ref": "#/components/schemas/Job" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounts/{id}/workflows": { "post": { "tags": [ "Workflows" ], "operationId": "runWorkflow", "summary": "Run a workflow", "description": "Runs a tree of actions in one job. Each node is `{ action, label?, params?, then?: node | node[] }`; actions are the command names plus `for_each_person` (after `search_people` or `list_invites`; runs `then` once per person, first 20) and `wait` (`days`, `workingDays` or `hours`). Nesting is limited to 5 levels. Inside `for_each_person`, `person` is implied and text may use `{{first_name}}`, `{{company}}`, `{{headline}}`. Call with `dryRun: true` first to get the plan with per-category cost.", "parameters": [ { "$ref": "#/components/parameters/AccountId" }, { "$ref": "#/components/parameters/ClientName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workflow" ], "properties": { "workflow": { "description": "A node or an array of nodes." }, "label": { "type": "string", "maxLength": 80 }, "dryRun": { "type": "boolean", "default": false } } }, "example": { "label": "RevOps leads in London", "dryRun": true, "workflow": { "action": "search_people", "params": { "keywords": "head of revops", "limit": 10, "filters": { "location": [ "London" ] } }, "then": { "action": "for_each_person", "params": { "skipIf": [ "connected", "pending_invite", "contacted_last_30d", "dnc" ] }, "then": { "action": "connect", "params": { "note": "Hi {{first_name}}, I work with RevOps teams in London and would be glad to connect." } } } } } } } }, "responses": { "200": { "description": "Dry run: the plan only", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "plan": { "type": "object", "properties": { "actions": { "type": "integer" }, "writes": { "type": "integer" }, "byCategory": { "type": "object", "additionalProperties": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } } }, "fanOuts": { "type": "array", "items": { "type": "object", "properties": { "after": { "type": "string" }, "upTo": { "type": "integer" } } } }, "outline": { "type": "array", "items": { "type": "string" } } } }, "job": { "type": "null" } } } } } }, "202": { "description": "Started", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "plan": { "type": "object" }, "job": { "$ref": "#/components/schemas/Job" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/approvals": { "get": { "tags": [ "Approvals" ], "operationId": "listApprovals", "summary": "List approvals", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ], "default": "pending" } }, { "$ref": "#/components/parameters/AccountFilter" }, { "$ref": "#/components/parameters/Limit200" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" } } } }, "example": { "ok": true, "approvals": [ { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "status": "pending", "jobId": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "preview": { "command": "connect", "target": "Jana Novak, VP Sales at Northwind", "text": "Hi Jana, enjoyed your post on RevOps hiring. Would be glad to connect.", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”" }, "editedText": null, "requestedBy": "mcp:claude-ai", "decidedBy": null, "decidedAt": null, "expiresAt": "2026-10-21T09:14:03.000Z", "createdAt": "2026-10-18T09:14:03.000Z" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/approvals/{id}": { "get": { "tags": [ "Approvals" ], "operationId": "getApproval", "summary": "Get an approval", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "approval": { "$ref": "#/components/schemas/Approval" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/approvals/{id}/approve": { "post": { "tags": [ "Approvals" ], "operationId": "approve", "summary": "Approve", "description": "Approves the write, optionally replacing its text (message, note or comment). The action then goes through the Governor like any other: working hours, budgets, pacing. Fails if the request expired (72 hours) or was already decided.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 3000, "description": "Edited text to send instead." } } }, "example": { "text": "Hi Jana, loved your post on RevOps hiring. Would be glad to connect." } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "approval": { "$ref": "#/components/schemas/Approval" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/approvals/{id}/reject": { "post": { "tags": [ "Approvals" ], "operationId": "reject", "summary": "Reject", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } } }, "example": { "reason": "Not a fit for this quarter." } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "approval": { "$ref": "#/components/schemas/Approval" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/automations": { "get": { "tags": [ "Automations" ], "operationId": "listAutomations", "summary": "List automations", "parameters": [ { "$ref": "#/components/parameters/AccountFilter" } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "automations": { "type": "array", "items": { "$ref": "#/components/schemas/Automation" } } } }, "example": { "ok": true, "automations": [ { "id": "5a7c9e1b-3d5f-4a6b-8c0d-2e4f6a8b0c1d", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "name": "Thank new connections", "trigger": { "event": "invitation.accepted" }, "steps": [ { "action": "wait", "workingDays": 2 }, { "action": "send_message", "text": "Thanks for connecting, {{first_name}}. How is the quarter going at {{company}}?" } ], "status": "active", "runs": { "waiting": 3, "completed": 11, "stopped": 2 }, "createdAt": "2026-10-10T08:00:00.000Z" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Automations" ], "operationId": "createAutomation", "summary": "Create an automation", "description": "A trigger plus up to 10 steps. Any reply from the person stops their run. Sends go through approvals, budgets and pacing like every other write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "name", "trigger", "steps" ], "properties": { "account": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "trigger": { "$ref": "#/components/schemas/AutomationTrigger" }, "steps": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/AutomationStep" } } } }, "example": { "account": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "name": "Thank new connections", "trigger": { "event": "invitation.accepted" }, "steps": [ { "action": "wait", "workingDays": 2 }, { "action": "send_message", "text": "Thanks for connecting, {{first_name}}. How is the quarter going at {{company}}?" } ] } } } }, "responses": { "201": { "description": "Created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "automation": { "$ref": "#/components/schemas/Automation" } } }, "example": { "ok": true, "automation": { "id": "5a7c9e1b-3d5f-4a6b-8c0d-2e4f6a8b0c1d", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "name": "Thank new connections", "trigger": { "event": "invitation.accepted" }, "steps": [ { "action": "wait", "workingDays": 2 }, { "action": "send_message", "text": "Thanks for connecting, {{first_name}}. How is the quarter going at {{company}}?" } ], "status": "active", "runs": { "waiting": 3, "completed": 11, "stopped": 2 }, "createdAt": "2026-10-10T08:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/automations/{id}/pause": { "post": { "tags": [ "Automations" ], "operationId": "pauseAutomation", "summary": "Pause an automation", "description": "Sets the status to `paused`. Everyone waiting in it is stopped.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "automation": { "$ref": "#/components/schemas/Automation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/automations/{id}/resume": { "post": { "tags": [ "Automations" ], "operationId": "resumeAutomation", "summary": "Resume an automation", "description": "Sets the automation back to active.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "automation": { "$ref": "#/components/schemas/Automation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/automations/{id}/archive": { "post": { "tags": [ "Automations" ], "operationId": "archiveAutomation", "summary": "Archive an automation", "description": "Sets the status to `archived`. Everyone waiting in it is stopped.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "automation": { "$ref": "#/components/schemas/Automation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/people/{person}/timeline": { "get": { "tags": [ "People" ], "operationId": "personTimeline", "summary": "Person timeline", "description": "Everything the organisation has done with one person across every connected account: invitations, messages, replies (with triage), automations, pending approvals and notes, newest first. Also says whether the person is on the do-not-contact list.", "parameters": [ { "name": "person", "in": "path", "required": true, "description": "Public identifier or provider id. URL-encode a profile URL.", "schema": { "type": "string" }, "example": "jana-novak" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "person": { "type": [ "object", "null" ], "properties": { "providerId": { "type": "string" }, "publicIdentifier": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } } }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEntry" } }, "onDnc": { "type": "boolean" } } }, "example": { "ok": true, "person": { "providerId": "ACoAAA0001", "publicIdentifier": "jana-novak", "name": "Jana Novak", "headline": "VP Sales at Northwind", "company": "Northwind" }, "entries": [ { "at": "2026-10-17T09:30:00.000Z", "type": "note", "accountId": null, "accountLabel": null, "summary": "Met at SaaStock, interested in Q1 pilot.", "detail": { "author": "user:2b4d…", "noteId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f" } }, { "at": "2026-10-16T10:02:00.000Z", "type": "invitation", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "accountLabel": "Emma (US SDR)", "summary": "Invitation sent: “Hi Jana, enjoyed your post on RevOps hiring.”", "detail": { "status": "pending" } } ], "onDnc": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/people/{person}/notes": { "post": { "tags": [ "People" ], "operationId": "addNote", "summary": "Add a note", "description": "A note about a person, visible to the whole organisation in the timeline. Never sent to LinkedIn. Up to 4000 characters.", "parameters": [ { "name": "person", "in": "path", "required": true, "schema": { "type": "string" }, "example": "jana-novak" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 4000 }, "author": { "type": "string", "maxLength": 120, "description": "Defaults to the caller." } } }, "example": { "body": "Met at SaaStock, interested in Q1 pilot." } } } }, "responses": { "201": { "description": "Created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "note": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "providerId": { "type": "string" }, "author": { "type": "string" }, "authorUserId": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "List webhook endpoints", "description": "Your endpoints and the event types you can subscribe to. Owners and admins only (API keys count as the owner).", "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Add a webhook endpoint", "description": "Registers an https URL that must resolve to public addresses. Returns the signing secret (`whsec_…`) once; store it. Leave `events` empty to receive every event. Owners and admins only (API keys count as the owner).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] }, "default": [] }, "mode": { "type": "string", "enum": [ "fat", "thin" ], "default": "fat" } } }, "example": { "url": "https://hooks.example.com/linnia", "events": [ "message.received", "invitation.accepted" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "webhook": { "$ref": "#/components/schemas/Webhook" }, "secret": { "type": "string" }, "note": { "type": "string" } } }, "example": { "ok": true, "webhook": { "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a", "url": "https://hooks.example.com/linnia", "events": [ "message.received", "invitation.accepted" ], "mode": "fat", "enabled": true, "createdAt": "2026-10-18T09:00:00.000Z" }, "secret": "whsec_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a", "note": "Verify deliveries with HMAC-SHA256 over `.` using this secret. It is not shown again." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhook", "summary": "Update a webhook endpoint", "description": "Change the URL, events or mode, or disable it. Owners and admins only (API keys count as the owner).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } }, "mode": { "type": "string", "enum": [ "fat", "thin" ] }, "enabled": { "type": "boolean" } } }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "webhook": { "$ref": "#/components/schemas/Webhook" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint", "description": "Owners and admins only (API keys count as the owner).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" }, "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listDeliveries", "summary": "Recent deliveries", "description": "The last 50 deliveries to this endpoint with attempts and the last status or error. Owners and admins only (API keys count as the owner).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventType": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] }, "attempts": { "type": "integer" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastStatus": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "example": { "ok": true, "deliveries": [ { "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "eventType": "message.received", "attempts": 1, "deliveredAt": "2026-10-18T07:41:03.000Z", "lastStatus": 200, "lastError": null, "nextAttemptAt": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/keys": { "get": { "tags": [ "API keys" ], "operationId": "listKeys", "summary": "List API keys", "description": "Every key in the organisation (never the secret). `current` is the key making this call. Owners and admins only.", "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "current": { "type": [ "string", "null" ], "format": "uuid" } } }, "example": { "ok": true, "keys": [ { "id": "3e5a7c9b-1d2f-4e6a-9b8c-7d6e5f4a3b2c", "name": "CRM sync", "prefix": "lin_AbCdEfG", "lastUsedAt": "2026-10-18T08:59:12.000Z", "revokedAt": null, "createdAt": "2026-09-30T12:00:00.000Z" } ], "current": "3e5a7c9b-1d2f-4e6a-9b8c-7d6e5f4a3b2c" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "API keys" ], "operationId": "createKey", "summary": "Create an API key", "description": "Returns the key once. Owners and admins only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "example": { "name": "CRM sync" } } } }, "responses": { "201": { "description": "Created", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "key": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" } } }, "apiKey": { "type": "string" }, "note": { "type": "string" } } }, "example": { "ok": true, "key": { "id": "3e5a7c9b-1d2f-4e6a-9b8c-7d6e5f4a3b2c", "name": "CRM sync", "prefix": "lin_AbCdEfG" }, "apiKey": "lin_AbCdEfGhIjKlMnOpQrStUvWxYz012345", "note": "Store this key; it is not shown again." } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/keys/{id}/revoke": { "post": { "tags": [ "API keys" ], "operationId": "revokeKey", "summary": "Revoke an API key", "description": "Revokes the key at once. MCP connections that were authorised with this key stop working too. Owners and admins only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "key": { "$ref": "#/components/schemas/ApiKey" }, "revokedCurrent": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "webhooks": { "job.completed": { "post": { "tags": [ "Webhook events" ], "operationId": "event_job_completed", "summary": "A job finished", "description": "Sent to every enabled endpoint subscribed to `job.completed` (or to all events). Answer with any 2xx within 10 seconds; anything else (including a redirect) is retried with backoff, up to 8 attempts. In `thin` mode `data` keeps only ids, `status`, `kind` and `type`.", "parameters": [ { "name": "linnia-event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } }, { "name": "linnia-delivery", "in": "header", "required": true, "description": "Delivery id; stays the same across retries.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linnia-signature-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed.", "schema": { "type": "string" } }, { "name": "linnia-signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `.` with your endpoint secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "4f3e2d1c-0b9a-4876-9543-21fedcba9876", "type": "job.completed", "createdAt": "2026-10-18T07:41:02.000Z", "data": { "jobId": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "connect", "status": "completed", "result": { "person": { "providerId": "ACoAAA0001", "name": "Jana Novak" }, "invitationId": "7251234567890123456", "note": "Hi Jana, enjoyed your post on RevOps hiring. Would be glad to connect.", "quality": { "score": 72, "reasons": [ "2nd-degree connection", "4 shared connections" ] } }, "error": null } } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "job.failed": { "post": { "tags": [ "Webhook events" ], "operationId": "event_job_failed", "summary": "A job failed or its approval was rejected", "description": "Sent to every enabled endpoint subscribed to `job.failed` (or to all events). Answer with any 2xx within 10 seconds; anything else (including a redirect) is retried with backoff, up to 8 attempts. In `thin` mode `data` keeps only ids, `status`, `kind` and `type`.", "parameters": [ { "name": "linnia-event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } }, { "name": "linnia-delivery", "in": "header", "required": true, "description": "Delivery id; stays the same across retries.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linnia-signature-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed.", "schema": { "type": "string" } }, { "name": "linnia-signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `.` with your endpoint secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "4f3e2d1c-0b9a-4876-9543-21fedcba9876", "type": "job.failed", "createdAt": "2026-10-18T07:41:02.000Z", "data": { "jobId": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "send_message", "status": "failed", "result": null, "error": { "type": "notConnected", "message": "You're not connected with this person." } } } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "invitation.accepted": { "post": { "tags": [ "Webhook events" ], "operationId": "event_invitation_accepted", "summary": "Someone accepted an invitation", "description": "Sent to every enabled endpoint subscribed to `invitation.accepted` (or to all events). Answer with any 2xx within 10 seconds; anything else (including a redirect) is retried with backoff, up to 8 attempts. In `thin` mode `data` keeps only ids, `status`, `kind` and `type`.", "parameters": [ { "name": "linnia-event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } }, { "name": "linnia-delivery", "in": "header", "required": true, "description": "Delivery id; stays the same across retries.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linnia-signature-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed.", "schema": { "type": "string" } }, { "name": "linnia-signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `.` with your endpoint secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "4f3e2d1c-0b9a-4876-9543-21fedcba9876", "type": "invitation.accepted", "createdAt": "2026-10-18T07:41:02.000Z", "data": { "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "invitationId": "8a9b0c1d-2e3f-4a5b-8c6d-7e8f9a0b1c2d", "providerId": "ACoAAA0001", "name": "Jana Novak", "via": "relation" } } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "message.received": { "post": { "tags": [ "Webhook events" ], "operationId": "event_message_received", "summary": "A reply arrived", "description": "Sent to every enabled endpoint subscribed to `message.received` (or to all events). Answer with any 2xx within 10 seconds; anything else (including a redirect) is retried with backoff, up to 8 attempts. In `thin` mode `data` keeps only ids, `status`, `kind` and `type`.", "parameters": [ { "name": "linnia-event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } }, { "name": "linnia-delivery", "in": "header", "required": true, "description": "Delivery id; stays the same across retries.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linnia-signature-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed.", "schema": { "type": "string" } }, { "name": "linnia-signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `.` with your endpoint secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "4f3e2d1c-0b9a-4876-9543-21fedcba9876", "type": "message.received", "createdAt": "2026-10-18T07:41:02.000Z", "data": { "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "chatId": "2-YjM4ZTQ1MjAtNzQ4ZC00", "messageId": "7251234567890999999", "senderProviderId": "ACoAAA0001", "text": "Happy to chat, does Thursday work?", "sentAt": "2026-10-18T07:41:00.000Z", "triage": { "class": "meeting", "suggestedReply": null } } } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "account.connected": { "post": { "tags": [ "Webhook events" ], "operationId": "event_account_connected", "summary": "An account finished connecting or reconnecting", "description": "Sent to every enabled endpoint subscribed to `account.connected` (or to all events). Answer with any 2xx within 10 seconds; anything else (including a redirect) is retried with backoff, up to 8 attempts. In `thin` mode `data` keeps only ids, `status`, `kind` and `type`.", "parameters": [ { "name": "linnia-event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } }, { "name": "linnia-delivery", "in": "header", "required": true, "description": "Delivery id; stays the same across retries.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linnia-signature-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed.", "schema": { "type": "string" } }, { "name": "linnia-signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `.` with your endpoint secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "4f3e2d1c-0b9a-4876-9543-21fedcba9876", "type": "account.connected", "createdAt": "2026-10-18T07:41:02.000Z", "data": { "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "tier": "sales_nav", "products": [ "sales_navigator" ], "reconnected": false } } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "account.reconnection_required": { "post": { "tags": [ "Webhook events" ], "operationId": "event_account_reconnection_required", "summary": "LinkedIn signed an account out", "description": "Sent to every enabled endpoint subscribed to `account.reconnection_required` (or to all events). Answer with any 2xx within 10 seconds; anything else (including a redirect) is retried with backoff, up to 8 attempts. In `thin` mode `data` keeps only ids, `status`, `kind` and `type`.", "parameters": [ { "name": "linnia-event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } }, { "name": "linnia-delivery", "in": "header", "required": true, "description": "Delivery id; stays the same across retries.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linnia-signature-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed.", "schema": { "type": "string" } }, { "name": "linnia-signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `.` with your endpoint secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "4f3e2d1c-0b9a-4876-9543-21fedcba9876", "type": "account.reconnection_required", "createdAt": "2026-10-18T07:41:02.000Z", "data": { "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "reason": "Session expired", "needsHuman": true } } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "account.paused": { "post": { "tags": [ "Webhook events" ], "operationId": "event_account_paused", "summary": "An account was paused", "description": "Sent to every enabled endpoint subscribed to `account.paused` (or to all events). Answer with any 2xx within 10 seconds; anything else (including a redirect) is retried with backoff, up to 8 attempts. In `thin` mode `data` keeps only ids, `status`, `kind` and `type`.", "parameters": [ { "name": "linnia-event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } }, { "name": "linnia-delivery", "in": "header", "required": true, "description": "Delivery id; stays the same across retries.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linnia-signature-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed.", "schema": { "type": "string" } }, { "name": "linnia-signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `.` with your endpoint secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "4f3e2d1c-0b9a-4876-9543-21fedcba9876", "type": "account.paused", "createdAt": "2026-10-18T07:41:02.000Z", "data": { "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "reason": "Paused by an admin" } } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } }, "account.resumed": { "post": { "tags": [ "Webhook events" ], "operationId": "event_account_resumed", "summary": "An account was resumed", "description": "Sent to every enabled endpoint subscribed to `account.resumed` (or to all events). Answer with any 2xx within 10 seconds; anything else (including a redirect) is retried with backoff, up to 8 attempts. In `thin` mode `data` keeps only ids, `status`, `kind` and `type`.", "parameters": [ { "name": "linnia-event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] } }, { "name": "linnia-delivery", "in": "header", "required": true, "description": "Delivery id; stays the same across retries.", "schema": { "type": "string", "format": "uuid" } }, { "name": "linnia-signature-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was signed.", "schema": { "type": "string" } }, { "name": "linnia-signature", "in": "header", "required": true, "description": "Hex HMAC-SHA256 of `.` with your endpoint secret.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "4f3e2d1c-0b9a-4876-9543-21fedcba9876", "type": "account.resumed", "createdAt": "2026-10-18T07:41:02.000Z", "data": { "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "wasRestricted": false } } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the delivery." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "lin_…", "description": "An API key (`lin_…`) created in the dashboard under API keys, sent as `Authorization: Bearer lin_…`. Keys act as the organisation's owner." } }, "schemas": { "Error": { "type": "object", "required": [ "ok", "error" ], "description": "Every error has the same envelope. Read `type` in code, show `message` to people, and follow `next` when present.", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "required": [ "type", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalidParams", "personNotFound", "companyNotFound", "chatNotFound", "notFound", "alreadyConnected", "alreadyInvitedRecently", "invitationPending", "notConnected", "cannotInvite", "recipientUnavailable", "alreadyDone", "notAllowed", "limitExceeded", "linkedinLimitReached", "linkedinThrottled", "connectionCapReached", "noInmailCredits", "outsideWorkingHours", "accountPaused", "lowQualityTarget", "duplicateContent", "doNotContact", "recentlyContactedByColleague", "accountRestricted", "reconnectionRequired", "accountNotReady", "featureUnavailable", "providerUnavailable", "providerTimeout", "linkedinError", "unexpectedError", "unauthorized", "totpRequired", "rateLimited" ], "description": "Stable machine-readable error type." }, "message": { "type": "string", "description": "Human-readable explanation." }, "next": { "type": "string", "description": "What to do about it, when Linnia knows." }, "issues": { "type": "array", "items": { "type": "object" }, "description": "Validation details (only for request validation errors)." } } } }, "examples": [ { "ok": false, "error": { "type": "invalidParams", "message": "note: String must contain at most 300 character(s)" } } ] }, "Ok": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true } } }, "WorkingHours": { "type": "object", "required": [ "days", "from", "to" ], "description": "When the account may act, in its own timezone. Days: 0 = Sunday … 6 = Saturday. Default: Monday to Friday, 09:00–17:30.", "properties": { "days": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "from": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "examples": [ "09:00" ] }, "to": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "examples": [ "17:30" ] } } }, "Budget": { "type": "object", "properties": { "today": { "type": [ "integer", "null" ], "description": "Left today (null when the category has no daily limit)." }, "week": { "type": [ "integer", "null" ], "description": "Left this week (null when there is no weekly limit)." } } }, "Seats": { "type": "object", "description": "Seats are LinkedIn accounts. A connect that was started in the last hour holds a seat until it finishes or lapses.", "properties": { "used": { "type": "integer" }, "pending": { "type": "integer" }, "total": { "type": "integer", "description": "Seats on the workspace (default 1)." } } }, "Account": { "type": "object", "description": "Everything needed to plan work for one LinkedIn account: status, health, working hours and budgets left.", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "connecting", "warming", "active", "cooling", "paused", "reconnection_required", "frozen" ] }, "tier": { "type": "string", "enum": [ "free", "premium", "sales_nav", "recruiter" ] }, "products": { "type": "array", "items": { "type": "string" }, "examples": [ [ "sales_navigator" ] ] }, "health": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "green", "watch", "caution", "stop" ] }, "reason": { "type": [ "string", "null" ] }, "pausedUntil": { "type": [ "string", "null" ], "format": "date-time" }, "readsOnlyUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "After a LinkedIn restriction the account only reads until this time." } } }, "connections": { "type": [ "integer", "null" ] }, "settings": { "type": "object", "properties": { "minInviteQuality": { "type": "integer", "minimum": 0, "maximum": 100 }, "autoWithdrawDays": { "type": [ "integer", "null" ] } } }, "warmup": { "type": [ "object", "null" ], "properties": { "day": { "type": "integer" }, "of": { "type": "integer", "const": 15 } } }, "workingHours": { "allOf": [ { "$ref": "#/components/schemas/WorkingHours" } ], "type": "object", "properties": { "timezone": { "type": "string" }, "openNow": { "type": "boolean" }, "nextOpening": { "type": [ "string", "null" ], "format": "date-time" } } }, "offHoursPolicy": { "type": "string", "enum": [ "queue", "reject", "run" ] }, "mode": { "type": "string", "enum": [ "assist", "approve", "autopilot" ] }, "budgets": { "type": [ "object", "null" ], "additionalProperties": { "$ref": "#/components/schemas/Budget" }, "description": "Budget left per category; null until the account is connected." }, "pendingInvitations": { "type": "integer" }, "reconnectUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Set when the account needs a person to sign in to LinkedIn again." }, "connectedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "examples": [ { "id": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "label": "Emma (US SDR)", "status": "warming", "tier": "sales_nav", "products": [ "sales_navigator" ], "health": { "level": "green", "reason": null, "pausedUntil": null, "readsOnlyUntil": null }, "connections": 1840, "settings": { "minInviteQuality": 30, "autoWithdrawDays": 21 }, "warmup": { "day": 4, "of": 15 }, "workingHours": { "days": [ 1, 2, 3, 4, 5 ], "from": "09:00", "to": "17:30", "timezone": "America/New_York", "openNow": true, "nextOpening": null }, "offHoursPolicy": "queue", "mode": "approve", "budgets": { "invites": { "today": 9, "week": 41 }, "messages": { "today": 27, "week": null }, "profile_views": { "today": 52, "week": null } }, "pendingInvitations": 12, "reconnectUrl": null, "connectedAt": "2026-10-13T14:02:11.000Z" } ] }, "Job": { "type": "object", "description": "A command becomes a job. Writes return at once and run later, paced by the Governor; poll with `GET /v1/jobs/{id}?wait=…` or subscribe to `job.completed` / `job.failed` webhooks.", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "The command name, or `workflow`.", "examples": [ "connect" ] }, "status": { "type": "string", "enum": [ "awaiting_approval", "queued", "scheduled", "running", "completed", "failed", "cancelled" ] }, "approval": { "type": [ "object", "null" ], "description": "Set while a person needs to approve this job.", "properties": { "id": { "type": "string", "format": "uuid" }, "summary": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "input": { "type": "object", "description": "The validated, normalised input." }, "result": { "description": "The outcome once completed. Shape depends on the command." }, "error": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "invalidParams", "personNotFound", "companyNotFound", "chatNotFound", "notFound", "alreadyConnected", "alreadyInvitedRecently", "invitationPending", "notConnected", "cannotInvite", "recipientUnavailable", "alreadyDone", "notAllowed", "limitExceeded", "linkedinLimitReached", "linkedinThrottled", "connectionCapReached", "noInmailCredits", "outsideWorkingHours", "accountPaused", "lowQualityTarget", "duplicateContent", "doNotContact", "recentlyContactedByColleague", "accountRestricted", "reconnectionRequired", "accountNotReady", "featureUnavailable", "providerUnavailable", "providerTimeout", "linkedinError", "unexpectedError", "unauthorized", "totpRequired", "rateLimited" ] }, "message": { "type": "string" }, "next": { "type": "string" } } }, "eta": { "type": [ "string", "null" ], "format": "date-time", "description": "Earliest time Linnia plans to run it." }, "waitingOn": { "type": [ "string", "null" ], "description": "Why it hasn't run yet (outside working hours, budget, approval…)." }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "examples": [ { "id": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "kind": "connect", "status": "awaiting_approval", "approval": { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "expiresAt": "2026-10-21T09:14:03.000Z" }, "input": { "person": "jana-novak", "note": "Hi Jana, enjoyed your post on RevOps hiring. Would be glad to connect." }, "result": null, "error": null, "eta": "2026-10-18T09:14:03.000Z", "waitingOn": "Waiting for a person to approve: Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”", "createdAt": "2026-10-18T09:14:03.000Z", "finishedAt": null } ] }, "JobResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "created": { "type": "boolean", "description": "false when an identical request (same idempotency key) already made this job." }, "job": { "$ref": "#/components/schemas/Job" } } }, "Approval": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "jobId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "preview": { "type": "object", "properties": { "command": { "type": "string" }, "target": { "type": "string" }, "text": { "type": "string" }, "summary": { "type": "string" } } }, "editedText": { "type": [ "string", "null" ] }, "requestedBy": { "type": [ "string", "null" ], "examples": [ "mcp:claude-ai" ] }, "decidedBy": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "72 hours after the request." }, "createdAt": { "type": "string", "format": "date-time" } }, "examples": [ { "id": "b2e4f6a8-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "status": "pending", "jobId": "0c9b6d3e-12f4-4a8b-b5e1-7d2c9f0a6e13", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "preview": { "command": "connect", "target": "Jana Novak, VP Sales at Northwind", "text": "Hi Jana, enjoyed your post on RevOps hiring. Would be glad to connect.", "summary": "Connection request to Jana Novak, VP Sales at Northwind: “Hi Jana, enjoyed your post on RevOps hiring…”" }, "editedText": null, "requestedBy": "mcp:claude-ai", "decidedBy": null, "decidedAt": null, "expiresAt": "2026-10-21T09:14:03.000Z", "createdAt": "2026-10-18T09:14:03.000Z" } ] }, "AutomationStep": { "oneOf": [ { "type": "object", "title": "wait", "required": [ "action" ], "properties": { "action": { "const": "wait" }, "workingDays": { "type": "integer", "minimum": 0, "maximum": 30 }, "days": { "type": "number", "minimum": 0, "maximum": 30 }, "hours": { "type": "number", "minimum": 0, "maximum": 720 } }, "description": "Needs one of workingDays, days or hours." }, { "type": "object", "title": "send_message", "required": [ "action", "text" ], "properties": { "action": { "const": "send_message" }, "text": { "type": "string", "minLength": 1, "maxLength": 1900, "description": "May use {{first_name}} and {{company}}." } } }, { "type": "object", "title": "connect", "required": [ "action" ], "properties": { "action": { "const": "connect" }, "note": { "type": "string", "maxLength": 300 } }, "description": "Not allowed after an `invitation.accepted` trigger." } ], "discriminator": { "propertyName": "action" } }, "AutomationTrigger": { "type": "object", "required": [ "event" ], "properties": { "event": { "type": "string", "enum": [ "invitation.accepted", "message.received" ] }, "sourceJobId": { "type": "string", "format": "uuid", "description": "Only people first touched by this job enter the automation." } } }, "Automation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "trigger": { "$ref": "#/components/schemas/AutomationTrigger" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationStep" } }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "runs": { "type": "object", "properties": { "waiting": { "type": "integer" }, "completed": { "type": "integer" }, "stopped": { "type": "integer" } } }, "createdAt": { "type": "string", "format": "date-time" } }, "examples": [ { "id": "5a7c9e1b-3d5f-4a6b-8c0d-2e4f6a8b0c1d", "accountId": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44", "name": "Thank new connections", "trigger": { "event": "invitation.accepted" }, "steps": [ { "action": "wait", "workingDays": 2 }, { "action": "send_message", "text": "Thanks for connecting, {{first_name}}. How is the quarter going at {{company}}?" } ], "status": "active", "runs": { "waiting": 3, "completed": 11, "stopped": 2 }, "createdAt": "2026-10-10T08:00:00.000Z" } ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] }, "description": "Empty means every event." }, "mode": { "type": "string", "enum": [ "fat", "thin" ], "description": "`fat` sends the full event data; `thin` sends only ids, status, kind and type." }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "createdAt", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id. The same event delivered to several endpoints has the same id; use it to de-duplicate." }, "type": { "type": "string", "enum": [ "job.completed", "job.failed", "invitation.accepted", "message.received", "account.connected", "account.reconnection_required", "account.paused", "account.resumed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "First 11 characters, e.g. `lin_AbCdEfG`." }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "TimelineEntry": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "touch", "invitation", "reply", "note", "automation", "approval" ] }, "accountId": { "type": [ "string", "null" ], "format": "uuid" }, "accountLabel": { "type": [ "string", "null" ] }, "summary": { "type": "string" }, "detail": { "type": "object" } } }, "NativeConnectResult": { "type": "object", "description": "Either `connected`, or a LinkedIn checkpoint to complete with `native-checkpoint`.", "properties": { "ok": { "type": "boolean", "const": true }, "kind": { "type": "string", "enum": [ "connected", "checkpoint" ] }, "providerAccountId": { "type": "string" }, "checkpoint": { "type": "string", "description": "Checkpoint type, e.g. 2FA, OTP, CAPTCHA, IN_APP_VALIDATION, OTP_OR_IN_APP_VALIDATION, PHONE_REGISTER, PAIRING_CODE, CONTRACT_SELECTION, CHALLENGE_SELECTION." }, "publicKey": { "type": [ "string", "null" ], "description": "CAPTCHA public key." }, "data": { "type": [ "string", "null" ], "description": "CAPTCHA data blob." }, "pairingCode": { "type": [ "string", "null" ], "description": "Code to show the person (PAIRING_CODE). Do not send it back." }, "channel": { "type": [ "string", "null" ], "description": "Where an OTP or 2FA code was sent, when known." }, "platform": { "type": [ "string", "null" ] }, "contracts": { "type": "array", "items": { "type": "object" } }, "products": { "type": "array", "items": { "type": "object" } }, "challenges": { "type": "array", "items": { "type": "object" } }, "provider": { "type": "string" } }, "examples": [ { "ok": true, "kind": "checkpoint", "providerAccountId": "kL9xQ2mN", "checkpoint": "2FA", "channel": "SMS", "provider": "unipile-v1" } ] } }, "responses": { "BadRequest": { "description": "Invalid input, or a record that doesn't exist (`invalidParams`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation": { "value": { "ok": false, "error": { "type": "invalidParams", "message": "note: String must contain at most 300 character(s)" } } }, "noSuchAccount": { "value": { "ok": false, "error": { "type": "invalidParams", "message": "No such account." } } } } } } }, "Unauthorized": { "description": "Missing, unknown, revoked or expired credential; or a signed-in person who still has to enter their two-factor code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "value": { "ok": false, "error": { "type": "unauthorized", "message": "Send your API key as `Authorization: Bearer lin_…`, or sign in." } } }, "unknown": { "value": { "ok": false, "error": { "type": "unauthorized", "message": "Unknown, revoked or expired credential." } } }, "totp": { "value": { "ok": false, "error": { "type": "totpRequired", "message": "Enter your two-factor code to continue." } } } } } } }, "Forbidden": { "description": "The caller isn't allowed to do this (for example a member using an owner/admin endpoint).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "member": { "value": { "ok": false, "error": { "type": "notAllowed", "message": "Only owners and admins can do this." } } } } } } }, "NotFound": { "description": "Malformed id, or no such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "notFound": { "value": { "ok": false, "error": { "type": "notFound", "message": "Not found." } } } } } } }, "Conflict": { "description": "The account can't act right now (not connected yet, needs reconnection, paused, or outside working hours with `offHoursPolicy: reject`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reconnect": { "value": { "ok": false, "error": { "type": "reconnectionRequired", "message": "LinkedIn signed this account out.", "next": "Ask the rep to reconnect from the Linnia dashboard." } } }, "paused": { "value": { "ok": false, "error": { "type": "accountPaused", "message": "The account is paused." } } } } } } }, "Unprocessable": { "description": "Refused for a business reason: any error type without its own status, for example `notAllowed` (such as all seats in use), `featureUnavailable` or a guardrail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "seats": { "value": { "ok": false, "error": { "type": "notAllowed", "message": "All 1 seat is in use. Remove an account, or contact Linnia to add seats." } } } } } } }, "RateLimited": { "description": "Too many requests for this credential, or a budget/LinkedIn limit was hit (`limitExceeded`, `linkedinLimitReached`, `linkedinThrottled`).", "headers": { "ratelimit-limit": { "$ref": "#/components/headers/RateLimitLimit" }, "ratelimit-remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "ratelimit-reset": { "$ref": "#/components/headers/RateLimitReset" }, "retry-after": { "schema": { "type": "integer" }, "description": "Seconds until the window resets (request rate limit only)." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rateLimited": { "value": { "ok": false, "error": { "type": "rateLimited", "message": "Too many requests: 600 per minute per credential.", "next": "Retry in 42s. Reads of job status can use ?wait= instead of polling." } } }, "budget": { "value": { "ok": false, "error": { "type": "limitExceeded", "message": "Daily invitation budget used up for this account." } } } } } } }, "ServerError": { "description": "Something went wrong on Linnia's side, or LinkedIn's provider was unavailable (503) or timed out (504).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unexpected": { "value": { "ok": false, "error": { "type": "unexpectedError", "message": "Something went wrong on our side." } } } } } } } }, "parameters": { "AccountId": { "name": "id", "in": "path", "required": true, "description": "Account id (from `GET /v1/accounts`).", "schema": { "type": "string", "format": "uuid" }, "example": "6f1c2a9e-4b7d-4c1e-9a53-2f8e0d7b1c44" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Up to 200 characters. A repeat with the same key on the same account returns the original job (200, `created: false`). Without it, Linnia de-duplicates identical commands within 15 minutes.", "schema": { "type": "string", "maxLength": 200 } }, "ClientName": { "name": "X-Linnia-Client", "in": "header", "required": false, "description": "Optional name of your integration, recorded on the job (defaults to `rest`).", "schema": { "type": "string" } }, "AccountFilter": { "name": "account", "in": "query", "required": false, "description": "Only this account.", "schema": { "type": "string", "format": "uuid" } }, "Limit200": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } }, "headers": { "RateLimitLimit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer" }, "example": 600 }, "RateLimitRemaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" }, "example": 598 }, "RateLimitReset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" }, "example": 42 } } } }