> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.heyreach.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.heyreach.io/_mcp/server.

# AddLeadsToListV2

POST https://api//api/public/list/AddLeadsToListV2
Content-Type: application/json

Add leads to a lead list. Add up to 100 leads per request. Same as the **AddLeadsToList** request, however this request returns counts for how many of the leads were added, how many were update and how many failed to be added.

**The** **`name`** **field in the** **`customUserFields`** **array of the leads you are importing, must contain only alpha-numeric characters or underscores** **`_`**. **An error will be return in the case the** **`name`** **field does not follow this format.**

**Be aware that adding leads to a list is not the same as adding them to a campaign. If the campaign is in a finished state or has already used all the leads in it, then leads added to the list will not be started in the campaign. If you want to add the leads to a specific campaign, then use the AddLeadsToCampaign or AddLeadsToCampaignV2 methods.**

Reference: https://docs.heyreach.io/hey-reach-api/lists/add-leads-to-list-v-2

## Request

### Headers

- `X-API-KEY` (string, optional) — API key header using this scheme. Example: "X-API-KEY: \{API\_KEY}"

### Body (application/json)

This endpoint expects an object.

- `leads` (list of object, required)
  - `firstName` (string, required)
  - `lastName` (string, required)
  - `location` (string, required)
  - `summary` (string, required)
  - `companyName` (string, required)
  - `position` (string, required)
  - `about` (string, required)
  - `emailAddress` (string, required)
  - `customUserFields` (list of object, required)
    - `name` (string, required)
    - `value` (string, required)
  - `profileUrl` (string, required)
- `listId` (integer, required)

## Response

### 200

OK

- `addedLeadsCount` (integer, required)
- `updatedLeadsCount` (integer, required)
- `failedLeadsCount` (integer, required)

## Errors

### 400 Add Leads to List V2lists Request Bad Request Error

Bad Request

- `errorMessage` (string, required)

### 401 Add Leads to List V2lists Request Unauthorized Error

Unauthorized

- `type` (string, required)
- `title` (string, required)
- `status` (string, required)
- `detail` (string, required)
- `instance` (string, required)
- `ut8c` (object, required)
- `laborum__e5` (object, required)
- `occaecat100` (object, required)

### 404 Add Leads to List V2lists Request Not Found Error

Not Found

- `errorMessage` (string, required)

### 429 Add Leads to List V2lists Request Too Many Requests Error

Too Many Requests

- `type` (string, required)
- `title` (string, required)
- `status` (string, required)
- `detail` (string, required)
- `instance` (string, required)
- `ut8c` (object, required)
- `laborum__e5` (object, required)
- `occaecat100` (object, required)

## Examples

**Request**

```json
{
  "leads": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "location": "USA",
      "summary": "SDR @ HeyReach",
      "companyName": "HeyReach",
      "position": "SDR",
      "about": "I like LinkedIn",
      "emailAddress": "john_doe@example.com",
      "customUserFields": [
        {
          "name": "favorite_color",
          "value": "blue"
        }
      ],
      "profileUrl": "https://www.linkedin.com/in/john-doe"
    }
  ],
  "listId": 123
}
```

**Response**

```json
{
  "addedLeadsCount": 10,
  "updatedLeadsCount": 1,
  "failedLeadsCount": 0
}
```

**SDK Code**

