Blacklist Management Guide¶

Exclude known companies from your enrichment and discovery orders.

Overview¶

Blacklists let you maintain lists of companies that should be excluded from prospecting results. Common uses:

Existing customers you don't want to prospect again
Competitors you want to filter out
Disqualified leads from previous campaigns

You can create multiple blacklists, add entries in bulk, and assign them to prospect searches or discovery orders. When assigned, blacklisted companies are automatically excluded from results.

How It Works¶

flowchart LR
    A[Create Blacklist] --> B[Add Entries]
    B --> C[Assign to Order]
    C --> D[Companies Excluded]

Create a named blacklist
Add company entries (individually or in bulk up to 10,000)
Assign the blacklist to a prospect search or include it in a discovery order
Companies matching your blacklist entries are automatically excluded from results

Matching Accuracy¶

Blacklist matching uses a tiered approach for best accuracy:

Priority	Match Method	Accuracy	When Used
1 (best)	`external_id`	Exact	Your CRM ID matches a company's source ID
2	`website_url` domain	High	Domain extracted and compared
3	`company_name` + `city`	Good	Name and city combination
4	`company_name` only	Fair	Name-only match (less precise)

Best Practice

Always provide website_url when you have it. Domain-based matching is far more reliable than name-only matching, especially for companies with common names.

Prerequisites¶

Before you begin:

API Key with blacklists:read and blacklists:write scopes. Create one in the OpenProspect dashboard under Settings > Developer > API Keys.
Base URL: https://api.openprospect.io/api/v1

Scopes

Blacklist management needs two scopes: blacklists:read and blacklists:write. If you also need to create discovery orders with blacklists, add orders:read and orders:write. See Authentication for the full scope list.

Step 1: Create a Blacklist¶

Create a named blacklist to organize your exclusion lists.

Request¶

POST /api/v1/blacklists

cURLPythonJavaScriptTypeScriptC#

curl -X POST "https://api.openprospect.io/api/v1/blacklists" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Existing Customers",
    "description": "Companies already in our CRM"
  }'

import httpx

API_KEY = "lnc_live_your_api_key_here"
BASE_URL = "https://api.openprospect.io/api/v1"

blacklist = {
    "name": "Existing Customers",
    "description": "Companies already in our CRM",
}

response = httpx.post(
    f"{BASE_URL}/blacklists",
    json=blacklist,
    headers={"Authorization": f"Bearer {API_KEY}"},
)

if response.status_code == 201:
    data = response.json()
    print(f"Blacklist created: {data['id']}")
else:
    print(f"Error {response.status_code}: {response.json()}")

const API_KEY = "lnc_live_your_api_key_here";
const BASE_URL = "https://api.openprospect.io/api/v1";

const blacklist = {
  name: "Existing Customers",
  description: "Companies already in our CRM",
};

const response = await fetch(`${BASE_URL}/blacklists`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(blacklist),
});

if (response.status === 201) {
  const data = await response.json();
  console.log(`Blacklist created: ${data.id}`);
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

const API_KEY = "lnc_live_your_api_key_here";
const BASE_URL = "https://api.openprospect.io/api/v1";

interface BlacklistResponse {
  id: string;
  name: string;
  description: string | null;
  entry_count: number;
  created_at: string;
  updated_at: string;
}

const blacklist = {
  name: "Existing Customers",
  description: "Companies already in our CRM",
};

const response = await fetch(`${BASE_URL}/blacklists`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(blacklist),
});

if (response.status === 201) {
  const data: BlacklistResponse = await response.json();
  console.log(`Blacklist created: ${data.id}`);
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var apiKey = "lnc_live_your_api_key_here";
var baseUrl = "https://api.openprospect.io/api/v1";

var blacklist = new
{
    name = "Existing Customers",
    description = "Companies already in our CRM"
};

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", apiKey);

var json = JsonSerializer.Serialize(blacklist);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync($"{baseUrl}/blacklists", content);

if ((int)response.StatusCode == 201)
{
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"Blacklist created: {body}");
}
else
{
    Console.WriteLine($"Error {(int)response.StatusCode}");
    Console.WriteLine(await response.Content.ReadAsStringAsync());
}

Response (201 Created)¶

