{"openapi":"3.0.0","info":{"title":"Sillage Partner API (v3)","version":"3.0.0","description":"v3 of the Sillage partner API. Authenticate with a master key (`mk_live_...`) issued per partner, provided in the Authorization header as a Bearer token. Every integration starts by creating a workspace for a client. `partner_workspace_id` is your own ID for that client: you choose it when you create the workspace, and every other route then names the client by it in its path."},"servers":[{"url":"/api","description":"API server"}],"security":[{"MasterKeyAuth":[]}],"tags":[{"name":"Signal templates"},{"name":"Signal setups"},{"name":"Signal runs"},{"name":"Signals"},{"name":"Leads"},{"name":"Companies"},{"name":"Company mappings"},{"name":"Contents"},{"name":"Content requests"},{"name":"Lists"},{"name":"Personas"},{"name":"Account monitoring"},{"name":"Usage"},{"name":"Requests status"},{"name":"Setup state"},{"name":"Workspaces"}],"paths":{"/v3/partner/workspaces":{"post":{"tags":["Workspaces"],"summary":"Create a client workspace","description":"Creates a workspace for one of your clients. `partner_workspace_id` is your own ID for the client; the other routes then name the client by it in their path.\n\n`owner_email` is the person who gets admin access to the workspace in the Sillage app; it is never returned. `domain` is the main website of the client, lowercased when saved. You have one live workspace per domain: to cover another team of the same client, create a persona in its workspace instead. Returns the saved workspace.\n\nA retry answers `409`, because the domain is already taken by the workspace the first call created: read it back with `GET /v3/partner/workspaces`.","security":[{"MasterKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3CreatePartnerWorkspaceBody"}}}},"responses":{"201":{"description":"The workspace was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PartnerWorkspaceResponse"},"example":{"data":{"partner_workspace_id":"<partner_workspace_id>","name":"<name>","domain":"<domain>","archived":true,"created_at":"2026-01-15T09:30:00.000Z"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"409":{"description":"You already have a workspace with this `partner_workspace_id`, or a live workspace for this `domain`, or another workspace is being created or restored for you right now (retry in a moment).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"get":{"tags":["Workspaces"],"summary":"List your client workspaces","description":"Returns your client workspaces, newest first. Paused (archived) workspaces and deleted workspaces are left out unless you ask for them with `include_archived` and `include_deleted`; each switch works on its own, so a workspace that is both paused and deleted shows only when both are on.","security":[{"MasterKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page."},{"name":"include_archived","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"Set to `true` to also list paused (archived) workspaces."},{"name":"include_deleted","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"Set to `true` to also list deleted workspaces. Every item then carries `deleted_at`, `null` for the ones that are not deleted."}],"responses":{"200":{"description":"Your client workspaces, paginated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PartnerWorkspaceListResponse"},"example":{"data":[{"partner_workspace_id":"<partner_workspace_id>","name":"<name>","domain":"<domain>","archived":true,"created_at":"2026-01-15T09:30:00.000Z","deleted_at":"2026-01-15T09:30:00.000Z"}],"meta":{"pagination":{"page":1,"page_size":1,"page_count":1,"total":1}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}":{"get":{"tags":["Workspaces"],"summary":"Get a client workspace","description":"Returns one of your client workspaces by your `partner_workspace_id`. A deleted workspace, or one that belongs to another partner, is reported as not found.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"responses":{"200":{"description":"The workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PartnerWorkspaceResponse"},"example":{"data":{"partner_workspace_id":"<partner_workspace_id>","name":"<name>","domain":"<domain>","archived":true,"created_at":"2026-01-15T09:30:00.000Z"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"patch":{"tags":["Workspaces"],"summary":"Update a client workspace","description":"Renames a client workspace, or pauses and resumes it. Send only the fields to change; every field you leave out is kept. The domain of a workspace cannot be changed. A deleted workspace, or one that belongs to another partner, is reported as not found. Returns the saved workspace.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3UpdatePartnerWorkspaceBody"}}}},"responses":{"200":{"description":"The updated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PartnerWorkspaceResponse"},"example":{"data":{"partner_workspace_id":"<partner_workspace_id>","name":"<name>","domain":"<domain>","archived":true,"created_at":"2026-01-15T09:30:00.000Z"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"delete":{"tags":["Workspaces"],"summary":"Delete a client workspace","description":"Deletes a client workspace. It disappears from your lists and every route of that client answers not found, but nothing is erased: you can bring it back with `POST /v3/partner/workspaces/{partner_workspace_id}/restore`. The `partner_workspace_id` stays taken, so you cannot reuse it for a new workspace. Deleting a workspace that is already deleted is reported as not found.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"responses":{"200":{"description":"The workspace was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PartnerWorkspaceDeleted"},"example":{"data":{"partner_workspace_id":"<partner_workspace_id>","deleted":true}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/restore":{"post":{"tags":["Workspaces"],"summary":"Restore a deleted client workspace","description":"Brings a deleted client workspace back, as it was. Send no body. Restoring a workspace that is not deleted changes nothing and returns it. If you created another workspace for the same domain in the meantime, the restore is refused: create a persona in that workspace instead. A workspace that was permanently erased cannot be restored. Returns the workspace.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"responses":{"200":{"description":"The restored workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PartnerWorkspaceResponse"},"example":{"data":{"partner_workspace_id":"<partner_workspace_id>","name":"<name>","domain":"<domain>","archived":true,"created_at":"2026-01-15T09:30:00.000Z"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"description":"You already have another live workspace for the same `domain`, this workspace was permanently erased, or another workspace is being created or restored for you right now (retry in a moment).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/signal-templates":{"get":{"tags":["Signal templates"],"summary":"List a client's signal templates","description":"Returns every signal template the named client can set up. Archived signal templates are left out of this list but can still be fetched by their ID; setting one up is refused with a 409.\n\nFilters combine: a template must match every filter you send, and any one of the values inside a comma-separated filter.\n\nComputed defaults in `setup.fields` (the domain of the client, the names of its competitors) are resolved the way a setup creation would resolve them. Send `persona_id` (from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`) to see them for one persona. Without it, a workspace with one persona sees them as for that persona, and a workspace with several personas does not see them: those properties then carry no `default`. An unknown or archived `persona_id` is refused with a 422.\n\nA signal template carries the `not_set_up` tag when the client workspace has no active or paused signal setup of it; a setup that belongs to no persona counts for every persona. With `persona_id`, only the setups of that persona count; without it, the setups of every persona do.\n\nSignal templates come in the order of the Sillage catalog. The order is fixed.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"categories","in":"query","required":false,"description":"Only return signal templates of one of these categories, as a comma-separated list: `my_properties`, `my_network`, `competition`, `people`, `market`, `internal_intents`. A template matches when it is in any of the values you list. Up to 20 values. Any other value is refused with a 422.","schema":{"type":"string"}},{"name":"subjects","in":"query","required":false,"description":"Only return signal templates that watch one of these subjects, as a comma-separated list: `person`, `company`. A template matches when it watches any of the values you list. Up to 20 values.","schema":{"type":"string","example":"person,company"}},{"name":"scopes","in":"query","required":false,"description":"Only return signal templates that support one of these setups, as a comma-separated list: `discovery`, `account_monitoring`. A template matches when it supports any of the values you list. Up to 20 values.","schema":{"type":"string","example":"discovery,account_monitoring"}},{"name":"tags","in":"query","required":false,"description":"Only return signal templates carrying one of these tags, as a comma-separated list: `popular`, `not_set_up`. A template matches when it carries any of the values you list. Up to 20 values; a tag we do not know is refused with a 422.","schema":{"type":"string","example":"popular,not_set_up"}},{"name":"name","in":"query","required":false,"description":"Only return signal templates whose name contains this text, ignoring case, up to 100 characters. `keyword` matches \"Mentioned keywords on LinkedIn\".","schema":{"type":"string","maxLength":100}},{"name":"persona_id","in":"query","required":false,"description":"Resolve the computed defaults (the domain of the client, the names of its competitors) and the `not_set_up` tag for this persona, given as its ID from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`. Must be an active persona of the client workspace, otherwise the request is refused with a 422. Only the signal setups of this persona, and those that belong to no persona, count for `not_set_up`.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"The client's signal templates.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SignalTemplate"}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["page","page_size","page_count","total"],"properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"page_count":{"type":"integer"},"total":{"type":"integer"}}}}}}},"example":{"data":[{"id":1,"key":"<key>","name":"<name>","description":"<description>","row_summary":"<row_summary>","category":"my_properties","status":"live","subjects":["person"],"scopes":["discovery"],"tags":["popular"],"pricing":{"account_monitoring":{"signal_bucket":"essential","credits":1,"unit":"per_key_account_per_month"},"discovery":{"credits":1,"unit":"signal_found"}},"setup":{"fields":{},"shape":"keyword"},"archived_at":"2026-01-15T09:30:00.000Z"}],"meta":{"pagination":{"page":1,"page_size":1,"page_count":1,"total":1}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/signal-templates/{signal_template_id}":{"get":{"tags":["Signal templates"],"summary":"Get a client's signal template","description":"Returns one signal template, including an archived one: archived signal templates are hidden from the list but stay readable by their ID. Setting up an archived signal template is refused with a 409.\n\nComputed defaults in `setup.fields` (the domain of the client, the names of its competitors) are resolved the way a setup creation would resolve them. Send `persona_id` (from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`) to see them for one persona. Without it, a workspace with one persona sees them as for that persona, and a workspace with several personas does not see them: those properties then carry no `default`. An unknown or archived `persona_id` is refused with a 422.\n\nA signal template carries the `not_set_up` tag when the client workspace has no active or paused signal setup of it; a setup that belongs to no persona counts for every persona. With `persona_id`, only the setups of that persona count; without it, the setups of every persona do.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"signal_template_id","in":"path","required":true,"description":"The ID of the signal template.","schema":{"type":"integer"}},{"name":"persona_id","in":"query","required":false,"description":"Resolve the computed defaults (the domain of the client, the names of its competitors) and the `not_set_up` tag for this persona, given as its ID from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`. Must be an active persona of the client workspace, otherwise the request is refused with a 422. Only the signal setups of this persona, and those that belong to no persona, count for `not_set_up`.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"The signal.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SignalTemplate"}}},"example":{"data":{"id":1,"key":"<key>","name":"<name>","description":"<description>","row_summary":"<row_summary>","category":"my_properties","status":"live","subjects":["person"],"scopes":["discovery"],"tags":["popular"],"pricing":{"account_monitoring":{"signal_bucket":"essential","credits":1,"unit":"per_key_account_per_month"},"discovery":{"credits":1,"unit":"signal_found"}},"setup":{"fields":{},"shape":"keyword"},"archived_at":"2026-01-15T09:30:00.000Z"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/signal-setups":{"get":{"tags":["Signal setups"],"summary":"List a client's signal setups","description":"Returns every signal the named client has set up.\n\nSignal setups come oldest first, by `id`. The order is fixed.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"persona_id","in":"query","required":false,"schema":{"type":"integer"},"description":"Only return the signal setups of this persona, given as its persona ID (from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`), plus the ones that belong to no persona. Omit to get every signal setup."}],"responses":{"200":{"description":"The client's signal setups.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SignalSetup"}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["page","page_size","page_count","total"],"properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"page_count":{"type":"integer"},"total":{"type":"integer"}}}}}}},"example":{"data":[{"id":1,"signal_template":{"id":1,"key":"<key>","name":"<name>","description":"<description>","row_summary":"<row_summary>","category":"my_properties","status":"live","subjects":["person"],"scopes":["discovery"],"tags":["popular"],"pricing":{"account_monitoring":{"signal_bucket":"essential","credits":1,"unit":"per_key_account_per_month"},"discovery":{"credits":1,"unit":"signal_found"}},"archived_at":"2026-01-15T09:30:00.000Z"},"name":"<name>","status":"enabled","parameters":{},"schedule":"weekly","persona_id":1,"created_at":"2026-01-15T09:30:00.000Z","last_detected_at":"2026-01-15T09:30:00.000Z"}],"meta":{"pagination":{"page":1,"page_size":1,"page_count":1,"total":1}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"post":{"tags":["Signal setups"],"summary":"Set up a signal for a client","description":"Sets up a signal for the named client's workspace. Name the signal with its `signal_template_id` from `GET /v3/partner/workspaces/{partner_workspace_id}/signal-templates` and set its `parameters`, which are checked against the `setup.fields` that signal returns. `parameters` is required. A property you leave out is filled with its default, and the response shows the parameters as applied.\n\nA setup runs on a schedule only when you ask for one: send `schedule: \"weekly\"` for a weekly run, or leave it out (or send `null`) to run only when you launch a signal run. `weekly` runs the setup a first time right away, then every week, so it spends credits immediately when `scopes` includes `discovery`.\n\nSome signals watch a list the client has built — of competitors, partners, influencers or champions. Those signals declare a `list_id` property in their `setup.fields`, carrying an `x-list-type` that says which kind of list it accepts. Send the id of one of that client's own lists of that type, from `GET /v3/partner/workspaces/{partner_workspace_id}/lists`. A signal that watches a list is never set up without one, and no list is created for you — except Engaged with my content on LinkedIn, which reads an employee list and defaults `list_id` to the client's All my employees list. That default cannot be cleared on update, and a list that is not an employee list is refused with a 422.\n\nPersona: most signals look for people matching the client's persona, so the request is refused with a 422 until the persona has at least one job title and one location — create or complete it with `POST /v3/partner/workspaces/{partner_workspace_id}/personas` or `PATCH /v3/partner/workspaces/{partner_workspace_id}/personas/{persona_id}` first. Champion and job-offer signals need no persona. A list attached only to personas other than the client's persona cannot be used: the request is refused with a 409 whose `detail` names the list and the personas it is attached to.\n\nA signal belongs to one persona: pass its `persona_id` from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`. With one persona you can leave it out; with several it is required (the request is refused with a 422 naming `persona_id` without it), except for champion signals and for job-offer signals that use their own job titles. A signal that uses the job titles of the persona (`use_persona_job_titles`, on by default, as for a job-offer signal) needs a `persona_id` in a workspace with several personas: the API never picks one for you, and the request is refused with a 422 naming `persona_id`. In a workspace with one persona, that persona is used and the signal setup stays bound to it. You can create several setups of the same signal for one persona — for example one per keyword set.\n\nThe call takes no idempotency key: a retry creates a second signal setup. Before retrying a call that did not answer, check `GET /v3/partner/workspaces/{partner_workspace_id}/signal-setups`.\n\nA `signal_template_id` that is not an available signal template (unknown, or coming soon) is refused with a 422 (`errors.signal_template_id`: must be the id of an available signal template, see `GET /v3/partner/workspaces/{partner_workspace_id}/signal-templates`), and an archived one with a 409. A `list_id` that is not a list of the right type in the workspace is refused with a 422 (`errors.list_id`).","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSignalSetupBody"}}}},"responses":{"201":{"description":"The signal setup was created.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SignalSetup"}}},"example":{"data":{"id":1,"signal_template":{"id":1,"key":"<key>","name":"<name>","description":"<description>","row_summary":"<row_summary>","category":"my_properties","status":"live","subjects":["person"],"scopes":["discovery"],"tags":["popular"],"pricing":{"account_monitoring":{"signal_bucket":"essential","credits":1,"unit":"per_key_account_per_month"},"discovery":{"credits":1,"unit":"signal_found"}},"archived_at":"2026-01-15T09:30:00.000Z"},"name":"<name>","status":"enabled","parameters":{},"schedule":"weekly","persona_id":1,"created_at":"2026-01-15T09:30:00.000Z","last_detected_at":"2026-01-15T09:30:00.000Z"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"$ref":"#/components/responses/V3Conflict"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/signal-setups/{signal_setup_id}":{"get":{"tags":["Signal setups"],"summary":"Get a client's signal setup","description":"Retrieves one of the named client's signal setups by ID.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"signal_setup_id","in":"path","required":true,"description":"The ID of the signal setup.","schema":{"type":"integer"}}],"responses":{"200":{"description":"The signal setup.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SignalSetup"}}},"example":{"data":{"id":1,"signal_template":{"id":1,"key":"<key>","name":"<name>","description":"<description>","row_summary":"<row_summary>","category":"my_properties","status":"live","subjects":["person"],"scopes":["discovery"],"tags":["popular"],"pricing":{"account_monitoring":{"signal_bucket":"essential","credits":1,"unit":"per_key_account_per_month"},"discovery":{"credits":1,"unit":"signal_found"}},"archived_at":"2026-01-15T09:30:00.000Z"},"name":"<name>","status":"enabled","parameters":{},"schedule":"weekly","persona_id":1,"created_at":"2026-01-15T09:30:00.000Z","last_detected_at":"2026-01-15T09:30:00.000Z"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"patch":{"tags":["Signal setups"],"summary":"Update a client's signal setup","description":"Updates one of the named client's signal setups. Set `status` to `disabled` to pause it or `enabled` to resume it (a resumed weekly signal setup waits for its next weekly slot instead of running at once), and `schedule` to `weekly` or `null` to start or stop its weekly run.\n\nSent `parameters` are merged into the stored ones: an included key overwrites the stored value, `null` removes it (refused with a 422 for a parameter that has a default), and every key left out is kept. Switching to `weekly` does not run the setup right away. The schedule is not a parameter: sending it inside `parameters` is refused. The merged result is validated the same way as on creation.\n\nThe list can be changed: send another `list_id` of the right type (a list attached only to personas other than the one of the setup is refused with a 409). The persona cannot: `persona_id` can be left out or resent unchanged, and a different one is refused with a 422 (`errors.persona_id`: cannot be changed); set the signal up again in the other persona instead. A setup that has no persona can be given one once.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"signal_setup_id","in":"path","required":true,"description":"The ID of the signal setup.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSignalSetupBody"}}}},"responses":{"200":{"description":"The updated signal setup.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SignalSetup"}}},"example":{"data":{"id":1,"signal_template":{"id":1,"key":"<key>","name":"<name>","description":"<description>","row_summary":"<row_summary>","category":"my_properties","status":"live","subjects":["person"],"scopes":["discovery"],"tags":["popular"],"pricing":{"account_monitoring":{"signal_bucket":"essential","credits":1,"unit":"per_key_account_per_month"},"discovery":{"credits":1,"unit":"signal_found"}},"archived_at":"2026-01-15T09:30:00.000Z"},"name":"<name>","status":"enabled","parameters":{},"schedule":"weekly","persona_id":1,"created_at":"2026-01-15T09:30:00.000Z","last_detected_at":"2026-01-15T09:30:00.000Z"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"$ref":"#/components/responses/V3Conflict"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"delete":{"tags":["Signal setups"],"summary":"Delete a client's signal setup","description":"Removes one of the named client's signal setups. If no other signal setup reads the list it was watching, you can then delete that list.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"signal_setup_id","in":"path","required":true,"description":"The ID of the signal setup.","schema":{"type":"integer"}}],"responses":{"200":{"description":"The signal setup was deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3Deleted"},"example":{"data":{"id":1,"deleted":true}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/signals/query":{"post":{"tags":["Signals"],"summary":"Query a client's signal detections","description":"Returns a cursor-paginated list of signal detections for the named client, most recent detection first. Searches and counts return the detections rated top priority (the ones shown in the app); a detection read by ID may not appear in a search. Pass `meta.cursor.next` as `cursor` on the next request to keep paging, until `meta.cursor.has_more` is `false`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SignalsQueryBody"}}}},"responses":{"200":{"description":"A page of the client's signal detections, most recent first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SignalListResponse"},"examples":{"sample":{"summary":"One keyword detection","value":{"data":[{"id":101,"signal_type":"keyword_detection","details":{"keywords_found":["AI"]},"detected_at":"2026-06-01T10:00:00.000Z","signal_date":"2026-05-30T09:00:00.000Z","lead_id":456,"company_id":789,"signal_setup_id":12,"source_url":null,"author":null,"excerpt":null}],"meta":{"cursor":{"next":"eyJzY29wZSI6InNpZ25hbHMiLCJ3b3Jrc3BhY2VJZCI6MX0.k3VQ2Zr1","has_more":true}}}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/signals/count":{"post":{"tags":["Signals"],"summary":"Count a client's signal detections","description":"Returns the total number of signal detections matching the given filters, for the named client. Takes exactly the filters of `POST /v3/partner/workspaces/{partner_workspace_id}/signals/query` in the same JSON body, without `cursor` and `limit`. Like the search, it counts the detections rated top priority.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SignalsCountBody"}}}},"responses":{"200":{"description":"The total number of the client's matching signal detections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SignalCountResponse"},"examples":{"sample":{"summary":"Count result","value":{"data":{"total":42}}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/signals/{signal_id}":{"get":{"tags":["Signals"],"summary":"Get a client's signal detection","description":"Returns one of the named client's signal detections by its ID.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"signal_id","in":"path","required":true,"description":"The ID of the detection (the `id` field returned by `POST /v3/partner/workspaces/{partner_workspace_id}/signals/query`).","schema":{"type":"integer"}}],"responses":{"200":{"description":"The signal detection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SignalResponse"},"example":{"data":{"id":1,"signal_type":"<signal_type>","details":"<details>","detected_at":"2026-01-15T09:30:00.000Z","signal_date":"2026-01-15T09:30:00.000Z","lead":{"id":1,"full_name":"<full_name>","first_name":"<first_name>","last_name":"<last_name>","linkedin_url":"<linkedin_url>","linkedin_headline":"<linkedin_headline>","position":"<position>","avatar_url":"<avatar_url>"},"company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"},"signal_setup_id":1,"source_url":"<source_url>","author":{"full_name":"<full_name>","first_name":"<first_name>","last_name":"<last_name>","linkedin_url":"<linkedin_url>","linkedin_headline":"<linkedin_headline>","position":"<position>","avatar_url":"<avatar_url>"},"excerpt":"<excerpt>"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"delete":{"tags":["Signals"],"summary":"Delete a client's signal detection","description":"Removes one of the named client's signal detections.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"signal_id","in":"path","required":true,"description":"The ID of the detection.","schema":{"type":"integer"}}],"responses":{"200":{"description":"The id of the deleted signal detection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3Deleted"},"example":{"data":{"id":1,"deleted":true}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/signal-runs":{"get":{"tags":["Signal runs"],"summary":"List a client's in-flight signal runs","description":"Returns all signal runs currently in progress for the named client: each item has an `id`, a `status` (`pending` or `in_progress` here) with a readable `label`, a `companies` array (the accounts being scanned) and the `signal_setup_id` it belongs to. Runs come newest first. `signal_setup_id` is `null` when the run is not tied to one of the client's signal setups. This is a snapshot, not a page: an empty `data` array means no runs are in progress.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"responses":{"200":{"description":"The in-flight signal runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SignalRunListResponse"},"example":{"data":[{"id":1,"signal_setup_id":1,"status":"pending","label":"<label>","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","companies":[{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"}]}]}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"post":{"tags":["Signal runs"],"summary":"Launch a client's signal run","description":"Starts a detection run for the signal setup across the named client's key accounts. A launch starts one run per direction (inbound and outbound) for signal setups that watch a competitor, partner or influencer list, plus one Discovery run when the signal setup's `scopes` include `discovery`. Champion signal setups always start one run. Each run returns one element in `data`. The runs start immediately and the response is `202 Accepted`.\n\nUse each `id` from `data` with `GET /v3/partner/workspaces/{partner_workspace_id}/signal-runs/{signal_run_id}` to follow that run until its `status` is `completed` or `failed`.\n\nA launch is refused with `409 Conflict` while any run of the signal setup is still in progress (poll to completion first, then launch again), when the signal setup is disabled, and when none of the accounts it checks is monitored right now (`code` is `no_monitored_account` or `no_covered_account`).\n\nSignals found in Discovery are invoiced to you at the template's Discovery price (see Usage); the launch is never refused for credits. A launch the signal setup cannot run as configured (for example it has no list or no keywords), a job-change signal setup that looks for new people but has no job titles (neither on the setup nor on the client's persona), and a `signal_setup_id` that is not a signal setup of the client's workspace are refused with `422`. Every refusal ends its `detail` with the sentence Nothing was started.\n\nThe launch takes no idempotency key: each call starts new runs, so check `GET /v3/partner/workspaces/{partner_workspace_id}/signal-runs` (runs in progress) or `GET /v3/partner/workspaces/{partner_workspace_id}/requests-status` before retrying a call that did not answer.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3LaunchSignalRunBody"}}}},"responses":{"202":{"description":"Signal run(s) accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SignalRunLaunchResponse"},"examples":{"list_signal":{"summary":"Signal setup watching a list — two runs (inbound + outbound)","value":{"data":[{"id":12345,"status":"in_progress","label":"Detecting signals","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","companies":[],"signal_setup_id":42},{"id":12346,"status":"in_progress","label":"Detecting signals","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","companies":[],"signal_setup_id":42}]}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"403":{"description":"The client's workspace is blocked, so no run can be launched. Nothing was started.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"description":"The launch is refused: a run of this signal setup is already in progress, the signal setup is disabled, or none of the accounts it checks is monitored right now (`code` is `no_monitored_account` or `no_covered_account`). Nothing was started.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"The launch is refused: the signal setup cannot be launched as configured (for example it has no list or no keywords), or `signal_setup_id` is not a signal setup of the client (`errors.signal_setup_id`). Nothing was started.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/signal-runs/{signal_run_id}":{"get":{"tags":["Signal runs"],"summary":"Get a client's signal run","description":"Returns the current status of a run: its `id`, `status` (`pending`, `in_progress`, `completed` or `failed`) and `label`, the accounts it covers and the signal setup it belongs to. It answers the same item as the in-flight list, with a `status` that ends at `completed` or `failed`, plus `metadata`. A run belonging to a different workspace returns `404`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"signal_run_id","in":"path","required":true,"description":"The run `id` returned by the launch endpoint.","schema":{"type":"integer"}}],"responses":{"200":{"description":"The signal run status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SignalRunResponse"},"example":{"data":{"id":1,"signal_setup_id":1,"status":"pending","label":"<label>","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","companies":[{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"}],"metadata":{"failed":{"dropped_company_ids":[1]}}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/lists":{"post":{"tags":["Lists"],"summary":"Create a list for a client","description":"Creates a reusable list of companies or people for the named client. What it holds follows from the type you pick, which cannot be changed afterwards. A prospect list carries a `tier` (1, 2 or 3; Tier 1 when you send none). A customer list carries none, and sending a `tier` for it is refused with a 422.\n\nThe call takes no idempotency key: a retry creates a second list (list names do not have to be unique). Before retrying a call that did not answer, check `GET /v3/partner/workspaces/{partner_workspace_id}/lists`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ListCreateBody"}}}},"responses":{"201":{"description":"The created list.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3List"}}},"example":{"data":{"id":1,"kind":"company","type":"competitor","name":"<name>","description":"<description>","member_count":1,"bound_signal_setup_count":1,"tier":1,"signal_buckets":["essential"],"monitoring_by_persona":[{"persona_id":1,"monitored_count":1,"not_covered_count":1}],"mode":"manual","archived_at":"2026-01-15T09:30:00.000Z","archived":true,"persona_ids":[1],"is_deletable":true,"not_deletable_reason":"last_list_of_tier"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"get":{"tags":["Lists"],"summary":"List the lists of a client","description":"Returns the lists in the client's workspace, a page at a time. The total is in `meta.pagination`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["competitor","partner","customer","prospect","influencer","champion","employee"]},"description":"Only return lists of this type."},{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to get archived lists alongside the active ones, or `false` (the default) to leave them out. Deleted lists never appear. Any other value is refused with a 422 that names the accepted values."},{"name":"persona_id","in":"query","required":false,"schema":{"type":"integer"},"description":"Narrow to one persona, given as its persona ID (from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`). Returns the lists attached to it plus every list that belongs to no persona, since those stay visible from all of them. Omit to get every list in the workspace."},{"name":"response_format","in":"query","required":false,"schema":{"type":"string","enum":["concise","normalized"],"default":"normalized"},"description":"How much detail to return. `concise` gives you exactly id, kind, type and name; `normalized` (the default) adds the description, the counts, the tier, the monitoring settings, the mode, the archive date and the personas. In `concise`, every other field is absent rather than null."}],"responses":{"200":{"description":"A page of lists.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3List"}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["page","page_size","page_count","total"],"properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"page_count":{"type":"integer"},"total":{"type":"integer"}}}}}}},"example":{"data":[{"id":1,"kind":"company","type":"competitor","name":"<name>","description":"<description>","member_count":1,"bound_signal_setup_count":1,"tier":1,"signal_buckets":["essential"],"monitoring_by_persona":[{"persona_id":1,"monitored_count":1,"not_covered_count":1}],"mode":"manual","archived_at":"2026-01-15T09:30:00.000Z","archived":true,"persona_ids":[1],"is_deletable":true,"not_deletable_reason":"last_list_of_tier"}],"meta":{"pagination":{"page":1,"page_size":1,"page_count":1,"total":1}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/lists/{kind}/{list_id}":{"get":{"tags":["Lists"],"summary":"Get a list","description":"Returns one list.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["company","profile"]},"description":"Whether the list holds companies or people, matching its type. It is part of the path so the two id spaces can never collide."},{"name":"list_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the list."},{"name":"response_format","in":"query","required":false,"schema":{"type":"string","enum":["concise","normalized"],"default":"normalized"},"description":"How much detail to return. `concise` gives you exactly id, kind, type and name; `normalized` (the default) adds the description, the counts, the tier, the monitoring settings, the mode, the archive date and the personas. In `concise`, every other field is absent rather than null."}],"responses":{"200":{"description":"The list.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3List"}}},"example":{"data":{"id":1,"kind":"company","type":"competitor","name":"<name>","description":"<description>","member_count":1,"bound_signal_setup_count":1,"tier":1,"signal_buckets":["essential"],"monitoring_by_persona":[{"persona_id":1,"monitored_count":1,"not_covered_count":1}],"mode":"manual","archived_at":"2026-01-15T09:30:00.000Z","archived":true,"persona_ids":[1],"is_deletable":true,"not_deletable_reason":"last_list_of_tier"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"patch":{"tags":["Lists"],"summary":"Update a list","description":"Renames a list, changes its description, archives or brings it back, and replaces which personas it belongs to. The list type cannot be changed. Archiving follows the same rule as deleting: it is refused when the list is the only one of its kind for its persona (for a prospect list, of its tier) (for example, the only prospect Tier 1 list of a persona), when a signal setup still reads it, or when it is the client's \"All my employees\" list. The \"All my employees\" list cannot be moved to a persona either. `is_deletable` and `not_deletable_reason` on the list tell you beforehand.\n\n**Monitor or stop a whole list.** Send `signal_buckets: [\"essential\"]` to monitor every account on a customer or prospect list, including the accounts added to it later, or `signal_buckets: null` to stop monitoring all of them. To pick individual accounts instead, use `PUT /v3/partner/workspaces/{partner_workspace_id}/account-monitoring/accounts`.\n\nSend only the fields you want to change. A field this route does not accept, such as `type` or `mode`, is refused with a 422.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["company","profile"]},"description":"Whether the list holds companies or people, matching its type. It is part of the path so the two id spaces can never collide."},{"name":"list_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the list."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ListUpdateBody"}}}},"responses":{"200":{"description":"The updated list.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3List"}}},"example":{"data":{"id":1,"kind":"company","type":"competitor","name":"<name>","description":"<description>","member_count":1,"bound_signal_setup_count":1,"tier":1,"signal_buckets":["essential"],"monitoring_by_persona":[{"persona_id":1,"monitored_count":1,"not_covered_count":1}],"mode":"manual","archived_at":"2026-01-15T09:30:00.000Z","archived":true,"persona_ids":[1],"is_deletable":true,"not_deletable_reason":"last_list_of_tier"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"description":"The change is refused. `code` tells why: `last_list_of_tier` (archiving the only list of its kind for its persona, of its tier for a prospect list), `list_in_use` (a signal setup or an older app signal uses the list), `list_persona_setup_conflict` (a signal setup would end up on a list its persona is not attached to; `signal_setup_ids` names them), or `conflict` (the employee list, which cannot be archived or moved). Nothing was changed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"delete":{"tags":["Lists"],"summary":"Delete a list","description":"Deletes a list. It and its members stop being returned everywhere. Deleting a monitored list stops its monitoring. The month already invoiced is not credited back. Refused when the list is the only one of its kind for its persona (for a prospect list, of its tier) (for example, the only prospect Tier 1 list of a persona), when a signal setup still reads it, or when it is the client's \"All my employees\" list. To move a list out of the way without deleting it, archive it instead.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["company","profile"]},"description":"Whether the list holds companies or people, matching its type. It is part of the path so the two id spaces can never collide."},{"name":"list_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the list."}],"responses":{"200":{"description":"The id of the deleted list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3Deleted"},"example":{"data":{"id":1,"deleted":true}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"description":"The list cannot be deleted. `code` tells why: `last_list_of_tier` (the only list of its kind for its persona, of its tier for a prospect list), `list_in_use` (a signal setup or an older app signal uses it) or `conflict` (the employee list, which can never be deleted).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/lists/{kind}/{list_id}/members":{"get":{"tags":["Lists"],"summary":"List members","description":"Returns the members of a list, a page at a time. A member's `id` is the one the rest of the API uses for that company or person: `GET /v3/partner/workspaces/{partner_workspace_id}/companies/{company_id}` for a company, `GET /v3/partner/workspaces/{partner_workspace_id}/leads/{lead_id}` for a person.\n\nEach member carries `signal_buckets` (null when its account is not monitored). On customer and prospect lists it also carries its `monitoring`: one entry per persona the list is attached to, or per active persona when it is attached to none; on every other list `monitoring` is null. `monitoring` is an empty array when the client has no persona (every member then counts as `not_monitored`). `monitoring` comes in the `normalized` format only: with `response_format=concise` members do not carry it.\n\nMembers come in the order they were added to the list, latest first. The order is fixed.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["company","profile"]},"description":"Whether the list holds companies or people, matching its type. It is part of the path so the two id spaces can never collide."},{"name":"list_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the list."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"response_format","in":"query","required":false,"schema":{"type":"string","enum":["concise","normalized"],"default":"normalized"},"description":"How much detail to return for each member. `concise` gives you exactly id, linkedin_handle and linkedin_url; `normalized` (the default) adds the name and logo of a company, or the name, photo, position, headline, enrichment status and current company of a person, plus `signal_buckets` and, on customer and prospect lists, `monitoring`. In `concise`, every other field is absent rather than null."},{"name":"signal_buckets","in":"query","required":false,"schema":{"type":"string","enum":["essential","none"]},"description":"Only members monitored through this list (`essential`) or not monitored through this list (`none`). An account monitored through another list still counts as `none` here; its `monitoring` field tells whether the account is monitored at all."},{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Searches members by name or LinkedIn handle, and people also by their current company's name. Not case-sensitive. 1 to 255 characters."},{"name":"persona_id","in":"query","required":false,"schema":{"type":"integer"},"description":"Only read monitoring in this persona, given as its persona ID (from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`): `monitoring` then holds this persona only, and `monitoring_status` is checked against it. Customer and prospect lists only: any other list answers 422, and so does an id that is not one of the client's active personas."},{"name":"monitoring_status","in":"query","required":false,"schema":{"type":"string","enum":["monitored","not_covered","monitored_elsewhere","not_monitored"]},"description":"Only members with this monitoring status in at least one persona of their `monitoring` (or in the persona given by `persona_id`). When the client's workspace has no persona, `not_monitored` matches every member and any other status matches none. Customer and prospect lists only: any other list answers 422."}],"responses":{"200":{"description":"A page of members.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3ListMember"}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["page","page_size","page_count","total"],"properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"page_count":{"type":"integer"},"total":{"type":"integer"}}}}}}},"example":{"data":[{"id":1,"name":"<name>","first_name":"<first_name>","last_name":"<last_name>","linkedin_handle":"<linkedin_handle>","linkedin_url":"<linkedin_url>","logo_url":"<logo_url>","avatar_url":"<avatar_url>","position":"<position>","linkedin_headline":"<linkedin_headline>","enrichment_status":"<enrichment_status>","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"},"signal_buckets":["essential"],"monitoring":[{"persona_id":1,"status":"monitored","covered_until":"2026-01-15T09:30:00.000Z","not_covered_since":"2026-01-15T09:30:00.000Z"}]}],"meta":{"pagination":{"page":1,"page_size":1,"page_count":1,"total":1}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"post":{"tags":["Lists"],"summary":"Add members","description":"Adds companies or people to a list. Identify each one by its LinkedIn URL or handle; on company lists a domain also works when you have nothing else. Members that could not be added (the wrong kind for the list, or not a usable identifier) come back in `rejected`, one entry each — the rest are still added. Someone already on the list is returned in `already_in_list`, and nothing changes for them. Adding accounts to a monitored list starts monitoring, and invoicing, them right away. Smart lists are managed in the app; their members can't be added or removed through the API.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["company","profile"]},"description":"Whether the list holds companies or people, matching its type. It is part of the path so the two id spaces can never collide."},{"name":"list_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the list."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ListAddMembersBody"}}}},"responses":{"200":{"description":"What happened to each member you sent. `added`: now on the list. `already_in_list`: was already on it, so nothing changed. `rejected`: could not be added, with a `code` and a `message`; the others are still added. Every added or already-present member carries the `input` you sent for it. The status is 200 even when nothing could be added: `added` is then empty and `rejected` says why. Unlike the members list, these members do not carry `monitoring`.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["added","already_in_list","rejected"],"properties":{"added":{"type":"array","items":{"$ref":"#/components/schemas/V3ListMemberResult"}},"already_in_list":{"type":"array","items":{"$ref":"#/components/schemas/V3ListMemberResult"}},"rejected":{"type":"array","items":{"$ref":"#/components/schemas/V3ListMemberAddError"}}}}}},"example":{"data":{"added":[{"id":1,"name":"<name>","first_name":"<first_name>","last_name":"<last_name>","linkedin_handle":"<linkedin_handle>","linkedin_url":"<linkedin_url>","logo_url":"<logo_url>","avatar_url":"<avatar_url>","position":"<position>","linkedin_headline":"<linkedin_headline>","enrichment_status":"<enrichment_status>","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"},"signal_buckets":["essential"],"monitoring":[{"persona_id":1,"status":"monitored","covered_until":"2026-01-15T09:30:00.000Z","not_covered_since":"2026-01-15T09:30:00.000Z"}],"input":{"linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","domain":"<domain>","company":{"name":"<name>","domain":"<domain>"}}}],"already_in_list":[{"id":1,"name":"<name>","first_name":"<first_name>","last_name":"<last_name>","linkedin_handle":"<linkedin_handle>","linkedin_url":"<linkedin_url>","logo_url":"<logo_url>","avatar_url":"<avatar_url>","position":"<position>","linkedin_headline":"<linkedin_headline>","enrichment_status":"<enrichment_status>","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"},"signal_buckets":["essential"],"monitoring":[{"persona_id":1,"status":"monitored","covered_until":"2026-01-15T09:30:00.000Z","not_covered_since":"2026-01-15T09:30:00.000Z"}],"input":{"linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","domain":"<domain>","company":{"name":"<name>","domain":"<domain>"}}}],"rejected":[{"input":{"linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","domain":"<domain>"},"code":"multiple_domain_matches","message":"<message>"}]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"description":"The list does not take members through the API. `code` is `smart_list`: Smart lists are managed in the app.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/lists/{kind}/{list_id}/restore":{"post":{"tags":["Lists"],"summary":"Restore a list","description":"Brings a deleted list back, with the same members and settings it had. A list that was monitored starts being monitored, and invoiced, again right away. Calling it on a list that was never deleted changes nothing and still succeeds. It takes no body: any field sent is refused with a 422.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["company","profile"]},"description":"Whether the list holds companies or people, matching its type. It is part of the path so the two id spaces can never collide."},{"name":"list_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the list."}],"responses":{"200":{"description":"The restored list.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3List"}}},"example":{"data":{"id":1,"kind":"company","type":"competitor","name":"<name>","description":"<description>","member_count":1,"bound_signal_setup_count":1,"tier":1,"signal_buckets":["essential"],"monitoring_by_persona":[{"persona_id":1,"monitored_count":1,"not_covered_count":1}],"mode":"manual","archived_at":"2026-01-15T09:30:00.000Z","archived":true,"persona_ids":[1],"is_deletable":true,"not_deletable_reason":"last_list_of_tier"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/lists/{kind}/{list_id}/membership-logs":{"get":{"tags":["Lists"],"summary":"List membership log","description":"Returns every time a company or a person entered or left this list, or had its owner or monitoring changed, newest first. Only real changes are recorded.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["company","profile"]},"description":"Whether the list holds companies or people, matching its type. It is part of the path so the two id spaces can never collide."},{"name":"list_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the list."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"A page of history entries, newest first.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3ListMembershipLogItem"}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["page","page_size","page_count","total"],"properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"page_count":{"type":"integer"},"total":{"type":"integer"}}}}}}},"example":{"data":[{"id":1,"transition":"entered","reason":"manual","reason_detail":{},"previous_value":"<previous_value>","new_value":"<new_value>","created_at":"2026-01-15T09:30:00.000Z","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"},"lead":{"id":1,"full_name":"<full_name>","first_name":"<first_name>","last_name":"<last_name>","linkedin_url":"<linkedin_url>","linkedin_headline":"<linkedin_headline>","position":"<position>","avatar_url":"<avatar_url>"}}],"meta":{"pagination":{"page":1,"page_size":1,"page_count":1,"total":1}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/lists/{kind}/{list_id}/members/{member_id}":{"delete":{"tags":["Lists"],"summary":"Remove a member from a list","description":"Removes one member from a list. When the list is monitored, removing a member stops monitoring that account through this list; the month already paid is kept (`covered_until` on the member's `monitoring` tells when it ends). Smart lists are managed in the app; their members can't be added or removed through the API.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["company","profile"]},"description":"Whether the list holds companies or people, matching its type. It is part of the path so the two id spaces can never collide."},{"name":"list_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the list."},{"name":"member_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Identifier of the member, as returned by the members endpoint."}],"responses":{"200":{"description":"The id of the removed member.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3Deleted"},"example":{"data":{"id":1,"deleted":true}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"description":"The list does not take members through the API. `code` is `smart_list`: Smart lists are managed in the app.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/leads/query":{"post":{"tags":["Leads"],"summary":"Query leads","description":"Returns the leads in the client's workspace, sorted by creation date (most recent first by default). Each item has the same shape as `GET /v3/partner/workspaces/{partner_workspace_id}/leads/{lead_id}`.\n\nThe list is cursor-paginated: each response includes `meta.cursor.next` — pass it back as `cursor` (with the same `sort` and filters) to fetch the next page, until `meta.cursor.has_more` is `false`.\n\nFilters are passed as a JSON body, so identifier arrays (`company_domain`, `company_linkedin_handle`, `company_linkedin_url`) are not bound by URL length limits. A company filter that matches no company in the workspace returns an empty page, not an error.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3LeadsQueryBody"}}}},"responses":{"200":{"description":"Cursor-paginated list of leads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3LeadsPaginatedResponse"},"example":{"data":[{"id":1,"created_at":"2026-01-15T09:30:00.000Z","first_name":"<first_name>","last_name":"<last_name>","full_name":"<full_name>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","linkedin_headline":"<linkedin_headline>","avatar_url":"<avatar_url>","email":"<email>","phone":"<phone>","position":"<position>","location":{"city":"<city>","region":"<region>","country":"<country>","country_code":"<country_code>"},"company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>","activity_summary":"<activity_summary>","employee_range":"<employee_range>","location":{"city":"<city>","region":"<region>","country":"<country>","country_code":"<country_code>"},"in_key_account_list":true},"experiences":[{"position":"<position>","company_name":"<company_name>","company_linkedin_url":"<company_linkedin_url>","location":"<location>","start_date":"2026-01-15T09:30:00.000Z","end_date":"2026-01-15T09:30:00.000Z","is_current":true}],"status":"pending","owner":{"email":"<email>","first_name":"<first_name>","last_name":"<last_name>"},"crm_records":[{"provider":"salesforce","contact_id":"<contact_id>","account_id":"<account_id>"}]}],"meta":{"cursor":{"next":"<next>","has_more":true},"resolved_companies":[{"matched_by":"company_ids","identifier":"<identifier>","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"}}]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/leads/count":{"post":{"tags":["Leads"],"summary":"Count leads","description":"Returns the number of leads in the client's workspace matching the same filters as `POST /v3/partner/workspaces/{partner_workspace_id}/leads/query`, sent in the same JSON body without `cursor`, `limit` and `sort`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3LeadsCountBody"}}}},"responses":{"200":{"description":"The number of matching leads.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["total"],"properties":{"total":{"type":"integer"}}}}},"example":{"data":{"total":1}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/leads/{lead_id}":{"get":{"tags":["Leads"],"summary":"Get a lead","description":"Returns a lead in the client's workspace, with its linked profile details, a reference to its current company, its LinkedIn work history, and its current pipeline status and owner.\n\nA lead with no linked profile is returned with the profile fields set to `null`. When the current company cannot be resolved, the `company` field is `null`. The `experiences` array lists the lead's work history in the order it appears on their LinkedIn profile, including their current position; it is `null` when this data is not available for this lead. None of these cases is an error.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"lead_id","in":"path","required":true,"description":"The lead's numeric ID. Always use the `lead_id` returned by the signals endpoints — don't guess, hard-code, or copy an id from an example or another workspace.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Lead data.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3Lead"}}},"example":{"data":{"id":1,"created_at":"2026-01-15T09:30:00.000Z","first_name":"<first_name>","last_name":"<last_name>","full_name":"<full_name>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","linkedin_headline":"<linkedin_headline>","avatar_url":"<avatar_url>","email":"<email>","phone":"<phone>","position":"<position>","location":{"city":"<city>","region":"<region>","country":"<country>","country_code":"<country_code>"},"company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>","activity_summary":"<activity_summary>","employee_range":"<employee_range>","location":{"city":"<city>","region":"<region>","country":"<country>","country_code":"<country_code>"},"in_key_account_list":true},"experiences":[{"position":"<position>","company_name":"<company_name>","company_linkedin_url":"<company_linkedin_url>","location":"<location>","start_date":"2026-01-15T09:30:00.000Z","end_date":"2026-01-15T09:30:00.000Z","is_current":true}],"status":"pending","owner":{"email":"<email>","first_name":"<first_name>","last_name":"<last_name>"},"crm_records":[{"provider":"salesforce","contact_id":"<contact_id>","account_id":"<account_id>"}]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"patch":{"tags":["Leads"],"summary":"Update a client's lead","description":"Updates a lead's pipeline status and/or its assigned owner, in the client's workspace. Send only the fields you want to change.\n\n---\n\n## Status values\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Default status for new leads |\n| `contacted_email` | Contacted via email |\n| `contacted_phone` | Contacted via phone |\n| `contacted_linkedin` | Contacted via LinkedIn |\n| `meeting_booked` | Meeting has been booked |\n| `need_follow_up` | Requires follow-up |\n| `already_in_touch` | Already in contact |\n| `customer` | Converted to customer |\n| `declined` | Lead declined |\n| `disqualified` | Lead disqualified |\n| `company_not_icp` | Company does not match the ideal customer profile |\n| `job_title_not_icp` | Job title does not match the ideal customer profile |\n\n---\n\n## Owner\n\nSet `owner_email` to a workspace member's email to assign ownership. Send `owner_email: null` to unassign the current owner. At least one of `status` or `owner_email` must be present.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"lead_id","in":"path","required":true,"description":"The lead's numeric ID.","schema":{"type":"integer","minimum":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3LeadUpdateBody"}}}},"responses":{"200":{"description":"The updated lead, in the same shape as `GET /v3/partner/workspaces/{partner_workspace_id}/leads/{lead_id}`.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3Lead"}}},"example":{"data":{"id":1,"created_at":"2026-01-15T09:30:00.000Z","first_name":"<first_name>","last_name":"<last_name>","full_name":"<full_name>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","linkedin_headline":"<linkedin_headline>","avatar_url":"<avatar_url>","email":"<email>","phone":"<phone>","position":"<position>","location":{"city":"<city>","region":"<region>","country":"<country>","country_code":"<country_code>"},"company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>","activity_summary":"<activity_summary>","employee_range":"<employee_range>","location":{"city":"<city>","region":"<region>","country":"<country>","country_code":"<country_code>"},"in_key_account_list":true},"experiences":[{"position":"<position>","company_name":"<company_name>","company_linkedin_url":"<company_linkedin_url>","location":"<location>","start_date":"2026-01-15T09:30:00.000Z","end_date":"2026-01-15T09:30:00.000Z","is_current":true}],"status":"pending","owner":{"email":"<email>","first_name":"<first_name>","last_name":"<last_name>"},"crm_records":[{"provider":"salesforce","contact_id":"<contact_id>","account_id":"<account_id>"}]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/companies/query":{"post":{"tags":["Companies"],"summary":"Search companies","description":"Searches the companies in the client's workspace by name and/or domain (case-insensitive substring) and returns the matches with their identifier in the client's workspace, sorted by name from A to Z.\n\nProvide at least one of `name` or `domain`. When both are given, only companies matching both are returned.\n\nUse the returned `id` directly as `company_ids` on `POST /v3/partner/workspaces/{partner_workspace_id}/leads/query` to filter leads by company.\n\nThe search is not paged: it returns the first `limit` matches. If you get exactly `limit` results there may be more, so refine `name` or `domain`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","anyOf":[{"required":["name"]},{"required":["domain"]}],"properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Case-insensitive substring to match against company names. At least one of `name` or `domain` is required.","example":"sales"},"domain":{"type":"string","minLength":1,"maxLength":200,"description":"Case-insensitive substring to match against company website domains. At least one of `name` or `domain` is required.","example":"salesforce.com"},"limit":{"type":"integer","minimum":1,"maximum":50,"description":"Maximum number of matches to return (default 20, max 50)."}}}}}},"responses":{"200":{"description":"Matching companies. No `meta` — this is a capped search, not a page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3CompanySearchResponse"},"examples":{"sample":{"summary":"Search result","value":{"data":[{"id":70030,"name":"Salesforce","domain":"salesforce.com","linkedin_handle":"salesforce"}]}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/companies/{company_id}":{"get":{"tags":["Companies"],"summary":"Get a company","description":"Returns the enrichment data for a company in the client's workspace.\n\n`id` in the response is the company's identifier within the workspace: the same value passed in the URL, the one returned as `company.id` on a lead.\n\nIf the company has not been enriched yet, the enrichment fields are returned as `null` — this endpoint never triggers enrichment.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"company_id","in":"path","required":true,"description":"The company's identifier in this workspace, as returned by other v3 endpoints.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Company data.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3Company"}}},"example":{"data":{"id":1,"name":"<name>","domain":"<domain>","website_url":"<website_url>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>","location":{"city":"<city>","region":"<region>","country":"<country>","country_code":"<country_code>"},"locations":[{"is_hq":true,"city":"<city>","region":"<region>","state":"<state>","country":"<country>","country_code":"<country_code>","postal_code":"<postal_code>","line1":"<line1>","line2":"<line2>","formatted_address":"<formatted_address>","latitude":1,"longitude":1}],"number_of_employees":1,"employee_range":"<employee_range>","founded_year":1,"industries":["<industries>"],"activity_summary":"<activity_summary>","tagline":"<tagline>"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/contents/query":{"post":{"tags":["Contents"],"summary":"Query contents","description":"Returns a cursor-paginated list of content items — LinkedIn posts, comments, reactions and job postings, plus articles, press releases and blog posts, collected for the client's key accounts — most recent first. Pass `meta.cursor.next` as `cursor` on the next request to keep paging, until `meta.cursor.has_more` is `false`.\n\nFilters are passed as a JSON body, so identifier arrays (`company_domain`, `company_linkedin_handle`, `company_linkedin_url`) are not bound by URL length limits.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ContentsQueryBody"}}}},"responses":{"200":{"description":"A page of contents, most recent first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ContentsPaginatedResponse"},"example":{"data":[{"id":1,"content_type":"linkedin_comment","created_at":"2026-01-15T09:30:00.000Z","details":{"linkedin_post_id":"<linkedin_post_id>","linkedin_original_post_id":"<linkedin_original_post_id>","is_repost":true,"linkedin_url":"<linkedin_url>","text":"<text>","posted_at":"2026-01-15T09:30:00.000Z","engagement":{"likes":1,"comments":1,"shares":1,"praise":1,"empathy":1,"interest":1,"appreciation":1},"author":{},"mentions":{"profiles":[null],"companies":[null]},"image_urls":["<image_urls>"]},"lead":{"id":1,"full_name":"<full_name>","first_name":"<first_name>","last_name":"<last_name>","linkedin_url":"<linkedin_url>","linkedin_headline":"<linkedin_headline>","position":"<position>","avatar_url":"<avatar_url>"},"company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"}}],"meta":{"cursor":{"next":"<next>","has_more":true},"resolved_companies":[{"matched_by":"company_ids","identifier":"<identifier>","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"}}]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/contents/{content_id}":{"get":{"tags":["Contents"],"summary":"Get a content item","description":"Returns a single content item from the client's workspace.\n\nPass the `id` returned by `POST /v3/partner/workspaces/{partner_workspace_id}/contents/query`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"content_id","in":"path","required":true,"description":"The content item id, as returned by `POST /v3/partner/workspaces/{partner_workspace_id}/contents/query`.","schema":{"type":"integer","minimum":1}},{"name":"response_format","in":"query","description":"Controls how much detail the `details` field includes.\n\n- `normalized` (default): a clean, stable projection of the content — see `details` in the response schema.\n- `concise`: `details` is omitted entirely.\nAny other value is refused with a 422.","schema":{"type":"string","enum":["concise","normalized"],"default":"normalized"}}],"responses":{"200":{"description":"Content item.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3ContentItem"}}},"example":{"data":{"id":1,"content_type":"linkedin_comment","created_at":"2026-01-15T09:30:00.000Z","details":{"linkedin_post_id":"<linkedin_post_id>","linkedin_original_post_id":"<linkedin_original_post_id>","is_repost":true,"linkedin_url":"<linkedin_url>","text":"<text>","posted_at":"2026-01-15T09:30:00.000Z","engagement":{"likes":1,"comments":1,"shares":1,"praise":1,"empathy":1,"interest":1,"appreciation":1},"author":{"type":"person"},"mentions":{"profiles":[{"full_name":"<full_name>","linkedin_url":"<linkedin_url>"}],"companies":[{"name":"<name>","linkedin_url":"<linkedin_url>"}]},"image_urls":["<image_urls>"]},"lead":{"id":1,"full_name":"<full_name>","first_name":"<first_name>","last_name":"<last_name>","linkedin_url":"<linkedin_url>","linkedin_headline":"<linkedin_headline>","position":"<position>","avatar_url":"<avatar_url>"},"company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/account-monitoring":{"get":{"tags":["Account monitoring"],"summary":"Get monitoring summary","description":"Returns how many accounts are monitored for this client and what monitoring costs each month. Monitoring is invoiced to you per account, per persona, per month, at your partner price. An account is monitored once per persona, so an account monitored in two personas counts twice and is invoiced twice.\n\nWithout `persona_id` the totals cover the whole workspace; with it, that persona only. `by_persona` always lists every persona.\n\nA renewal is never refused for a client, so `not_covered_count` is always 0, `not_covered_since` is `null` and `renewal_shortfall_credits` is 0.\n\nIf monitoring is not billed for this workspace, `is_billed` is `false` and every cost is 0.\n\nTo monitor or stop a whole list, including the accounts added to it later, use `PATCH /v3/partner/workspaces/{partner_workspace_id}/lists/{kind}/{list_id}` with `signal_buckets: [\"essential\"]` (or `null` to stop).\n\nMonitoring an account covers its account mapping, its signals and its content.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"persona_id","in":"query","required":false,"schema":{"type":"integer"},"description":"Only count this persona (from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`)."}],"responses":{"200":{"description":"The monitoring totals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AccountMonitoringSummaryResponse"},"example":{"data":{"is_billed":true,"price_per_account_credits":1,"monitored_count":1,"not_covered_count":1,"not_covered_since":"2026-01-15T09:30:00.000Z","monthly_cost_credits":1,"renewal_shortfall_credits":1,"by_persona":[{"persona_id":1,"monitored_count":1,"not_covered_count":1,"monthly_cost_credits":1}]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/account-monitoring/accounts":{"put":{"tags":["Account monitoring"],"summary":"Monitor or stop accounts","description":"Turns monitoring on (`signal_buckets: [\"essential\"]`) or off (`signal_buckets: null`) for up to 1,000 accounts in one persona. It is invoiced to you per account and persona for a month, at your partner price.\n\nMonitoring applies through the customer and prospect lists attached to the persona. An account that is not on such a list, or only on lists attached to no persona or to other personas, is returned in `rejected`, and so is an id that is not an account of the workspace (`not_found`). Stopping an account that is also monitored through a list attached to no persona is refused too: stop that list instead. When a list is attached to several personas, monitoring or stopping an account on it does so in each of them.\n\nAccounts already in the state you ask for are returned in `already_in_state` and are not charged twice. A request where every account is refused still succeeds with status 200; check `rejected`.\n\nNothing is taken from a balance: `charged_credits` is always 0 and `balance_after_credits` is `null`. Stopping does not cancel the month already started: `covered_until` is when signals stop.\n\nTo monitor or stop a whole list, including the accounts added to it later, use `PATCH /v3/partner/workspaces/{partner_workspace_id}/lists/{kind}/{list_id}` with `signal_buckets: [\"essential\"]` (or `null` to stop) instead of picking accounts here.\n\nMonitoring an account covers its account mapping, its signals and its content.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AccountMonitoringApplyBody"}}}},"responses":{"200":{"description":"What changed, what was already in the asked state, what was refused, and what it cost.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3AccountMonitoringApplyResponse"},"example":{"data":{"changed":[{"company_id":1,"status":"monitored","covered_until":"2026-01-15T09:30:00.000Z"}],"already_in_state":[1],"rejected":[{"input":{"company_id":1},"code":"not_found","message":"<message>"}],"charged_credits":1,"balance_after_credits":1}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/content-requests/query":{"post":{"tags":["Content requests"],"summary":"Query content requests","description":"Lists the client's content requests, most recent first, filtered by the JSON arrays you send in the body. The list is cursor-paginated: pass `meta.cursor.next` as `cursor` on the next request to keep paging, until `meta.cursor.has_more` is `false`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ContentRequestsQueryBody"}}}},"responses":{"200":{"description":"A page of content requests, most recent first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3ContentRequestsPaginatedResponse"},"example":{"data":[{"id":1,"type":"account_mapping","status":"pending","label":"<label>","failed_reason":"no_employee_resolved","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"},"persona_ids":[1]}],"meta":{"cursor":{"next":"<next>","has_more":true},"resolved_companies":[{"matched_by":"company_ids","identifier":"<identifier>","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"}}]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/content-requests/{content_request_id}":{"get":{"tags":["Content requests"],"summary":"Get a content request","description":"Returns a single content request from the client's workspace.\n\nPass the `id` returned by `POST /v3/partner/workspaces/{partner_workspace_id}/content-requests/query`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"content_request_id","in":"path","required":true,"description":"The content request id, as returned by `POST /v3/partner/workspaces/{partner_workspace_id}/content-requests/query`.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Content request item.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3ContentRequestItem"}}},"example":{"data":{"id":1,"type":"account_mapping","status":"pending","label":"<label>","failed_reason":"no_employee_resolved","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"},"persona_ids":[1]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/personas":{"get":{"tags":["Personas"],"summary":"List personas","description":"Returns the client's personas, oldest first. A persona is the job titles, locations and company profile one team targets. Use a persona `id` as `persona_id` when you set up a signal in a workspace that has several personas. Archived personas are not listed. Personas drive account mapping, content and the client's signals (which people found by signals are kept and how well they fit); `tag` is only your own label.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Page number."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page."}],"responses":{"200":{"description":"The personas, paginated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PersonaListResponse"},"example":{"data":[{"id":1,"name":"<name>","job_titles":["<job_titles>"],"excluded_job_titles":["<excluded_job_titles>"],"locations":["<locations>"],"headcounts":["<headcounts>"],"industries":["<industries>"],"seniorities":["<seniorities>"],"exclusion_criteria":["<exclusion_criteria>"],"tag":"<tag>"}],"meta":{"pagination":{"page":1,"page_size":1,"page_count":1,"total":1}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"post":{"tags":["Personas"],"summary":"Create a persona","description":"Adds a persona to the client's workspace, next to the ones it already has. It never replaces an existing persona.\n\n`job_titles` and `locations` are required and must each carry at least one value. Returns the saved persona. `meta.warnings` carries advisory notes and is present only when there is something to report; the persona is saved either way.\n\nThe call takes no idempotency key: a retry creates a second persona. Before retrying a call that did not answer, check `GET /v3/partner/workspaces/{partner_workspace_id}/personas`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PersonaBody"}}}},"responses":{"201":{"description":"The persona was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PersonaUpsertResponse"},"example":{"data":{"id":1,"name":"<name>","job_titles":["<job_titles>"],"excluded_job_titles":["<excluded_job_titles>"],"locations":["<locations>"],"headcounts":["<headcounts>"],"industries":["<industries>"],"seniorities":["<seniorities>"],"exclusion_criteria":["<exclusion_criteria>"],"tag":"<tag>"},"meta":{"warnings":["<warnings>"]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"$ref":"#/components/responses/V3Conflict"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/personas/{persona_id}":{"get":{"tags":["Personas"],"summary":"Get a persona","description":"Retrieves one of the client's personas by ID. An archived persona, or one that belongs to another workspace, is reported as not found.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"persona_id","in":"path","required":true,"description":"The ID of the persona, from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`.","schema":{"type":"integer"}}],"responses":{"200":{"description":"The persona.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PersonaGetResponse"},"example":{"data":{"id":1,"name":"<name>","job_titles":["<job_titles>"],"excluded_job_titles":["<excluded_job_titles>"],"locations":["<locations>"],"headcounts":["<headcounts>"],"industries":["<industries>"],"seniorities":["<seniorities>"],"exclusion_criteria":["<exclusion_criteria>"],"tag":"<tag>"}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}},"patch":{"tags":["Personas"],"summary":"Update a persona","description":"Updates one of the client's personas. Send only the fields to change; every field you leave out is kept. A persona that is archived, or that belongs to another workspace, is reported as not found.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"persona_id","in":"path","required":true,"description":"The ID of the persona, from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`.","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PersonaPatchBody"}}}},"responses":{"200":{"description":"The updated persona.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PersonaUpsertResponse"},"example":{"data":{"id":1,"name":"<name>","job_titles":["<job_titles>"],"excluded_job_titles":["<excluded_job_titles>"],"locations":["<locations>"],"headcounts":["<headcounts>"],"industries":["<industries>"],"seniorities":["<seniorities>"],"exclusion_criteria":["<exclusion_criteria>"],"tag":"<tag>"},"meta":{"warnings":["<warnings>"]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"409":{"$ref":"#/components/responses/V3Conflict"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/company-mappings":{"get":{"tags":["Company mappings"],"summary":"List a client's company mappings","description":"Returns a paginated list of this client's company mappings, with their processing status, newest first.\n\nEmployee profiles aren't included here. Use `GET /v3/partner/workspaces/{partner_workspace_id}/company-mappings/{mapping_id}` to read a mapping together with its enriched profiles.\n\n`company.id` is the `id` of a member of a company list, and the value `company_ids` takes. It is `null` when the company is not one of this client's companies; `name` and `domain` are still returned.\n\nA `persona_id` that is not an active persona of the workspace is refused with a 422 (`errors.persona_id`).","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page."},{"name":"company_ids","in":"query","required":false,"description":"Only return the mappings of these companies, as a comma-separated list of company ids (the `company.id` of a mapping, the `id` of a member of a company list). Up to 20 values. An id that is not one of this client's companies matches nothing.","schema":{"type":"string","example":"81183,81190"}},{"name":"persona_id","in":"query","required":false,"description":"Only return the mappings made for this persona. Mappings made for every persona (`persona_id: null`) are left out.","schema":{"type":"integer","minimum":1}},{"name":"latest","in":"query","required":false,"description":"`true` to return only the newest mapping of each company for each persona, leaving out the older ones. Defaults to `false`.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"This client's company mappings, paginated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3CompanyMappingListResponse"},"example":{"data":[{"id":1,"created_at":"2026-01-15T09:30:00.000Z","version":1,"status":"in_progress","label":"<label>","persona_id":1,"company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"}}],"meta":{"pagination":{"page":1,"page_size":1,"page_count":1,"total":1}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/company-mappings/{mapping_id}":{"get":{"tags":["Company mappings"],"summary":"Get a client's company mapping","description":"Returns a single company mapping for this client, together with every enriched employee profile found for it.\n\nUse the `id` a list item returns from `GET /v3/partner/workspaces/{partner_workspace_id}/company-mappings` as `mapping_id`.\n\n`company.id` is the `id` of a member of a company list, and the value the `company_ids` filters take. It is `null` when the company is not one of this client's companies; `name` and `domain` are still returned.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"mapping_id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"The mapping id, as returned by `GET /v3/partner/workspaces/{partner_workspace_id}/company-mappings`."}],"responses":{"200":{"description":"Company mapping with its enriched profiles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3CompanyMappingResponse"},"example":{"data":{"id":1,"created_at":"2026-01-15T09:30:00.000Z","version":1,"status":"in_progress","label":"<label>","persona_id":1,"company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"},"profiles":[{"id":1,"linkedin_handle":"<linkedin_handle>","linkedin_url":"<linkedin_url>","avatar_url":"<avatar_url>","linkedin_about":"<linkedin_about>","position":"<position>","position_start_date":"<position_start_date>","first_name":"<first_name>","last_name":"<last_name>","full_name":"<full_name>","email":"<email>","phone":"<phone>","linkedin_headline":"<linkedin_headline>","location":{"city":"<city>","region":"<region>","country":"<country>","country_code":"<country_code>"},"seniority":"owner","department":"executive"}]}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/usage":{"get":{"tags":["Usage"],"summary":"List usage","description":"Returns the billing events behind the named client's credit consumption that are billed to you, as a cursor-paginated list, newest first. Each event is one movement of credits: what it paid for, the credits involved and where it stands in your invoicing.\n\n`created_at_from` and `created_at_to` are optional filters, each usable on its own, and both moments are included. With neither, the whole history is returned.\n\nEvents are ordered by `created_at`, newest first; events created at the same instant are ordered by `id`, highest first.\n\nPass `meta.cursor.next` from one response as `cursor` on the next request, with the same filters, to keep paging. When `meta.cursor.has_more` is `false`, you have reached the end.\n\nOnly finished charges are listed: reserved credits and cancelled reservations do not appear. Each event carries a `status`, which tells where its credits are in your invoicing:\n\n- `to_invoice` — will appear on your next invoice.\n- `invoiced` — an invoice covering it has been issued to you.\n- `paid` — that invoice has been paid.\n\nWhat you are invoiced for is the sum of the `credits` of the listed events.\n\nEach event carries a `product` object telling what the credits paid for. Its `scope` is `discovery` (a signal found by one of the client's signal setups) or `account_monitoring` (the monitoring of an account). Every key of `product` is always present and is `null` when it does not apply:\n\n- `signal_template_key`, `signal_setup_id`: the signal template and the signal setup that found the signal (`discovery` only). `signal_setup_id` is `null` when that signal setup no longer exists.\n- `signal_bucket`: the monitoring that was paid for (`account_monitoring` only).\n- `company_id`: the company, as its identifier in the client's workspace.\n- `persona_id`: the persona the signal setup or the monitoring was for, `null` when it had none.\n\nWhen a signal is deleted, the Discovery event that paid for it stays in the list, with `signal_template_key`, `signal_setup_id`, `company_id` and `persona_id` set to `null`.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"created_at_from","in":"query","required":false,"description":"Only events created at or after this moment, the moment itself included. ISO 8601 date and time with a UTC offset (encode `+` as `%2B` in the URL); a date without a time is rejected. When omitted, events are not bounded on the older side.","schema":{"type":"string","format":"date-time"}},{"name":"created_at_to","in":"query","required":false,"description":"Only events created at or before this moment, the moment itself included. ISO 8601 date and time with a UTC offset (encode `+` as `%2B` in the URL); a date without a time is rejected. When omitted, events are not bounded on the newer side. When both are provided, `created_at_to` must not be before `created_at_from`.","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Opaque pagination cursor. Pass `meta.cursor.next` from the previous response, with the same filters, to fetch the next page. Omit for the first page. A cursor that was not issued to you by this endpoint, or that is reused with other filters, is rejected with a 422."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of events to return."}],"responses":{"200":{"description":"Billing events matching the filters, one page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3PartnerUsageListResponse"},"example":{"data":[{"id":4812,"created_at":"2026-08-14T09:30:12.000Z","status":"to_invoice","credits":1.5,"product":{"scope":"discovery","signal_bucket":null,"signal_template_key":"mentioned-my-brand","signal_setup_id":31,"company_id":1207,"persona_id":12}},{"id":4790,"created_at":"2026-08-12T16:02:44.000Z","status":"invoiced","credits":30,"product":{"scope":"account_monitoring","signal_bucket":"essential","signal_template_key":null,"signal_setup_id":null,"company_id":1207,"persona_id":12}},{"id":4655,"created_at":"2026-07-03T08:15:00.000Z","status":"paid","credits":1.5,"product":{"scope":"discovery","signal_bucket":null,"signal_template_key":"mentioned-my-brand","signal_setup_id":31,"company_id":1310,"persona_id":12}}],"meta":{"cursor":{"next":null,"has_more":false}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/requests-status":{"get":{"tags":["Requests status"],"summary":"Get requests status","description":"Returns all work currently being processed in the named client's workspace as a flat, paginated list, newest first. Each item carries a `type` field telling you what kind of work it is.\n\nOnly pending and in-progress items are returned — failed and completed requests are excluded from this snapshot.\n\nEach item carries a `status` field and a `label`: a short readable description of the current step.\n\nItems of a content-request type carry the company they are running for and the timestamps. Items of type `signal` are exactly the items `GET /v3/partner/workspaces/{partner_workspace_id}/signal-runs` answers: a `companies` array (the accounts being scanned) and the `signal_setup_id` they belong to.\n\n`meta.pagination.total` is the true count of pending and in-progress items. The snapshot is paginated for extreme cases (e.g. a large account list being ingested): one call returns up to `page_size` items (default and maximum 500, newest first). When `meta.pagination.page_count` is greater than 1, request the remaining pages with `?page=2`, `?page=3`, and so on.\n\nAn empty `data` array means nothing is running — not an error.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number. Only needed when a previous response reported `meta.pagination.page_count` greater than 1."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":500},"description":"Items per page."}],"responses":{"200":{"description":"In-flight work across the client workspace, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3RequestsStatusResponse"},"example":{"data":[{"id":1,"type":"account_mapping","status":"pending","label":"<label>","failed_reason":"no_employee_resolved","created_at":"2026-01-15T09:30:00.000Z","updated_at":"2026-01-15T09:30:00.000Z","company":{"id":1,"name":"<name>","domain":"<domain>","linkedin_url":"<linkedin_url>","linkedin_handle":"<linkedin_handle>","logo_url":"<logo_url>"}}],"meta":{"pagination":{"page":1,"page_size":1,"page_count":1,"total":1}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}},"/v3/partner/workspaces/{partner_workspace_id}/setup-state":{"get":{"tags":["Setup state"],"summary":"Get a client's setup state","description":"Returns the named client's workspace setup completeness in one call, as a per-dimension checklist.\n\nThe checklist covers `persona`, `accounts`, `signal_setups`, and `contents`. Each dimension has a `status` (`ok`, `warning`, or `blocked`), a plain-language `message`, and, when relevant, a `recommended_next_route` naming what to call next, as `METHOD /path`. The path does not carry the partner prefix: call it under `/v3/partner/workspaces/{partner_workspace_id}` to act on the client.\n\nA `blocked` status on `contents` distinguishes two cases: the contents feature is not enabled for this workspace (contact Sillage) versus the feature being enabled with nothing generated yet (`warning`).\n\nThe `accounts` step is done once at least one company sits on a customer or prospect list.\n\n`signal_setups.count` counts the signal setups of the client workspace. `missing_priority_types` is informational only; `status` never depends on it.","security":[{"MasterKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PartnerWorkspaceId"}],"responses":{"200":{"description":"Setup state retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V3SetupStateResponse"},"example":{"data":{"checklist":{"persona":{"status":"ok","message":"<message>","recommended_next_route":"POST /v3/personas","job_titles_set":true,"locations_set":true},"accounts":{"status":"ok","message":"<message>","recommended_next_route":"POST /v3/personas","count":1},"signal_setups":{"status":"ok","message":"<message>","recommended_next_route":"POST /v3/personas","count":1,"missing_priority_types":["<missing_priority_types>"]},"contents":{"status":"ok","message":"<message>","recommended_next_route":"POST /v3/personas","has_contents":true}}}}}}},"401":{"$ref":"#/components/responses/V3Unauthorized"},"404":{"$ref":"#/components/responses/V3NotFound"},"422":{"$ref":"#/components/responses/V3UnprocessableEntity"},"429":{"$ref":"#/components/responses/V3TooManyRequests"},"500":{"$ref":"#/components/responses/V3InternalServerError"}}}}},"components":{"securitySchemes":{"MasterKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"mk_live_<key>","description":"Master API key issued per partner. Prefix: `mk_live_`."}},"parameters":{"PartnerWorkspaceId":{"name":"partner_workspace_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^/?#\\s]+$"},"description":"Your own ID for the client workspace, as you chose it at creation: 1 to 255 characters, with no `/`, `?`, `#` or whitespace. URL-encode it in the path. A malformed id is refused with a 422 and `errors.partner_workspace_id`."}},"responses":{"V3Unauthorized":{"description":"Unauthorized, invalid or missing master key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"V3TooManyRequests":{"description":"Too many requests. Wait `Retry-After` seconds, then retry.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The number of requests allowed in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"When the current window ends, as a Unix timestamp in milliseconds.","schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"V3InternalServerError":{"description":"Something went wrong on our side","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"V3NotFound":{"description":"No resource matches the given ID, or no workspace matches this partner_workspace_id","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"V3Conflict":{"description":"The request conflicts with the current state of the resource","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"V3UnprocessableEntity":{"description":"The request body is not valid JSON, or the request fails validation. A date range whose start is after its end is refused with `code` `invalid_date_range`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"schemas":{"V3PartnerWorkspace":{"type":"object","description":"One of your client workspaces.","required":["partner_workspace_id","name","domain","archived","created_at"],"properties":{"partner_workspace_id":{"type":"string","description":"Your own ID for the client."},"name":{"type":"string","description":"The name of the workspace."},"domain":{"type":"string","nullable":true,"description":"The main website of the client. Empty for the oldest workspaces, created before a domain was required."},"archived":{"type":"boolean","description":"Whether the workspace is paused."},"created_at":{"type":"string","format":"date-time","description":"When the workspace was created."}}},"V3PartnerWorkspaceListItem":{"description":"A workspace of the list. With `include_deleted=true`, every item also carries `deleted_at`.","allOf":[{"$ref":"#/components/schemas/V3PartnerWorkspace"},{"type":"object","properties":{"deleted_at":{"type":"string","format":"date-time","nullable":true,"description":"When the workspace was deleted, `null` if it is not. Present only with `include_deleted=true`."}}}]},"V3PartnerWorkspaceResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3PartnerWorkspace"}}},"V3PartnerWorkspaceListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3PartnerWorkspaceListItem"}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["page","page_size","page_count","total"],"properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"page_count":{"type":"integer"},"total":{"type":"integer"}}}}}}},"V3UpdatePartnerWorkspaceBody":{"type":"object","minProperties":1,"description":"The fields of a workspace you can change, all optional. Only the ones you send are changed.","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"The new name of the workspace, 1 to 255 characters.","example":"Acme"},"archived":{"type":"boolean","description":"`true` pauses the client: no scheduled weekly signal runs, no scheduled content, no weekly email report. Its data, its API routes and manual runs keep working. `false` resumes it."},"domain":{"description":"The domain of a workspace cannot be changed: a request that names one is refused with a 422 (`errors.domain`, \"cannot be changed\"). Leave it out."}}},"V3PartnerWorkspaceDeleted":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["partner_workspace_id","deleted"],"properties":{"partner_workspace_id":{"type":"string","description":"Your ID for the client that was deleted."},"deleted":{"type":"boolean","enum":[true]}}}}},"V3CreatePartnerWorkspaceBody":{"type":"object","required":["partner_workspace_id","name","domain","owner_email"],"properties":{"partner_workspace_id":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[^/?#\\s]+$","description":"Your own ID for the client, up to 255 characters, with no `/`, `?`, `#` or space. It must be new: an ID you already used, even for a deleted workspace, is refused with a 409.","example":"crm-4821"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"The name of the workspace, 1 to 255 characters.","example":"Acme"},"domain":{"type":"string","description":"The main website of the client, as a hostname with no protocol or path. Lowercased when saved. You can have only one live workspace per domain.","example":"acme.com"},"owner_email":{"type":"string","format":"email","description":"The email of the person who gets admin access to the workspace in the Sillage app."}}},"V3Deleted":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","deleted"],"properties":{"id":{"type":"integer","description":"The ID that was removed."},"deleted":{"type":"boolean","enum":[true]}}}}},"SignalTemplate":{"type":"object","description":"One signal the client's workspace can set up. Its setup grammar tells a client what a setup for this signal can carry — see the setup field.","required":["id","key","name","description","row_summary","category","status","subjects","scopes","tags","pricing","setup","archived_at"],"properties":{"id":{"type":"integer","description":"The ID of the signal template."},"key":{"type":"string","description":"Stable identifier of this signal. Prefer it to `id` when you store a reference to a signal."},"name":{"type":"string","description":"The signal name."},"description":{"type":"string","nullable":true,"description":"A short explanation of what this signal watches for."},"row_summary":{"type":"string","nullable":true,"description":"A one-line summary, for a compact list display."},"category":{"type":"string","enum":["my_properties","my_network","competition","people","market","internal_intents"],"description":"The family of signals this one belongs to."},"status":{"type":"string","enum":["live","coming_soon"],"description":"Whether this signal can be set up."},"subjects":{"type":"array","items":{"type":"string","enum":["person","company"]},"description":"Who this signal watches — a person, a company, or both."},"scopes":{"type":"array","items":{"type":"string","enum":["discovery","account_monitoring"]},"description":"Which setups this signal supports."},"tags":{"type":"array","items":{"type":"string","enum":["popular","not_set_up"]},"description":"Labels you can filter signal templates on. `popular` is set by Sillage. `not_set_up` means the client workspace has no active or paused signal setup of this template; it is worked out on every read, and a template inside a signal setup never carries it."},"pricing":{"type":"object","description":"What this signal costs the client's workspace, by mode. Each mode is `null` on its own when this signal has no price for it.","required":["account_monitoring","discovery"],"properties":{"account_monitoring":{"type":"object","nullable":true,"description":"This signal's account-monitoring price, `null` when this signal has no account-monitoring price.","required":["signal_bucket","credits","unit"],"properties":{"signal_bucket":{"type":"string","enum":["essential","standard","advanced"],"description":"The pricing tier this price belongs to."},"credits":{"type":"number","description":"The exact price, in credits — never rounded."},"unit":{"type":"string","enum":["per_key_account_per_month"],"description":"What is being priced."}}},"discovery":{"type":"object","nullable":true,"description":"This signal's discovery price, per signal found. `null` when this signal has no discovery price.","required":["credits","unit"],"properties":{"credits":{"type":"number","description":"The exact price, in credits — never rounded."},"unit":{"type":"string","enum":["signal_found"],"description":"What is being priced."}}}}},"setup":{"type":"object","description":"What a setup for this signal can carry. fields is a JSON Schema document describing the setup's parameters object — render it, or validate against it, rather than hard-coding a form.","required":["fields","shape"],"properties":{"fields":{"type":"object","additionalProperties":true,"description":"A JSON Schema (2020-12) document. Each property may carry `x-label`/`x-hint`/`x-control` extensions describing how to render it, and a `default` that is stored on the setup when you leave the property out. A `list_id` property carries `x-list-type`, the kind of list it accepts: `competitor`, `partner`, `influencer`, `champion` or `employee`. A property marked `x-honoured: false` is accepted and stored, but does not change what the signal detects."},"shape":{"type":"string","enum":["keyword","engagement","job_change","job_posting","firmographic","internal_signal","custom"],"description":"The family of parameters this signal asks for."}}},"archived_at":{"type":"string","format":"date-time","nullable":true,"description":"When this signal was archived, `null` while still active. An archived signal is left out of the list but still resolves by ID."}}},"SignalSetup":{"type":"object","description":"One signal the client's workspace has set up.","required":["id","signal_template","name","status","parameters","schedule","persona_id","created_at","last_detected_at"],"properties":{"id":{"type":"integer","description":"The ID of the signal setup."},"signal_template":{"$ref":"#/components/schemas/SignalSetupTemplate"},"name":{"type":"string","description":"Display name for this setup."},"status":{"type":"string","enum":["enabled","disabled"],"description":"`enabled` when this setup is active, `disabled` when it is paused. A setup runs on its own only when it has a weekly `schedule`; otherwise it runs when you launch a signal run."},"parameters":{"type":"object","additionalProperties":true,"description":"The parameters this setup runs with, as applied: the ones you sent, plus the default of every property you left out. The schedule is not one of them, it has its own `schedule` field. Send a changed value back in a `PATCH` to update the setup."},"schedule":{"type":"string","nullable":true,"enum":["weekly"],"description":"`weekly` when this setup runs on its own every week, `null` when it has no schedule."},"persona_id":{"type":"integer","nullable":true,"description":"The persona this setup belongs to, as a persona ID from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`. `null` when the signal is not tied to a persona. It never changes."},"created_at":{"type":"string","format":"date-time","description":"When this setup was created."},"last_detected_at":{"type":"string","format":"date-time","nullable":true,"description":"When this setup last found a signal you can list, `null` if it has not found one yet."}}},"CreateSignalSetupBody":{"type":"object","required":["signal_template_id","parameters"],"properties":{"signal_template_id":{"type":"integer","description":"The ID of the signal template to set up, from `GET /v3/partner/workspaces/{partner_workspace_id}/signal-templates`."},"name":{"type":"string","description":"Display name for the new signal setup, 1 to 100 characters. Defaults to the signal template name."},"parameters":{"type":"object","additionalProperties":true,"description":"The parameters of the setup, as the `setup.fields` of the signal template describe them. A property you leave out is filled with its `default` in `setup.fields`, when it has one."},"schedule":{"type":"string","nullable":true,"enum":["weekly"],"description":"`weekly` runs the signal every week; `null`, or leaving it out, means no schedule."},"persona_id":{"type":"integer","description":"The persona this signal is for, as a persona ID from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`. Optional when the client has one persona; required when it has several. A signal that is not tied to a persona (champion tracking, job offers) may carry one or none."}}},"UpdateSignalSetupBody":{"type":"object","description":"At least one property must be provided.","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["enabled","disabled"],"description":"Set to `disabled` to pause the signal and `enabled` to resume it. A resumed weekly signal setup waits for its next weekly slot instead of running at once."},"persona_id":{"type":"integer","description":"The signal's current persona. A signal keeps its persona: sending a different one is refused with a 409."},"parameters":{"type":"object","additionalProperties":true,"description":"Merged into the stored setup — an included key overwrites its stored value, `null` removes it (a parameter that has a default cannot be removed: 422), and every key left out is kept. The merged result is validated the same way as on creation."},"schedule":{"type":"string","nullable":true,"enum":["weekly"],"description":"`weekly` runs the signal every week, `null` removes its schedule. Leave it out to keep the current one."}}},"V3Signal":{"type":"object","description":"One signal detection.","required":["id","signal_type","details","detected_at","signal_date","lead","company","signal_setup_id","source_url","author","excerpt"],"properties":{"id":{"type":"integer","description":"The ID of the detection."},"signal_type":{"type":"string","nullable":true,"description":"The kind of signal, e.g. `keyword_detection`."},"details":{"nullable":true,"description":"The detection payload — its shape depends on `signal_type`."},"detected_at":{"type":"string","format":"date-time","nullable":true,"description":"When this signal was detected."},"signal_date":{"type":"string","format":"date-time","nullable":true,"description":"When the underlying event happened (e.g. a post was published), when known."},"lead":{"nullable":true,"description":"The lead this signal is about. For a signal with no lead of its own (for example a keyword match), the lead of the content's author when known. `null` when it is not known.","allOf":[{"$ref":"#/components/schemas/V3LeadSummary"}]},"company":{"nullable":true,"description":"The company this signal is about. `null` when it is not known.","allOf":[{"$ref":"#/components/schemas/V3CompanySummary"}]},"signal_setup_id":{"type":"integer","nullable":true,"description":"The ID of the signal setup that produced this signal. `null` when the signal does not come from a current signal setup (an older signal, or a setup since deleted), as on signal runs."},"source_url":{"type":"string","nullable":true,"description":"A link to where this signal happened, when one exists."},"author":{"nullable":true,"description":"Who is behind this signal, when known.","allOf":[{"$ref":"#/components/schemas/V3PersonSummary"}]},"excerpt":{"type":"string","nullable":true,"description":"A short quote from the signal, when one exists."}}},"V3SignalResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3Signal"}}},"V3SignalListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3Signal"}},"meta":{"type":"object","required":["cursor","resolved_companies"],"properties":{"cursor":{"type":"object","required":["next","has_more"],"properties":{"next":{"type":"string","nullable":true,"description":"Opaque cursor to pass as `cursor` on the next request. `null` on the last page."},"has_more":{"type":"boolean","description":"Whether more results exist beyond this page."}}},"resolved_companies":{"type":"array","description":"The companies your company filters matched, each with the filter value that matched it. Empty when you sent no company filter.","items":{"$ref":"#/components/schemas/V3ResolvedCompany"}}}}}},"V3SignalCountResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["total"],"properties":{"total":{"type":"integer","description":"The total number of detections matching the supplied filters."}}}}},"V3CompanySummary":{"type":"object","description":"A company as every read that names one shows it. Pass its `id` as `company_ids` to a search, or as `company_id` to `GET /v3/partner/workspaces/{partner_workspace_id}/companies/{company_id}`.","required":["id","name","domain","linkedin_url","linkedin_handle","logo_url"],"properties":{"id":{"type":"integer","nullable":true,"description":"The company's id in the client's workspace. `null` when the company is not one of its companies."},"name":{"type":"string","description":"The company's name."},"domain":{"type":"string","nullable":true,"description":"The company's website domain."},"linkedin_url":{"type":"string","nullable":true,"description":"The company's LinkedIn page URL."},"linkedin_handle":{"type":"string","nullable":true,"description":"The last part of the LinkedIn page address of the company."},"logo_url":{"type":"string","nullable":true,"description":"The URL of the company's logo."}}},"V3PersonSummary":{"type":"object","description":"A person with no lead of their own, such as the author of a post. Every field is `null` when it is not known.","required":["full_name","first_name","last_name","linkedin_url","linkedin_headline","position","avatar_url"],"properties":{"full_name":{"type":"string","nullable":true,"description":"The person's full name."},"first_name":{"type":"string","nullable":true,"description":"The person's first name."},"last_name":{"type":"string","nullable":true,"description":"The person's last name."},"linkedin_url":{"type":"string","nullable":true,"description":"The person's LinkedIn profile URL."},"linkedin_headline":{"type":"string","nullable":true,"description":"The person's LinkedIn headline."},"position":{"type":"string","nullable":true,"description":"The person's current job title."},"avatar_url":{"type":"string","nullable":true,"description":"The URL of the person's profile photo."}}},"V3LeadSummary":{"type":"object","description":"A lead as every read that names one shows it. Pass its `id` as `lead_id` to `GET /v3/partner/workspaces/{partner_workspace_id}/leads/{lead_id}` or to a search. Every field but `id` is `null` when it is not known.","required":["id","full_name","first_name","last_name","linkedin_url","linkedin_headline","position","avatar_url"],"properties":{"id":{"type":"integer","description":"The lead's id in the client's workspace."},"full_name":{"type":"string","nullable":true,"description":"The person's full name."},"first_name":{"type":"string","nullable":true,"description":"The person's first name."},"last_name":{"type":"string","nullable":true,"description":"The person's last name."},"linkedin_url":{"type":"string","nullable":true,"description":"The person's LinkedIn profile URL."},"linkedin_headline":{"type":"string","nullable":true,"description":"The person's LinkedIn headline."},"position":{"type":"string","nullable":true,"description":"The person's current job title."},"avatar_url":{"type":"string","nullable":true,"description":"The URL of the person's profile photo."}}},"V3SignalsQueryBody":{"type":"object","description":"Body for `POST /v3/partner/workspaces/{partner_workspace_id}/signals/query`. Every field is optional. The company filters (`company_ids`, `company_domains`, `company_linkedin_handles` and `company_linkedin_urls`) add up: a result matches when its company is any of the ids, domains, handles or URLs you send. A value that matches no company in the client's workspace matches nothing, so the answer is an empty list, never an error. The company filters combine with every other filter, which all have to match.","properties":{"cursor":{"type":"string","minLength":1,"description":"The `meta.cursor.next` of the previous response, to fetch the next page. Omit it for the first page. Send the same filters with it. A cursor that was not issued to you by this search, or that is reused with other filters or another sort, is rejected with a 422."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Number of items per page. Defaults to 25. Maximum: 100."},"signal_date_from":{"type":"string","format":"date-time","description":"Only detections whose signal date is at or after this moment, the moment itself included. ISO 8601 date and time with a UTC offset; a date without a time is rejected. Defaults to 90 days before now. Cannot go further back than 180 days: an older value is refused with a 422."},"signal_date_to":{"type":"string","format":"date-time","description":"Only detections whose signal date is at or before this moment, the moment itself included. ISO 8601 date and time with a UTC offset; a date without a time is rejected."},"detected_at_from":{"type":"string","format":"date-time","description":"Only detections first seen at or after this moment, the moment itself included. ISO 8601 date and time with a UTC offset; a date without a time is rejected."},"detected_at_to":{"type":"string","format":"date-time","description":"Only detections first seen at or before this moment, the moment itself included. ISO 8601 date and time with a UTC offset; a date without a time is rejected."},"signal_setup_id":{"type":"integer","minimum":1,"description":"Only detections produced by this signal setup.","example":12},"signal_run_id":{"type":"integer","minimum":1,"description":"Only detections from this run."},"signal_types":{"type":"array","minItems":1,"description":"Only detections of these signal types.","items":{"type":"string","enum":["linkedin_comment","linkedin_reaction","keyword_detection","recently_promoted","new_job","hubspot_contact_detection","lead_liked_competitor_content","lead_commented_competitor_content","lead_liked_own_content","lead_commented_own_content","lead_liked_influencer_content","lead_commented_influencer_content","salesforce_contact_detection","job_posting","job_posting_insight","job_posting_hiring_manager","competitor_inbound_comment","competitor_outbound_comment","partner_inbound_comment","partner_outbound_comment","customer_inbound_comment","customer_outbound_comment","influencer_inbound_comment","influencer_outbound_comment","champion_inbound_comment","champion_outbound_comment","job_posting_keyword_detection","champion_job_change","partner_staff_comment","partner_staff_reaction","lead_liked_partner_content","lead_commented_partner_content"]}},"company_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"integer","minimum":1},"description":"Only detections whose company is one of these companies. Pass company ids, as returned as the `id` of a list member or as `company.id` on a lead. Maximum 100 values."},"company_domains":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only detections whose company has one of these website domains (e.g. `acme.com`). Maximum 100 values."},"company_linkedin_handles":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only detections whose company has one of these LinkedIn handles (the last part of the LinkedIn page address). Maximum 100 values."},"company_linkedin_urls":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only detections whose company has one of these LinkedIn page URLs. Maximum 100 values."},"lead_id":{"type":"integer","minimum":1,"description":"Only detections linked to this lead. Matches detections directly linked to the lead, not signals attributed to that lead through fallback matching."},"countries":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only detections whose linked lead is located in one of these countries. 1 to 100 values. Combined with `cities`: a match is in one of the countries or one of the cities.","example":["France","Germany"]},"cities":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["name","country"],"properties":{"name":{"type":"string","minLength":1},"country":{"type":"string","minLength":1}}},"description":"Only detections whose linked lead is located in one of these cities. Each city is paired with its country so \"Paris, France\" and \"Paris, US\" stay distinct. 1 to 100 values.","example":[{"name":"Paris","country":"France"}]}}},"V3SignalsCountBody":{"type":"object","description":"Body for `POST /v3/partner/workspaces/{partner_workspace_id}/signals/count`: the filters of `POST /v3/partner/workspaces/{partner_workspace_id}/signals/query`, without `cursor` and `limit`. Every field is optional. The company filters (`company_ids`, `company_domains`, `company_linkedin_handles` and `company_linkedin_urls`) add up: a result matches when its company is any of the ids, domains, handles or URLs you send. A value that matches no company in the client's workspace matches nothing, so the answer is an empty list, never an error. The company filters combine with every other filter, which all have to match.","properties":{"signal_date_from":{"type":"string","format":"date-time","description":"Only detections whose signal date is at or after this moment, the moment itself included. ISO 8601 date and time with a UTC offset; a date without a time is rejected. Defaults to 90 days before now. Cannot go further back than 180 days: an older value is refused with a 422."},"signal_date_to":{"type":"string","format":"date-time","description":"Only detections whose signal date is at or before this moment, the moment itself included. ISO 8601 date and time with a UTC offset; a date without a time is rejected."},"detected_at_from":{"type":"string","format":"date-time","description":"Only detections first seen at or after this moment, the moment itself included. ISO 8601 date and time with a UTC offset; a date without a time is rejected."},"detected_at_to":{"type":"string","format":"date-time","description":"Only detections first seen at or before this moment, the moment itself included. ISO 8601 date and time with a UTC offset; a date without a time is rejected."},"signal_setup_id":{"type":"integer","minimum":1,"description":"Only detections produced by this signal setup.","example":12},"signal_run_id":{"type":"integer","minimum":1,"description":"Only detections from this run."},"signal_types":{"type":"array","minItems":1,"description":"Only detections of these signal types.","items":{"type":"string","enum":["linkedin_comment","linkedin_reaction","keyword_detection","recently_promoted","new_job","hubspot_contact_detection","lead_liked_competitor_content","lead_commented_competitor_content","lead_liked_own_content","lead_commented_own_content","lead_liked_influencer_content","lead_commented_influencer_content","salesforce_contact_detection","job_posting","job_posting_insight","job_posting_hiring_manager","competitor_inbound_comment","competitor_outbound_comment","partner_inbound_comment","partner_outbound_comment","customer_inbound_comment","customer_outbound_comment","influencer_inbound_comment","influencer_outbound_comment","champion_inbound_comment","champion_outbound_comment","job_posting_keyword_detection","champion_job_change","partner_staff_comment","partner_staff_reaction","lead_liked_partner_content","lead_commented_partner_content"]}},"company_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"integer","minimum":1},"description":"Only detections whose company is one of these companies. Pass company ids, as returned as the `id` of a list member or as `company.id` on a lead. Maximum 100 values."},"company_domains":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only detections whose company has one of these website domains (e.g. `acme.com`). Maximum 100 values."},"company_linkedin_handles":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only detections whose company has one of these LinkedIn handles (the last part of the LinkedIn page address). Maximum 100 values."},"company_linkedin_urls":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only detections whose company has one of these LinkedIn page URLs. Maximum 100 values."},"lead_id":{"type":"integer","minimum":1,"description":"Only detections linked to this lead. Matches detections directly linked to the lead, not signals attributed to that lead through fallback matching."},"countries":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only detections whose linked lead is located in one of these countries. 1 to 100 values. Combined with `cities`: a match is in one of the countries or one of the cities.","example":["France","Germany"]},"cities":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["name","country"],"properties":{"name":{"type":"string","minLength":1},"country":{"type":"string","minLength":1}}},"description":"Only detections whose linked lead is located in one of these cities. Each city is paired with its country so \"Paris, France\" and \"Paris, US\" stay distinct. 1 to 100 values.","example":[{"name":"Paris","country":"France"}]}}},"V3LeadsQueryBody":{"type":"object","description":"Filters for the leads list. All fields are optional — an empty body returns the first page of every lead in the client's workspace, most recent first. A lead's company is its current company. The company filters (`company_ids`, `company_domains`, `company_linkedin_handles` and `company_linkedin_urls`) add up: a result matches when its company is any of the ids, domains, handles or URLs you send. A value that matches no company in the client's workspace matches nothing, so the answer is an empty list, never an error. The company filters combine with every other filter, which all have to match.","properties":{"cursor":{"type":"string","minLength":1,"description":"The `meta.cursor.next` of the previous response, to fetch the next page. Omit it for the first page. Send the same `sort` and filters with it. A cursor that was not issued to you by this search, or that is reused with other filters or another sort, is rejected with a 422."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Number of items per page. Defaults to 25. Maximum: 100."},"sort":{"type":"string","enum":["created_at:asc","created_at:desc"],"default":"created_at:desc","description":"Sort order. Leads are sorted by creation date only — most recent first by default."},"created_at_from":{"type":"string","format":"date-time","description":"Only leads created at or after this moment, the moment itself included. ISO 8601 date and time with a UTC offset, e.g. `2026-09-01T00:00:00Z`; a date without a time is rejected."},"created_at_to":{"type":"string","format":"date-time","description":"Only leads created at or before this moment, the moment itself included. ISO 8601 date and time with a UTC offset, e.g. `2026-09-30T23:59:59Z`; a date without a time is rejected."},"company_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"integer","minimum":1},"description":"Only leads whose company is one of these companies. Pass company ids, as returned as the `id` of a list member or as `company.id` on a lead. Maximum 100 values."},"company_domains":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only leads whose company has one of these website domains (e.g. `acme.com`). Maximum 100 values."},"company_linkedin_handles":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only leads whose company has one of these LinkedIn handles (the last part of the LinkedIn page address). Maximum 100 values."},"company_linkedin_urls":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only leads whose company has one of these LinkedIn page URLs. Maximum 100 values."},"countries":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only leads located in one of these countries. 1 to 100 values. Combined with `cities`: a match is in one of the countries or one of the cities.","example":["France","Germany"]},"cities":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["name","country"],"properties":{"name":{"type":"string","minLength":1},"country":{"type":"string","minLength":1}}},"description":"Only leads located in one of these cities. Each city is paired with its country so \"Paris, France\" and \"Paris, US\" stay distinct. 1 to 100 values.","example":[{"name":"Paris","country":"France"}]}}},"V3ContentItem":{"type":"object","required":["id","content_type","created_at","lead","company"],"properties":{"id":{"type":"integer","description":"The content item id, as returned by this endpoint."},"content_type":{"type":"string","enum":["linkedin_comment","recently_promoted","linkedin_post","linkedin_company_post","linkedin_job_posting","web_article","press_release","blog_post","linkedin_reaction"],"description":"The kind of content."},"created_at":{"type":"string","format":"date-time","description":"When the content record was created."},"details":{"$ref":"#/components/schemas/V3ContentData"},"lead":{"nullable":true,"description":"The lead who posted, commented, or reacted, when they are one of the client's leads. `null` otherwise.","allOf":[{"$ref":"#/components/schemas/V3LeadSummary"}]},"company":{"nullable":true,"description":"The company the content is about. `null` when it is not one of the companies of the client's workspace.","allOf":[{"$ref":"#/components/schemas/V3CompanySummary"}]}}},"V3ContentsPaginatedResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3ContentItem"}},"meta":{"type":"object","required":["cursor","resolved_companies"],"properties":{"cursor":{"type":"object","required":["next","has_more"],"properties":{"next":{"type":"string","nullable":true,"description":"Pass this value as `cursor` in the next request to fetch the following page. `null` on the last page."},"has_more":{"type":"boolean","description":"Whether more contents exist after this page."}}},"resolved_companies":{"type":"array","description":"The companies your company filters matched, each with the filter value that matched it. Empty when you sent no company filter.","items":{"$ref":"#/components/schemas/V3ResolvedCompany"}}}}}},"V3ContentsQueryBody":{"type":"object","description":"Filters for the contents list. All fields are optional — an empty body returns the first page of every content, most recent first. The company filters (`company_ids`, `company_domains`, `company_linkedin_handles` and `company_linkedin_urls`) add up: a result matches when its company is any of the ids, domains, handles or URLs you send. A value that matches no company in the client's workspace matches nothing, so the answer is an empty list, never an error. The company filters combine with every other filter, which all have to match.","properties":{"cursor":{"type":"string","minLength":1,"description":"The `meta.cursor.next` of the previous response, to fetch the next page. Omit it for the first page. Send the same filters with it. A cursor that was not issued to you by this search, or that is reused with other filters or another sort, is rejected with a 422."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Number of items per page. Defaults to 25. Maximum: 100."},"created_at_from":{"type":"string","format":"date-time","description":"Only contents created at or after this moment, the moment itself included. ISO 8601 date and time with a UTC offset, e.g. `2026-09-01T00:00:00Z`; a date without a time is rejected."},"created_at_to":{"type":"string","format":"date-time","description":"Only contents created at or before this moment, the moment itself included. ISO 8601 date and time with a UTC offset, e.g. `2026-09-30T23:59:59Z`; a date without a time is rejected."},"content_types":{"type":"array","minItems":1,"description":"Only contents of these types.","items":{"type":"string","enum":["linkedin_comment","recently_promoted","linkedin_post","linkedin_company_post","linkedin_job_posting","web_article","press_release","blog_post","linkedin_reaction"]}},"company_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"integer","minimum":1},"description":"Only contents whose company is one of these companies. Pass company ids, as returned as the `id` of a list member or as `company.id` on a lead. Maximum 100 values."},"company_domains":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only contents whose company has one of these website domains (e.g. `acme.com`). Maximum 100 values."},"company_linkedin_handles":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only contents whose company has one of these LinkedIn handles (the last part of the LinkedIn page address). Maximum 100 values."},"company_linkedin_urls":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only contents whose company has one of these LinkedIn page URLs. Maximum 100 values."},"lead_id":{"type":"integer","minimum":1,"description":"Only content authored by this lead. Use the `lead_id` shown on each content item, or from the leads endpoints."},"response_format":{"type":"string","enum":["concise","normalized"],"default":"normalized","description":"Controls how much detail the `details` field of each item includes. `normalized` (default): a clean, stable projection of the content. `concise`: `details` is omitted entirely."}}},"V3ContentRequestsPaginatedResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3ContentRequestItem"}},"meta":{"type":"object","required":["cursor","resolved_companies"],"properties":{"cursor":{"type":"object","required":["next","has_more"],"properties":{"next":{"type":"string","nullable":true,"description":"Pass this value as `cursor` in the next request to fetch the following page. `null` on the last page."},"has_more":{"type":"boolean","description":"Whether more content requests exist after this page."}}},"resolved_companies":{"type":"array","description":"The companies your company filters matched, each with the filter value that matched it. Empty when you sent no company filter.","items":{"$ref":"#/components/schemas/V3ResolvedCompany"}}}}}},"V3ContentRequestsQueryBody":{"type":"object","description":"Body for `POST /v3/partner/workspaces/{partner_workspace_id}/content-requests/query`. All fields are optional — an empty body returns the first page of every content request, most recent first. The company filters (`company_ids`, `company_domains`, `company_linkedin_handles` and `company_linkedin_urls`) add up: a result matches when its company is any of the ids, domains, handles or URLs you send. A value that matches no company in the client's workspace matches nothing, so the answer is an empty list, never an error. The company filters combine with every other filter, which all have to match.","properties":{"cursor":{"type":"string","minLength":1,"description":"The `meta.cursor.next` of the previous response, to fetch the next page. Omit it for the first page. Send the same filters with it. A cursor that was not issued to you by this search, or that is reused with other filters or another sort, is rejected with a 422."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Number of items per page. Defaults to 25. Maximum: 100."},"created_at_from":{"type":"string","format":"date-time","description":"Only content requests created at or after this moment, the moment itself included. ISO 8601 date and time with a UTC offset, e.g. `2026-09-01T00:00:00Z`; a date without a time is rejected."},"created_at_to":{"type":"string","format":"date-time","description":"Only content requests created at or before this moment, the moment itself included. ISO 8601 date and time with a UTC offset, e.g. `2026-09-30T23:59:59Z`; a date without a time is rejected."},"type":{"type":"string","enum":["account_mapping","key_account_content"],"description":"Only content requests of this type."},"statuses":{"type":"array","minItems":1,"description":"Only content requests in one of these statuses. Omit it to get every content request, finished ones included.","items":{"type":"string","enum":["pending","in_progress","completed","failed"]}},"company_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"integer","minimum":1},"description":"Only content requests whose company is one of these companies. Pass company ids, as returned as the `id` of a list member or as `company.id` on a lead. Maximum 100 values."},"company_domains":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only content requests whose company has one of these website domains (e.g. `acme.com`). Maximum 100 values."},"company_linkedin_handles":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only content requests whose company has one of these LinkedIn handles (the last part of the LinkedIn page address). Maximum 100 values."},"company_linkedin_urls":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only content requests whose company has one of these LinkedIn page URLs. Maximum 100 values."}}},"V3LeadsCountBody":{"type":"object","description":"Body for `POST /v3/partner/workspaces/{partner_workspace_id}/leads/count`: the filters of `POST /v3/partner/workspaces/{partner_workspace_id}/leads/query`, without `cursor`, `limit` and `sort`. Every field is optional. The company filters (`company_ids`, `company_domains`, `company_linkedin_handles` and `company_linkedin_urls`) add up: a result matches when its company is any of the ids, domains, handles or URLs you send. A value that matches no company in the client's workspace matches nothing, so the answer is an empty list, never an error. The company filters combine with every other filter, which all have to match.","properties":{"created_at_from":{"type":"string","format":"date-time","description":"Only leads created at or after this moment, the moment itself included. ISO 8601 date and time with a UTC offset, e.g. `2026-09-01T00:00:00Z`; a date without a time is rejected."},"created_at_to":{"type":"string","format":"date-time","description":"Only leads created at or before this moment, the moment itself included. ISO 8601 date and time with a UTC offset, e.g. `2026-09-30T23:59:59Z`; a date without a time is rejected."},"company_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"integer","minimum":1},"description":"Only leads whose company is one of these companies. Pass company ids, as returned as the `id` of a list member or as `company.id` on a lead. Maximum 100 values."},"company_domains":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only leads whose company has one of these website domains (e.g. `acme.com`). Maximum 100 values."},"company_linkedin_handles":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only leads whose company has one of these LinkedIn handles (the last part of the LinkedIn page address). Maximum 100 values."},"company_linkedin_urls":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only leads whose company has one of these LinkedIn page URLs. Maximum 100 values."},"countries":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1},"description":"Only leads located in one of these countries. 1 to 100 values. Combined with `cities`: a match is in one of the countries or one of the cities.","example":["France","Germany"]},"cities":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["name","country"],"properties":{"name":{"type":"string","minLength":1},"country":{"type":"string","minLength":1}}},"description":"Only leads located in one of these cities. Each city is paired with its country so \"Paris, France\" and \"Paris, US\" stay distinct. 1 to 100 values.","example":[{"name":"Paris","country":"France"}]}}},"V3SignalRunListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3SignalRun"}}}},"V3LeadUpdateBody":{"type":"object","description":"At least one of `status` or `owner_email` must be present. An empty body is rejected.","properties":{"status":{"type":"string","enum":["pending","contacted_email","contacted_phone","contacted_linkedin","meeting_booked","need_follow_up","declined","disqualified","already_in_touch","customer","company_not_icp","job_title_not_icp"],"description":"New pipeline status for the lead. See the status table above."},"owner_email":{"type":"string","nullable":true,"description":"Email of a workspace member to assign as owner. Must belong to a member of the client's workspace. Send `null` to unassign the current owner."}}},"V3UsageProduct":{"type":"object","required":["scope","signal_bucket","signal_template_key","signal_template_id","signal_setup_id","company_id","persona_id"],"description":"What the credits paid for. Every key is always present; it is `null` when it does not apply to the line.","properties":{"scope":{"type":"string","enum":["discovery","account_monitoring"],"description":"`discovery` for a signal found by one of the client's signal setups, `account_monitoring` for the monitoring of an account."},"signal_bucket":{"type":"string","nullable":true,"enum":["essential","standard","advanced",null],"description":"The `signal_bucket` of the monitoring that was paid for, as in the monitoring pricing of `GET /v3/partner/workspaces/{partner_workspace_id}/signal-templates`. `null` on a `discovery` line."},"signal_template_key":{"type":"string","nullable":true,"description":"The key of the signal template that found the signal, as returned by `GET /v3/partner/workspaces/{partner_workspace_id}/signal-templates`. `null` on an `account_monitoring` line, and on a `discovery` line whose signal was deleted."},"signal_template_id":{"type":"integer","nullable":true,"description":"The id of the signal template that found the signal, as returned by `GET /v3/partner/workspaces/{partner_workspace_id}/signal-templates`. `null` on an `account_monitoring` line, and on a `discovery` line whose signal was deleted."},"signal_setup_id":{"type":"integer","nullable":true,"description":"The identifier of the signal setup that found the signal. `null` on an `account_monitoring` line, when the signal setup no longer exists, and when the signal was deleted."},"company_id":{"type":"integer","nullable":true,"description":"The company the credits were spent on, as its identifier in the client's workspace. `null` on a `discovery` line whose signal was deleted."},"persona_id":{"type":"integer","nullable":true,"description":"The persona the signal setup or the monitoring was for. `null` when it had none, and on a `discovery` line whose signal was deleted."}}},"V3ContentRequestStatusItem":{"type":"object","required":["id","type","status","label","failed_reason","created_at","updated_at","company"],"description":"A single in-flight content request, with the company it is running for. It reads like an item of `POST /v3/partner/workspaces/{partner_workspace_id}/content-requests/query`.","properties":{"id":{"type":"integer","description":"Identifier of the request."},"type":{"type":"string","enum":["account_mapping","key_account_content"],"description":"What kind of work this item is."},"status":{"type":"string","enum":["pending","in_progress","completed","failed"],"description":"Where the request stands. `pending`: waiting to start. `in_progress`: being processed. `completed`: finished. `failed`: stopped without finishing."},"label":{"type":"string","description":"A short readable description of the current step."},"failed_reason":{"type":"string","nullable":true,"enum":["no_employee_resolved","persona_without_job_titles","missing_linkedin_target","request_timed_out","insufficient_credits","internal_error"],"description":"Always `null` here: a request that failed is no longer in flight."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"company":{"nullable":true,"description":"`null` for workspace-wide items.","allOf":[{"$ref":"#/components/schemas/V3CompanySummary"}]}}},"V3SignalRequestStatusItem":{"description":"A single in-flight signal run: exactly the item `GET /v3/partner/workspaces/{partner_workspace_id}/signal-runs` answers, plus its `type`.","allOf":[{"$ref":"#/components/schemas/V3SignalRun"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["signal"],"description":"What kind of work this item is."}}}]},"V3RequestsStatusResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","description":"All in-flight items, newest first, mixed kinds — branch on `type`.","items":{"oneOf":[{"$ref":"#/components/schemas/V3ContentRequestStatusItem"},{"$ref":"#/components/schemas/V3SignalRequestStatusItem"}]}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["page","page_size","page_count","total"],"properties":{"page":{"type":"integer","description":"Current page."},"page_size":{"type":"integer","description":"Items per page."},"page_count":{"type":"integer","description":"Total number of pages. Greater than 1 only in extreme cases — fetch the remaining pages to see everything."},"total":{"type":"integer","description":"True total of in-flight items, regardless of pagination."}}}}}}},"V3SetupDimensionStatus":{"type":"object","required":["status","message"],"properties":{"status":{"type":"string","enum":["ok","warning","blocked"]},"message":{"type":"string"},"recommended_next_route":{"type":"string","enum":["POST /v3/personas","PATCH /v3/personas/{persona_id}","POST /v3/lists","POST /v3/lists/{kind}/{list_id}/members","POST /v3/signal-setups","GET /v3/requests-status","POST /v3/contents/query"],"description":"The v3 route to call next, as `METHOD /path`. Absent when nothing more is recommended right now."}}},"V3SetupStateResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["checklist"],"properties":{"checklist":{"type":"object","required":["persona","accounts","signal_setups","contents"],"properties":{"persona":{"allOf":[{"$ref":"#/components/schemas/V3SetupDimensionStatus"},{"type":"object","required":["job_titles_set","locations_set"],"properties":{"job_titles_set":{"type":"boolean"},"locations_set":{"type":"boolean"}}}]},"accounts":{"allOf":[{"$ref":"#/components/schemas/V3SetupDimensionStatus"},{"type":"object","required":["count"],"properties":{"count":{"type":"integer","minimum":0,"description":"How many accounts sit on the client's customer and prospect lists. The step is done (`ok`) once there is at least one."}}}]},"signal_setups":{"allOf":[{"$ref":"#/components/schemas/V3SetupDimensionStatus"},{"type":"object","required":["count","missing_priority_types"],"properties":{"count":{"type":"integer","minimum":0,"description":"The signal setups of this workspace."},"missing_priority_types":{"type":"array","items":{"type":"string"},"description":"The `key` of each signal template still worth setting up, in priority order (see `GET /v3/partner/workspaces/{partner_workspace_id}/signal-templates`). Informational — `status` never depends on it."}}}]},"contents":{"allOf":[{"$ref":"#/components/schemas/V3SetupDimensionStatus"},{"type":"object","required":["has_contents"],"properties":{"has_contents":{"type":"boolean"}}}]}}}}}}},"V3PartnerUsageEvent":{"type":"object","required":["id","created_at","status","credits","product"],"properties":{"id":{"type":"integer","description":"Identifier of the billing event."},"created_at":{"type":"string","format":"date-time","description":"When the event was created."},"status":{"type":"string","enum":["to_invoice","invoiced","paid"],"description":"Where the credits are in your invoicing: `to_invoice` (will appear on your next invoice), `invoiced` (an invoice covering it has been issued) or `paid`."},"credits":{"type":"number","description":"Credits of this event."},"product":{"$ref":"#/components/schemas/V3UsageProduct"}}},"V3PartnerUsageListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3PartnerUsageEvent"}},"meta":{"type":"object","required":["cursor"],"properties":{"cursor":{"type":"object","required":["next","has_more"],"properties":{"next":{"type":"string","nullable":true,"description":"Opaque cursor to pass as `cursor` on the next request. `null` on the last page."},"has_more":{"type":"boolean","description":"Whether more results exist beyond this page."}}}}}}},"V3LaunchSignalRunBody":{"type":"object","description":"Body for `POST /v3/partner/workspaces/{partner_workspace_id}/signal-runs`.","required":["signal_setup_id"],"properties":{"signal_setup_id":{"type":"integer","description":"The ID of the signal setup to run.","example":42},"parameters":{"type":"object","description":"Optional run parameters. An unknown key is refused with 422. `lookback_days` is the only one: it applies to the account monitoring runs of keyword, job-offer, competitor, partner and influencer signals, and is refused with 422 on any other launch.","additionalProperties":false,"properties":{"lookback_days":{"type":"integer","minimum":1,"maximum":180,"description":"How many days back to scan for matches, counted from now. Defaults to 90. Only for the account monitoring runs of keyword, job-offer, competitor, partner and influencer signals; refused with 422 anywhere else."}}}}},"V3SignalRun":{"type":"object","description":"One signal run, with its status and the accounts it covers. The launch, the poll, the in-flight list and the request status all answer this same item.","required":["id","status","label","created_at","updated_at","companies","signal_setup_id"],"properties":{"id":{"type":"integer","description":"The ID of the signal run."},"signal_setup_id":{"type":"integer","nullable":true,"description":"The signal setup this run belongs to — the same ID as in `GET /v3/partner/workspaces/{partner_workspace_id}/signal-setups`. `null` when the run is not tied to one of the client's signal setups (for example a very old run, or a setup deleted while it was running)."},"status":{"type":"string","enum":["pending","in_progress","completed","failed"],"description":"Where the run stands. `pending`: waiting to start. `in_progress`: being processed. `completed`: finished (some accounts may not have been checked: poll the run and read `metadata`). `failed`: stopped without finishing."},"label":{"type":"string","description":"A short readable description of the current step."},"created_at":{"type":"string","format":"date-time","description":"When the run was started."},"updated_at":{"type":"string","format":"date-time","description":"When the run was last updated."},"companies":{"type":"array","description":"The accounts being scanned in this run. Empty when the run is not tied to specific accounts, which is expected, not missing data.","items":{"$ref":"#/components/schemas/V3CompanySummary"}}}},"V3SignalRunLaunchResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3SignalRun"}}}},"V3SignalRunStatus":{"type":"object","description":"The current state of one signal run: the run item, plus the accounts a partly done run dropped.","allOf":[{"$ref":"#/components/schemas/V3SignalRun"},{"type":"object","required":["metadata"],"properties":{"metadata":{"type":"object","nullable":true,"description":"Lists the accounts that were not checked, when there are any: those whose job could not be started when the run was launched (the run is then `failed`) and those whose job failed while the run was going (the run is `completed`, and these accounts could not be checked). A failure that covers the whole workspace names no account, so `null` does not on its own mean every account was checked: `status` and `label` say that.","required":["failed"],"properties":{"failed":{"type":"object","required":["dropped_company_ids"],"properties":{"dropped_company_ids":{"type":"array","items":{"type":"integer"},"description":"Ids of the accounts (company ids, as in `company_ids`) that were not checked in this run."}}}}}}}]},"V3SignalRunResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3SignalRunStatus"}}},"V3Location":{"type":"object","description":"A place, broken down into city, region, country and ISO country code. Any part can be `null` when it is not known.","required":["city","region","country","country_code"],"properties":{"city":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO country code."}}},"V3List":{"type":"object","required":["id","kind","type","name"],"properties":{"id":{"type":"integer","description":"Identifier of the list."},"kind":{"type":"string","enum":["company","profile"],"description":"Whether the list holds companies or people. Derived from `type`, read-only."},"type":{"type":"string","enum":["competitor","partner","customer","prospect","influencer","champion","employee"],"description":"What the list is for. Set once at creation and never changeable. competitor, partner, customer and prospect hold companies; influencer, champion and employee hold people. The employee list is the client's own \"All my employees\" list: it is created with the workspace and cannot be created through the API."},"name":{"type":"string","description":"Name of the list."},"description":{"type":"string","nullable":true,"description":"Omitted when a read uses `response_format=concise`."},"member_count":{"type":"integer","description":"How many companies or people are on the list. Omitted when a read uses `response_format=concise`."},"bound_signal_setup_count":{"type":"integer","description":"How many signal setups and older app signals use this list. Omitted when a read uses `response_format=concise`."},"tier":{"type":"integer","nullable":true,"description":"Tier of the list, on prospect lists only (1, 2 or 3). Null on every other type, customer lists included. Omitted when a read uses `response_format=concise`."},"signal_buckets":{"type":"array","items":{"type":"string","enum":["essential"]},"nullable":true,"description":"The signal groups every account of this list is monitored with, including the ones that join later. Null when the whole list is not monitored. Only customer and prospect lists can have them. Monitoring an account covers its account mapping, its signals and its content. An archived list keeps its signal groups, but nothing is monitored while it is archived (see `monitoring_by_persona`). Omitted when a read uses `response_format=concise`."},"monitoring_by_persona":{"type":"array","nullable":true,"description":"On a customer or prospect list, one entry per persona the list is watched for: the personas it is attached to, or every active persona when it is attached to none (a list of a one-persona workspace has one entry). `monitored_count` is the number of accounts of the list with monitoring on and paid in that persona, `not_covered_count` the number with monitoring on whose month could not be paid yet. Both read 0 while the list is archived. `null` on every other type of list. Entries come in persona id order. Omitted when a read uses `response_format=concise`.","items":{"type":"object","required":["persona_id","monitored_count","not_covered_count"],"properties":{"persona_id":{"type":"integer","description":"The persona this entry counts for."},"monitored_count":{"type":"integer","description":"Accounts monitored and paid in this persona."},"not_covered_count":{"type":"integer","description":"Accounts with monitoring on in this persona whose month could not be paid yet."}}}},"mode":{"type":"string","enum":["manual","smart"],"description":"How this list gets its members. `manual` means you add and remove them yourself. `smart` means Sillage maintains them from conditions set in the app. Smart lists are managed in the app; their members can't be added or removed through the API. Read-only: no route changes it. Omitted when a read uses `response_format=concise`."},"archived_at":{"type":"string","format":"date-time","nullable":true,"description":"When the list was archived, or null while it is in use. An archived list keeps every member; it just drops out of `GET /v3/partner/workspaces/{partner_workspace_id}/lists` unless you ask for it. Omitted when a read uses `response_format=concise`."},"archived":{"type":"boolean","description":"Whether the list is archived. `true` exactly when `archived_at` is set. Omitted when a read uses `response_format=concise`."},"persona_ids":{"type":"array","items":{"type":"integer"},"description":"The persona IDs of the personas this list belongs to. An empty array means the list belongs to no persona: it is visible from every persona and, if monitored, monitored and invoiced in every active persona. It is not an error state. Omitted when a read uses `response_format=concise`."},"is_deletable":{"type":"boolean","description":"Whether deleting or archiving this list would succeed right now. Omitted when a read uses `response_format=concise`."},"not_deletable_reason":{"type":"string","enum":["last_list_of_tier","in_use","employee_list"],"nullable":true,"description":"Why the list cannot be deleted or archived, or null when it can: `last_list_of_tier` (it is the only list of its kind for its persona, or of its tier for a prospect list, or the only one attached to no persona: create another one first), `in_use` (a signal setup or an older app signal uses it), or `employee_list` (the client's employee list can never be deleted). Omitted when a read uses `response_format=concise`."}}},"V3ListCreateBody":{"type":"object","additionalProperties":false,"description":"Only the fields below can be sent. Any other field is refused with a 422.","required":["type","name"],"properties":{"type":{"type":"string","enum":["competitor","partner","customer","prospect","influencer","champion","employee"],"description":"What the list is for. Cannot be changed later, and decides whether the list holds companies or people. `employee` is created for you and is refused here."},"name":{"type":"string","minLength":1,"maxLength":255,"description":"The name of the list, 255 characters at most. Names do not have to be unique."},"description":{"type":"string","maxLength":1000,"description":"What the list is for, 1000 characters at most."},"signal_buckets":{"type":"array","items":{"type":"string","enum":["essential"]},"minItems":1,"nullable":true,"description":"Allowed on a customer or prospect list only. Monitor every account of the list with these signal groups, including the ones added later. Monitoring an account covers its account mapping, its signals and its content. Send null, or omit it, to add accounts without monitoring them."},"tier":{"type":"integer","nullable":true,"minimum":1,"maximum":3,"description":"Prospect lists only (1, 2 or 3): leaving it out, or sending null, creates a Tier 1 list. Refused with a 422 on every other type, customer lists included. Set once at creation and never changeable afterwards: create a different list rather than re-tiering this one, since a tier change would silently re-tier every account already on it."},"persona_ids":{"type":"array","items":{"type":"integer"},"description":"The persona IDs of the personas to attach the list to. Omit to create it unattached: visible from every persona and, if monitored, monitored and invoiced in every active persona.","maxItems":100}}},"V3ListUpdateBody":{"type":"object","additionalProperties":false,"description":"Only the fields below can be sent. Any other field is refused with a 422, including `type` (it cannot be changed) and `mode` (it is read-only).","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"The new name, 255 characters at most."},"description":{"type":"string","nullable":true,"maxLength":1000,"description":"Send null to clear it. 1000 characters at most."},"signal_buckets":{"type":"array","items":{"type":"string","enum":["essential"]},"minItems":1,"nullable":true,"description":"Allowed on a customer or prospect list only. Applies to every account already on the list as well as to the ones added later: `[\"essential\"]` monitors all of them, null stops all of them. Monitoring an account covers its account mapping, its signals and its content. Omit it to leave the list and its accounts as they are."},"archived":{"type":"boolean","description":"Set to `true` to archive the list, `false` to bring it back. Archiving keeps every member; the list just leaves the default listing. Archiving a monitored list stops its monitoring. The month already invoiced is not credited back. The list keeps its `signal_buckets`, so every `monitoring_by_persona` entry reads 0 until you bring it back; bringing it back starts monitoring and invoicing again right away. Omit to leave it as it is."},"persona_ids":{"type":"array","items":{"type":"integer"},"description":"Replaces the full set of personas this list belongs to, as persona IDs. Omit to leave it untouched; send an empty array to detach the list from every persona.","maxItems":100}}},"V3AccountMonitoringApplyBody":{"type":"object","required":["company_ids","signal_buckets"],"properties":{"persona_id":{"type":"integer","description":"The persona to act in, from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`. Optional when the client's workspace has a single persona; required when it has several."},"company_ids":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"integer"},"description":"The accounts to monitor or stop, by company id: the `id` of a list member, as returned by the list members route and used by the company routes."},"signal_buckets":{"type":"array","items":{"type":"string","enum":["essential"]},"minItems":1,"nullable":true,"description":"The signal groups to monitor the accounts with, or null to stop monitoring them. Monitoring an account covers its account mapping, its signals and its content."}}},"V3AccountMonitoringApplyResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["changed","already_in_state","rejected","charged_credits","balance_after_credits"],"properties":{"changed":{"type":"array","description":"The accounts that changed, with their status once the change ran.","items":{"type":"object","required":["company_id","status","covered_until"],"properties":{"company_id":{"type":"integer"},"status":{"type":"string","enum":["monitored","not_covered","monitored_elsewhere","not_monitored"]},"covered_until":{"type":"string","format":"date-time","nullable":true,"description":"When the paid month ends; after a stop, when signals stop."}}}},"already_in_state":{"type":"array","items":{"type":"integer"},"description":"The accounts already in the state you asked for. Not invoiced again."},"rejected":{"type":"array","description":"The accounts that were refused, one entry each, with the `input` you sent for it. The other accounts of the request are still handled.","items":{"type":"object","required":["input","code","message"],"properties":{"input":{"type":"object","required":["company_id"],"properties":{"company_id":{"type":"integer"}}},"code":{"type":"string","enum":["not_found","workspace_wide_list_only","not_in_persona","monitored_through_workspace_wide_list"],"description":"`not_found`: the id is not an account of this client's workspace (an unknown id, a company id from outside the workspace, or an id from another workspace). `not_in_persona`: the account is not on a customer or prospect list of this persona. `workspace_wide_list_only`: the account is only on lists attached to no persona, so it cannot be monitored in one persona (only when the workspace has several personas). `monitored_through_workspace_wide_list`: the account is also monitored through a list attached to no persona, so stopping it here would not stop it (only when the workspace has several personas)."},"message":{"type":"string","description":"What went wrong, in words."}}}},"charged_credits":{"type":"number","description":"Always 0: monitoring is invoiced to you, not taken from a balance."},"balance_after_credits":{"type":"integer","nullable":true,"description":"Always `null`: a client has no balance."}}}}},"V3AccountMonitoringSummaryResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["is_billed","price_per_account_credits","monitored_count","not_covered_count","not_covered_since","monthly_cost_credits","renewal_shortfall_credits","by_persona"],"properties":{"is_billed":{"type":"boolean","description":"Whether this workspace is billed for account monitoring."},"price_per_account_credits":{"type":"number","description":"Credits per account, per persona, per month."},"monitored_count":{"type":"integer","description":"Accounts monitored, counted once per persona. It never includes the `not_covered_count` ones."},"not_covered_count":{"type":"integer"},"not_covered_since":{"type":"string","format":"date-time","nullable":true},"monthly_cost_credits":{"type":"number"},"renewal_shortfall_credits":{"type":"integer","description":"Always 0: a renewal is never refused for a client."},"by_persona":{"type":"array","items":{"type":"object","required":["persona_id","monitored_count","not_covered_count","monthly_cost_credits"],"properties":{"persona_id":{"type":"integer"},"monitored_count":{"type":"integer"},"not_covered_count":{"type":"integer"},"monthly_cost_credits":{"type":"number"}}}}}}}},"V3ListMember":{"type":"object","required":["id"],"description":"A member of a list: a company (carrying `name`) or a person (carrying `first_name` and `last_name`).","properties":{"id":{"type":"integer","description":"Identifier of the member: the company id for a company (as in `GET /v3/partner/workspaces/{partner_workspace_id}/companies/{company_id}`), the lead id for a person (as in `GET /v3/partner/workspaces/{partner_workspace_id}/leads/{lead_id}`). Send it as `member_id` to remove the member."},"name":{"type":"string","nullable":true,"description":"Company members only."},"first_name":{"type":"string","nullable":true,"description":"People only."},"last_name":{"type":"string","nullable":true,"description":"People only."},"linkedin_handle":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true},"logo_url":{"type":"string","nullable":true,"description":"Company members only. The company's logo, when we have one."},"avatar_url":{"type":"string","nullable":true,"description":"People only."},"position":{"type":"string","nullable":true,"description":"People only."},"linkedin_headline":{"type":"string","nullable":true,"description":"People only."},"enrichment_status":{"type":"string","nullable":true,"description":"People only."},"company":{"nullable":true,"description":"People only. The person's current company, when we know it.","allOf":[{"$ref":"#/components/schemas/V3CompanySummary"}]},"signal_buckets":{"type":"array","items":{"type":"string","enum":["essential"]},"nullable":true,"description":"The signal groups this member's account is monitored with through this list. Null means it is not monitored. Set from the list's `signal_buckets` when the member joins; to monitor or stop one account, use `PUT /v3/partner/workspaces/{partner_workspace_id}/account-monitoring/accounts`."},"monitoring":{"type":"array","nullable":true,"description":"Whether this account is monitored for the client, in each persona the list is attached to; in each active persona when the list is attached to none, or only in the persona you read with `persona_id`. Null on every list that is not a customer or prospect company list. `status` is one of:\n\n- `monitored`: monitored in this persona and paid up. `covered_until` is when the paid month ends.\n- `monitored_elsewhere`: monitored in another persona only.\n- `not_monitored`: not monitored. If you stopped it and the month you paid has not ended, `covered_until` still tells you when signals stop.","items":{"type":"object","required":["persona_id","status","covered_until","not_covered_since"],"properties":{"persona_id":{"type":"integer"},"status":{"type":"string","enum":["monitored","not_covered","monitored_elsewhere","not_monitored"]},"covered_until":{"type":"string","format":"date-time","nullable":true},"not_covered_since":{"type":"string","format":"date-time","nullable":true}}}}}},"V3ListAddMembersBody":{"type":"object","required":["members"],"properties":{"members":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","description":"Identify each member by its LinkedIn URL or handle. On company lists only, a domain is accepted as a fallback when you have no LinkedIn identifier.","properties":{"linkedin_url":{"type":"string","description":"LinkedIn URL of the company or person. The `https://` is optional (\"linkedin.com/company/stripe\" works)."},"linkedin_handle":{"type":"string"},"domain":{"type":"string","description":"Company domain, for example \"stripe.com\". Accepted on company lists only, and only when no LinkedIn URL or handle is available. Sending it on a list of people, or sending a value that is not a valid domain (no extension such as \".com\", or a malformed one such as \"a..com\"), comes back in `rejected` and does not block the other members."},"company":{"type":"object","description":"The company where you know this person — we use it to tell you when they move on. Accepted on champion lists only. Give at least a name or a domain; any other field is refused with a 422.","additionalProperties":false,"properties":{"name":{"type":"string"},"domain":{"type":"string"}}}},"anyOf":[{"required":["linkedin_url"]},{"required":["linkedin_handle"]},{"required":["domain"]}]}}}},"V3ListMemberResult":{"description":"A member of the list, with the `input` you sent for it.","allOf":[{"$ref":"#/components/schemas/V3ListMember"},{"type":"object","required":["input"],"properties":{"input":{"type":"object","description":"The member you sent.","properties":{"linkedin_url":{"type":"string"},"linkedin_handle":{"type":"string"},"domain":{"type":"string"},"company":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"}}}}}}}]},"V3ListMemberAddError":{"type":"object","required":["input","code","message"],"description":"One member that could not be added, and why.","properties":{"input":{"type":"object","description":"The member you sent that failed.","properties":{"linkedin_url":{"type":"string"},"linkedin_handle":{"type":"string"},"domain":{"type":"string"}}},"code":{"type":"string","enum":["multiple_domain_matches","domain_not_resolved","resolution_failed","wrong_entity_type","invalid_identifier"],"description":"`multiple_domain_matches`, the domain matched more than one company; `domain_not_resolved`, the company could not be identified from its domain; `resolution_failed`, something unexpected went wrong while identifying it; `wrong_entity_type`, the member is a company on a list of people or a person on a list of companies; `invalid_identifier`, the value is not a usable LinkedIn URL, handle or domain (for example a domain with no extension such as \".com\", or a malformed one such as \"a..com\")."},"message":{"type":"string","description":"What went wrong, in words."}}},"V3ListMembershipLogItem":{"type":"object","required":["id","transition","reason","reason_detail","previous_value","new_value","created_at"],"properties":{"id":{"type":"integer","description":"Identifier of the history entry."},"transition":{"type":"string","enum":["entered","left","owner_changed","bucket_changed"],"description":"What kind of change this entry records."},"reason":{"type":"string","enum":["manual","csv_import","api","rule_match","rule_unmatch","mode_switch"],"description":"Why it happened."},"reason_detail":{"type":"object","nullable":true,"additionalProperties":true,"description":"A little more context, when there is any, as an object with snake_case keys: `user_email` when a person made the change, `rule_group_id` when a condition did. Null otherwise."},"previous_value":{"type":"string","nullable":true,"description":"The value before the change, on entries that record one. On a `bucket_changed` entry it is `essential` when the account was monitored, or `null` when it was not. Null otherwise."},"new_value":{"type":"string","nullable":true,"description":"The value after the change, on entries that record one. On a `bucket_changed` entry it is `essential` when the account was monitored, or `null` when it was not. Null otherwise."},"created_at":{"type":"string","format":"date-time"},"company":{"nullable":true,"description":"The company this entry is about, on a company list. `null` on a list of people, and when the company is no longer there.","allOf":[{"$ref":"#/components/schemas/V3CompanySummary"}]},"lead":{"nullable":true,"description":"The person this entry is about, on a list of people. `null` on a company list, and when the person is no longer there.","allOf":[{"$ref":"#/components/schemas/V3LeadSummary"}]}}},"V3ResolvedCompany":{"type":"object","required":["company","matched_by","identifier"],"description":"A company matched from a company filter. `matched_by` says which filter matched the company; it can differ from one entry to the next.","properties":{"matched_by":{"type":"string","enum":["company_ids","company_domains","company_linkedin_handles","company_linkedin_urls"],"description":"The company filter that matched this company."},"identifier":{"type":"string","description":"The original identifier value supplied by the caller (domain, handle, URL, or numeric id echoed as a string)."},"company":{"$ref":"#/components/schemas/V3CompanySummary"}}},"V3Lead":{"type":"object","description":"A lead in the client's workspace, with its linked profile, a reference to its current company, its LinkedIn work history, and its pipeline status and owner. Most fields are nullable — a lead with no linked profile, or with a profile that has no current company, is returned with those fields set to `null` rather than an error.","required":["id","created_at","first_name","last_name","full_name","linkedin_url","linkedin_handle","linkedin_headline","avatar_url","email","phone","position","location","company","experiences","status","owner","crm_records"],"properties":{"id":{"type":"integer","description":"The lead's ID, as returned by the signals endpoints. Always use the `lead_id` value from those responses — don't guess, hard-code, or reuse an id from another workspace."},"created_at":{"type":"string","format":"date-time","nullable":true,"description":"When the lead was added to the workspace."},"first_name":{"type":"string","nullable":true,"description":"The lead's first name."},"last_name":{"type":"string","nullable":true,"description":"The lead's last name."},"full_name":{"type":"string","nullable":true,"description":"The lead's full name."},"linkedin_url":{"type":"string","nullable":true,"description":"The lead's LinkedIn profile URL."},"linkedin_handle":{"type":"string","nullable":true,"description":"LinkedIn profile handle (slug)."},"linkedin_headline":{"type":"string","nullable":true,"description":"The lead's LinkedIn headline."},"avatar_url":{"type":"string","nullable":true,"description":"The URL of the lead's profile photo."},"email":{"type":"string","nullable":true,"description":"The lead's email address, when known. `null` if not set."},"phone":{"type":"string","nullable":true,"description":"The lead's phone number, when known. `null` if not set."},"position":{"type":"string","nullable":true,"description":"The lead's job title."},"location":{"nullable":true,"description":"The lead's location. `null` when no location could be resolved for this lead — not an error.","allOf":[{"$ref":"#/components/schemas/V3Location"}]},"company":{"type":"object","nullable":true,"description":"The lead's current company, when one can be resolved. `null` when the lead has no current company.","required":["id","name","domain","linkedin_url","linkedin_handle","logo_url","activity_summary","employee_range","location","in_key_account_list"],"properties":{"id":{"type":"integer","description":"This company's ID in the workspace. Always use the `id` returned here — don't guess, hard-code, or copy it from another workspace — then pass it to the companies endpoints to fetch its full enrichment data."},"name":{"type":"string","nullable":true,"description":"The company's name."},"domain":{"type":"string","nullable":true,"description":"The company's website domain."},"linkedin_url":{"type":"string","nullable":true,"description":"The company's LinkedIn page URL."},"linkedin_handle":{"type":"string","nullable":true,"description":"The last part of the LinkedIn page address of the company."},"logo_url":{"type":"string","nullable":true,"description":"The URL of the company's logo."},"activity_summary":{"type":"string","nullable":true,"description":"A short summary of the company's activity."},"employee_range":{"type":"string","nullable":true,"description":"Employee headcount range, e.g. \"51-200\"."},"location":{"nullable":true,"description":"The company's headquarters. `null` when it is not known.","allOf":[{"$ref":"#/components/schemas/V3Location"}]},"in_key_account_list":{"type":"boolean","description":"True when this company is on one of the workspace's customer or prospect lists. Reflects those lists at the time of the request, so it changes as they change."}}},"experiences":{"type":"array","description":"The lead's work history, in the order it appears on their LinkedIn profile, including their current position. An empty array means no work history is known for this lead (for example a profile that was not sourced from LinkedIn).","items":{"type":"object","description":"One entry in the work history. All fields are nullable — a position with incomplete details is still returned, never dropped.","required":["position","company_name","company_linkedin_url","location","start_date","end_date","is_current"],"properties":{"position":{"type":"string","nullable":true,"description":"Job title held in this position."},"company_name":{"type":"string","nullable":true},"company_linkedin_url":{"type":"string","nullable":true,"description":"The employer's LinkedIn page, when known."},"location":{"type":"string","nullable":true,"description":"The job's location as written on LinkedIn (free text)."},"start_date":{"type":"string","nullable":true,"format":"date-time","description":"When this position started."},"end_date":{"type":"string","nullable":true,"format":"date-time","description":"When this position ended. `null` for the current position or when the end date is unknown."},"is_current":{"type":"boolean","description":"Whether this is the lead's current position."}}}},"status":{"type":"string","nullable":true,"enum":["pending","contacted_email","contacted_phone","contacted_linkedin","meeting_booked","need_follow_up","declined","disqualified","already_in_touch","customer","company_not_icp","job_title_not_icp"],"description":"Where this lead stands in the workspace's pipeline. `null` when no status has been set yet."},"owner":{"type":"object","nullable":true,"description":"The workspace member currently assigned to this lead, or `null` when unassigned.","required":["email","first_name","last_name"],"properties":{"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true}}},"crm_records":{"type":"array","description":"The CRMs this lead is matched in, one item per CRM, sorted by `provider`. Empty when Sillage has not matched the lead to a contact in any of your CRMs.","items":{"type":"object","required":["provider","contact_id","account_id"],"properties":{"provider":{"type":"string","enum":["salesforce","hubspot"],"description":"The CRM this record comes from. More providers may be added, so ignore values you do not handle."},"contact_id":{"type":"string","nullable":true,"description":"The lead's Contact ID in this CRM."},"account_id":{"type":"string","nullable":true,"description":"The ID of the Account associated with the contact in this CRM. `null` when the contact has no associated account."}}}}}},"V3LeadsPaginatedResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3Lead"}},"meta":{"type":"object","required":["cursor","resolved_companies"],"properties":{"cursor":{"type":"object","required":["next","has_more"],"properties":{"next":{"type":"string","nullable":true,"description":"Pass this token as `cursor` in the next request to fetch the following page. `null` when there is no next page."},"has_more":{"type":"boolean","description":"Whether more leads exist after this page."}}},"resolved_companies":{"type":"array","description":"Companies resolved from the company filter.","items":{"$ref":"#/components/schemas/V3ResolvedCompany"}}}}}},"V3CompanySearchResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","domain","linkedin_url","linkedin_handle","logo_url"],"properties":{"id":{"type":"integer","description":"The company's identifier in the client's workspace. Pass it as `company_ids` on `POST /v3/partner/workspaces/{partner_workspace_id}/leads/query`, or as the path id on `GET /v3/partner/workspaces/{partner_workspace_id}/companies/{company_id}`."},"name":{"type":"string","description":"The company's name."},"domain":{"type":"string","nullable":true,"description":"The company's website domain."},"linkedin_handle":{"type":"string","nullable":true,"description":"The last part of the LinkedIn page address of the company."},"linkedin_url":{"type":"string","nullable":true,"description":"The company's LinkedIn page URL."},"logo_url":{"type":"string","nullable":true,"description":"The URL of the company's logo."}}}}}},"V3Company":{"type":"object","description":"Enrichment data for a company. A company that has not been enriched yet is returned with `null` enrichment fields and empty `locations` and `industries`.","required":["id","name","domain","website_url","linkedin_url","linkedin_handle","logo_url","location","locations","number_of_employees","employee_range","founded_year","industries","activity_summary","tagline"],"properties":{"id":{"type":"integer","description":"The company's identifier in this workspace. The same value as the path parameter, as `lead.company.id`."},"name":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"website_url":{"type":"string","nullable":true,"description":"The company's website."},"linkedin_url":{"type":"string","nullable":true},"linkedin_handle":{"type":"string","nullable":true,"description":"LinkedIn company handle (slug)."},"logo_url":{"type":"string","nullable":true},"location":{"nullable":true,"description":"The company's headquarters. `null` when it is not known. `locations` lists every known site with its full address.","allOf":[{"$ref":"#/components/schemas/V3Location"}]},"locations":{"type":"array","description":"The company's known locations, HQ first. `is_hq` marks the headquarters; every other entry is a secondary location.","items":{"type":"object","required":["is_hq","city","region","state","country","country_code","postal_code","line1","line2","formatted_address","latitude","longitude"],"properties":{"is_hq":{"type":"boolean","description":"True for the headquarters location."},"city":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO country code."},"postal_code":{"type":"string","nullable":true},"line1":{"type":"string","nullable":true,"description":"First line of the street address."},"line2":{"type":"string","nullable":true,"description":"Second line of the street address, if any."},"formatted_address":{"type":"string","nullable":true,"description":"The full address as a single formatted string."},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true}}}},"number_of_employees":{"type":"integer","nullable":true},"employee_range":{"type":"string","nullable":true,"description":"Employee headcount range, e.g. \"51-200\"."},"founded_year":{"type":"integer","nullable":true},"industries":{"type":"array","items":{"type":"string"},"description":"The industries the company operates in. Empty when none is known."},"activity_summary":{"type":"string","nullable":true,"description":"A short summary of the company's activity."},"tagline":{"type":"string","nullable":true,"description":"The company's LinkedIn tagline — a short one-line headline, distinct from `activity_summary`. `null` when the company has no LinkedIn data, or LinkedIn has no tagline for it."}}},"V3ContentAuthor":{"description":"Who posted, commented, or reacted: a person or a company page. A person has the keys of a person summary, a company page the keys of a company summary, and `type` says which.","oneOf":[{"allOf":[{"$ref":"#/components/schemas/V3PersonSummary"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["person"]}}}]},{"allOf":[{"$ref":"#/components/schemas/V3CompanySummary"},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["company"]}}}]}]},"V3ContentProfileMention":{"type":"object","required":["full_name","linkedin_url"],"properties":{"full_name":{"type":"string"},"linkedin_url":{"type":"string"}}},"V3ContentCompanyMention":{"type":"object","required":["name","linkedin_url"],"properties":{"name":{"type":"string"},"linkedin_url":{"type":"string"}}},"V3ContentEmbeddedPost":{"type":"object","description":"The post a comment or a reaction was made on. All four keys are always present, and `null` when we do not have the value.","required":["content_id","linkedin_url","text","author"],"properties":{"content_id":{"type":"integer","nullable":true,"description":"The post's id among the contents of the workspace, usable with the contents endpoints. `null` when that post is not one of them."},"linkedin_url":{"type":"string","nullable":true,"description":"The URL of the post on LinkedIn."},"text":{"type":"string","nullable":true,"description":"The text of the post."},"author":{"nullable":true,"description":"Who wrote the post.","allOf":[{"$ref":"#/components/schemas/V3ContentAuthor"}]}}},"V3ContentData":{"description":"What this content item is about. Its shape depends on `content_type`. Fields marked as optional are included only when we could extract them.\n\n- LinkedIn posts (`linkedin_post`, `linkedin_company_post`): `linkedin_post_id`, `linkedin_original_post_id` (set when this is a repost), `is_repost`, `linkedin_url`, `text` (full text, never truncated), `posted_at`, `engagement`, `author`, `mentions` (`{ profiles: [...], companies: [...] }`), `image_urls`.\n- LinkedIn comments (`linkedin_comment`): `linkedin_comment_id`, `text`, `linkedin_url`, `posted_at`, `engagement`, `author` and `post`, the post the comment answers: `{ content_id, linkedin_url, text, author }`.\n- LinkedIn reactions (`linkedin_reaction`): `reaction_type`, `author` and `post`, the post that was reacted to.\n- LinkedIn job postings (`linkedin_job_posting`): `linkedin_job_id`, `linkedin_url`, `title`, `min_salary`, `max_salary` (a number or a free-text string such as `\"$100K/yr\"`, when disclosed), `location` (as written on the job offer, free text), `posted_at`, `description` (full text).\n- Every other content type (articles, press releases, blog posts): `text`.","oneOf":[{"type":"object","required":["author"],"properties":{"linkedin_post_id":{"type":"string","description":"The post's id on LinkedIn."},"linkedin_original_post_id":{"type":"string","nullable":true,"description":"The LinkedIn id of the original post, when this is a repost."},"is_repost":{"type":"boolean"},"linkedin_url":{"type":"string","description":"The URL of the post on LinkedIn."},"text":{"type":"string"},"posted_at":{"type":"string","format":"date-time"},"engagement":{"type":"object","description":"The same flat shape for posts and comments. `shares` is for posts only; `comments` is the number of comments on a post, or of replies to a comment. The reaction breakdown (`praise`, `empathy`, `interest`, `appreciation`) is present whenever the source gives it.","properties":{"likes":{"type":"integer"},"comments":{"type":"integer","description":"Number of comments on a post, or number of replies to a comment."},"shares":{"type":"integer","description":"Posts only."},"praise":{"type":"integer"},"empathy":{"type":"integer"},"interest":{"type":"integer"},"appreciation":{"type":"integer"}}},"author":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/V3ContentAuthor"}]},"mentions":{"type":"object","properties":{"profiles":{"type":"array","items":{"$ref":"#/components/schemas/V3ContentProfileMention"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/V3ContentCompanyMention"}}}},"image_urls":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["author","post"],"properties":{"linkedin_comment_id":{"type":"string","description":"The comment's own id on LinkedIn."},"text":{"type":"string"},"linkedin_url":{"type":"string","description":"The URL of the comment on LinkedIn."},"posted_at":{"type":"string","format":"date-time"},"engagement":{"type":"object","description":"The same flat shape for posts and comments. `shares` is for posts only; `comments` is the number of comments on a post, or of replies to a comment. The reaction breakdown (`praise`, `empathy`, `interest`, `appreciation`) is present whenever the source gives it.","properties":{"likes":{"type":"integer"},"comments":{"type":"integer","description":"Number of comments on a post, or number of replies to a comment."},"shares":{"type":"integer","description":"Posts only."},"praise":{"type":"integer"},"empathy":{"type":"integer"},"interest":{"type":"integer"},"appreciation":{"type":"integer"}}},"author":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/V3ContentAuthor"}]},"post":{"$ref":"#/components/schemas/V3ContentEmbeddedPost"}}},{"type":"object","required":["author","post"],"properties":{"reaction_type":{"type":"string"},"author":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/V3ContentAuthor"}]},"post":{"$ref":"#/components/schemas/V3ContentEmbeddedPost"}}},{"type":"object","properties":{"linkedin_job_id":{"type":"string","description":"The job posting's id on LinkedIn."},"linkedin_url":{"type":"string","description":"The URL of the job posting on LinkedIn."},"title":{"type":"string","description":"Job posting title."},"min_salary":{"oneOf":[{"type":"number"},{"type":"string"}],"nullable":true,"description":"Minimum disclosed salary, when available."},"max_salary":{"oneOf":[{"type":"number"},{"type":"string"}],"nullable":true,"description":"Maximum disclosed salary, when available."},"location":{"type":"string","description":"The job's location as written on the job offer (free text)."},"posted_at":{"type":"string","format":"date-time"},"description":{"type":"string","description":"Full job posting description."}}},{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}}]},"V3ContentRequestItem":{"type":"object","required":["id","type","status","label","failed_reason","persona_ids","created_at","updated_at","company"],"properties":{"id":{"type":"integer","description":"The content request id, as returned by this endpoint."},"type":{"type":"string","enum":["account_mapping","key_account_content"],"description":"Request type."},"status":{"type":"string","enum":["pending","in_progress","completed","failed"],"description":"Where the request stands. `pending`: waiting to start. `in_progress`: being processed. `completed`: finished. `failed`: stopped without finishing."},"label":{"type":"string","description":"A short readable description of the current step."},"failed_reason":{"type":"string","nullable":true,"enum":["no_employee_resolved","persona_without_job_titles","missing_linkedin_target","request_timed_out","insufficient_credits","internal_error"],"description":"Why the request failed, when its status is `failed`. `null` for every request that has not failed. `no_employee_resolved`: no employee matching the workspace persona was found for the company. `persona_without_job_titles`: the workspace persona has no job title, so accounts cannot be mapped until one is added. `missing_linkedin_target`: the company had no usable LinkedIn page to work from. `request_timed_out`: the request took too long and was stopped. `insufficient_credits`: not returned for a client, whose usage is invoiced to you rather than taken from a credit balance. `internal_error`: the request failed on our side."},"created_at":{"type":"string","format":"date-time","description":"When the request was created."},"updated_at":{"type":"string","format":"date-time","description":"When the request was last updated."},"company":{"nullable":true,"description":"The company this request runs for. `null` for a request that covers the whole workspace.","allOf":[{"$ref":"#/components/schemas/V3CompanySummary"}]},"persona_ids":{"type":"array","items":{"type":"integer"},"description":"The personas this request maps people for, from the personas endpoints. Empty when none."}}},"V3PersonaItem":{"type":"object","required":["id","name","job_titles","excluded_job_titles","locations","headcounts","industries","seniorities","exclusion_criteria","tag"],"properties":{"id":{"type":"integer","description":"Identifier of the persona."},"name":{"type":"string","description":"The persona's name, as shown in the app."},"job_titles":{"type":"array","items":{"type":"string"},"description":"Target job titles."},"excluded_job_titles":{"type":"array","items":{"type":"string"},"description":"People whose LinkedIn headline contains one of these words won't become leads."},"locations":{"type":"array","items":{"type":"string"},"description":"Target locations (countries or regions)."},"headcounts":{"type":"array","items":{"type":"string"},"description":"Target headcount ranges."},"industries":{"type":"array","items":{"type":"string"},"description":"Target industries."},"seniorities":{"type":"array","items":{"type":"string"},"description":"The seniority levels this persona targets."},"exclusion_criteria":{"type":"array","items":{"type":"string"},"description":"Sentences or keywords describing who to leave out; leads and companies that match score lower."},"tag":{"type":"string","nullable":true,"description":"Short free-form label you can set to recognise this persona in your own systems. Never used for targeting, and unique across the personas of the client's workspace."}}},"V3PersonaGetResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/V3PersonaItem"}}},"V3PersonaListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3PersonaItem"}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["page","page_size","page_count","total"],"properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"page_count":{"type":"integer"},"total":{"type":"integer"}}}}}}},"V3PersonaPatchBody":{"type":"object","minProperties":1,"description":"The fields of a persona, all optional. Only the ones you send are changed.","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"The persona's name, as shown in the app. Defaults to '<the client's domain> persona' (or the client's workspace name if it has no domain), numbered when taken."},"job_titles":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1100},"maxItems":1000,"minItems":1,"description":"Target job titles — at least one value when you send it. Used for account mapping and content, as the job titles a signal searches when its `use_persona_job_titles` is on (the default), and to keep the people found by signals."},"excluded_job_titles":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1100},"maxItems":1000,"description":"People whose LinkedIn headline contains one of these words won't become leads."},"locations":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1100},"maxItems":1000,"minItems":1,"description":"Target locations — at least one value when you send it. Countries (names, ISO codes and the usual aliases) and regions are recognised, in any letter case; new values may be added. Regions: EMEA, LATAM, Latin America, Western Europe, Eastern Europe, Northern Europe, Southern Europe, North America, North America (US & Canada), South America, APAC, Asia Pacific, Asia-Pacific, Asia, MENA, Middle East, Middle-East, Africa, Nordics, Benelux, DACH, Australia & New Zealand, Australia and New Zealand, ANZ, United Kingdom & Ireland, UK & Ireland, Europe, EU, Europe (EU), European Union, EEA, EU/EEA. A region stands for its countries. Europe, EU and Europe (EU) are the same 20 countries: France, Germany, United Kingdom, Spain, Italy, Portugal, Netherlands, Belgium, Switzerland, Austria, Ireland, Sweden, Norway, Denmark, Finland, Poland, Czechia, Hungary, Romania, Greece. European Union is the 27 member states only. EEA and EU/EEA are the 27 member states plus Iceland, Liechtenstein and Norway. Global, Worldwide, World and Anywhere mean no location filter. A value that is not recognised, such as a city, is kept and raises a warning in `meta.warnings`; it is never refused. A city-only list is kept but matches no country, so account mapping will not run for it. Used for account mapping and content."},"headcounts":{"type":"array","items":{"type":"string","enum":["1-10","11-50","51-200","201-500","501-1,000","1,001-5,000","5,001-10,000","10,001+"]},"description":"Target headcount ranges. Used to keep the people found by signals and to rate how well they fit."},"industries":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1100},"maxItems":1000,"description":"Target industries. Used to keep the people found by signals and to rate how well they fit."},"seniorities":{"type":"array","items":{"type":"string","enum":["owner","founder","c_suite","partner","vp","head","director","manager","senior","entry","intern"]},"description":"The seniority levels this persona targets."},"exclusion_criteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":50,"description":"Sentences or keywords describing who to leave out; leads and companies that match score lower. Send an empty array to clear them."},"tag":{"type":"string","maxLength":255,"description":"Short free-form label you can set to recognise this persona in your own systems. Never used for targeting. Two personas of the same workspace cannot share a tag — reusing one returns 409. Omit it to leave the persona untagged."}}},"V3PersonaUpsertResponse":{"type":"object","required":["data"],"properties":{"data":{"description":"The saved persona.","allOf":[{"$ref":"#/components/schemas/V3PersonaItem"}]},"meta":{"type":"object","description":"Present only when there is advisory feedback about the persona you just saved.","required":["warnings"],"properties":{"warnings":{"type":"array","items":{"type":"string"},"description":"Advisory notes about the submitted persona (e.g. missing job_titles/locations, or a location that could not be resolved to a country). Never blocks the write — the persona above is already saved."}}}}},"V3PersonaBody":{"type":"object","required":["job_titles","locations"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"The persona's name, as shown in the app. Defaults to '<the client's domain> persona' (or the client's workspace name if it has no domain), numbered when taken."},"job_titles":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1100},"maxItems":1000,"minItems":1,"description":"Required. Target job titles — at least one value. Used for account mapping and content, as the job titles a signal searches when its `use_persona_job_titles` is on (the default), and to keep the people found by signals."},"excluded_job_titles":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1100},"maxItems":1000,"description":"People whose LinkedIn headline contains one of these words won't become leads."},"locations":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1100},"maxItems":1000,"minItems":1,"description":"Required. Target locations — at least one value. Countries (names, ISO codes and the usual aliases) and regions are recognised, in any letter case; new values may be added. Regions: EMEA, LATAM, Latin America, Western Europe, Eastern Europe, Northern Europe, Southern Europe, North America, North America (US & Canada), South America, APAC, Asia Pacific, Asia-Pacific, Asia, MENA, Middle East, Middle-East, Africa, Nordics, Benelux, DACH, Australia & New Zealand, Australia and New Zealand, ANZ, United Kingdom & Ireland, UK & Ireland, Europe, EU, Europe (EU), European Union, EEA, EU/EEA. A region stands for its countries. Europe, EU and Europe (EU) are the same 20 countries: France, Germany, United Kingdom, Spain, Italy, Portugal, Netherlands, Belgium, Switzerland, Austria, Ireland, Sweden, Norway, Denmark, Finland, Poland, Czechia, Hungary, Romania, Greece. European Union is the 27 member states only. EEA and EU/EEA are the 27 member states plus Iceland, Liechtenstein and Norway. Global, Worldwide, World and Anywhere mean no location filter. A value that is not recognised, such as a city, is kept and raises a warning in `meta.warnings`; it is never refused. A city-only list is kept but matches no country, so account mapping will not run for it. Used for account mapping and content."},"headcounts":{"type":"array","items":{"type":"string","enum":["1-10","11-50","51-200","201-500","501-1,000","1,001-5,000","5,001-10,000","10,001+"]},"description":"Target headcount ranges. Used to keep the people found by signals and to rate how well they fit."},"industries":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1100},"maxItems":1000,"description":"Target industries. Used to keep the people found by signals and to rate how well they fit."},"seniorities":{"type":"array","items":{"type":"string","enum":["owner","founder","c_suite","partner","vp","head","director","manager","senior","entry","intern"]},"description":"The seniority levels this persona targets."},"exclusion_criteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":500},"maxItems":50,"description":"Sentences or keywords describing who to leave out; leads and companies that match score lower. Send an empty array to clear them."},"tag":{"type":"string","maxLength":255,"description":"Short free-form label you can set to recognise this persona in your own systems. Never used for targeting. Two personas of the same workspace cannot share a tag — reusing one returns 409. Omit it to leave the persona untagged."}}},"V3CompanyMapping":{"type":"object","required":["id","created_at","version","status","label","persona_id","company"],"properties":{"id":{"type":"integer","description":"The mapping id."},"created_at":{"type":"string","format":"date-time","nullable":true},"version":{"type":"integer","nullable":true,"description":"The mapping's number among this company's mappings."},"status":{"type":"string","enum":["in_progress","completed","failed"],"description":"`in_progress`: employees are still being resolved. `completed`: every profile has been enriched. `failed`: the mapping could not finish and will not change. More values may be added: ignore the ones you do not know."},"label":{"type":"string","description":"A short readable description of the current step."},"persona_id":{"type":"integer","nullable":true,"description":"The persona this mapping was made for, from `GET /v3/partner/workspaces/{partner_workspace_id}/personas`. `null` when it applies to every persona."},"company":{"nullable":true,"description":"The company the mapping was run on, or `null` when the mapping has no company.","allOf":[{"$ref":"#/components/schemas/V3CompanySummary"}]}}},"V3CompanyMappingListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V3CompanyMapping"}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["page","page_size","page_count","total"],"properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"page_count":{"type":"integer"},"total":{"type":"integer"}}}}}}},"V3CompanyMappingProfile":{"type":"object","required":["id","full_name","first_name","last_name","linkedin_handle","linkedin_url","linkedin_headline","linkedin_about","avatar_url","email","phone","position","position_start_date","location","seniority","department"],"properties":{"id":{"type":"integer","description":"The lead ID; open it with Get a lead."},"linkedin_handle":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"linkedin_about":{"type":"string","nullable":true},"position":{"type":"string","nullable":true},"position_start_date":{"type":"string","format":"date","nullable":true,"description":"Date this person started their current role, ISO 8601 (YYYY-MM-DD)."},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true,"description":"The person's full name."},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"linkedin_headline":{"type":"string","nullable":true},"location":{"nullable":true,"description":"The person's location. `null` when it is not known.","allOf":[{"$ref":"#/components/schemas/V3Location"}]},"seniority":{"type":"string","enum":["owner","founder","c_suite","partner","vp","head","director","manager","senior","entry","intern","unspecified"],"description":"The person's seniority level, deduced from their position."},"department":{"type":"string","enum":["executive","board_investors","sales","marketing_communications","revenue_operations","customer_success","product_design","engineering","data_ai_analytics","it_security","rd_science","finance_accounting","legal_compliance","people_hr","business_operations","site_network_operations","supply_chain","manufacturing","procurement","quality_regulatory","strategy_corporate_development","consulting_delivery","other","unspecified"],"description":"The person's department, deduced from their position."}}},"V3CompanyMappingResponse":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/V3CompanyMapping"},{"type":"object","required":["profiles"],"properties":{"profiles":{"type":"array","description":"The enriched employee profiles found for this company.","items":{"$ref":"#/components/schemas/V3CompanyMappingProfile"}}}}]}}},"ProblemDetails":{"type":"object","description":"RFC 9457 error body. Returned with Content-Type: application/problem+json on every v3 error response.","required":["type","title","status","code"],"properties":{"type":{"type":"string","format":"uri","description":"Always `about:blank`. Use `code` to identify the problem.","example":"about:blank"},"title":{"type":"string","description":"A short, human-readable summary of the HTTP status, the same for every problem with that status. Do not use it to tell problems apart: use `code`.","example":"Unauthorized"},"status":{"type":"integer","description":"The HTTP status code.","example":401},"code":{"type":"string","description":"A stable, machine-readable identifier of the problem (for example `invalid_body` or `not_found`). Switch on it rather than on `title` or `detail`. New codes may be added: handle the ones you know and treat any other as the generic problem of its status.","example":"invalid_api_key"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence. Its wording may change: do not parse it."},"signal_setup_ids":{"type":"array","items":{"type":"integer"},"description":"The signal setups that block the change. Present only on the 409 that refuses a list change because signal setups depend on it."},"instance":{"type":"string","description":"The request path that produced this error.","example":"/api/v3/partner/workspaces/ws_123/lists"},"errors":{"type":"object","description":"Field-level validation errors, keyed by field name. Present only on a 422, and absent on a 422 that names no field. The key `_root` stands for the whole body or for a rule that spans several fields.","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"SignalSetupTemplate":{"type":"object","description":"The signal this setup is for, as `GET /v3/partner/workspaces/{partner_workspace_id}/signal-templates` returns it, without its `setup` definition of the parameters.","required":["id","key","name","description","row_summary","category","status","subjects","scopes","tags","pricing","archived_at"],"properties":{"id":{"type":"integer","description":"The ID of the signal template."},"key":{"type":"string","description":"Stable identifier of this signal. Prefer it to `id` when you store a reference to a signal."},"name":{"type":"string","description":"The signal name."},"description":{"type":"string","nullable":true,"description":"A short explanation of what this signal watches for."},"row_summary":{"type":"string","nullable":true,"description":"A one-line summary, for a compact list display."},"category":{"type":"string","enum":["my_properties","my_network","competition","people","market","internal_intents"],"description":"The family of signals this one belongs to."},"status":{"type":"string","enum":["live","coming_soon"],"description":"Whether this signal can be set up."},"subjects":{"type":"array","items":{"type":"string","enum":["person","company"]},"description":"Who this signal watches — a person, a company, or both."},"scopes":{"type":"array","items":{"type":"string","enum":["discovery","account_monitoring"]},"description":"Which setups this signal supports."},"tags":{"type":"array","items":{"type":"string","enum":["popular","not_set_up"]},"description":"Labels you can filter signal templates on. `popular` is set by Sillage. `not_set_up` means the client workspace has no active or paused signal setup of this template; it is worked out on every read, and a template inside a signal setup never carries it."},"pricing":{"type":"object","description":"What this signal costs the client's workspace, by mode. Each mode is `null` on its own when this signal has no price for it.","required":["account_monitoring","discovery"],"properties":{"account_monitoring":{"type":"object","nullable":true,"description":"This signal's account-monitoring price, `null` when this signal has no account-monitoring price.","required":["signal_bucket","credits","unit"],"properties":{"signal_bucket":{"type":"string","enum":["essential","standard","advanced"],"description":"The pricing tier this price belongs to."},"credits":{"type":"number","description":"The exact price, in credits — never rounded."},"unit":{"type":"string","enum":["per_key_account_per_month"],"description":"What is being priced."}}},"discovery":{"type":"object","nullable":true,"description":"This signal's discovery price, per signal found. `null` when this signal has no discovery price.","required":["credits","unit"],"properties":{"credits":{"type":"number","description":"The exact price, in credits — never rounded."},"unit":{"type":"string","enum":["signal_found"],"description":"What is being priced."}}}}},"archived_at":{"type":"string","format":"date-time","nullable":true,"description":"When this signal was archived, `null` while still active. An archived signal is left out of the list but still resolves by ID."}}}}}}