Request a New Intent Topic

Summary: If the catalog has no topic for a subject, request one. We check the request against the catalog, place it in the taxonomy and publish it, usually within an hour. This page walks through the flow from search to first data. Field-level details are in the Taxonomy API.

search the catalog  ->  POST topic request  ->  poll status  ->  use the topic_id  ->  data builds over 14 days

1. Search the Catalog First

Most requests match a topic we already track. Search before you submit:

curl "https://api.delivr.ai/api/v1/taxonomy/topics?search=data+warehouse&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

If a result covers the subject, use its topic_id and stop here. An existing topic already has data. A new topic starts from zero.


2. Submit the Request

curl -X POST "https://api.delivr.ai/api/v1/taxonomy/topic-requests" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Snowflake Data Cloud",
    "description": "Cloud data warehouse product from Snowflake Inc. Researched by data engineers and analytics leaders who compare warehouse platforms.",
    "type": "B2B"
  }'

name, description and type are required. type is B2B, B2C, B2B2C, B2G or B2E.

A clear request is approved faster:

  • Name one subject. Use the full company or product name, not an abbreviation.
  • Say what it is and who researches it. We must confirm that the subject is a real company, product or subject people research.
  • Say what makes it different. If a broader topic exists, describe what your topic adds.
ResponseMeaningWhat to do
201We created the request.Save topic_id and go to step 3.
200You already requested this name. We treated the call as a resubmission: your latest request with this name now holds the new text and is back in waiting_for_approval.Save topic_id. Check the status with GET, not with a second POST.
409A catalog topic has this exact name, and you have no request with that name.If the body carries existing_topic, use its topic_id. If it does not, the topic with that name is not active, so request a different name.

The 200 match is on the request's current name. If we renamed your request when we approved it, a POST with the name you first sent can create a second request. Keep the topic_id and use it for every status check and update.


3. What We Do With It

  1. Duplicate check. We compare the request with the catalog by name and by subject. A request for a subject we track under another name is matched to that topic.
  2. Classification. We confirm the subject and choose its category and subcategory.
  3. Publish. The topic goes into the catalog and the request becomes approved.

These steps run without a person in most cases. If the topic's place in the catalog is unclear, our taxonomy team reviews it. The request stays waiting_for_approval during the review.

We often rename a topic when we approve it, so the name matches how people search for the subject. requested_name keeps the name you sent.


4. Poll the Status

curl "https://api.delivr.ai/api/v1/taxonomy/topic-requests/TOPIC_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

To check many requests in one call, use GET /api/v1/taxonomy/topic-requests?status=approved.

statusMeaningWhat to do
waiting_for_approvalIn the queue, or in review by our team.Poll again. One check every few minutes is enough.
approvedThe topic is in the catalog.Use topic_id. Show name, which can differ from requested_name.
rejected with existing_topicWe already track this subject.Use existing_topic.topic_id. This is a successful result.
rejected without existing_topicOne of three causes. Another request for the same subject is in review. Or the matched topic is no longer active. Or we could not confirm the subject.Search the catalog again later, because a request in review becomes a topic you can use when we approve it. Resubmit only to correct the request or to describe a more specific subject. To resubmit, use PUT /api/v1/taxonomy/topic-requests/{topic_request_id}, where the ID is the request's topic_id.

A resubmitted request goes back to waiting_for_approval.

If you request topics for your own users, store your user's ID next to the topic_id. The list endpoint returns every request from your organization. Do not send the same name twice to check on it, because a repeated name resubmits the request.


5. When Data Arrives

  • A new topic collects intent from the day we publish it. Research before that day is not added later, so request a topic when you first need it.
  • Intent data is rebuilt once a day. A topic has no people on the day you request it.
  • Counts grow for 14 days. A score adds up 14 days of research, so the first days show fewer people and more low rows. See How to Read Intent Scores.
  • Approval is not a volume promise. A narrow topic stays small if few people research it on the pages we see.

Check the size at no cost with the preview's count. A response with no count means the total is not known yet, not that it is zero:

curl -X POST "https://api.delivr.ai/api/v1/intent/people/preview" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"topic_id": "TOPIC_ID", "min_score": "medium"}'

6. Use the Topic

Pass the topic_id wherever a topic is accepted:


Did this page help you?