{
  "id": "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
  "name": "Existing Customers",
  "description": "Companies already in our CRM",
  "entry_count": 0,
  "created_at": "2026-03-01T10:30:00.000000Z",
  "updated_at": "2026-03-01T10:30:00.000000Z"
}

Checkpoint

Save the id from the response. You need it to add entries and manage the blacklist.

Request Parameters¶

Parameter	Type	Required	Description
`name`	string	Yes	Blacklist name (1-500 chars)
`description`	string	No	Optional description (max 2,000 chars)

Step 2: Add Entries¶

Add companies to your blacklist in bulk. You can add up to 10,000 entries per request.

Request¶

POST /api/v1/blacklists/{blacklist_id}/entries

cURLPythonJavaScriptTypeScriptC#

curl -X POST "https://api.openprospect.io/api/v1/blacklists/d33b69ce-80ce-4ede-b4df-4b11427f8b55/entries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "company_name": "Acme Corp",
        "website_url": "https://www.acme-corp.com",
        "city": "Berlin",
        "country": "Germany",
        "external_id": "CRM-5001",
        "reason": "Existing customer"
      },
      {
        "company_name": "Global Industries GmbH",
        "city": "Munich",
        "country": "Germany",
        "reason": "Competitor"
      },
      {
        "company_name": "TechStart AG",
        "website_url": "https://techstart.de",
        "external_id": "CRM-5003"
      }
    ]
  }'

blacklist_id = "d33b69ce-80ce-4ede-b4df-4b11427f8b55"

entries = {
    "entries": [
        {
            "company_name": "Acme Corp",
            "website_url": "https://www.acme-corp.com",
            "city": "Berlin",
            "country": "Germany",
            "external_id": "CRM-5001",
            "reason": "Existing customer",
        },
        {
            "company_name": "Global Industries GmbH",
            "city": "Munich",
            "country": "Germany",
            "reason": "Competitor",
        },
        {
            "company_name": "TechStart AG",
            "website_url": "https://techstart.de",
            "external_id": "CRM-5003",
        },
    ]
}

response = httpx.post(
    f"{BASE_URL}/blacklists/{blacklist_id}/entries",
    json=entries,
    headers={"Authorization": f"Bearer {API_KEY}"},
)

if response.status_code == 201:
    created_entries = response.json()
    print(f"Added {len(created_entries)} entries")
    for entry in created_entries:
        print(f"  {entry['company_name']} (ID: {entry['id']})")
else:
    print(f"Error {response.status_code}: {response.json()}")

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

const entries = {
  entries: [
    {
      company_name: "Acme Corp",
      website_url: "https://www.acme-corp.com",
      city: "Berlin",
      country: "Germany",
      external_id: "CRM-5001",
      reason: "Existing customer",
    },
    {
      company_name: "Global Industries GmbH",
      city: "Munich",
      country: "Germany",
      reason: "Competitor",
    },
    {
      company_name: "TechStart AG",
      website_url: "https://techstart.de",
      external_id: "CRM-5003",
    },
  ],
};

const response = await fetch(
  `${BASE_URL}/blacklists/${blacklistId}/entries`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(entries),
  }
);

if (response.status === 201) {
  const createdEntries = await response.json();
  console.log(`Added ${createdEntries.length} entries`);
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

interface BlacklistEntryResponse {
  id: string;
  company_name: string;
  website_url: string | null;
  city: string | null;
  country: string | null;
  external_id: string | null;
  reason: string | null;
  created_at: string;
}

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

const entries = {
  entries: [
    {
      company_name: "Acme Corp",
      website_url: "https://www.acme-corp.com",
      city: "Berlin",
      country: "Germany",
      external_id: "CRM-5001",
      reason: "Existing customer",
    },
    {
      company_name: "Global Industries GmbH",
      city: "Munich",
      country: "Germany",
      reason: "Competitor",
    },
    {
      company_name: "TechStart AG",
      website_url: "https://techstart.de",
      external_id: "CRM-5003",
    },
  ],
};

const response = await fetch(
  `${BASE_URL}/blacklists/${blacklistId}/entries`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(entries),
  }
);

