Skip to main content
POST
/
v1
/
social
/
mapping
curl -X POST https://api.trigify.io/v1/social/mapping \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engaged_with_keywords": ["ai infrastructure", "model serving"],
    "engaged_with_topic_strength": 2,
    "engaged_with_days": 14,
    "job_titles": ["CTO", "VP Engineering", "Head of Data"],
    "job_titles_excludes": ["Consultant"],
    "company_domain_includes": ["northstarcloud.com", "lighthousedata.io"],
    "company_sizes": ["51-200", "201-500"],
    "industries": ["Computer Software", "Information Technology"],
    "location_country": ["United States", "Canada"],
    "page": 1,
    "page_size": 10,
    "includes": [
      "first_name",
      "last_name",
      "linkedin_url",
      "company",
      "job_title",
      "post.text",
      "post.url",
      "engagement.type"
    ]
  }'

{
  "message": "<string>",
  "success": true,
  "data": {
    "results": [
      {
        "post": {
          "text": "<string>",
          "url": "<string>",
          "date": "<string>",
          "likes": 123,
          "comments": 123
        },
        "engagement": {
          "type": "like"
        },
        "first_name": "<string>",
        "last_name": "<string>",
        "linkedin_url": "<string>",
        "avatar": "<string>",
        "location": "<string>",
        "company": "<string>",
        "company_domain": "<string>",
        "job_title": "<string>"
      }
    ],
    "page": 123,
    "total": 123
  }
}
Use this endpoint to query Trigify’s Social Mapping engagement graph for professionals who have engaged with the topics your organisation monitors.
Enterprise-only endpoint. Contact us at [email protected] to discuss access.
Social Mapping spends credits based on the number of returned results. The response includes the spend in the x-spent-credits header.

​
Relationship To Social Topics Monitoring

Social Mapping is a query layer over engagement data that Trigify has already collected. The underlying engagement corpus is continuously refreshed by the Social Topics monitoring cadence:
  • immediate discovery and initial hydration when a topic search is created
  • daily topic rediscovery at 06:00 UTC for active searches
  • follow-up engagement scrapes for tracked posts on Day 1, Day 3, and Day 5
  • a due-post scheduler that runs every 5 minutes
If you need broader or fresher coverage, create or expand the Social Topics searches feeding the engagement graph.

​
Authentication And Permissions

  • Send your API key in x-api-key
  • Required permission: social:mapping:read
  • Required plan: ENTERPRISE or CUSTOM
curl -X POST https://api.trigify.io/v1/social/mapping \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engaged_with_keywords": ["ai infrastructure", "model serving"],
    "engaged_with_topic_strength": 2,
    "engaged_with_days": 14,
    "job_titles": ["CTO", "VP Engineering", "Head of Data"],
    "job_titles_excludes": ["Consultant"],
    "company_domain_includes": ["northstarcloud.com", "lighthousedata.io"],
    "company_sizes": ["51-200", "201-500"],
    "industries": ["Computer Software", "Information Technology"],
    "location_country": ["United States", "Canada"],
    "page": 1,
    "page_size": 10,
    "includes": [
      "first_name",
      "last_name",
      "linkedin_url",
      "company",
      "job_title",
      "post.text",
      "post.url",
      "engagement.type"
    ]
  }'

​
Request Parameters

ParameterRequiredDescription
engaged_with_keywordsYesTopic keywords the returned people engaged with
engaged_with_topic_strengthNoMinimum engagement strength, 0–5. Defaults to 1
engaged_with_daysYesLookback window in days, minimum 1, maximum 30
job_titlesNoJob titles to include
job_titles_excludesNoJob titles to exclude
company_domain_includesNoCompany domains to include (e.g. ["example.com"])
company_domain_excludesNoCompany domains to exclude
company_sizesNoCompany size buckets to include. Values: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+
company_sizes_excludesNoCompany size buckets to exclude. Same values as company_sizes
industriesNoIndustries to include (e.g. ["Computer Software"])
industries_excludesNoIndustries to exclude
location_countryNoCountries to include (e.g. ["United States"])
location_excludesNoLocations to exclude
followersNoFollower count ranges to filter by
pageNoPage number, minimum 1. Defaults to 1
page_sizeNoResults per page. One of: 10, 25, 50. Defaults to 10
includesNoFields to include in the response to keep payloads smaller. See Available Fields below