```python
import requests

url = "https://api//api/public/list/AddLeadsToListV2"

payload = {
    "leads": [
        {
            "firstName": "John",
            "lastName": "Doe",
            "location": "USA",
            "summary": "SDR @ HeyReach",
            "companyName": "HeyReach",
            "position": "SDR",
            "about": "I like LinkedIn",
            "emailAddress": "john_doe@example.com",
            "customUserFields": [
                {
                    "name": "favorite_color",
                    "value": "blue"
                }
            ],
            "profileUrl": "https://www.linkedin.com/in/john-doe"
        }
    ],
    "listId": 123
}
headers = {
    "X-API-KEY": "<string>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api//api/public/list/AddLeadsToListV2';
const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<string>', 'Content-Type': 'application/json'},
  body: '{"leads":[{"firstName":"John","lastName":"Doe","location":"USA","summary":"SDR @ HeyReach","companyName":"HeyReach","position":"SDR","about":"I like LinkedIn","emailAddress":"john_doe@example.com","customUserFields":[{"name":"favorite_color","value":"blue"}],"profileUrl":"https://www.linkedin.com/in/john-doe"}],"listId":123}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api//api/public/list/AddLeadsToListV2"

	payload := strings.NewReader("{\n  \"leads\": [\n    {\n      \"firstName\": \"John\",\n      \"lastName\": \"Doe\",\n      \"location\": \"USA\",\n      \"summary\": \"SDR @ HeyReach\",\n      \"companyName\": \"HeyReach\",\n      \"position\": \"SDR\",\n      \"about\": \"I like LinkedIn\",\n      \"emailAddress\": \"john_doe@example.com\",\n      \"customUserFields\": [\n        {\n          \"name\": \"favorite_color\",\n          \"value\": \"blue\"\n        }\n      ],\n      \"profileUrl\": \"https://www.linkedin.com/in/john-doe\"\n    }\n  ],\n  \"listId\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<string>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api//api/public/list/AddLeadsToListV2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<string>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"leads\": [\n    {\n      \"firstName\": \"John\",\n      \"lastName\": \"Doe\",\n      \"location\": \"USA\",\n      \"summary\": \"SDR @ HeyReach\",\n      \"companyName\": \"HeyReach\",\n      \"position\": \"SDR\",\n      \"about\": \"I like LinkedIn\",\n      \"emailAddress\": \"john_doe@example.com\",\n      \"customUserFields\": [\n        {\n          \"name\": \"favorite_color\",\n          \"value\": \"blue\"\n        }\n      ],\n      \"profileUrl\": \"https://www.linkedin.com/in/john-doe\"\n    }\n  ],\n  \"listId\": 123\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api//api/public/list/AddLeadsToListV2")
  .header("X-API-KEY", "<string>")
  .header("Content-Type", "application/json")
  .body("{\n  \"leads\": [\n    {\n      \"firstName\": \"John\",\n      \"lastName\": \"Doe\",\n      \"location\": \"USA\",\n      \"summary\": \"SDR @ HeyReach\",\n      \"companyName\": \"HeyReach\",\n      \"position\": \"SDR\",\n      \"about\": \"I like LinkedIn\",\n      \"emailAddress\": \"john_doe@example.com\",\n      \"customUserFields\": [\n        {\n          \"name\": \"favorite_color\",\n          \"value\": \"blue\"\n        }\n      ],\n      \"profileUrl\": \"https://www.linkedin.com/in/john-doe\"\n    }\n  ],\n  \"listId\": 123\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api//api/public/list/AddLeadsToListV2', [
  'body' => '{
  "leads": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "location": "USA",
      "summary": "SDR @ HeyReach",
      "companyName": "HeyReach",
      "position": "SDR",
      "about": "I like LinkedIn",
      "emailAddress": "john_doe@example.com",
      "customUserFields": [
        {
          "name": "favorite_color",
          "value": "blue"
        }
      ],
      "profileUrl": "https://www.linkedin.com/in/john-doe"
    }
  ],
  "listId": 123
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-API-KEY' => '<string>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api//api/public/list/AddLeadsToListV2");
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-KEY", "<string>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"leads\": [\n    {\n      \"firstName\": \"John\",\n      \"lastName\": \"Doe\",\n      \"location\": \"USA\",\n      \"summary\": \"SDR @ HeyReach\",\n      \"companyName\": \"HeyReach\",\n      \"position\": \"SDR\",\n      \"about\": \"I like LinkedIn\",\n      \"emailAddress\": \"john_doe@example.com\",\n      \"customUserFields\": [\n        {\n          \"name\": \"favorite_color\",\n          \"value\": \"blue\"\n        }\n      ],\n      \"profileUrl\": \"https://www.linkedin.com/in/john-doe\"\n    }\n  ],\n  \"listId\": 123\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-API-KEY": "<string>",
  "Content-Type": "application/json"
]
let parameters = [
  "leads": [
    [
      "firstName": "John",
      "lastName": "Doe",
      "location": "USA",
      "summary": "SDR @ HeyReach",
      "companyName": "HeyReach",
      "position": "SDR",
      "about": "I like LinkedIn",
      "emailAddress": "john_doe@example.com",
      "customUserFields": [
        [
          "name": "favorite_color",
          "value": "blue"
        ]
      ],
      "profileUrl": "https://www.linkedin.com/in/john-doe"
    ]
  ],
  "listId": 123
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api//api/public/list/AddLeadsToListV2")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```