if (response.status === 201) {
  const createdEntries: BlacklistEntryResponse[] = await response.json();
  console.log(`Added ${createdEntries.length} entries`);
  for (const entry of createdEntries) {
    console.log(`  ${entry.company_name} (ID: ${entry.id})`);
  }
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

var blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

var entries = new
{
    entries = new[]
    {
        new
        {
            company_name = "Acme Corp",
            website_url = "https://www.acme-corp.com",
            city = "Berlin",
            country = "Germany",
            external_id = "CRM-5001",
            reason = "Existing customer"
        },
        new
        {
            company_name = "Global Industries GmbH",
            website_url = (string?)null,
            city = "Munich",
            country = "Germany",
            external_id = (string?)null,
            reason = "Competitor"
        },
        new
        {
            company_name = "TechStart AG",
            website_url = "https://techstart.de",
            city = (string?)null,
            country = (string?)null,
            external_id = "CRM-5003",
            reason = (string?)null
        }
    }
};

var json = JsonSerializer.Serialize(entries);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(
    $"{baseUrl}/blacklists/{blacklistId}/entries", content);

if ((int)response.StatusCode == 201)
{
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"Entries added: {body}");
}
else
{
    Console.WriteLine($"Error {(int)response.StatusCode}");
    Console.WriteLine(await response.Content.ReadAsStringAsync());
}

Response (201 Created)¶

The response is a flat array of the created entries:

[
  {
    "id": "37186b8e-08e6-4fa3-938e-6ddcb0da5061",
    "company_name": "Acme Corp",
    "website_url": "https://www.acme-corp.com",
    "city": "Berlin",
    "country": "Germany",
    "external_id": "CRM-5001",
    "reason": "Existing customer",
    "created_at": "2026-03-01T10:35:00.000000Z"
  },
  {
    "id": "c6749d45-0b15-4e53-a827-786fd743558b",
    "company_name": "Global Industries GmbH",
    "website_url": null,
    "city": "Munich",
    "country": "Germany",
    "external_id": null,
    "reason": "Competitor",
    "created_at": "2026-03-01T10:35:00.000000Z"
  },
  {
    "id": "2859943a-8245-44cd-9b45-36493e24b2fb",
    "company_name": "TechStart AG",
    "website_url": "https://techstart.de",
    "city": null,
    "country": null,
    "external_id": "CRM-5003",
    "reason": null,
    "created_at": "2026-03-01T10:35:00.000000Z"
  }
]

Response Format

The add entries response is a flat array of created entries. This differs from the list entries response, which wraps entries in {"entries": [...]}.

Entry Fields¶

Each entry in the entries array accepts these fields:

Field	Type	Required	Max Length	Description
`company_name`	string	Yes	500	Company name
`website_url`	string	No	2,048	Company website URL (must start with `http://`, `https://`, or `www.`)
`city`	string	No	255	City name
`country`	string	No	255	Country name
`external_id`	string	No	255	Your CRM/system ID for this company
`reason`	string	No	2,000	Why this company is blacklisted

Step 3: List and Get Blacklists¶

List All Blacklists¶

GET /api/v1/blacklists

cURLPythonJavaScriptTypeScriptC#

curl -X GET "https://api.openprospect.io/api/v1/blacklists" \
  -H "Authorization: Bearer YOUR_API_KEY"

