Role Lookup

Find a person at a company by job role

POST /v1/people/role

Role Lookup

cURL

curl --request POST \
  --url https://api.gtmapis.com/v1/people/role \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "role": "<string>",
  "company_name": "<string>",
  "enrich_profile": true
}
'

200

{
  "linkedin_url": "<string>",
  "profile": {},
  "found": true,
  "confidence": 123,
  "source_provider": "<string>",
  "credits_charged": 123,
  "cache_hit": true,
  "latency_ms": 123
}

Role Lookup

Find a person at a specific company based on their job role (e.g., “CEO”, “VP of Sales”, “Head of Engineering”).

Endpoint

POST /v1/people/role

Request

role · string · required

The job role to search for (e.g., “CEO”, “VP of Sales”, “CTO”)

company_name · string · required

Company name to search within

enrich_profile · boolean · default: "false"

If true, returns full profile data (adds 1 credit)

Example Request

cURL

curl -X POST https://api.gtmapis.com/v1/people/role \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_your_key_here" \
  -d '{
    "role": "VP of Sales",
    "company_name": "Acme Inc",
    "enrich_profile": true
  }'

Response

linkedin_url · string

The person’s LinkedIn profile URL

profile · object

Full profile data (only if enrich_profile: true). See Profile Enrichment for fields.

found · boolean

Whether a matching person was found

confidence · integer

Overall confidence score (0-100)

source_provider · string

Data provider that returned the result

credits_charged · integer

Credits charged for this request

cache_hit · boolean

Whether result was served from cache

latency_ms · integer

Request time in milliseconds

Success Response

{
  "linkedin_url": "https://linkedin.com/in/janedoe",
  "profile": {
    "first_name": "Jane",
    "last_name": "Doe",
    "full_name": "Jane Doe",
    "title": "VP of Sales",
    "company": "Acme Inc",
    "company_domain": "acme.com",
    "linkedin_url": "https://linkedin.com/in/janedoe",
    "location": "New York, NY",
    "seniority": "VP",
    "department": "Sales"
  },
  "found": true,
  "confidence": 88,
  "source_provider": "leadmagic",
  "credits_charged": 4,
  "cache_hit": false,
  "latency_ms": 523
}

Not Found Response

{
  "linkedin_url": "",
  "found": false,
  "confidence": 0,
  "credits_charged": 0,
  "cache_hit": false,
  "latency_ms": 312,
  "error": "No matching person found for role"
}

Credit Pricing

Result	Credits Charged
Person found by role	3 credits
Person found + profile enrichment	4 credits
Not found	0 credits
Error / failure	0 credits

Role lookup costs more than person lookup because it searches across the entire company, not just a specific person.

Common Roles

The API understands common job role variations:

Search Term	Also Matches
CEO	Chief Executive Officer, Founder & CEO
VP of Sales	Vice President of Sales, VP Sales, Head of Sales
CTO	Chief Technology Officer, VP Engineering
CFO	Chief Financial Officer, VP Finance
Head of Marketing	VP Marketing, CMO, Marketing Director
HR Manager	Human Resources Manager, People Manager

Error Responses

400 Bad Request

{
  "error": "Bad Request",
  "message": "role is required"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

503 Service Unavailable

{
  "error": "Service Unavailable",
  "message": "role lookup not configured"
}

Use Cases

Account-based selling

Find the right decision-maker at target accounts without knowing their name.

Organizational mapping

Build org charts by looking up key roles at a company.

Multi-threading deals

Find multiple stakeholders (VP Sales, VP Engineering, CFO) for enterprise deals.

Competitive intelligence

Track leadership changes by monitoring key roles at competitor companies.

Related Endpoints

Person Lookup

Find people by name and company

Employee Search

Search employees with filters

Find Email

Find professional email addresses