nv.saveLead

Save a person as a lead in Sales Navigator and, optionally, add them to one of your custom lead lists. Sales Navigator raises lead alerts for the leads you save. To read only alerts about subjects you saved, set filter.excludeSuggested to true in nv.retrieveAlerts. An alert's subject.url can be passed straight to this action.

An active Sales Navigator subscription is required. To find a list's ID, call nv.retrieveLists with type set to lead. To create a new lead list, call nv.createList and use the id it returns.

Constraints

⏺️ Root Start: allowed, when personHashedUrl parameter is provided.

⬆️ Parent Actions: nv.openPersonPage, nv.doForPeople under nv.searchPeople, nv.retrieveCompanyEmployees or nv.retrieveCompanyDMs.

⬇️ Child Actions: N/A.

Parameters

{
  "actionType": "nv.saveLead",
  "label": "saveLead1",
  "personHashedUrl": "https://www.linkedin.com/in/SInQBmjJ015eLr8",
  "listId": "7420000000000000001"
}

const workflow = await linkedapi.nvSaveLead.execute({
  personHashedUrl: "https://www.linkedin.com/in/SInQBmjJ015eLr8",
  listId: "7420000000000000001"
});

const { errors } = await linkedapi.nvSaveLead.result(workflow.workflowId);

from linkedapi import NvSaveLeadParams

workflow = linkedapi.nv_save_lead.execute(
    NvSaveLeadParams(
        person_hashed_url="https://www.linkedin.com/in/SInQBmjJ015eLr8",
        list_id="7420000000000000001",
    )
)

result = linkedapi.nv_save_lead.result(workflow.workflow_id)

In AI assistants, the MCP tool is nv_save_lead. The n8n action is Save lead in Sales Navigator; the Make module is Save Lead in Sales Navigator.

Parameter	Description
`label`	Optional label included in workflow completion.
`personHashedUrl`	Required for root start, forbidden for parent start. LinkedIn URL of the person, in any form `nv.openPersonPage` accepts: a hashed URL, an alert's `subject.url` (`/sales/lead/…`), or a public profile URL (`linkedin.com/in/<vanity>`), which costs one extra page load. Under a parent action, the person comes from the parent.
`listId`	Optional. ID of one of your custom lead lists, as returned in `id` by `nv.retrieveLists` or `nv.createList`. Pass it as a string. Omit it to save the lead without changing any list. More than 10 lead lists, for now: Sales Navigator's save menu shows lists ten at a time. If you have more than 10 lead lists and the requested list is not among those the menu shows, the call fails with `unexpectedError`. The lead may already be saved by then, but is not added to that list. This is a current limitation.

Saving behaviour

Saved, and in the list you name. The action makes sure the person is a saved lead. With listId, it also makes sure the lead is in that one list and leaves the lead's other lists as they are. Without listId, no list changes.
Safe to repeat. Saving a lead that is already saved, or already in the requested list, succeeds without changing anything.
The lead's company may be saved too. Saving a lead can make Sales Navigator also save the lead's current company as an account. This is Sales Navigator's own behaviour.
Which lists you can save to. listId must be one of your custom lead lists. nv.retrieveLists also returns Sales Navigator's system lists, such as Recommended Leads, but Sales Navigator does not offer them as save targets. Any other ID returns listNotFound, and nothing is written. The same applies when another of your lead lists has exactly the same name: the save menu shows lists by name only, so rename one of them first. nv.createList never creates a lead list with a name you already use.
Changes can take up to a few minutes to appear. Sales Navigator can take up to a few minutes to reflect a change. A call that conflicts with a change you just made through Linked API, such as unsaving a lead you have just saved, may fail with unexpectedError; retry it a little later.
English interface only, for now. This is a current limitation: saving and unsaving work only with an English Sales Navigator interface. On a German, Spanish, French or Portuguese interface, the call fails with interfaceLanguageNotSupported.

To take the lead out of one list and keep them saved, use nv.removeLeadFromList; to unsave them, use nv.unsaveLead.

Saving from search results

Under nv.doForPeople, whose parent is nv.searchPeople, nv.retrieveCompanyEmployees or nv.retrieveCompanyDMs, the action saves each person straight from the parent's result list, without opening their page. If that list is no longer open when the save runs, for example because an earlier action for the same person opened their page, the action saves on the person's page instead. Saving 20 search results costs the search result pages instead of 20 extra profile page loads, so your LinkedIn account does far less browsing for the same result. How many people are saved is set by the parent action's limit.