response = httpx.get(
    f"{BASE_URL}/blacklists",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

data = response.json()
for bl in data["blacklists"]:
    print(f"{bl['name']} ({bl['entry_count']} entries)")

const response = await fetch(`${BASE_URL}/blacklists`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

const data = await response.json();
for (const bl of data.blacklists) {
  console.log(`${bl.name} (${bl.entry_count} entries)`);
}

interface BlacklistListResponse {
  blacklists: BlacklistResponse[];
}

const response = await fetch(`${BASE_URL}/blacklists`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

const data: BlacklistListResponse = await response.json();
for (const bl of data.blacklists) {
  console.log(`${bl.name} (${bl.entry_count} entries)`);
}

var response = await client.GetAsync($"{baseUrl}/blacklists");
var body = await response.Content.ReadAsStringAsync();
var data = JsonSerializer.Deserialize<JsonElement>(body);

foreach (var bl in data.GetProperty("blacklists").EnumerateArray())
{
    Console.WriteLine(
        $"{bl.GetProperty("name")} ({bl.GetProperty("entry_count")} entries)");
}

Response (200 OK)¶

{
  "blacklists": [
    {
      "id": "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
      "name": "Existing Customers",
      "description": "Companies already in our CRM",
      "entry_count": 3,
      "created_at": "2026-03-01T10:30:00.000000Z",
      "updated_at": "2026-03-01T10:35:00.000000Z"
    },
    {
      "id": "27241af2-118b-4e66-b101-716ece38b312",
      "name": "Competitors",
      "description": "Known competitor companies to exclude",
      "entry_count": 12,
      "created_at": "2026-02-15T09:00:00.000000Z",
      "updated_at": "2026-02-28T14:20:00.000000Z"
    }
  ]
}

Get a Single Blacklist¶

GET /api/v1/blacklists/{blacklist_id}

cURLPythonJavaScriptTypeScriptC#

curl -X GET "https://api.openprospect.io/api/v1/blacklists/d33b69ce-80ce-4ede-b4df-4b11427f8b55" \
  -H "Authorization: Bearer YOUR_API_KEY"

blacklist_id = "d33b69ce-80ce-4ede-b4df-4b11427f8b55"

response = httpx.get(
    f"{BASE_URL}/blacklists/{blacklist_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

data = response.json()
print(f"{data['name']}: {data['entry_count']} entries")

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

const response = await fetch(`${BASE_URL}/blacklists/${blacklistId}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

const data = await response.json();
console.log(`${data.name}: ${data.entry_count} entries`);

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

const response = await fetch(`${BASE_URL}/blacklists/${blacklistId}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

const data: BlacklistResponse = await response.json();
console.log(`${data.name}: ${data.entry_count} entries`);

var blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

var response = await client.GetAsync($"{baseUrl}/blacklists/{blacklistId}");
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

Response (200 OK)¶

{
  "id": "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
  "name": "Existing Customers",
  "description": "Companies already in our CRM",
  "entry_count": 3,
  "created_at": "2026-03-01T10:30:00.000000Z",
  "updated_at": "2026-03-01T10:35:00.000000Z"
}

Step 4: List Entries (Paginated)¶

Browse the entries within a blacklist. Results are paginated.

Request¶

GET /api/v1/blacklists/{blacklist_id}/entries

cURLPythonJavaScriptTypeScriptC#

curl -X GET "https://api.openprospect.io/api/v1/blacklists/d33b69ce-80ce-4ede-b4df-4b11427f8b55/entries?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

blacklist_id = "d33b69ce-80ce-4ede-b4df-4b11427f8b55"
all_entries = []
offset = 0
limit = 50

while True:
    response = httpx.get(
        f"{BASE_URL}/blacklists/{blacklist_id}/entries",
        params={"limit": limit, "offset": offset},
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    data = response.json()

    for entry in data["entries"]:
        print(f"  {entry['company_name']} ({entry['external_id'] or 'no ID'})")
        all_entries.append(entry)

    if offset + limit >= data["total"]:
        break
    offset += limit

print(f"\nTotal entries: {len(all_entries)}")

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";
const allEntries = [];
let offset = 0;
const limit = 50;

while (true) {
  const response = await fetch(
    `${BASE_URL}/blacklists/${blacklistId}/entries?limit=${limit}&offset=${offset}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const data = await response.json();

  for (const entry of data.entries) {
    console.log(`  ${entry.company_name} (${entry.external_id || "no ID"})`);
    allEntries.push(entry);
  }

  if (offset + limit >= data.total) break;
  offset += limit;
}

console.log(`\nTotal entries: ${allEntries.length}`);

interface EntryListResponse {
  entries: BlacklistEntryResponse[];
  total: number;
  limit: number;
  offset: number;
}

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";
const allEntries: BlacklistEntryResponse[] = [];
let offset = 0;
const limit = 50;

while (true) {
  const response = await fetch(
    `${BASE_URL}/blacklists/${blacklistId}/entries?limit=${limit}&offset=${offset}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const data: EntryListResponse = await response.json();
  allEntries.push(...data.entries);

  if (offset + limit >= data.total) break;
  offset += limit;
}

console.log(`Total entries: ${allEntries.length}`);

var blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";
var offset = 0;
var limit = 50;
var allEntries = new List<JsonElement>();

while (true)
{
    var response = await client.GetAsync(
        $"{baseUrl}/blacklists/{blacklistId}/entries?limit={limit}&offset={offset}");
    var body = await response.Content.ReadAsStringAsync();
    var data = JsonSerializer.Deserialize<JsonElement>(body);

    foreach (var entry in data.GetProperty("entries").EnumerateArray())
    {
        Console.WriteLine($"  {entry.GetProperty("company_name")}");
        allEntries.Add(entry);
    }

    var total = data.GetProperty("total").GetInt32();
    if (offset + limit >= total) break;
    offset += limit;
}

Console.WriteLine($"\nTotal entries: {allEntries.Count}");

Response (200 OK)¶

{
  "entries": [
    {
      "id": "37186b8e-08e6-4fa3-938e-6ddcb0da5061",
      "company_name": "Acme Corp",
      "website_url": "https://www.acme-corp.com",
      "city": "Berlin",
      "country": "Germany",
      "external_id": "CRM-5001",
      "reason": "Existing customer",
      "created_at": "2026-03-01T10:35:00.000000Z"
    },
    {
      "id": "c6749d45-0b15-4e53-a827-786fd743558b",
      "company_name": "Global Industries GmbH",
      "website_url": null,
      "city": "Munich",
      "country": "Germany",
      "external_id": null,
      "reason": "Competitor",
      "created_at": "2026-03-01T10:35:00.000000Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

Pagination¶

Parameter	Default	Range	Description
`limit`	50	1-200	Entries per page
`offset`	0	0+	Number of entries to skip

The response includes total for the full count. Calculate whether more pages exist: offset + limit < total.

Step 5: Update a Blacklist¶

Update the name and/or description of a blacklist. This is a partial update (PATCH) \u2014 only provided fields are changed.

Request¶

PATCH /api/v1/blacklists/{blacklist_id}

cURLPythonJavaScriptTypeScriptC#

curl -X PATCH "https://api.openprospect.io/api/v1/blacklists/d33b69ce-80ce-4ede-b4df-4b11427f8b55" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Existing Customers Q1 2026"}'

blacklist_id = "d33b69ce-80ce-4ede-b4df-4b11427f8b55"

response = httpx.patch(
    f"{BASE_URL}/blacklists/{blacklist_id}",
    json={"name": "Existing Customers Q1 2026"},
    headers={"Authorization": f"Bearer {API_KEY}"},
)

if response.status_code == 200:
    data = response.json()
    print(f"Updated: {data['name']}")
else:
    print(f"Error {response.status_code}: {response.json()}")

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

const response = await fetch(`${BASE_URL}/blacklists/${blacklistId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Existing Customers Q1 2026" }),
});

if (response.status === 200) {
  const data = await response.json();
  console.log(`Updated: ${data.name}`);
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

const response = await fetch(`${BASE_URL}/blacklists/${blacklistId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Existing Customers Q1 2026" }),
});

if (response.status === 200) {
  const data: BlacklistResponse = await response.json();
  console.log(`Updated: ${data.name}`);
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

var blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

var update = new { name = "Existing Customers Q1 2026" };
var json = JsonSerializer.Serialize(update);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PatchAsync(
    $"{baseUrl}/blacklists/{blacklistId}", content);

if ((int)response.StatusCode == 200)
{
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine($"Updated: {body}");
}
else
{
    Console.WriteLine($"Error {(int)response.StatusCode}");
}

Response (200 OK)¶

{
  "id": "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
  "name": "Existing Customers Q1 2026",
  "description": "Companies already in our CRM",
  "entry_count": 3,
  "created_at": "2026-03-01T10:30:00.000000Z",
  "updated_at": "2026-03-01T10:40:00.000000Z"
}

Update Parameters¶

Parameter	Type	Required	Description
`name`	string	No	New name (1-500 chars). Cannot be set to `null`.
`description`	string	No	New description (max 2,000 chars). Set to `null` to clear.

Omitted fields are left unchanged.

Step 6: Remove Entries¶

Remove specific entries from a blacklist by their IDs. You can remove up to 1,000 entries per request.

Request¶

DELETE /api/v1/blacklists/{blacklist_id}/entries

cURLPythonJavaScriptTypeScriptC#

curl -X DELETE "https://api.openprospect.io/api/v1/blacklists/d33b69ce-80ce-4ede-b4df-4b11427f8b55/entries" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entry_ids": ["c6749d45-0b15-4e53-a827-786fd743558b"]}'

blacklist_id = "d33b69ce-80ce-4ede-b4df-4b11427f8b55"
entry_ids_to_remove = ["c6749d45-0b15-4e53-a827-786fd743558b"]

response = httpx.request(
    "DELETE",
    f"{BASE_URL}/blacklists/{blacklist_id}/entries",
    json={"entry_ids": entry_ids_to_remove},
    headers={"Authorization": f"Bearer {API_KEY}"},
)

if response.status_code == 204:
    print("Entries removed successfully")
else:
    print(f"Error {response.status_code}: {response.json()}")

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";
const entryIdsToRemove = ["c6749d45-0b15-4e53-a827-786fd743558b"];

const response = await fetch(
  `${BASE_URL}/blacklists/${blacklistId}/entries`,
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ entry_ids: entryIdsToRemove }),
  }
);

if (response.status === 204) {
  console.log("Entries removed successfully");
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";
const entryIdsToRemove: string[] = [
  "c6749d45-0b15-4e53-a827-786fd743558b",
];

const response = await fetch(
  `${BASE_URL}/blacklists/${blacklistId}/entries`,
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ entry_ids: entryIdsToRemove }),
  }
);

if (response.status === 204) {
  console.log("Entries removed successfully");
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

var blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

var removeRequest = new
{
    entry_ids = new[] { "c6749d45-0b15-4e53-a827-786fd743558b" }
};

var json = JsonSerializer.Serialize(removeRequest);
var request = new HttpRequestMessage(HttpMethod.Delete,
    $"{baseUrl}/blacklists/{blacklistId}/entries")
{
    Content = new StringContent(json, Encoding.UTF8, "application/json")
};
var response = await client.SendAsync(request);

if ((int)response.StatusCode == 204)
{
    Console.WriteLine("Entries removed successfully");
}
else
{
    Console.WriteLine($"Error {(int)response.StatusCode}");
}

Response¶

204 No Content \u2014 empty body on success.

Request Body¶

Field	Type	Required	Description
`entry_ids`	UUID[]	Yes	1 to 1,000 entry IDs to remove

Finding Entry IDs

Use the List Entries endpoint to get the id of each entry you want to remove.

Step 7: Delete a Blacklist¶

Delete an entire blacklist and all its entries. This also removes the blacklist from any prospect search assignments.

Request¶

DELETE /api/v1/blacklists/{blacklist_id}

cURLPythonJavaScriptTypeScriptC#

curl -X DELETE "https://api.openprospect.io/api/v1/blacklists/d33b69ce-80ce-4ede-b4df-4b11427f8b55" \
  -H "Authorization: Bearer YOUR_API_KEY"

blacklist_id = "d33b69ce-80ce-4ede-b4df-4b11427f8b55"

response = httpx.delete(
    f"{BASE_URL}/blacklists/{blacklist_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

if response.status_code == 204:
    print("Blacklist deleted")
else:
    print(f"Error {response.status_code}: {response.json()}")

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

const response = await fetch(`${BASE_URL}/blacklists/${blacklistId}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (response.status === 204) {
  console.log("Blacklist deleted");
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

const blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

const response = await fetch(`${BASE_URL}/blacklists/${blacklistId}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (response.status === 204) {
  console.log("Blacklist deleted");
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

var blacklistId = "d33b69ce-80ce-4ede-b4df-4b11427f8b55";

var response = await client.DeleteAsync(
    $"{baseUrl}/blacklists/{blacklistId}");

if ((int)response.StatusCode == 204)
{
    Console.WriteLine("Blacklist deleted");
}
else
{
    Console.WriteLine($"Error {(int)response.StatusCode}");
}

Response¶

204 No Content \u2014 empty body on success.

Cascade Delete

Deleting a blacklist permanently removes all entries in the blacklist and all prospect search assignments. This cannot be undone.

Step 8: Assign Blacklists to a Prospect Search¶

Assign one or more blacklists to a prospect search. When assigned, matching companies are excluded from the prospect search results.

This is an atomic replace-all operation \u2014 the provided list replaces any previous assignments.

Request¶

PUT /api/v1/prospect-searches/{prospect_search_id}/blacklists

cURLPythonJavaScriptTypeScriptC#

curl -X PUT "https://api.openprospect.io/api/v1/prospect-searches/2d173914-2d33-4def-acc9-0ace8e4ce895/blacklists" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blacklist_ids": [
      "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
      "27241af2-118b-4e66-b101-716ece38b312"
    ]
  }'

prospect_search_id = "2d173914-2d33-4def-acc9-0ace8e4ce895"

response = httpx.put(
    f"{BASE_URL}/prospect-searches/{prospect_search_id}/blacklists",
    json={
        "blacklist_ids": [
            "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
            "27241af2-118b-4e66-b101-716ece38b312",
        ]
    },
    headers={"Authorization": f"Bearer {API_KEY}"},
)

if response.status_code == 204:
    print("Blacklists assigned")
else:
    print(f"Error {response.status_code}: {response.json()}")

const prospectSearchId = "2d173914-2d33-4def-acc9-0ace8e4ce895";

const response = await fetch(
  `${BASE_URL}/prospect-searches/${prospectSearchId}/blacklists`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      blacklist_ids: [
        "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
        "27241af2-118b-4e66-b101-716ece38b312",
      ],
    }),
  }
);

if (response.status === 204) {
  console.log("Blacklists assigned");
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

const prospectSearchId = "2d173914-2d33-4def-acc9-0ace8e4ce895";

const response = await fetch(
  `${BASE_URL}/prospect-searches/${prospectSearchId}/blacklists`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      blacklist_ids: [
        "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
        "27241af2-118b-4e66-b101-716ece38b312",
      ],
    }),
  }
);

if (response.status === 204) {
  console.log("Blacklists assigned");
} else {
  console.error(`Error ${response.status}:`, await response.json());
}

var prospectSearchId = "2d173914-2d33-4def-acc9-0ace8e4ce895";

var assignRequest = new
{
    blacklist_ids = new[]
    {
        "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
        "27241af2-118b-4e66-b101-716ece38b312"
    }
};

var json = JsonSerializer.Serialize(assignRequest);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PutAsync(
    $"{baseUrl}/prospect-searches/{prospectSearchId}/blacklists", content);

if ((int)response.StatusCode == 204)
{
    Console.WriteLine("Blacklists assigned");
}
else
{
    Console.WriteLine($"Error {(int)response.StatusCode}");
}

Response¶

204 No Content \u2014 empty body on success.

Request Body¶

Field	Type	Required	Description
`blacklist_ids`	UUID[]	Yes	Blacklist IDs to assign (max 100). Duplicates are automatically removed. Send an empty array `[]` to unassign all blacklists.

Replace-All Semantics

This endpoint replaces the full list of assigned blacklists. To add a blacklist without removing existing ones, first list the current assignments, append the new ID, then send the full list.

Step 9: List Assigned Blacklists¶

See which blacklists are currently assigned to a prospect search.

Request¶

GET /api/v1/prospect-searches/{prospect_search_id}/blacklists

cURLPythonJavaScriptTypeScriptC#

curl -X GET "https://api.openprospect.io/api/v1/prospect-searches/2d173914-2d33-4def-acc9-0ace8e4ce895/blacklists" \
  -H "Authorization: Bearer YOUR_API_KEY"

prospect_search_id = "2d173914-2d33-4def-acc9-0ace8e4ce895"

response = httpx.get(
    f"{BASE_URL}/prospect-searches/{prospect_search_id}/blacklists",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

data = response.json()
for bl in data["blacklists"]:
    print(f"  {bl['name']} ({bl['entry_count']} entries)")

const prospectSearchId = "2d173914-2d33-4def-acc9-0ace8e4ce895";

const response = await fetch(
  `${BASE_URL}/prospect-searches/${prospectSearchId}/blacklists`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

const data = await response.json();
for (const bl of data.blacklists) {
  console.log(`  ${bl.name} (${bl.entry_count} entries)`);
}

const prospectSearchId = "2d173914-2d33-4def-acc9-0ace8e4ce895";

const response = await fetch(
  `${BASE_URL}/prospect-searches/${prospectSearchId}/blacklists`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

const data: BlacklistListResponse = await response.json();
for (const bl of data.blacklists) {
  console.log(`  ${bl.name} (${bl.entry_count} entries)`);
}

var prospectSearchId = "2d173914-2d33-4def-acc9-0ace8e4ce895";

var response = await client.GetAsync(
    $"{baseUrl}/prospect-searches/{prospectSearchId}/blacklists");
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

Response (200 OK)¶

{
  "blacklists": [
    {
      "id": "d33b69ce-80ce-4ede-b4df-4b11427f8b55",
      "name": "Existing Customers",
      "description": "Companies already in our CRM",
      "entry_count": 3,
      "created_at": "2026-03-01T10:30:00.000000Z",
      "updated_at": "2026-03-01T10:35:00.000000Z"
    },
    {
      "id": "27241af2-118b-4e66-b101-716ece38b312",
      "name": "Competitors",
      "description": "Known competitor companies to exclude",
      "entry_count": 12,
      "created_at": "2026-02-15T09:00:00.000000Z",
      "updated_at": "2026-02-28T14:20:00.000000Z"
    }
  ]
}

Returns an empty array when no blacklists are assigned: {"blacklists": []}.

Using Blacklists with Discovery Orders¶

You can also attach blacklists when creating a discovery order. Include blacklist_ids in the order request:

{
  "order_type": "DISCOVERY",
  "title": "DACH SaaS Discovery",
  "features": ["COMPANY_DATA", "CONTACTS", "ANALYSIS"],
  "ideal_customer_profile": "Mid-market SaaS companies in the DACH region",
  "seller_offering": "AI-powered lead generation platform",
  "target_countries": ["Germany", "Austria", "Switzerland"],
  "blacklist_ids": ["d33b69ce-80ce-4ede-b4df-4b11427f8b55"]
}

For the full discovery order workflow, see the Discovery Order Guide.

Error Handling¶

Authentication Error (401)¶

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or expired API key",
  "request_id": "abc123-def456"
}

Cause: Invalid API key, expired key, or missing Authorization header.

Resolution: Verify your API key in the OpenProspect dashboard. Ensure the header format is Authorization: Bearer lnc_live_....

Insufficient Permissions (403)¶

{
  "code": "AUTHORIZATION_ERROR",
  "message": "Insufficient permissions. Required scopes: blacklists:write",
  "required_scopes": ["blacklists:write"],
  "user_scopes": ["orders:read", "orders:write"]
}

Cause: Your API key is missing required scopes.

Resolution: Create a new API key with blacklists:read and blacklists:write scopes in the dashboard under Settings > Developer > API Keys.

Blacklist Not Found (404)¶

{
  "code": "BLACKLIST_NOT_FOUND",
  "message": "Blacklist with identifier 00000000-0000-0000-0000-000000000000 not found",
  "resource_type": "Blacklist",
  "identifier": "00000000-0000-0000-0000-000000000000",
  "blacklist_id": "00000000-0000-0000-0000-000000000000"
}

Cause: The blacklist ID does not exist or belongs to a different organization.

Resolution: Verify the id from the create blacklist response or list your blacklists to find valid IDs.

Validation Errors (422)¶

Common validation errors:

Error	Cause	Fix
`name` too short	Empty name string	Provide a name with at least 1 character
`entries` too short	Empty entries array	Provide at least 1 entry
`entry_ids` too short	Empty entry_ids array	Provide at least 1 entry ID
Invalid `website_url`	URL missing protocol	Use `http://`, `https://`, or `www.` prefix
`name` cannot be null	PATCH with `name: null`	Omit the field to leave it unchanged

For the full error reference, see Error Codes.

API Reference Summary¶

Method	Path	Scope	Description
`POST`	`/api/v1/blacklists`	`blacklists:write`	Create a blacklist (201)
`GET`	`/api/v1/blacklists`	`blacklists:read`	List all blacklists
`GET`	`/api/v1/blacklists/{blacklist_id}`	`blacklists:read`	Get a blacklist
`PATCH`	`/api/v1/blacklists/{blacklist_id}`	`blacklists:write`	Update name/description
`DELETE`	`/api/v1/blacklists/{blacklist_id}`	`blacklists:write`	Delete blacklist + entries (204)
`POST`	`/api/v1/blacklists/{blacklist_id}/entries`	`blacklists:write`	Add entries in bulk (201)
`GET`	`/api/v1/blacklists/{blacklist_id}/entries`	`blacklists:read`	List entries (paginated)
`DELETE`	`/api/v1/blacklists/{blacklist_id}/entries`	`blacklists:write`	Remove entries by ID (204)
`GET`	`/api/v1/prospect-searches/{id}/blacklists`	`blacklists:read`	List assigned blacklists
`PUT`	`/api/v1/prospect-searches/{id}/blacklists`	`blacklists:write`	Set assigned blacklists (204)