POST

people

role-finder

Role Finder

curl --request POST \
  --url https://api.leadmagic.io/v1/people/role-finder \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "company_name": "leadmagic",
  "company_domain": "leadmagic.io",
  "job_title": "ceo"
}
'

import requests

url = "https://api.leadmagic.io/v1/people/role-finder"

payload = {
    "company_name": "leadmagic",
    "company_domain": "leadmagic.io",
    "job_title": "ceo"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({company_name: 'leadmagic', company_domain: 'leadmagic.io', job_title: 'ceo'})
};

fetch('https://api.leadmagic.io/v1/people/role-finder', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.leadmagic.io/v1/people/role-finder"

	payload := strings.NewReader("{\n  \"company_name\": \"leadmagic\",\n  \"company_domain\": \"leadmagic.io\",\n  \"job_title\": \"ceo\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.leadmagic.io/v1/people/role-finder",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'company_name' => 'leadmagic',
    'company_domain' => 'leadmagic.io',
    'job_title' => 'ceo'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "name": "Alex Rivera",
  "profile_url": "alex-rivera",
  "first_name": "Alex",
  "last_name": "Rivera",
  "message": "Role found.",
  "credits_consumed": 2,
  "company_name": "Leadmagic",
  "company_website": "leadmagic.io"
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/validation_error",
      "title": "Request validation failed. Check your input parameters.",
      "status": 400,
      "code": "validation_error",
      "param": [
        "email"
      ],
      "detail": "Email format is invalid. Expected format: user@domain.com",
      "action": "Provide a valid email address in the 'email' field.",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/missing_authentication",
      "title": "Authentication required. Provide a valid API key in the X-API-Key header (case-insensitive).",
      "status": 401,
      "code": "missing_authentication",
      "docs": "https://leadmagic.io/docs/api-reference/authentication"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/insufficient_credits",
      "title": "Insufficient credits: need 5, have 2.50. Add credits to continue.",
      "status": 402,
      "code": "insufficient_credits",
      "detail": "This request requires 5 credit(s) but your account only has 2.50 credits remaining.",
      "action": "Add credits to your account at https://app.leadmagic.io/billing or contact support@leadmagic.io for enterprise plans.",
      "docs": "https://leadmagic.io/docs/api-reference/credits",
      "context": {
        "credits_required": 5,
        "credits_available": 2.5,
        "credits_needed": 2.5
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/resource_not_found",
      "title": "Resource not found.",
      "status": 404,
      "code": "resource_not_found",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/rate_limit_exceeded",
      "title": "Rate limit exceeded: 300 requests per 1 minute. Wait and try again.",
      "status": 429,
      "code": "rate_limit_exceeded",
      "detail": "You have exceeded the maximum allowed request rate. Please wait before making additional requests.",
      "action": "Wait 42 seconds before retrying. Consider implementing exponential backoff.",
      "docs": "https://leadmagic.io/docs/api-reference/rate-limits",
      "context": {
        "limit": 300,
        "window": "1 minute",
        "remaining": 0,
        "reset_at": 1706745642,
        "retry_after_seconds": 42
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/INTERNAL_ERROR",
      "title": "Something went wrong on our end. Our team has been notified and is investigating.",
      "status": 500,
      "code": "INTERNAL_ERROR",
      "detail": "This is a temporary server error. The issue has been automatically reported to our team.",
      "action": "Wait 30 seconds and retry your request. If the problem persists, contact support@leadmagic.io",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

Find by Role

Find a person at a company by their job title. Perfect for ABM campaigns targeting specific roles like “VP of Sales” or “Head of Marketing”.

Endpoint Details

Pricing
Rate Limits

Metric	Value
Cost	2 credits per person found
No Results	FREE if no match found

Returns the first matching person. For multiple results, use People Search with title and company filters.

Metric	Value
Requests/Minute	300
Burst Capacity	~5 requests/second

Quick Example

curl -X POST 'https://api.leadmagic.io/v1/people/role-finder' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "job_title": "VP of Sales",
    "company_domain": "leadmagic.io"
  }'

const response = await fetch('https://api.leadmagic.io/v1/people/role-finder', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    job_title: 'VP of Sales',
    company_domain: 'leadmagic.io'
  })
});
const data = await response.json();
if (data.profile_url) {
  console.log(`Found: ${data.first_name} ${data.last_name}`);
}

import requests

response = requests.post(
    'https://api.leadmagic.io/v1/people/role-finder',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'job_title': 'VP of Sales',
        'company_domain': 'leadmagic.io'
    }
)
data = response.json()
print(f"Found: {data.get('full_name', 'Not found')}")

Request Parameters

string

required

The job title to search for. Matches partial titles (e.g., “Sales” matches “VP of Sales”).

string

Company website domain (preferred). More accurate than company_name.

string

Company name. Use if domain is not available.

You must provide either company_domain or company_name (or both).

Response

string

First name of the person found

string

Last name of the person found

string

Full name of the person found

string

Professional profile URL

string

Company name

string

Company website domain

number

required

Credits used (2 if found, 0 if not)

string

required

Human-readable status message

Example Response

{
  "first_name": "Alex",
  "last_name": "Rivera",
  "full_name": "Alex Rivera",
  "profile_url": "linkedin.com/in/alex-rivera",
  "job_title": "VP of Sales",
  "company_name": "Example Robotics",
  "company_website": "leadmagic.io",
  "credits_consumed": 2,
  "message": "Role found."
}

Success Messages

Message	Meaning	Cost
`Role Found`	Person with matching role found	2 credits
`No matching role found at this company.`	No matching role exists	FREE

Best Practices

Use domain over company name

Domain lookups are more accurate. leadmagic.io resolves directly to LeadMagic, while a company name can match multiple entities.

