{"openapi":"3.0.3","info":{"title":"GenuineLink Public API","version":"1.0.0","description":"Company-scoped REST API with optional agency access via agency tokens + X-Company-Id. Production API host: app.genuinelink.ai (same-origin on developer/app hosts locally)."},"servers":[{"url":"https://developer.genuinelink.ai","description":"Current host"},{"url":"https://app.genuinelink.ai","description":"Production (app.genuinelink.ai)"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Company key `glc_…` or agency key `gla_…` from Account/Agency settings."}}},"tags":[{"name":"Auth"},{"name":"Agency"},{"name":"Campaigns"},{"name":"Lists"},{"name":"Leads"},{"name":"Inbox"},{"name":"Accounts"},{"name":"Stats"},{"name":"Webhooks"}],"x-webhook-events":{"live":["CONNECTION_REQUEST_SENT","CONNECTION_REQUEST_ACCEPTED","MESSAGE_SENT","MESSAGE_REPLY_RECEIVED","EVERY_MESSAGE_REPLY_RECEIVED","CAMPAIGN_COMPLETED","LEAD_TAG_UPDATED"],"stubbed":["INMAIL_SENT","INMAIL_REPLY_RECEIVED","FOLLOW_SENT","LIKE_SENT","PROFILE_VIEWED"]},"paths":{"/api/v1/auth/check":{"get":{"operationId":"checkApiKey","summary":"Check API key","description":"Validates the Bearer API key supplied in the `Authorization` header and returns metadata about its scope and identity. Use this endpoint to verify credentials before integrating other endpoints, or to distinguish company keys (`glc_…`) from agency keys (`gla_…`).\n\nNo `X-Company-Id` header is required — this endpoint introspects the key itself.","tags":["Auth"],"security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"OK. Agency API key (`gla_…`).","content":{"application/json":{"schema":{"type":"object","description":"API key validation result.","properties":{"valid":{"type":"boolean","description":"Always true on a successful check.","example":true},"scope":{"type":"string","description":"Whether the key is scoped to a company or agency.","enum":["COMPANY","AGENCY"],"example":"COMPANY"},"apiKeyId":{"type":"string","description":"Opaque public API key record identifier.","example":"pV3xB8gA1uWc"},"apiKeyName":{"type":"string","description":"Label given to the key in settings.","example":"Production integration"},"companyAccountId":{"type":"string","description":"Opaque public company account ID when scope is COMPANY (or agency + X-Company-Id).","nullable":true,"example":"pT1vZ6eY9sUa"},"agencyId":{"type":"string","description":"Opaque public agency ID. Present when scope is AGENCY, or when scope is COMPANY and the company belongs to an agency. Null for independent company accounts.","nullable":true,"example":null}},"required":["valid","scope","apiKeyId","apiKeyName"]},"example":{"valid":true,"scope":"AGENCY","apiKeyId":"pW4yC9hB2vXd","apiKeyName":"Agency production","companyAccountId":null,"agencyId":"pX5zD0iC3wYe"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]}}}},"/api/v1/agency/companies":{"get":{"operationId":"listAgencyCompanies","summary":"List agency companies","description":"Returns all client company accounts managed by the authenticated agency. This endpoint is only available with an agency API key (`gla_…`). Use the returned `id` values as `X-Company-Id` when calling company-scoped endpoints on behalf of a client.\n\nCompany API keys (`glc_…`) are not permitted on this endpoint.","tags":["Agency"],"security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Client companies owned by the agency.","items":{"type":"object","description":"A client company managed by the agency.","properties":{"id":{"type":"string","description":"Opaque public company account identifier.","example":"pU2wA7fZ0tVb"},"name":{"type":"string","description":"Internal account name.","example":"Acme Corp"},"companyName":{"type":"string","description":"Public company display name.","nullable":true,"example":"Acme Corporation"},"status":{"type":"string","description":"Account status.","enum":["PENDING","ACTIVE","SUSPENDED","DELETED"],"example":"ACTIVE"},"timezone":{"type":"string","description":"Default timezone.","nullable":true,"example":"Europe/Amsterdam"},"websiteUrl":{"type":"string","description":"Company website URL.","nullable":true,"example":"https://acme.com"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-01-15T09:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-10T11:30:00.000Z"}},"required":["id","name","status","createdAt","updatedAt"]}}},"required":["items"]},"example":{"items":[{"id":"pU2wA7fZ0tVb","name":"Acme Corp","companyName":"Acme Corporation","status":"ACTIVE","timezone":"Europe/Amsterdam","websiteUrl":"https://acme.com","createdAt":"2026-01-15T09:00:00.000Z","updatedAt":"2026-07-10T11:30:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"This endpoint requires an agency API key"}}}},"x-error-examples":[{"title":"Company key not allowed","type":"errors/agency_only","description":"This endpoint requires an agency API key (`gla_…`). Company keys are not permitted.","example":{"error":{"code":"forbidden","message":"This endpoint requires an agency API key"}}}]}}}},"/api/v1/campaigns":{"get":{"operationId":"listCampaigns","summary":"List campaigns","description":"Returns a paginated list of outreach campaigns for the authenticated company account. Use query filters to narrow by lifecycle status or search campaign names. Results are ordered by most recently updated first.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"description":"Filter campaigns by lifecycle status. When omitted, all non-archived statuses are returned."},{"name":"keyword","in":"query","required":false,"schema":{"type":"string","example":"outbound"},"description":"Case-insensitive substring match against the campaign name. Useful for quick search in large workspaces."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"example":50},"description":"Maximum number of campaigns to return in a single page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"example":0},"description":"Number of campaigns to skip before returning results. Use with `limit` for pagination."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Campaigns for the current page.","items":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]}},"total":{"type":"integer","description":"Total campaigns matching the filter (across all pages).","example":2},"limit":{"type":"integer","description":"Page size that was applied.","example":50},"offset":{"type":"integer","description":"Offset that was applied.","example":0}},"required":["items","total","limit","offset"]},"example":{"items":[{"id":"p7Kq2mXn9vLw","name":"Q3 outbound — SaaS founders","status":"ACTIVE","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false},{"id":"p8Lr3nYo0wMx","name":"Recruiting — senior engineers","status":"PAUSED","settings":null,"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":"pM4oS9xR2lNt","priority":"MEDIUM","createdAt":"2026-05-12T09:15:00.000Z","updatedAt":"2026-07-18T11:02:44.000Z","archived":false}],"total":2,"limit":50,"offset":0}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"Invalid status filter"}}}},"x-error-examples":[{"title":"Invalid status","type":"errors/invalid_status","description":"`status` must be one of DRAFT, ACTIVE, PAUSED, COMPLETED, or INITIALIZE.","example":{"error":{"code":"bad_request","message":"Invalid status filter"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency’s clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]}}},"post":{"operationId":"createCampaign","summary":"Create campaign draft","description":"Creates a new outreach campaign in `DRAFT` status. Provide a name and the LinkedIn account that will send the campaign. Optionally attach a lead list and configure the sending schedule in the same request.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"My campaign","linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"timezone":"UTC","startHour":7,"endHour":20,"workOnWeekends":false,"startDate":null,"endDate":null}}}},"responses":{"200":{"description":"OK. Campaign created.","content":{"application/json":{"schema":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]},"example":{"id":"p7Kq2mXn9vLw","name":"Q3 outbound — SaaS founders","status":"DRAFT","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"name is required"}}}},"x-error-examples":[{"title":"Missing name","type":"errors/invalid_name","description":"The `name` field is required and must be a non-empty string.","example":{"error":{"code":"bad_request","message":"name is required"}}},{"title":"Invalid LinkedIn account","type":"errors/invalid_linkedin_account","description":"The `linkedinAccountId` does not exist or is not connected for this company.","example":{"error":{"code":"bad_request","message":"linkedinAccountId is invalid for this company"}}},{"title":"Invalid lead list","type":"errors/invalid_leadlist","description":"The optional `leadlistId` does not reference an existing list for this company.","example":{"error":{"code":"bad_request","message":"leadlistId is invalid for this company"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]}}}},"/api/v1/campaigns/{campaignId}":{"get":{"operationId":"getCampaign","summary":"Get campaign","description":"Retrieves a single campaign by ID, including its current status, settings, and linked resources.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]},"example":{"id":"p7Kq2mXn9vLw","name":"Q3 outbound — SaaS founders","status":"ACTIVE","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}},"delete":{"operationId":"archiveCampaign","summary":"Archive campaign","description":"Soft-deletes (archives) a campaign. Archived campaigns are excluded from default list queries and can no longer be started or resumed.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign to archive."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Campaign archived.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success.","example":true}},"required":["success"]},"example":{"success":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}}},"/api/v1/campaigns/{campaignId}/start":{"post":{"operationId":"startCampaign","summary":"Start campaign","description":"Transitions a campaign to `ACTIVE` status and begins outreach according to its sequence and schedule. The campaign must have a LinkedIn account, lead list, and configured sequence before starting.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign to start."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Campaign started.","content":{"application/json":{"schema":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]},"example":{"id":"p7Kq2mXn9vLw","name":"Q3 outbound — SaaS founders","status":"ACTIVE","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"Campaign is not ready to start"}}}},"x-error-examples":[{"title":"Campaign not ready","type":"errors/campaign_not_ready","description":"The campaign is missing required configuration (sequence, leads, or LinkedIn account).","example":{"error":{"code":"bad_request","message":"Campaign is not ready to start"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}}},"/api/v1/campaigns/{campaignId}/pause":{"post":{"operationId":"pauseCampaign","summary":"Pause campaign","description":"Pauses an active campaign. No new outreach actions are dispatched while paused, but the campaign retains its queue and can be resumed later.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign to pause."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Campaign paused.","content":{"application/json":{"schema":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]},"example":{"id":"p7Kq2mXn9vLw","name":"Q3 outbound — SaaS founders","status":"PAUSED","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"Campaign is not active"}}}},"x-error-examples":[{"title":"Invalid status transition","type":"errors/invalid_status_transition","description":"Only active campaigns can be paused.","example":{"error":{"code":"bad_request","message":"Campaign is not active"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}}},"/api/v1/campaigns/{campaignId}/resume":{"post":{"operationId":"resumeCampaign","summary":"Resume campaign","description":"Resumes a paused campaign, transitioning it back to `ACTIVE` and continuing outreach from where it left off.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign to resume."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Campaign resumed.","content":{"application/json":{"schema":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]},"example":{"id":"p7Kq2mXn9vLw","name":"Q3 outbound — SaaS founders","status":"ACTIVE","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"Campaign is not paused"}}}},"x-error-examples":[{"title":"Invalid status transition","type":"errors/invalid_status_transition","description":"Only paused campaigns can be resumed.","example":{"error":{"code":"bad_request","message":"Campaign is not paused"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}}},"/api/v1/campaigns/{campaignId}/settings":{"patch":{"operationId":"updateCampaignSettings","summary":"Update campaign settings","description":"Updates general campaign settings such as the display name and attached lead list. Only the fields you include in the request body are changed.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Renamed campaign","leadlistId":null}}}},"responses":{"200":{"description":"OK. Settings updated.","content":{"application/json":{"schema":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]},"example":{"id":"p7Kq2mXn9vLw","name":"Renamed campaign","status":"ACTIVE","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"name cannot be empty"}}}},"x-error-examples":[{"title":"Invalid name","type":"errors/invalid_name","description":"When provided, `name` must be a non-empty string.","example":{"error":{"code":"bad_request","message":"name cannot be empty"}}},{"title":"Invalid lead list","type":"errors/invalid_leadlist","description":"The `leadlistId` does not reference an existing list.","example":{"error":{"code":"bad_request","message":"leadlistId is invalid"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}}},"/api/v1/campaigns/{campaignId}/schedule":{"patch":{"operationId":"updateCampaignSchedule","summary":"Update campaign schedule","description":"Updates the sending schedule for a campaign, including timezone, daily sending window, weekend behavior, and optional start/end dates. Only the fields you include in the request body are changed.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false,"startDate":null,"endDate":null}}}},"responses":{"200":{"description":"OK. Schedule updated.","content":{"application/json":{"schema":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]},"example":{"id":"p7Kq2mXn9vLw","name":"Q3 outbound — SaaS founders","status":"ACTIVE","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"Invalid timezone"}}}},"x-error-examples":[{"title":"Invalid timezone","type":"errors/invalid_timezone","description":"`timezone` must be a valid IANA timezone identifier.","example":{"error":{"code":"bad_request","message":"Invalid timezone"}}},{"title":"Invalid hours","type":"errors/invalid_hours","description":"`startHour` and `endHour` must be integers between 0 and 23, with start before end.","example":{"error":{"code":"bad_request","message":"Invalid sending hours"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}}},"/api/v1/campaigns/{campaignId}/accounts":{"patch":{"operationId":"updateCampaignAccounts","summary":"Update campaign LinkedIn account","description":"Assigns or changes the LinkedIn sender account used by the campaign. The account must be connected and belong to the authenticated company.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"linkedinAccountId":"pL3nR8wQ1kMs"}}}},"responses":{"200":{"description":"OK. LinkedIn account updated.","content":{"application/json":{"schema":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]},"example":{"id":"p7Kq2mXn9vLw","name":"Q3 outbound — SaaS founders","status":"ACTIVE","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"linkedinAccountId is invalid"}}}},"x-error-examples":[{"title":"Invalid LinkedIn account","type":"errors/invalid_linkedin_account","description":"The `linkedinAccountId` does not exist or is not connected for this company.","example":{"error":{"code":"bad_request","message":"linkedinAccountId is invalid"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}}},"/api/v1/campaigns/{campaignId}/sequence":{"get":{"operationId":"getCampaignSequence","summary":"Get campaign sequence","description":"Returns the outreach sequence graph for a campaign, including all nodes (steps) and edges (transitions). Use this to inspect or replicate the campaign workflow programmatically.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","description":"Campaign identifier.","example":"p7Kq2mXn9vLw"},"sequenceId":{"type":"string","description":"Opaque public sequence identifier, if assigned.","nullable":true,"example":"pA1bC2dE3fGh"},"nodes":{"type":"array","description":"Sequence step nodes.","items":{"type":"object","properties":{"id":{"type":"string","example":"pB2cD3eF4gHi"},"type":{"type":"string","example":"SEND_INVITE"},"position":{"type":"object","description":"Canvas position {x, y}."},"data":{"type":"object","description":"Step-specific configuration payload."}}}},"edges":{"type":"array","description":"Transitions between sequence nodes.","items":{"type":"object","properties":{"id":{"type":"string","example":"pC3dE4fG5hIj"},"source":{"type":"string","example":"pB2cD3eF4gHi"},"target":{"type":"string","example":"pD4eF5gH6iJk"},"data":{"type":"object","description":"Edge-specific configuration payload."}}}}},"required":["campaignId","nodes","edges"]},"example":{"campaignId":"p7Kq2mXn9vLw","sequenceId":"pA1bC2dE3fGh","nodes":[{"id":"pB2cD3eF4gHi","type":"SEND_INVITE","position":{"x":0,"y":0},"data":{}},{"id":"pD4eF5gH6iJk","type":"SEND_MESSAGE","position":{"x":200,"y":0},"data":{"text":"Hi {{firstName}}!"}}],"edges":[{"id":"pC3dE4fG5hIj","source":"pB2cD3eF4gHi","target":"pD4eF5gH6iJk","data":{}}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}}},"/api/v1/campaigns/{campaignId}/leads":{"get":{"operationId":"getCampaignLeads","summary":"Get campaign leads","description":"Returns a paginated list of leads enrolled in the campaign's attached lead list. Results include basic lead fields and their current status within the campaign.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"example":50},"description":"Maximum number of records to return in a single page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"example":0},"description":"Number of records to skip before returning results. Use with `limit` for pagination."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Leads for the current page.","items":{"type":"object","description":"A lead row as returned in campaign or list lead listings.","properties":{"id":{"type":"string","description":"Opaque public lead identifier.","example":"pO6qU1zT4nPv"},"firstName":{"type":"string","description":"Lead first name.","nullable":true,"example":"Jane"},"lastName":{"type":"string","description":"Lead last name.","nullable":true,"example":"Doe"},"linkedinUrl":{"type":"string","description":"LinkedIn profile URL.","example":"https://www.linkedin.com/in/jane-doe"},"email":{"type":"string","description":"Email address.","nullable":true,"example":"jane@acme.com"},"company":{"type":"string","description":"Company name.","nullable":true,"example":"Acme"},"title":{"type":"string","description":"Job title.","nullable":true,"example":"CEO"},"status":{"type":"string","description":"Lead status within the list or campaign.","enum":["NEW","CONTACTED","RESPONDED","QUALIFIED","CONVERTED","REJECTED","DUPLICATE","FAILED","INVITED","ACCEPTED","WITHDRAWN","IN_NETWORK","IN_SEQUENCE","DISCONNECTED"],"example":"NEW"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"}},"required":["id","linkedinUrl","status","createdAt"]}},"total":{"type":"integer","description":"Total records matching the filter (across all pages).","example":2},"limit":{"type":"integer","description":"Page size that was applied.","example":50},"offset":{"type":"integer","description":"Offset that was applied.","example":0}},"required":["items","total","limit","offset"]},"example":{"items":[{"id":"pO6qU1zT4nPv","firstName":"Jane","lastName":"Doe","linkedinUrl":"https://www.linkedin.com/in/jane-doe","email":"jane@acme.com","company":"Acme","title":"CEO","status":"NEW","createdAt":"2026-06-01T10:00:00.000Z"}],"total":1,"limit":50,"offset":0}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}},"post":{"operationId":"addLeadsToCampaign","summary":"Add leads to campaign","description":"Adds one or more leads to the campaign's lead list by LinkedIn URL. Existing leads with the same URL are deduplicated. Optional profile fields (name, email, company, etc.) enrich the lead record.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"leads":[{"linkedinUrl":"https://www.linkedin.com/in/jane-doe","firstName":"Jane","lastName":"Doe","email":"jane@acme.com","phone":null,"company":"Acme","title":"CEO","location":"Amsterdam, NL"}]}}}},"responses":{"200":{"description":"OK. Leads processed.","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string","description":"Campaign identifier.","example":"p7Kq2mXn9vLw"},"listId":{"type":"string","description":"Lead list ID leads were added to.","example":"pN5pT0yS3mOu"},"submitted":{"type":"integer","description":"Number of leads submitted in the request.","example":1},"added":{"type":"integer","description":"Number of new leads actually added (after deduplication).","example":1},"totalInList":{"type":"integer","description":"Total leads now in the list.","example":153}},"required":["campaignId","listId","submitted","added","totalInList"]},"example":{"campaignId":"p7Kq2mXn9vLw","listId":"pN5pT0yS3mOu","submitted":1,"added":1,"totalInList":153}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"leads must include at least one linkedinUrl"}}}},"x-error-examples":[{"title":"Invalid leads array","type":"errors/invalid_leads","description":"`leads` must be a non-empty array with at least one object containing `linkedinUrl`.","example":{"error":{"code":"bad_request","message":"leads must include at least one linkedinUrl"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_not_found","description":"Campaign not found","example":{"error":{"code":"not_found","message":"Campaign not found"}}}]}}}},"/api/v1/campaigns/{campaignId}/leads/{leadId}/stop":{"post":{"operationId":"stopLeadInCampaign","summary":"Stop lead in campaign","description":"Stops outreach for a specific lead within a campaign. The lead remains in the list but will no longer receive sequence actions.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the campaign."},{"name":"leadId","in":"path","required":true,"schema":{"type":"string","example":"pO6qU1zT4nPv"},"description":"Unique identifier of the lead to stop."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Lead stopped.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success.","example":true},"leadId":{"type":"string","description":"Lead identifier.","example":"pO6qU1zT4nPv"},"campaignId":{"type":"string","description":"Campaign identifier.","example":"p7Kq2mXn9vLw"}},"required":["success","leadId","campaignId"]},"example":{"success":true,"leadId":"pO6qU1zT4nPv","campaignId":"p7Kq2mXn9vLw"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Campaign or lead not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/campaign_lead_not_found","description":"Campaign or lead not found","example":{"error":{"code":"not_found","message":"Campaign or lead not found"}}}]}}}},"/api/v1/lists":{"get":{"operationId":"listLists","summary":"List all lists","description":"Returns a paginated list of lead lists for the authenticated company account. Use the `keyword` filter to search by list name.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Lists"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"keyword","in":"query","required":false,"schema":{"type":"string","example":"clay"},"description":"Case-insensitive substring match against the list name."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"example":50},"description":"Maximum number of records to return in a single page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"example":0},"description":"Number of records to skip before returning results. Use with `limit` for pagination."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Lead lists for the current page.","items":{"type":"object","description":"A lead list belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public list identifier.","example":"pN5pT0yS3mOu"},"name":{"type":"string","description":"Display name of the list (derived from fileName).","example":"Inbound Clay list"},"totalLeads":{"type":"integer","description":"Number of leads currently in the list.","example":152},"status":{"type":"string","description":"Processing status of the list.","example":"COMPLETED"},"campaignId":{"type":"string","description":"Opaque public campaign ID if the list is attached to a campaign.","nullable":true,"example":null},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"}},"required":["id","name","totalLeads","status","createdAt","updatedAt"]}},"total":{"type":"integer","description":"Total records matching the filter (across all pages).","example":2},"limit":{"type":"integer","description":"Page size that was applied.","example":50},"offset":{"type":"integer","description":"Offset that was applied.","example":0}},"required":["items","total","limit","offset"]},"example":{"items":[{"id":"pN5pT0yS3mOu","name":"Inbound Clay list","totalLeads":152,"status":"COMPLETED","campaignId":null,"createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z"}],"total":1,"limit":50,"offset":0}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]}}},"post":{"operationId":"createEmptyList","summary":"Create empty list","description":"Creates a new empty lead list with the given name. Use `addLeadsToList` to populate it with leads.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Lists"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Inbound Clay list"}}}},"responses":{"200":{"description":"OK. List created.","content":{"application/json":{"schema":{"type":"object","description":"A lead list belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public list identifier.","example":"pN5pT0yS3mOu"},"name":{"type":"string","description":"Display name of the list (derived from fileName).","example":"Inbound Clay list"},"totalLeads":{"type":"integer","description":"Number of leads currently in the list.","example":152},"status":{"type":"string","description":"Processing status of the list.","example":"COMPLETED"},"campaignId":{"type":"string","description":"Opaque public campaign ID if the list is attached to a campaign.","nullable":true,"example":null},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"}},"required":["id","name","totalLeads","status","createdAt","updatedAt"]},"example":{"id":"pN5pT0yS3mOu","name":"Inbound Clay list","totalLeads":0,"status":"COMPLETED","campaignId":null,"createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-06-01T10:00:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"name is required"}}}},"x-error-examples":[{"title":"Invalid name","type":"errors/invalid_name","description":"The `name` field is required and must be a non-empty string.","example":{"error":{"code":"bad_request","message":"name is required"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]}}}},"/api/v1/lists/{listId}":{"get":{"operationId":"getList","summary":"Get list","description":"Retrieves a single lead list by ID, including its name, lead count, and status.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Lists"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string","example":"pN5pT0yS3mOu"},"description":"Unique identifier of the lead list."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","description":"A lead list belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public list identifier.","example":"pN5pT0yS3mOu"},"name":{"type":"string","description":"Display name of the list (derived from fileName).","example":"Inbound Clay list"},"totalLeads":{"type":"integer","description":"Number of leads currently in the list.","example":152},"status":{"type":"string","description":"Processing status of the list.","example":"COMPLETED"},"campaignId":{"type":"string","description":"Opaque public campaign ID if the list is attached to a campaign.","nullable":true,"example":null},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"}},"required":["id","name","totalLeads","status","createdAt","updatedAt"]},"example":{"id":"pN5pT0yS3mOu","name":"Inbound Clay list","totalLeads":152,"status":"COMPLETED","campaignId":null,"createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"List not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/list_not_found","description":"List not found","example":{"error":{"code":"not_found","message":"List not found"}}}]}}}},"/api/v1/lists/{listId}/leads":{"get":{"operationId":"getListLeads","summary":"Get list leads","description":"Returns a paginated list of leads in the specified lead list.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Lists"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string","example":"pN5pT0yS3mOu"},"description":"Unique identifier of the lead list."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"example":50},"description":"Maximum number of records to return in a single page."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"example":0},"description":"Number of records to skip before returning results. Use with `limit` for pagination."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Leads for the current page.","items":{"type":"object","description":"A lead row as returned in campaign or list lead listings.","properties":{"id":{"type":"string","description":"Opaque public lead identifier.","example":"pO6qU1zT4nPv"},"firstName":{"type":"string","description":"Lead first name.","nullable":true,"example":"Jane"},"lastName":{"type":"string","description":"Lead last name.","nullable":true,"example":"Doe"},"linkedinUrl":{"type":"string","description":"LinkedIn profile URL.","example":"https://www.linkedin.com/in/jane-doe"},"email":{"type":"string","description":"Email address.","nullable":true,"example":"jane@acme.com"},"company":{"type":"string","description":"Company name.","nullable":true,"example":"Acme"},"title":{"type":"string","description":"Job title.","nullable":true,"example":"CEO"},"status":{"type":"string","description":"Lead status within the list or campaign.","enum":["NEW","CONTACTED","RESPONDED","QUALIFIED","CONVERTED","REJECTED","DUPLICATE","FAILED","INVITED","ACCEPTED","WITHDRAWN","IN_NETWORK","IN_SEQUENCE","DISCONNECTED"],"example":"NEW"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"}},"required":["id","linkedinUrl","status","createdAt"]}},"total":{"type":"integer","description":"Total records matching the filter (across all pages).","example":2},"limit":{"type":"integer","description":"Page size that was applied.","example":50},"offset":{"type":"integer","description":"Offset that was applied.","example":0}},"required":["items","total","limit","offset"]},"example":{"items":[{"id":"pO6qU1zT4nPv","firstName":"Jane","lastName":"Doe","linkedinUrl":"https://www.linkedin.com/in/jane-doe","email":"jane@acme.com","company":"Acme","title":"CEO","status":"NEW","createdAt":"2026-06-01T10:00:00.000Z"}],"total":1,"limit":50,"offset":0}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"List not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/list_not_found","description":"List not found","example":{"error":{"code":"not_found","message":"List not found"}}}]}}},"post":{"operationId":"addLeadsToList","summary":"Add leads to list","description":"Adds one or more leads to a lead list by LinkedIn URL. Existing leads with the same URL are deduplicated. Optional profile fields enrich the lead record.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Lists"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string","example":"pN5pT0yS3mOu"},"description":"Unique identifier of the lead list."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"leads":[{"linkedinUrl":"https://www.linkedin.com/in/jane-doe","firstName":"Jane","lastName":"Doe","email":"jane@acme.com","phone":null,"company":"Acme","title":"CEO","location":"Amsterdam, NL"}]}}}},"responses":{"200":{"description":"OK. Leads processed.","content":{"application/json":{"schema":{"type":"object","properties":{"listId":{"type":"string","description":"Lead list identifier.","example":"pN5pT0yS3mOu"},"submitted":{"type":"integer","description":"Number of leads submitted in the request.","example":1},"added":{"type":"integer","description":"Number of new leads actually added (after deduplication).","example":1},"totalInList":{"type":"integer","description":"Total leads now in the list.","example":153}},"required":["listId","submitted","added","totalInList"]},"example":{"listId":"pN5pT0yS3mOu","submitted":1,"added":1,"totalInList":153}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"leads must include at least one linkedinUrl"}}}},"x-error-examples":[{"title":"Invalid leads array","type":"errors/invalid_leads","description":"`leads` must be a non-empty array with at least one object containing `linkedinUrl`.","example":{"error":{"code":"bad_request","message":"leads must include at least one linkedinUrl"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"List not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/list_not_found","description":"List not found","example":{"error":{"code":"not_found","message":"List not found"}}}]}}},"delete":{"operationId":"deleteListLeads","summary":"Delete leads from list","description":"Removes one or more leads from a lead list by their IDs. Soft-deletes membership in this list only; the same LinkedIn profile may still appear on other lists.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Lists"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"listId","in":"path","required":true,"schema":{"type":"string","example":"pN5pT0yS3mOu"},"description":"Unique identifier of the lead list."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"leadIds":["pO6qU1zT4nPv"]}}}},"responses":{"200":{"description":"OK. Leads deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer","description":"Number of leads removed.","example":1},"totalInList":{"type":"integer","description":"Total leads remaining in the list.","example":151}},"required":["deleted","totalInList"]},"example":{"deleted":1,"totalInList":151}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"leadIds is required"}}}},"x-error-examples":[{"title":"Invalid lead IDs","type":"errors/invalid_lead_ids","description":"`leadIds` must be a non-empty array of lead identifier strings.","example":{"error":{"code":"bad_request","message":"leadIds is required"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"List not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/list_not_found","description":"List not found","example":{"error":{"code":"not_found","message":"List not found"}}}]}}}},"/api/v1/leads/{leadId}":{"get":{"operationId":"getLead","summary":"Get lead","description":"Retrieves full details for a single lead, including profile fields, list context, and applied tags.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string","example":"pO6qU1zT4nPv"},"description":"Unique identifier of the lead."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","description":"Full lead detail including tags and list context.","properties":{"id":{"type":"string","description":"Opaque public lead identifier.","example":"pO6qU1zT4nPv"},"firstName":{"type":"string","description":"Lead first name.","nullable":true,"example":"Jane"},"lastName":{"type":"string","description":"Lead last name.","nullable":true,"example":"Doe"},"linkedinUrl":{"type":"string","description":"LinkedIn profile URL.","example":"https://www.linkedin.com/in/jane-doe"},"email":{"type":"string","description":"Email address.","nullable":true,"example":"jane@acme.com"},"phone":{"type":"string","description":"Phone number.","nullable":true,"example":"+31612345678"},"company":{"type":"string","description":"Company name.","nullable":true,"example":"Acme"},"title":{"type":"string","description":"Job title.","nullable":true,"example":"CEO"},"location":{"type":"string","description":"Geographic location.","nullable":true,"example":"Amsterdam, NL"},"status":{"type":"string","description":"Lead status.","enum":["NEW","CONTACTED","RESPONDED","QUALIFIED","CONVERTED","REJECTED","DUPLICATE","FAILED","INVITED","ACCEPTED","WITHDRAWN","IN_NETWORK","IN_SEQUENCE","DISCONNECTED"],"example":"NEW"},"listId":{"type":"string","description":"Opaque public list identifier this lead belongs to.","example":"pN5pT0yS3mOu"},"listName":{"type":"string","description":"Name of the list this lead belongs to.","example":"Inbound Clay list"},"tags":{"type":"array","description":"Tags applied to this lead.","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque public tag identifier.","example":"pQ8sW3bV6pRx"},"name":{"type":"string","description":"Tag display name.","example":"hot"},"color":{"type":"string","description":"Hex color code for the tag badge.","example":"#EF4444"}},"required":["id","name","color"]}},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"}},"required":["id","linkedinUrl","status","listId","listName","tags","createdAt","updatedAt"]},"example":{"id":"pO6qU1zT4nPv","firstName":"Jane","lastName":"Doe","linkedinUrl":"https://www.linkedin.com/in/jane-doe","email":"jane@acme.com","phone":"+31612345678","company":"Acme","title":"CEO","location":"Amsterdam, NL","status":"NEW","listId":"pN5pT0yS3mOu","listName":"Inbound Clay list","tags":[{"id":"pQ8sW3bV6pRx","name":"hot","color":"#EF4444"}],"createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Lead not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/lead_not_found","description":"Lead not found","example":{"error":{"code":"not_found","message":"Lead not found"}}}]}}}},"/api/v1/leads/{leadId}/campaigns":{"get":{"operationId":"getCampaignsForLead","summary":"Get campaigns for lead","description":"Returns all campaigns that the specified lead is enrolled in, based on the lead's list memberships.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string","example":"pO6qU1zT4nPv"},"description":"Unique identifier of the lead."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"leadId":{"type":"string","description":"Lead identifier.","example":"pO6qU1zT4nPv"},"campaigns":{"type":"array","description":"Campaigns the lead is enrolled in.","items":{"type":"object","description":"A campaign belonging to the authenticated company account.","properties":{"id":{"type":"string","description":"Opaque public campaign identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Campaign display name.","example":"Q3 outbound — SaaS founders"},"status":{"type":"string","description":"Lifecycle status of the campaign.","enum":["DRAFT","ACTIVE","PAUSED","COMPLETED","INITIALIZE"],"example":"ACTIVE"},"settings":{"type":"object","description":"Public campaign schedule and language settings. Internal-only fields are never included.","nullable":true,"properties":{"timezone":{"type":"string","description":"IANA timezone.","example":"Europe/Amsterdam"},"startHour":{"type":"integer","description":"Send window start hour (0–23).","example":8},"endHour":{"type":"integer","description":"Send window end hour (0–23).","example":18},"workOnWeekends":{"type":"boolean","description":"Whether outreach may run on weekends.","example":false},"startDate":{"type":"string","description":"Optional campaign start date (YYYY-MM-DD).","nullable":true,"example":"2026-06-01"},"endDate":{"type":"string","description":"Optional campaign end date (YYYY-MM-DD).","nullable":true,"example":null},"allowedAiLanguages":{"type":"array","description":"Allowed AI languages for personalized copy.","example":["en"],"items":{"type":"string"}},"defaultAiLanguage":{"type":"string","description":"Default AI language code.","example":"en"}}},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account identifier used to send this campaign.","nullable":true,"example":"pL3nR8wQ1kMs"},"leadlistId":{"type":"string","description":"Opaque public lead list identifier attached to the campaign.","nullable":true,"example":null},"priority":{"type":"string","description":"Scheduling priority relative to other campaigns.","enum":["LOW","MEDIUM","HIGH"],"example":"MEDIUM"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"},"archived":{"type":"boolean","description":"True when the campaign has been archived (soft-deleted).","example":false}},"required":["id","name","status","priority","createdAt","updatedAt","archived"]}}},"required":["leadId","campaigns"]},"example":{"leadId":"pO6qU1zT4nPv","campaigns":[{"id":"p7Kq2mXn9vLw","name":"Q3 outbound — SaaS founders","status":"ACTIVE","settings":{"timezone":"Europe/Amsterdam","startHour":8,"endHour":18,"workOnWeekends":false},"linkedinAccountId":"pL3nR8wQ1kMs","leadlistId":null,"priority":"MEDIUM","createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z","archived":false}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Lead not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/lead_not_found","description":"Lead not found","example":{"error":{"code":"not_found","message":"Lead not found"}}}]}}}},"/api/v1/leads/{leadId}/tags":{"get":{"operationId":"getLeadTags","summary":"Get lead tags","description":"Returns all tags applied to a lead.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string","example":"pO6qU1zT4nPv"},"description":"Unique identifier of the lead."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"leadId":{"type":"string","description":"Lead identifier.","example":"pO6qU1zT4nPv"},"tags":{"type":"array","description":"Tags applied to this lead.","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque public tag identifier.","example":"pQ8sW3bV6pRx"},"name":{"type":"string","description":"Tag display name.","example":"hot"},"color":{"type":"string","description":"Hex color code for the tag badge.","example":"#EF4444"}},"required":["id","name","color"]}}},"required":["leadId","tags"]},"example":{"leadId":"pO6qU1zT4nPv","tags":[{"id":"pQ8sW3bV6pRx","name":"hot","color":"#EF4444"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Lead not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/lead_not_found","description":"Lead not found","example":{"error":{"code":"not_found","message":"Lead not found"}}}]}}},"post":{"operationId":"addLeadTags","summary":"Add lead tags","description":"Adds one or more tags to a lead by name. Tags that do not yet exist are created automatically. Existing tags on the lead are preserved.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string","example":"pO6qU1zT4nPv"},"description":"Unique identifier of the lead."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"tags":["hot","demo"]}}}},"responses":{"200":{"description":"OK. Tags added.","content":{"application/json":{"schema":{"type":"object","properties":{"leadId":{"type":"string","description":"Lead identifier.","example":"pO6qU1zT4nPv"},"tags":{"type":"array","description":"Full tag list after the update.","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque public tag identifier.","example":"pQ8sW3bV6pRx"},"name":{"type":"string","description":"Tag display name.","example":"hot"},"color":{"type":"string","description":"Hex color code for the tag badge.","example":"#EF4444"}},"required":["id","name","color"]}}},"required":["leadId","tags"]},"example":{"leadId":"pO6qU1zT4nPv","tags":[{"id":"pQ8sW3bV6pRx","name":"hot","color":"#EF4444"},{"id":"pR1tY4dW7qSz","name":"demo","color":"#3B82F6"}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"tags must be a non-empty array of names"}}}},"x-error-examples":[{"title":"Invalid tags","type":"errors/invalid_tags","description":"`tags` must be a non-empty array of tag name strings.","example":{"error":{"code":"bad_request","message":"tags must be a non-empty array of names"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Lead not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/lead_not_found","description":"Lead not found","example":{"error":{"code":"not_found","message":"Lead not found"}}}]}}},"put":{"operationId":"replaceLeadTags","summary":"Replace lead tags","description":"Replaces all tags on a lead with the provided set. Tags not in the request are removed. Pass an empty array to clear all tags.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"leadId","in":"path","required":true,"schema":{"type":"string","example":"pO6qU1zT4nPv"},"description":"Unique identifier of the lead."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"tags":["nurture"]}}}},"responses":{"200":{"description":"OK. Tags replaced.","content":{"application/json":{"schema":{"type":"object","properties":{"leadId":{"type":"string","description":"Lead identifier.","example":"pO6qU1zT4nPv"},"tags":{"type":"array","description":"Full tag list after the replacement.","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque public tag identifier.","example":"pQ8sW3bV6pRx"},"name":{"type":"string","description":"Tag display name.","example":"hot"},"color":{"type":"string","description":"Hex color code for the tag badge.","example":"#EF4444"}},"required":["id","name","color"]}}},"required":["leadId","tags"]},"example":{"leadId":"pO6qU1zT4nPv","tags":[{"id":"pS0uY5dX8rTz","name":"nurture","color":"#10B981"}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"tags must be an array of names"}}}},"x-error-examples":[{"title":"Invalid tags","type":"errors/invalid_tags","description":"`tags` must be an array of tag name strings.","example":{"error":{"code":"bad_request","message":"tags must be an array of names"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Lead not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/lead_not_found","description":"Lead not found","example":{"error":{"code":"not_found","message":"Lead not found"}}}]}}}},"/api/v1/inbox/conversations":{"get":{"operationId":"listConversations","summary":"List conversations","description":"Returns a paginated list of LinkedIn inbox conversations for a sender account. Filter by LinkedIn account and search by participant name or message content. The opaque `linkedinAccountId` in the response is the same token to use as a path parameter when sending messages or marking conversations seen/unseen.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Inbox"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"linkedinAccountId","in":"query","required":false,"schema":{"type":"string","example":"pL3nR8wQ1kMs"},"description":"LinkedIn sender account ID. When omitted, the first active LinkedIn account for the company is used."},{"name":"search","in":"query","required":false,"schema":{"type":"string","example":"jane"},"description":"Case-insensitive search across participant names and message content."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50},"description":"Maximum number of conversations to return in a single page (max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"example":0},"description":"Number of records to skip before returning results. Use with `limit` for pagination."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account the conversations belong to. Null when the company has no active LinkedIn accounts.","nullable":true,"example":"pL3nR8wQ1kMs"},"items":{"type":"array","description":"Conversations for the current page.","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque public conversation identifier.","example":"pR9tX4cW7qSy"},"name":{"type":"string","description":"Participant display name.","nullable":true,"example":"Jane Doe"},"unreadCount":{"type":"integer","description":"Number of unread messages.","example":2},"lastMessageAt":{"type":"string","description":"Timestamp of the last message.","nullable":true,"example":"2026-07-20T14:32:11.000Z"},"lastMessage":{"type":"string","description":"Preview of the last message text.","nullable":true,"example":"Thanks for connecting!"},"archived":{"type":"boolean","description":"Whether the conversation is archived.","example":false}},"required":["id","unreadCount","archived"]}},"total":{"type":"integer","description":"Total records matching the filter (across all pages).","example":2},"limit":{"type":"integer","description":"Page size that was applied.","example":50},"offset":{"type":"integer","description":"Offset that was applied.","example":0}},"required":["items","total","limit","offset"]},"example":{"linkedinAccountId":"pL3nR8wQ1kMs","items":[{"id":"pR9tX4cW7qSy","name":"Jane Doe","unreadCount":2,"lastMessageAt":"2026-07-20T14:32:11.000Z","lastMessage":"Thanks for connecting!","archived":false}],"total":1,"limit":50,"offset":0}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"LinkedIn account not found or not active"}}}},"x-error-examples":[{"title":"No active LinkedIn account","type":"errors/no_active_linkedin_account","description":"The company has no active LinkedIn account, or the provided `linkedinAccountId` is not active.","example":{"error":{"code":"bad_request","message":"LinkedIn account not found or not active"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]}}}},"/api/v1/inbox/conversations/{conversationId}":{"get":{"operationId":"getConversation","summary":"Get conversation","description":"Retrieves a single conversation with its full message history. Messages are ordered chronologically.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Inbox"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","example":"pR9tX4cW7qSy"},"description":"Unique identifier of the conversation."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"conversation":{"type":"object","description":"Conversation metadata.","properties":{"id":{"type":"string","description":"Opaque public conversation identifier.","example":"pR9tX4cW7qSy"},"name":{"type":"string","description":"Participant display name.","nullable":true,"example":"Jane Doe"},"unreadCount":{"type":"integer","description":"Number of unread messages.","example":2},"lastMessageAt":{"type":"string","description":"Timestamp of the last message.","nullable":true,"example":"2026-07-20T14:32:11.000Z"},"linkedinAccountId":{"type":"string","description":"Opaque public LinkedIn account ID that owns this conversation.","nullable":true,"example":"pL3nR8wQ1kMs"}},"required":["id","unreadCount"]},"messages":{"type":"array","description":"Messages in chronological order.","items":{"type":"object","properties":{"id":{"type":"string","description":"Opaque public message identifier.","example":"pS0uY5dX8rTz"},"text":{"type":"string","description":"Message body text.","example":"Thanks for connecting!"},"isSender":{"type":"boolean","description":"True when sent by the LinkedIn account.","example":false},"timestamp":{"type":"string","description":"Message timestamp.","nullable":true,"example":"2026-07-20T14:32:11.000Z"},"seen":{"type":"boolean","description":"Whether the message has been seen.","example":true}},"required":["id","text","isSender","seen"]}}},"required":["conversation","messages"]},"example":{"conversation":{"id":"pR9tX4cW7qSy","name":"Jane Doe","unreadCount":2,"lastMessageAt":"2026-07-20T14:32:11.000Z","linkedinAccountId":"pL3nR8wQ1kMs"},"messages":[{"id":"pS0uY5dX8rTz","text":"Thanks for connecting!","isSender":false,"timestamp":"2026-07-20T14:32:11.000Z","seen":true}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Conversation not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/conversation_not_found","description":"Conversation not found","example":{"error":{"code":"not_found","message":"Conversation not found"}}}]}}}},"/api/v1/linkedin-accounts/{linkedinAccountId}/conversations/{conversationId}/messages":{"post":{"operationId":"sendMessage","summary":"Send message","description":"Sends a new message in an existing LinkedIn conversation. The message is delivered through the LinkedIn sender account in the path. Use the opaque `linkedinAccountId` returned by `listConversations` or `listLinkedInAccounts`.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Inbox"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"linkedinAccountId","in":"path","required":true,"schema":{"type":"string","example":"pL3nR8wQ1kMs"},"description":"Opaque public LinkedIn sender account ID (same value returned by listConversations)."},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","example":"pR9tX4cW7qSy"},"description":"Opaque public conversation identifier."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"text":"Hello!"}}}},"responses":{"200":{"description":"OK. Message sent.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success.","example":true},"conversationId":{"type":"string","description":"Conversation identifier.","example":"pR9tX4cW7qSy"},"messageId":{"type":"string","description":"Opaque public message identifier.","example":"pT1vZ6eY9sUa"},"messageUrn":{"type":"string","description":"LinkedIn message URN.","nullable":true,"example":"urn:li:message:12345"}},"required":["success","conversationId","messageId"]},"example":{"success":true,"conversationId":"pR9tX4cW7qSy","messageId":"pT1vZ6eY9sUa","messageUrn":"urn:li:message:12345"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"text is required"}}}},"x-error-examples":[{"title":"Missing text","type":"errors/invalid_message_text","description":"The `text` field is required and must be a non-empty string.","example":{"error":{"code":"bad_request","message":"text is required"}}},{"title":"Invalid LinkedIn account","type":"errors/invalid_linkedin_account","description":"The `linkedinAccountId` does not exist or is not connected.","example":{"error":{"code":"bad_request","message":"LinkedIn account not found or not active"}}},{"title":"Conversation / account mismatch","type":"errors/conversation_account_mismatch","description":"The conversation does not belong to the LinkedIn account in the path.","example":{"error":{"code":"bad_request","message":"Conversation does not belong to this LinkedIn account"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Conversation not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/conversation_not_found","description":"Conversation not found","example":{"error":{"code":"not_found","message":"Conversation not found"}}}]}}}},"/api/v1/linkedin-accounts/{linkedinAccountId}/conversations/{conversationId}/seen":{"post":{"operationId":"setConversationSeen","summary":"Mark conversation seen","description":"Marks all messages in a conversation as read for the LinkedIn sender account in the path. No request body. Use the opaque `linkedinAccountId` returned by `listConversations`.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Inbox"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"linkedinAccountId","in":"path","required":true,"schema":{"type":"string","example":"pL3nR8wQ1kMs"},"description":"Opaque public LinkedIn sender account ID (same value returned by listConversations)."},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","example":"pR9tX4cW7qSy"},"description":"Opaque public conversation identifier."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Conversation marked as seen.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success.","example":true},"conversationId":{"type":"string","description":"Conversation identifier.","example":"pR9tX4cW7qSy"},"seen":{"type":"boolean","description":"Always true.","example":true}},"required":["success","conversationId","seen"]},"example":{"success":true,"conversationId":"pR9tX4cW7qSy","seen":true}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"LinkedIn account not found or not active"}}}},"x-error-examples":[{"title":"Invalid LinkedIn account","type":"errors/invalid_linkedin_account","description":"The `linkedinAccountId` does not exist or is not connected.","example":{"error":{"code":"bad_request","message":"LinkedIn account not found or not active"}}},{"title":"Conversation / account mismatch","type":"errors/conversation_account_mismatch","description":"The conversation does not belong to the LinkedIn account in the path.","example":{"error":{"code":"bad_request","message":"Conversation does not belong to this LinkedIn account"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Conversation not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/conversation_not_found","description":"Conversation not found","example":{"error":{"code":"not_found","message":"Conversation not found"}}}]}}}},"/api/v1/linkedin-accounts/{linkedinAccountId}/conversations/{conversationId}/unseen":{"post":{"operationId":"setConversationUnseen","summary":"Mark conversation unseen","description":"Marks a conversation as unread for the LinkedIn sender account in the path. No request body. Use the opaque `linkedinAccountId` returned by `listConversations`.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Inbox"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"linkedinAccountId","in":"path","required":true,"schema":{"type":"string","example":"pL3nR8wQ1kMs"},"description":"Opaque public LinkedIn sender account ID (same value returned by listConversations)."},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","example":"pR9tX4cW7qSy"},"description":"Opaque public conversation identifier."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Conversation marked as unseen.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success.","example":true},"conversationId":{"type":"string","description":"Conversation identifier.","example":"pR9tX4cW7qSy"},"seen":{"type":"boolean","description":"Always false.","example":false}},"required":["success","conversationId","seen"]},"example":{"success":true,"conversationId":"pR9tX4cW7qSy","seen":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"LinkedIn account not found or not active"}}}},"x-error-examples":[{"title":"Invalid LinkedIn account","type":"errors/invalid_linkedin_account","description":"The `linkedinAccountId` does not exist or is not connected.","example":{"error":{"code":"bad_request","message":"LinkedIn account not found or not active"}}},{"title":"Conversation / account mismatch","type":"errors/conversation_account_mismatch","description":"The conversation does not belong to the LinkedIn account in the path.","example":{"error":{"code":"bad_request","message":"Conversation does not belong to this LinkedIn account"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Conversation not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/conversation_not_found","description":"Conversation not found","example":{"error":{"code":"not_found","message":"Conversation not found"}}}]}}}},"/api/v1/linkedin-accounts":{"get":{"operationId":"listLinkedInAccounts","summary":"List LinkedIn accounts","description":"Returns all LinkedIn sender accounts connected to the authenticated company. Use these account IDs when creating campaigns or listing inbox conversations.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Connected LinkedIn accounts.","items":{"type":"object","description":"A connected LinkedIn sender account.","properties":{"id":{"type":"string","description":"Opaque public LinkedIn account identifier.","example":"pL3nR8wQ1kMs"},"email":{"type":"string","description":"LinkedIn login email.","example":"sender@company.com"},"status":{"type":"string","description":"Connection status.","enum":["ACTIVE","SUSPENDED","TERMINATED","DRAFT","INITIALIZE","CONNECTING","DELETED"],"example":"ACTIVE"},"urn":{"type":"string","description":"LinkedIn member URN.","nullable":true,"example":"urn:li:member:12345"},"firstName":{"type":"string","description":"Profile first name.","nullable":true,"example":"Alex"},"lastName":{"type":"string","description":"Profile last name.","nullable":true,"example":"Sender"},"headline":{"type":"string","description":"LinkedIn headline.","nullable":true,"example":"Growth at Acme"},"profilePictureUrl":{"type":"string","description":"URL of the profile picture.","nullable":true,"example":"https://media.licdn.com/dms/image/example.jpg"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-05-01T08:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-15T12:00:00.000Z"}},"required":["id","email","status","createdAt","updatedAt"]}}},"required":["items"]},"example":{"items":[{"id":"pL3nR8wQ1kMs","email":"sender@company.com","status":"ACTIVE","urn":"urn:li:member:12345","firstName":"Alex","lastName":"Sender","headline":"Growth at Acme","profilePictureUrl":"https://media.licdn.com/dms/image/example.jpg","createdAt":"2026-05-01T08:00:00.000Z","updatedAt":"2026-07-15T12:00:00.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]}}}},"/api/v1/linkedin-accounts/{linkedinAccountId}":{"get":{"operationId":"getLinkedInAccount","summary":"Get LinkedIn account","description":"Retrieves details for a single connected LinkedIn sender account.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"linkedinAccountId","in":"path","required":true,"schema":{"type":"string","example":"pL3nR8wQ1kMs"},"description":"Unique identifier of the LinkedIn account."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","description":"A connected LinkedIn sender account.","properties":{"id":{"type":"string","description":"Opaque public LinkedIn account identifier.","example":"pL3nR8wQ1kMs"},"email":{"type":"string","description":"LinkedIn login email.","example":"sender@company.com"},"status":{"type":"string","description":"Connection status.","enum":["ACTIVE","SUSPENDED","TERMINATED","DRAFT","INITIALIZE","CONNECTING","DELETED"],"example":"ACTIVE"},"urn":{"type":"string","description":"LinkedIn member URN.","nullable":true,"example":"urn:li:member:12345"},"firstName":{"type":"string","description":"Profile first name.","nullable":true,"example":"Alex"},"lastName":{"type":"string","description":"Profile last name.","nullable":true,"example":"Sender"},"headline":{"type":"string","description":"LinkedIn headline.","nullable":true,"example":"Growth at Acme"},"profilePictureUrl":{"type":"string","description":"URL of the profile picture.","nullable":true,"example":"https://media.licdn.com/dms/image/example.jpg"},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-05-01T08:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-15T12:00:00.000Z"}},"required":["id","email","status","createdAt","updatedAt"]},"example":{"id":"pL3nR8wQ1kMs","email":"sender@company.com","status":"ACTIVE","urn":"urn:li:member:12345","firstName":"Alex","lastName":"Sender","headline":"Growth at Acme","profilePictureUrl":"https://media.licdn.com/dms/image/example.jpg","createdAt":"2026-05-01T08:00:00.000Z","updatedAt":"2026-07-15T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"LinkedIn account not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/linkedin_account_not_found","description":"LinkedIn account not found","example":{"error":{"code":"not_found","message":"LinkedIn account not found"}}}]}}}},"/api/v1/stats":{"get":{"operationId":"getOverallStats","summary":"Overall stats","description":"Returns high-level usage and performance statistics for the authenticated company account, including campaign counts, lead totals, and connection acceptance rates.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Stats"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"campaigns":{"type":"integer","description":"Total number of campaigns.","example":12},"activeCampaigns":{"type":"integer","description":"Number of currently active campaigns.","example":3},"lists":{"type":"integer","description":"Total number of lead lists.","example":8},"leads":{"type":"integer","description":"Total number of leads across all lists.","example":4520},"linkedinAccounts":{"type":"integer","description":"Number of connected LinkedIn accounts.","example":2},"sentLeads":{"type":"integer","description":"Total connection requests sent.","example":1200},"acceptedLeads":{"type":"integer","description":"Total connection requests accepted.","example":480},"acceptanceRate":{"type":"number","description":"Acceptance rate as a percentage (0–100).","example":40}},"required":["campaigns","activeCampaigns","lists","leads","linkedinAccounts","sentLeads","acceptedLeads","acceptanceRate"]},"example":{"campaigns":12,"activeCampaigns":3,"lists":8,"leads":4520,"linkedinAccounts":2,"sentLeads":1200,"acceptedLeads":480,"acceptanceRate":40}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]}}}},"/api/v1/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhooks","description":"Returns all outbound webhook subscriptions for the authenticated company. Signing secrets are not included — use create or update to retrieve a secret.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Webhook subscriptions (secrets are omitted).","items":{"type":"object","description":"Webhook subscription (signing secret values are never returned).","properties":{"id":{"type":"string","description":"Opaque public webhook identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Human-readable webhook name.","example":"CRM sync"},"url":{"type":"string","description":"HTTPS endpoint that receives event payloads.","example":"https://hooks.example.com/gl"},"events":{"type":"array","description":"Event types that trigger this webhook.","items":{"type":"string","enum":["CONNECTION_REQUEST_SENT","CONNECTION_REQUEST_ACCEPTED","MESSAGE_SENT","MESSAGE_REPLY_RECEIVED","EVERY_MESSAGE_REPLY_RECEIVED","CAMPAIGN_COMPLETED","LEAD_TAG_UPDATED","INMAIL_SENT","INMAIL_REPLY_RECEIVED","FOLLOW_SENT","LIKE_SENT","PROFILE_VIEWED"]}},"enabled":{"type":"boolean","description":"Whether the webhook is active.","example":true},"hasSecret":{"type":"boolean","description":"True when a signing secret is configured.","example":true},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"}},"required":["id","name","url","events","enabled","hasSecret","createdAt","updatedAt"]}}},"required":["items"]},"example":{"items":[{"id":"p7Kq2mXn9vLw","name":"CRM sync","url":"https://hooks.example.com/gl","events":["MESSAGE_REPLY_RECEIVED","CONNECTION_REQUEST_ACCEPTED"],"enabled":true,"hasSecret":true,"createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]}}},"post":{"operationId":"createWebhook","summary":"Create webhook","description":"Creates a new outbound webhook subscription. A signing secret is generated and returned once in the live API response — store it yourself; documentation examples never include secret values.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"CRM sync","url":"https://hooks.example.com/gl","events":["MESSAGE_REPLY_RECEIVED","CONNECTION_REQUEST_ACCEPTED"],"enabled":true}}}},"responses":{"200":{"description":"OK. Webhook created.","content":{"application/json":{"schema":{"type":"object","description":"Webhook subscription returned on create/update. A signing `secret` is returned once so you can verify deliveries — store it yourself. Documentation examples never include real secret values.","properties":{"id":{"type":"string","description":"Opaque public webhook identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Human-readable webhook name.","example":"CRM sync"},"url":{"type":"string","description":"HTTPS endpoint that receives event payloads.","example":"https://hooks.example.com/gl"},"events":{"type":"array","description":"Event types that trigger this webhook.","items":{"type":"string","enum":["CONNECTION_REQUEST_SENT","CONNECTION_REQUEST_ACCEPTED","MESSAGE_SENT","MESSAGE_REPLY_RECEIVED","EVERY_MESSAGE_REPLY_RECEIVED","CAMPAIGN_COMPLETED","LEAD_TAG_UPDATED","INMAIL_SENT","INMAIL_REPLY_RECEIVED","FOLLOW_SENT","LIKE_SENT","PROFILE_VIEWED"]}},"enabled":{"type":"boolean","description":"Whether the webhook is active.","example":true},"secret":{"type":"string","description":"HMAC signing secret for verifying deliveries. Returned only on create/update — never log or share it. List/get responses omit this field.","nullable":true,"example":null},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"}},"required":["id","name","url","events","enabled","createdAt","updatedAt"]},"example":{"id":"p7Kq2mXn9vLw","name":"CRM sync","url":"https://hooks.example.com/gl","events":["MESSAGE_REPLY_RECEIVED","CONNECTION_REQUEST_ACCEPTED"],"enabled":true,"secret":null,"createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-06-01T10:00:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"name is required"}}}},"x-error-examples":[{"title":"Invalid name","type":"errors/invalid_name","description":"The `name` field is required and must be a non-empty string.","example":{"error":{"code":"bad_request","message":"name is required"}}},{"title":"Invalid URL","type":"errors/invalid_url","description":"The `url` must be an absolute http(s) URL.","example":{"error":{"code":"bad_request","message":"url must be an absolute http(s) URL"}}},{"title":"Invalid events","type":"errors/invalid_events","description":"`events` must be a non-empty array of supported event type strings.","example":{"error":{"code":"bad_request","message":"events must be a non-empty array"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]}}}},"/api/v1/webhooks/{webhookId}":{"get":{"operationId":"getWebhook","summary":"Get webhook","description":"Retrieves a single webhook subscription by ID. The signing secret is not included.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the webhook."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Request succeeded.","content":{"application/json":{"schema":{"type":"object","description":"Webhook subscription (signing secret values are never returned).","properties":{"id":{"type":"string","description":"Opaque public webhook identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Human-readable webhook name.","example":"CRM sync"},"url":{"type":"string","description":"HTTPS endpoint that receives event payloads.","example":"https://hooks.example.com/gl"},"events":{"type":"array","description":"Event types that trigger this webhook.","items":{"type":"string","enum":["CONNECTION_REQUEST_SENT","CONNECTION_REQUEST_ACCEPTED","MESSAGE_SENT","MESSAGE_REPLY_RECEIVED","EVERY_MESSAGE_REPLY_RECEIVED","CAMPAIGN_COMPLETED","LEAD_TAG_UPDATED","INMAIL_SENT","INMAIL_REPLY_RECEIVED","FOLLOW_SENT","LIKE_SENT","PROFILE_VIEWED"]}},"enabled":{"type":"boolean","description":"Whether the webhook is active.","example":true},"hasSecret":{"type":"boolean","description":"True when a signing secret is configured.","example":true},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"}},"required":["id","name","url","events","enabled","hasSecret","createdAt","updatedAt"]},"example":{"id":"p7Kq2mXn9vLw","name":"CRM sync","url":"https://hooks.example.com/gl","events":["MESSAGE_REPLY_RECEIVED","CONNECTION_REQUEST_ACCEPTED"],"enabled":true,"hasSecret":true,"createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-20T14:32:11.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Webhook not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/webhook_not_found","description":"Webhook not found","example":{"error":{"code":"not_found","message":"Webhook not found"}}}]}}},"patch":{"operationId":"updateWebhook","summary":"Update webhook","description":"Updates an existing webhook subscription. Only the fields you include in the request body are changed. Documentation examples never include signing secrets.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the webhook."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"enabled":false}}}},"responses":{"200":{"description":"OK. Webhook updated.","content":{"application/json":{"schema":{"type":"object","description":"Webhook subscription returned on create/update. A signing `secret` is returned once so you can verify deliveries — store it yourself. Documentation examples never include real secret values.","properties":{"id":{"type":"string","description":"Opaque public webhook identifier.","example":"p7Kq2mXn9vLw"},"name":{"type":"string","description":"Human-readable webhook name.","example":"CRM sync"},"url":{"type":"string","description":"HTTPS endpoint that receives event payloads.","example":"https://hooks.example.com/gl"},"events":{"type":"array","description":"Event types that trigger this webhook.","items":{"type":"string","enum":["CONNECTION_REQUEST_SENT","CONNECTION_REQUEST_ACCEPTED","MESSAGE_SENT","MESSAGE_REPLY_RECEIVED","EVERY_MESSAGE_REPLY_RECEIVED","CAMPAIGN_COMPLETED","LEAD_TAG_UPDATED","INMAIL_SENT","INMAIL_REPLY_RECEIVED","FOLLOW_SENT","LIKE_SENT","PROFILE_VIEWED"]}},"enabled":{"type":"boolean","description":"Whether the webhook is active.","example":true},"secret":{"type":"string","description":"HMAC signing secret for verifying deliveries. Returned only on create/update — never log or share it. List/get responses omit this field.","nullable":true,"example":null},"createdAt":{"type":"string","description":"ISO-8601 creation timestamp.","example":"2026-06-01T10:00:00.000Z"},"updatedAt":{"type":"string","description":"ISO-8601 last update timestamp.","example":"2026-07-20T14:32:11.000Z"}},"required":["id","name","url","events","enabled","createdAt","updatedAt"]},"example":{"id":"p7Kq2mXn9vLw","name":"CRM sync","url":"https://hooks.example.com/gl","events":["MESSAGE_REPLY_RECEIVED","CONNECTION_REQUEST_ACCEPTED"],"enabled":false,"secret":null,"createdAt":"2026-06-01T10:00:00.000Z","updatedAt":"2026-07-21T09:00:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"error":{"code":"bad_request","message":"url must be an absolute http(s) URL"}}}},"x-error-examples":[{"title":"Invalid URL","type":"errors/invalid_url","description":"When provided, `url` must be an absolute http(s) URL.","example":{"error":{"code":"bad_request","message":"url must be an absolute http(s) URL"}}},{"title":"Invalid events","type":"errors/invalid_events","description":"When provided, `events` must be a non-empty array of supported event type strings.","example":{"error":{"code":"bad_request","message":"Unsupported webhook event"}}}]},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Webhook not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/webhook_not_found","description":"Webhook not found","example":{"error":{"code":"not_found","message":"Webhook not found"}}}]}}},"delete":{"operationId":"deleteWebhook","summary":"Delete webhook","description":"Permanently deletes a webhook subscription. This action cannot be undone.\n\nAuthenticate with a company API key (`glc_…`). Agency keys (`gla_…`) are supported when you also pass `X-Company-Id` for the target client company.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","example":"p7Kq2mXn9vLw"},"description":"Unique identifier of the webhook to delete."},{"name":"X-Company-Id","in":"header","required":false,"schema":{"type":"string"},"description":"Required when using an agency API key against company endpoints"}],"responses":{"200":{"description":"OK. Webhook deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true on success.","example":true}},"required":["success"]},"example":{"success":true}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}},"x-error-examples":[{"title":"Missing credentials","type":"errors/missing_credentials","description":"No `Authorization: Bearer` header was provided.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}},{"title":"Invalid credentials","type":"errors/invalid_credentials","description":"The API key is malformed, revoked, or does not match a stored hash.","example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}]},"403":{"description":"Forbidden","content":{"application/json":{"example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}},"x-error-examples":[{"title":"Missing company scope","type":"errors/forbidden","description":"An agency key was used without `X-Company-Id`, or the company is outside the agency's clients.","example":{"error":{"code":"forbidden","message":"X-Company-Id is required for agency keys on company endpoints"}}}]},"404":{"description":"Not Found","content":{"application/json":{"example":{"error":{"code":"not_found","message":"Webhook not found"}}}},"x-error-examples":[{"title":"Resource not found","type":"errors/webhook_not_found","description":"Webhook not found","example":{"error":{"code":"not_found","message":"Webhook not found"}}}]}}}}}}