Documentation / Getting Started / Your First API Call
Your First API Call
Check your daily usage, list your campaigns, and search the News Index, with a sample response for each call.
Before you start
- Get a token: Create an API Token.
- Send every call as a
POSTwith a JSON body tohttps://api.oppalerts.com/v1/. - Send the token in the header
Authorization: Bearer YOUR_TOKEN.
1. Check your daily counts
This call does not use an index search. It shows how many calls your account has left today.
curl -X POST https://api.oppalerts.com/v1/account/calls_left \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
The sample response below includes the unlimited field, which
appears only for an administrator.
{
"resets_at": "2026-11-07T09:00:00Z",
"index_searches": {
"used": 3,
"limit": 10,
"left": 7,
"tools": [
"news_search",
"prospects_search",
"news_brand_mentions"
]
},
"tools": {
"account_calls_left": {
"used": 2,
"limit": 100,
"left": 98
},
"backlinks": {
"used": 0,
"limit": 10,
"left": 10
},
"campaigns_dashboard": {
"used": 4,
"limit": 100,
"left": 96
}
},
"unlimited": true
}
2. List your campaigns
Most tools need a campaign ID. This call returns the ID of each campaign.
curl -X POST https://api.oppalerts.com/v1/campaigns/list \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
{
"campaigns": [
{
"id": 3,
"label": "Hotels",
"state": "active",
"finalized": true,
"research": "finished"
},
{
"id": 4,
"label": "Fitness Clubs",
"state": "active",
"finalized": false,
"research": "not_started"
}
]
}
finalizedistruewhen the campaign's research has started.researchshows the research progress.
3. Search the News Index by semantic similarity
This call is an index search. It finds news pages in your campaign's
market that are semantically similar to similarity_text.
curl -X POST https://api.oppalerts.com/v1/news/search \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"campaign": 3, "similarity_target": "similarity_text", "similarity_text": "Boutique hotels winning direct bookings from younger travelers in mid-size US cities.", "published_from": "2026-08-01", "pr_domain_min": 20, "type_scores": [{"opportunity_type": "advertising/newsletter-ads", "type_score_min": 50}], "sort": "best", "results_limit": 100}'
The full sample response:
{
"total_matches": 1240,
"returned": 100,
"results": [
{
"id": "1152921504611003120",
"url": "https://cityguide-example.org/advertise/media-kit",
"host": "cityguide-example.org",
"document_type": "page",
"published_at": "2026-05-10T00:00:00Z",
"indexed_at": "2026-08-17T21:00:00Z",
"pr_host": 39,
"prot_host": 678,
"pr_domain": 61,
"prot_domain": 861,
"similarity_score": 46.8,
"relevance_weight": 1247.0,
"org": {
"relationship": "org_publisher"
},
"page": {
"title": "Advertise with City Guide: media kit",
"snippet": "Reach 400,000 monthly readers planning weekend trips. Sponsorship and hotel placements available.",
"link_counts": {
"article": {
"follow": 12,
"nofollow": 3,
"sponsored": 2,
"ugc": 0
},
"nav": {
"follow": 34,
"nofollow": 0,
"sponsored": 0,
"ugc": 0
},
"comments": {
"follow": 0,
"nofollow": 0,
"sponsored": 0,
"ugc": 0
}
},
"meta": {
"favicon": "https://cityguide-example.org/favicon-32.png",
"feeds": [
"https://cityguide-example.org/feed"
],
"contact": [
"https://cityguide-example.org/contact"
]
},
"sections": {
"article": {
"links": [
{
"url": "https://grand-resorts.example/awards",
"text": "Grand Resorts",
"title": "",
"rel": [
"nofollow"
],
"org": {
"relationship": "org_competitor"
}
}
],
"emails": [
"press@cityguide-example.org"
],
"phones": [
"+1 555 0100"
],
"service_accounts": [
{
"service": "linkedin",
"username": "cityguide",
"label": "City Guide",
"url": "https://linkedin.com/company/cityguide"
}
]
},
"nav": {
"links": [
{
"url": "https://partner-example.com/",
"text": "Our partner",
"title": "Partner",
"rel": [
"sponsored"
],
"org": {
"relationship": "org_partner"
}
}
],
"emails": [
"hello@cityguide-example.org"
],
"phones": [
"+1 555 0101"
],
"service_accounts": [
{
"service": "twitter",
"username": "cityguide",
"label": "",
"url": "https://x.com/cityguide"
}
]
},
"comments": {
"links": [
{
"url": "https://reader-blog-example.net/trip-notes",
"text": "my trip notes",
"title": "",
"rel": [
"ugc"
],
"org": {
"relationship": "org_partner"
}
}
],
"emails": [
"comments@cityguide-example.org"
],
"phones": [
"+1 555 0102"
],
"service_accounts": [
{
"service": "reddit",
"username": "cityguide",
"label": "",
"url": "https://reddit.com/u/cityguide"
}
]
}
}
}
}
],
"contacts": {
"accounts": {
"head": {
"facebook": [
{
"username": "cityguide",
"url": "https://www.facebook.com/cityguide",
"type": "page",
"count": 14,
"nsfw": false
}
],
"x": [
{
"username": "cityguide",
"url": "https://x.com/cityguide",
"type": "user",
"count": 21,
"nsfw": false
},
{
"username": "cityguidedeals",
"url": "https://x.com/cityguidedeals",
"type": "user",
"count": 3,
"nsfw": false
}
]
},
"nav": {
"instagram": [
{
"username": "cityguide",
"url": "https://www.instagram.com/cityguide",
"type": "user",
"count": 18,
"nsfw": false
}
],
"x": [
{
"username": "cityguide",
"url": "https://x.com/cityguide",
"type": "user",
"count": 17,
"nsfw": false
}
]
},
"article": {
"linkedin": [
{
"username": "grand-resorts",
"url": "https://www.linkedin.com/company/grand-resorts",
"type": "page",
"count": 6,
"nsfw": false
}
],
"youtube": [
{
"username": "boutiquestays",
"url": "https://www.youtube.com/@boutiquestays",
"type": "channel",
"count": 4,
"nsfw": false
}
]
},
"comments": {
"onlyfans": [
{
"username": "examplecreator",
"url": "https://onlyfans.com/examplecreator",
"type": "user",
"count": 1,
"nsfw": true
}
],
"reddit": [
{
"username": "tripnotes",
"url": "https://www.reddit.com/user/tripnotes",
"type": "user",
"count": 2,
"nsfw": false
}
]
}
},
"emails": [
{
"email": "press@cityguide-example.org",
"count": 9
},
{
"email": "hello@cityguide-example.org",
"count": 4
}
],
"phones": [
{
"phone": "+1 555 0100",
"count": 7
},
{
"phone": "+1 555 0101",
"count": 2
}
]
}
}
Search Results explains each field.
Next
- Each tool has its own API page, with every parameter and a full sample response. The docs home page lists them all.
- Each tool has two routes. For example,
POST /v1/news/searchandPOST /v1/news_searchcall the same tool. - Authentication and Limits lists the errors and the limits.