Skip to main content

Examples

Common actions against the Lead Hero API. Every request needs an API key - see Authentication. Replace $ORG with your organization id and $KEY with your API key.

export ORG="a3f8c2d1-4e5b-6f7a-8b9c-0d1e2f3a4b5c"
export KEY="a3f8c2d1-....X9kLmNpQrStUv..."

List leads​

curl "https://api.leadhero.io/leads/$ORG" \
  -H "Authorization: Bearer $KEY"

Find leads by a field​

curl -G "https://api.leadhero.io/leads/$ORG" \
  -H "Authorization: Bearer $KEY" \
  --data-urlencode "filter[email]=jane@acme.com"

Combine filters by passing more keys:

curl -G "https://api.leadhero.io/leads/$ORG" \
  -H "Authorization: Bearer $KEY" \
  --data-urlencode "filter[status]=new" \
  --data-urlencode "filter[leadAgeBucket]=last-7-days"

Repeat a key to match any of several values:

curl -G "https://api.leadhero.io/leads/$ORG" \
  -H "Authorization: Bearer $KEY" \
  --data-urlencode "filter[leadFolders]=$FOLDER_A" \
  --data-urlencode "filter[leadFolders]=$FOLDER_B"

The supported filter keys for each list endpoint are shown under its filter parameter in the API Reference.

Sort and paginate​

curl -G "https://api.leadhero.io/leads/$ORG" \
  -H "Authorization: Bearer $KEY" \
  --data-urlencode "sort=-createdAt" \
  --data-urlencode "pageSize=50" \
  --data-urlencode "page=2"

Create a lead​

curl "https://api.leadhero.io/leads/$ORG" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@acme.com",
    "primaryPhone": "+15551234567"
  }'

Update a lead​

curl -X PUT "https://api.leadhero.io/leads/$ORG/$LEAD_ID" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "contacted" }'

Create a lead folder​

The body wraps the folder under data:

curl "https://api.leadhero.io/lead-folders/$ORG" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "name": "Q1 outbound" } }'

Send an SMS to a lead​

The message goes to a specific lead, so the lead id is in the path. orgNumber is optional - omit it to let Lead Hero pick the best number:

curl "https://api.leadhero.io/sms/$ORG/$LEAD_ID" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hi from Lead Hero" }'

See SMS vs. iMessage for choosing a channel and its requirements.