Under nv.openPersonPage, the action saves the person whose page is already open, so you can read their details, message them and save them in one workflow.

nv.unsaveLead is not available under nv.doForPeople.

Workflow:

{
  "actionType": "nv.searchPeople",
  "term": "Head of Sales",
  "limit": 2,
  "filter": {
    "locations": ["London"]
  },
  "then": {
    "actionType": "nv.doForPeople",
    "then": {
      "actionType": "nv.saveLead",
      "listId": "7420000000000000001"
    }
  }
}

const workflow = await linkedapi.customWorkflow.execute({
  actionType: "nv.searchPeople",
  term: "Head of Sales",
  limit: 2,
  filter: {
    locations: ["London"]
  },
  then: {
    actionType: "nv.doForPeople",
    then: {
      actionType: "nv.saveLead",
      listId: "7420000000000000001"
    }
  }
});

const { data, errors } = await linkedapi.customWorkflow.result(workflow.workflowId);

workflow = linkedapi.custom_workflow.execute(
    {
        "actionType": "nv.searchPeople",
        "term": "Head of Sales",
        "limit": 2,
        "filter": {
            "locations": ["London"],
        },
        "then": {
            "actionType": "nv.doForPeople",
            "then": {
                "actionType": "nv.saveLead",
                "listId": "7420000000000000001",
            },
        },
    }
)

result = linkedapi.custom_workflow.result(workflow.workflow_id)

linkedin workflow run <<'EOF'
{
  "actionType": "nv.searchPeople",
  "term": "Head of Sales",
  "limit": 2,
  "filter": {
    "locations": ["London"]
  },
  "then": {
    "actionType": "nv.doForPeople",
    "then": {
      "actionType": "nv.saveLead",
      "listId": "7420000000000000001"
    }
  }
}
EOF

Completion:

json

{
  "actionType": "nv.searchPeople",
  "success": true,
  "data": [
    {
      "name": "Jane Smith",
      "urn": "urn:li:member:123456789",
      "hashedUrl": "https://www.linkedin.com/in/SInQBmjJ015eLr8",
      "position": "Head of Sales",
      "location": "London",
      "avatarUrl": null,
      "viewerState": { "connectionDegree": "2nd" },
      "then": [
        {
          "actionType": "nv.saveLead",
          "success": true
        }
      ]
    },
    {
      "name": "Tom Brown",
      "urn": "urn:li:member:987654321",
      "hashedUrl": "https://www.linkedin.com/in/ACoAA2DdsSV83B48",
      "position": "Head of Sales EMEA",
      "location": "London",
      "avatarUrl": null,
      "viewerState": { "connectionDegree": "3rd+" },
      "then": [
        {
          "actionType": "nv.saveLead",
          "success": true
        }
      ]
    }
  ]
}

Result options

json

{
  "actionType": "nv.saveLead",
  "label": "saveLead1",
  "success": true
}

A successful save has no data. label is included only if specified in the action parameters.

Error result

An unsuccessful action returns success: false with an error object:

json

{
  "actionType": "nv.saveLead",
  "label": "saveLead1",
  "success": false,
  "error": {
    "type": "listNotFound",
    "message": "The list is not available for this subject in Sales Navigator."
  }
}

Possible error.type values:

noSalesNavigator — the account does not have an active Sales Navigator subscription.
personNotFound — the provided URL is not an existing LinkedIn person. This includes a public profile URL that leads to no LinkedIn profile.
listNotFound — listId is not one of your custom lead lists. This is checked before anything is written. Rarely, a valid list is missing from the lead's save menu; the lead may then already be saved when this error is returned.
interfaceLanguageNotSupported — the account's Sales Navigator interface is German, Spanish, French or Portuguese rather than English. Nothing is changed; this is a current limitation (see above).
unexpectedError — the save could not be completed. This includes a call that conflicts with a change you just made through Linked API: Sales Navigator can take up to a few minutes to reflect a change, so retry it a little later. It also includes a listId that the save menu did not show when you have more than 10 lead lists (see listId).

Previousnv.openPersonPage Nextnv.unsaveLead