Be flexible with titles

Try variations: “VP Sales”, “VP of Sales”, “Head of Sales” may all work depending on how the person lists their title.

Chain with Email Finder

After finding a person, use Email Finder with their name and company to get their email.

Use Cases

ABM Campaigns

Target specific roles at key accounts for personalized outreach.

Competitive Intelligence

Find your counterpart at competitor companies.

Partner Outreach

Find the right person to discuss partnerships.

Recruiting

Identify potential candidates by role at target companies.

Authorizations

X-API-Key

string

header

required

Your LeadMagic API key. Header name is case-insensitive (X-API-Key, X-API-KEY, x-api-key all work).

Body

application/json

company_name

string

default:leadmagic

Business Profile URL (with url or public_identifier)

company_domain

string

default:leadmagic.io

Company domain

job_title

string

default:ceo

Enter the job title you want to find in the company.

Response

Successful response with role details

name

string

Example:

"Alex Rivera"

profile_url

string

Example:

"alex-rivera"

first_name

string

Example:

"Alex"

last_name

string

Example:

"Rivera"

message

string

Example:

"Role found."

credits_consumed

integer

Example:

2

company_name

string

Example:

"Leadmagic"

company_website

string

Example:

"leadmagic.io"

Role Finder

curl --request POST \
  --url https://api.leadmagic.io/v1/people/role-finder \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "company_name": "leadmagic",
  "company_domain": "leadmagic.io",
  "job_title": "ceo"
}
'

import requests

url = "https://api.leadmagic.io/v1/people/role-finder"

payload = {
    "company_name": "leadmagic",
    "company_domain": "leadmagic.io",
    "job_title": "ceo"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({company_name: 'leadmagic', company_domain: 'leadmagic.io', job_title: 'ceo'})
};

fetch('https://api.leadmagic.io/v1/people/role-finder', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.leadmagic.io/v1/people/role-finder"

	payload := strings.NewReader("{\n  \"company_name\": \"leadmagic\",\n  \"company_domain\": \"leadmagic.io\",\n  \"job_title\": \"ceo\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.leadmagic.io/v1/people/role-finder",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'company_name' => 'leadmagic',
    'company_domain' => 'leadmagic.io',
    'job_title' => 'ceo'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "name": "Alex Rivera",
  "profile_url": "alex-rivera",
  "first_name": "Alex",
  "last_name": "Rivera",
  "message": "Role found.",
  "credits_consumed": 2,
  "company_name": "Leadmagic",
  "company_website": "leadmagic.io"
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/validation_error",
      "title": "Request validation failed. Check your input parameters.",
      "status": 400,
      "code": "validation_error",
      "param": [
        "email"
      ],
      "detail": "Email format is invalid. Expected format: user@domain.com",
      "action": "Provide a valid email address in the 'email' field.",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/missing_authentication",
      "title": "Authentication required. Provide a valid API key in the X-API-Key header (case-insensitive).",
      "status": 401,
      "code": "missing_authentication",
      "docs": "https://leadmagic.io/docs/api-reference/authentication"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/insufficient_credits",
      "title": "Insufficient credits: need 5, have 2.50. Add credits to continue.",
      "status": 402,
      "code": "insufficient_credits",
      "detail": "This request requires 5 credit(s) but your account only has 2.50 credits remaining.",
      "action": "Add credits to your account at https://app.leadmagic.io/billing or contact support@leadmagic.io for enterprise plans.",
      "docs": "https://leadmagic.io/docs/api-reference/credits",
      "context": {
        "credits_required": 5,
        "credits_available": 2.5,
        "credits_needed": 2.5
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/resource_not_found",
      "title": "Resource not found.",
      "status": 404,
      "code": "resource_not_found",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/rate_limit_exceeded",
      "title": "Rate limit exceeded: 300 requests per 1 minute. Wait and try again.",
      "status": 429,
      "code": "rate_limit_exceeded",
      "detail": "You have exceeded the maximum allowed request rate. Please wait before making additional requests.",
      "action": "Wait 42 seconds before retrying. Consider implementing exponential backoff.",
      "docs": "https://leadmagic.io/docs/api-reference/rate-limits",
      "context": {
        "limit": 300,
        "window": "1 minute",
        "remaining": 0,
        "reset_at": 1706745642,
        "retry_after_seconds": 42
      }
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/INTERNAL_ERROR",
      "title": "Something went wrong on our end. Our team has been notified and is investigating.",
      "status": 500,
      "code": "INTERNAL_ERROR",
      "detail": "This is a temporary server error. The issue has been automatically reported to our team.",
      "action": "Wait 30 seconds and retry your request. If the problem persists, contact support@leadmagic.io",
      "docs": "https://leadmagic.io/docs/api-reference/errors"
    }
  ],
  "meta": {
    "request_id": "ea6e3248-f4d2-437d-bca3-20881b529129",
    "timestamp": "2024-02-01T12:00:00.000Z"
  }
}

Get Started

API Endpoints

MCP Server

CLI

Role Finder

Find by Role

Endpoint Details

Per-Endpoint Limit

Quick Example

Request Parameters

Response

Example Response

Success Messages

Best Practices

Use Cases

ABM Campaigns

Competitive Intelligence

Partner Outreach

Recruiting

Authorizations

Body

Response

​Find by Role

​Endpoint Details

​Per-Endpoint Limit

​Quick Example

​Request Parameters

​Response

​Example Response

​Success Messages

​Best Practices

​Use Cases

ABM Campaigns

Competitive Intelligence

Partner Outreach

Recruiting

Authorizations

Body

Response

Find by Role

Endpoint Details

Per-Endpoint Limit

Quick Example

Request Parameters

Response

Example Response

Success Messages

Best Practices

Use Cases