API Reference
DiscussionsChangelog

Keyword Sets

Create and manage the keyword sets that intent is measured against.

Intent API

Manage keyword sets

Create keyword sets, add and remove keywords and seed URLs, and read them back from your own code. Use the resulting keyword-set IDs to filter Company Intent queries.

Beta 5 endpoints Requires Intent API access No credits deducted
Beta endpoints

The contract may change before general availability

Test integrations against the current schema and review release notes when upgrading production workflows that use these endpoints.

What you can manage

A keyword set is a named collection of keywords that Demandbase monitors for intent signals. These endpoints offer the same keyword-set management as the Demandbase One UI.

Keyword sets

Named collections

Give each set a unique name and mark competitive sets with isCompetitor.

Keywords

Research topics

Add the topics to monitor. Keywords are trimmed and de-duplicated without regard to case.

Seed URLs

Generated keywords

Attach a web page and Demandbase generates up to 100 related keywords from it.

Updates

Incremental changes

Add or remove individual keywords and seed URLs without resending the whole set. Repeating an update is safe.

Reads

Paginated lists

List sets by name, then page through each set's keywords and seed URLs separately.

Intent

Filter intent by set

Pass a keyword set's id in keywordSetIds when you query Company Intent.

Endpoints

All paths are relative to the Intent API production base URL, https://uapi.demandbase.com/data/intent/v1.

Method Path Description
POST /keyword-sets Create a keyword set with its initial keywords and optional seed URLs.
GET /keyword-sets List keyword-set metadata, or read one set with ?id=.
PATCH /keyword-sets/{keywordSetId} Rename a set, change isCompetitor, or add and remove keywords and seed URLs.
GET /keyword-sets/{keywordSetId}/keywords List the keywords in a set, one page at a time.
GET /keyword-sets/{keywordSetId}/seed-urls List the seed URLs in a set, one page at a time.
Not in this version

No get-by-ID, replace, or delete endpoint

Read a single set's metadata with GET /keyword-sets?id=9427. Clear a collection by removing its values with PATCH. To delete a keyword set, use the Demandbase One UI.

↑ Back to top

Quickstart

Create a keyword set, add keywords to it, and use it to filter intent. Request bodies must be JSON.

Step 1

Create a keyword set

Request
curl --request POST \
  --url "https://uapi.demandbase.com/data/intent/v1/keyword-sets" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "name": "Cloud Security Vendors",
    "keywords": ["zero trust", "casb", "sase"]
  }'
Step 2

Save the keyword-set ID

Illustrative response · 201 Created
{
  "id": 9427,
  "name": "Cloud Security Vendors",
  "isCompetitor": false,
  "keywords": [
    { "id": 551201, "keyword": "zero trust", "createdAt": "2026-08-20T09:14:22Z", "updatedAt": "2026-08-20T09:14:22Z" },
    { "id": 551202, "keyword": "casb", "createdAt": "2026-08-20T09:14:22Z", "updatedAt": "2026-08-20T09:14:22Z" },
    { "id": 551203, "keyword": "sase", "createdAt": "2026-08-20T09:14:22Z", "updatedAt": "2026-08-20T09:14:22Z" }
  ],
  "seedUrls": [],
  "createdAt": "2026-08-20T09:14:22Z",
  "updatedAt": "2026-08-20T09:14:22Z"
}
Step 3

Add keywords

Request
curl --request PATCH \
  --url "https://uapi.demandbase.com/data/intent/v1/keyword-sets/9427" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "keywords": { "add": ["microsegmentation", "ztna"] }
  }'
Step 4

Query intent for the set

Company Intent filters
"keywordSetIds": [9427],
"startDate": "2026-07-01",
"endDate": "2026-07-22"
Full representation

Create and update return the whole set

A successful POST returns 201 Created and a successful PATCH returns 200 OK. Both bodies include every keyword and seed URL in the set. keywords and seedUrls are always present and may be empty.

↑ Back to top

Create request

Field Required Description Accepted value
name Yes Keyword-set name, unique within your tenant. 1–255 characters after trimming
keywords Yes Initial keywords. Send an empty array to start with none. Array of 1–255 character strings
isCompetitor No Marks the set as competitive, which changes how keyword recommendations are generated. true or false; default false
seedUrls No Web pages to generate additional keywords from. Array of URLs up to 255 characters
Round trips

Unrecognized properties are ignored

id, createdAt, updatedAt, and unknown properties are ignored rather than rejected, so a keyword set read from this API can be sent back into a create request.

↑ Back to top

Update request

Every property is optional, and any property you omit keeps its stored value. Send at least one.

Field Effect Matching
name Replaces the name. Must stay unique within your tenant
isCompetitor Replaces the flag. Existing keywords are not changed. Not applicable
keywords.add Adds keywords that are not already present. Ignores case
keywords.remove Removes matching keywords. Ignores case
seedUrls.add Attaches seed URLs that are not already attached. Exact match
seedUrls.remove Detaches matching seed URLs. Exact match

Rename a set

Body
"name": "Cloud Security Vendors FY27"

Swap keywords in one request

Body
"keywords": {
  "add": ["ztna"],
  "remove": ["legacy vpn"]
}
Safe to retry

Adding a present value or removing a missing one is a no-op

You can resend the same update after a timeout without reading the set first. The same value cannot appear in both add and remove for one collection.

↑ Back to top

List requests

Keyword-set lists return metadata only. Read each set's keywords and seed URLs through their own endpoints, which page independently.