​
Available includes Fields

FieldDescription
first_nameProspect’s first name
last_nameProspect’s last name
linkedin_urlLinkedIn profile URL
avatarProfile picture URL
locationLocation
companyCompany name
company_domainCompany domain
job_titleJob title
followersFollower count
post.textText of the engaged post
post.urlURL of the engaged post
post.dateDate of the engaged post
post.likesLike count of the post
post.commentsComment count of the post
engagement.typeType of engagement (like or comment)

​
Example Response

{
  "success": true,
  "message": "Successfully retrieved results",
  "data": {
    "results": [
      {
        "first_name": "Jordan",
        "last_name": "Lee",
        "linkedin_url": "https://www.linkedin.com/in/jordan-lee",
        "company": "Northstar Cloud",
        "job_title": "VP of Engineering",
        "post": {
          "text": "We are reassessing our inference stack and vector storage approach.",
          "url": "https://www.linkedin.com/feed/update/urn:li:activity:7356241888074958848/"
        },
        "engagement": {
          "type": "comment"
        }
      }
    ],
    "page": 1,
    "total": 37
  }
}

​
Credit Usage

  • Social Mapping is metered separately from Social Topics monitoring
  • credits spent equal the number of returned results
  • the API returns the spend in the x-spent-credits response header
  • broad queries can fail with 422 if they exceed query limits; narrow them with fewer keywords, a shorter time window, or more firmographic filters

Headers

​
x-api-key
string

Body

application/json
​
engaged_with_keywords
string[]
required

Keywords that the prospect has engaged with. ex: ['keyword1', 'keyword2']

​
engaged_with_days
number
required

Number of days since engagement, min 1 day, max 30 days

Required range: 1 <= x <= 30
​
job_titles
string[]

List of job titles to include in the search. ex: ['Chief Executive Officer']

​
job_titles_excludes
string[]

List of job titles to exclude from the search. ex: ['Chief Executive Officer']

​
engaged_with_topic_strength
number
default:1

Strength of engagement with the specified keywords. 0-5

​
company_domain_includes
string[]

List of company domains to include in the search. ex: ['example.com']

​
company_domain_excludes
string[]

List of company domains to exclude from the search. ex: ['example.com']

​
followers
string[]

List of follower counts to include in the search.

​
location_country
string[]

List of locations to include in the search. ex: ['United States']

​
location_excludes
string[]

List of locations to exclude from the search. ex: ['United States']

​
industries
string[]

List of industries to include in the search. ex: ['Computer Software']

​
industries_excludes
string[]

List of industries to exclude from the search. ex: ['Computer Software']

​
company_sizes
enum<string>[]

List of company sizes to include in the search

Available options:
1-10,
11-50,
51-200,
201-500,
501-1000,
1001-5000,
5001-10000,
10001+
​
company_sizes_excludes
enum<string>[]

List of company sizes to exclude from the search

Available options:
1-10,
11-50,
51-200,
201-500,
501-1000,
1001-5000,
5001-10000,
10001+
​
page
number
default:1

The page number to retrieve

​
page_size
enum<integer>
default:10

The number of results to return per page

Available options:
10,
25,
50
​
includes
enum<string>[]

List of fields to include in the response

Available options:
first_name,
last_name,
linkedin_url,
avatar,
location,
company,
company_domain,
job_title,
followers,
post.text,
post.url,
post.date,
post.likes,
post.comments,
engagement.type

Response

200 - application/json
​
message
string
required
​
success
boolean
required
​
data
object
required