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

A list is a hard exclusion. A company that matches a list in force is not admitted into a search, is not worked on by any pipeline stage, and is not delivered, published in an order result, or written to by a campaign. Nothing overrides that, including a forced re-run.

Scope¶

Each list has a scope:

Scope	Where it applies
`organization`	Every search, order and campaign of the organization. This is the default for a new list.
`attached`	Only the searches, orders and campaigns the list is attached to.

A list is in force for a search when its scope is organization and it belongs to that search's organization, or when it is attached to the search. A campaign also honors organization-scope lists of its organization, lists attached to the campaign, the campaign's own hand-pick list, and lists attached to a search that feeds the campaign.

external_id is stored for a later CRM sync. It is not used for matching.

How matching works¶

Priority	Match	When
1	Registrable domain	The entry has a website. `werk.beispiel-bau.example` covers `beispiel-bau.example`. On a social, directory or search-engine site the page itself is matched: `facebook.com/baeckerei-mueller` covers that page, not every Facebook page.
2	Normalized name and city	The entry has no website. Cities are compared case-insensitively. A blank city is absent, and both sides absent is a match. A name-only entry does not match a company that has a city.

Best Practice

Always provide website_url when you have it. Domain matching is the reliable tier.

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.example",
        "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.example",
        "external_id": "CRM-5003"
      }
    ]
  }'

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

entries = {
    "entries": [
        {
            "company_name": "Acme Corp",
            "website_url": "https://www.acme-corp.example",
            "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.example",
            "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.example",
      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.example",
      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.example",
      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.example",
      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.example",
            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.example",
            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.example",
    "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.example",
    "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)");
}

Single Blacklist 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.example",
      "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 Profiles¶

Discovery orders reference an existing search profile. Assign blacklists to the profile before you place the order:

curl -sS -X PUT \
  "https://api.openprospect.io/api/v1/prospect-searches/${PROFILE_ID}/blacklists" \
  -H "Authorization: Bearer ${OPENPROSPECT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"blacklist_ids": ["d33b69ce-80ce-4ede-b4df-4b11427f8b55"]}'

For the full profile-first discovery 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)