Parameter Applies to Description Accepted value
id GET /keyword-sets Return one keyword set. Takes precedence over name. Positive integer
name GET /keyword-sets Partial match on the name, ignoring case. String
sortBy GET /keyword-sets Field to sort by. name, createdAt, or updatedAt; default createdAt
sortOrder GET /keyword-sets Sort direction. ASC or DESC; default DESC
page All list endpoints Page number, starting at 1. Returned as pageNo. Positive integer; default 1
perPage All list endpoints Results per page. Returned as pageSize. 1–500; default 25
Not found versus empty

An unknown id returns 404; an unmatched name returns 200

A keyword-set ID that does not exist, or belongs to another tenant, returns 404-106. A name search with no matches, or a page past the last one, returns 200 OK with an empty array.

↑ Back to top

Limits

Counts

Default ceilings

Keyword sets per tenant10
Keywords per set300
Seed URLs per set2
Lengths

Measured after trimming

name1–255 characters
keyword1–255 characters
seedUrlUp to 255 characters
Usage

Configuration, not data

Keyword-set endpoints deduct no credits. Only Company Intent queries are metered.

Adjustable limits

Count limits can be raised for your tenant

The three count limits are defaults. A request that would exceed one is rejected, and the error message states the limit configured for your tenant. Contact Demandbase Support if you need a higher ceiling.

↑ Back to top

Seed URLs generate keywords

Adding a seed URL starts keyword generation while the request waits. Requests that add seed URLs take noticeably longer than other calls.

Generation

Up to 100 keywords per request

The cap applies to the whole request, not to each URL. Keywords the set already holds are skipped, and resending a URL that is already attached does not generate again.

URL format

Stored exactly as sent

The http or https scheme is optional and the host must contain a dot. URLs are trimmed but not otherwise normalized, so https://Example.com/a and https://example.com/a are different seed URLs.

Keyword headroom

Updates need room for 100 generated keywords

A PATCH that adds a seed URL is rejected with 400-249 unless the set has room for 100 more keywords. A POST does not make this check, so a newly created set can hold up to 100 keywords more than the per-set limit. Until you remove enough keywords, updates that add keywords or seed URLs to that set are rejected.

↑ Back to top

Important rules

Write access

Intent API access includes write access

Any API key set with Intent API access can create and change keyword sets, not only read intent data. Review which integrations hold one.

Keywords

Duplicates collapse, ignoring case

Keywords are trimmed, then de-duplicated without regard to case. The first occurrence keeps its casing, so a set may hold fewer keywords than you sent.

Names

Names are case-sensitive

Names are trimmed and must be unique within your tenant. Competitors and competitors count as two different names.

Concurrency

Send one write per set at a time

Concurrent updates that remove keywords or change seed URLs on the same set can overwrite each other. Concurrent creates with the same name can fail with 500 instead of 409-101.

Retries

Re-read before retrying a 500 or 504

A rejected 4xx request changes nothing. A write that fails with 500 or 504 may have been partly applied, so read the set back before you retry.

Validation

Errors are reported one at a time

Only the first validation failure is returned. Fix it and resend to see the next one.

↑ Back to top

Common errors

Status Error How to fix it
400-166 The create request body is missing or is not valid JSON. Send a JSON body with Content-Type: application/json.
400-233 name is missing on create. Include a name.
400-244 The name is blank or longer than 255 characters. Send a name of 1–255 characters after trimming.
400-246 keywords is missing on create. Include keywords. An empty array is allowed.
400-234 A keyword is blank, null, or longer than 255 characters. Send keywords of 1–255 characters after trimming.
400-235 A seed URL is not a valid URL. Use an http or https URL, or a host name that contains a dot.
400-247 isCompetitor is not a boolean on create. Send true or false.
400-236 The keyword-set ID is not a positive integer. Use the numeric id returned by this API.
400-237 The sort field is invalid. Use name, createdAt, or updatedAt.
400-238 The sort order is invalid. Use ASC or DESC.
400-239 page or perPage is out of range. Set page to 1 or more and perPage from 1 through 500.
400-242 An update named no recognized property. Include at least one of name, isCompetitor, keywords, or seedUrls.
400-241 A keywords or seedUrls object asks for no change. Include a non-empty add or remove array, or omit the object.
400-243 The same value appears in both add and remove. Remove the value from one of the two arrays.
400-240 Your tenant already has its maximum number of keyword sets. Delete an unused set in the Demandbase One UI, or contact Demandbase Support.
400-248 The request would exceed the keywords-per-set limit. Remove keywords first, or contact Demandbase Support.
400-245 The request would exceed the seed-URLs-per-set limit. Remove a seed URL first, or contact Demandbase Support.
400-249 The set has no room for the up to 100 keywords a seed URL can generate. Remove keywords to make room, or contact Demandbase Support.
401 Authentication failed. Generate a valid token and send it in the Authorization: Bearer YOUR_ACCESS_TOKEN header.
403-100 The API key does not include Intent API access. Use an API Key Set with permission to access the Intent API.
404-106 The keyword set does not exist in your tenant. Check the ID with GET /keyword-sets.
409-101 Another keyword set already uses this name. Choose a different name. Names are case-sensitive.
↑ Back to top
Related resources

Next steps

Open the interactive endpoint reference, review the beta announcement, or query intent for your keyword sets.

Try creating a keyword set → · Beta API announcement → · Company Intent →

Updated 13 minutes ago

Did this page help you?

Updated 13 minutes ago

Did this page help you?