Lists

Targetable People

Add, update, and remove targetable people on account-based Lists by domain.

#Overview

Targetable people helpers are designed for account-based outreach lists. They let you write people data by account domain, so you do not need to fetch the account row first.

#Endpoints

Endpoint Description
GET /v1/lists/{tableId}/targetable-people Query and page through targetable people by target flag, persona, contactability, or text search.
POST /v1/lists/{tableId}/targetable-people Add targetable people to an account row.
PATCH /v1/lists/{tableId}/targetable-people Update targetable people on an account row.
DELETE /v1/lists/{tableId}/targetable-people Remove targetable people from an account row.

#Domain Matching

The request identifies the account by domain. Account-based lists can enforce unique domains on the targetable account column, which keeps this workflow deterministic.

#Example: Query People

Use query parameters to page through stakeholders without fetching every list row.

curl "https://api.bigmind.ai/v1/lists/tbl_123/targetable-people?target=true&personas=champion,decision_maker&limit=25&offset=0" \
  -H "Authorization: Bearer sk_your_api_key_here"

#Person Fields

Field Type Required Description
first_name string Yes Person's first name.
last_name string No Person's last name.
bio string No Short background or context for the person.
title string No Job title or role.
email string No Email address. Used for duplicate matching when present.
phone_number string No Phone number in E.164 format, for example +14155552671.
linkedin_profile_url string No LinkedIn profile URL. Used for duplicate matching when present.
avatar_url string No Profile image URL.
connection_paths array No Known paths from your team to this person.
target boolean No Whether this person should be targeted. Defaults to true when a contact channel is present.
personas string[] No Stakeholder persona keys, for example economic_buyer, champion, or technical_evaluator.
persona_rationale string No Short explanation for why the personas were assigned.

Connection Path Fields

Field Type Required Description
userId string Yes The Bigmind user ID for the teammate with the connection.
source linkedin | relation Yes Where the connection path came from.
degree 1st | 2nd Yes The relationship degree.
context string No Optional context about the relationship.

#Example: Add People by Domain

Use duplicateStrategy to control what happens when a matching person already exists. The default is update-existing.

{
  "userId": "usr_123",
  "accounts": [
    {
      "accountDomain": "acme.com",
      "people": [
        {
          "first_name": "Avery",
          "last_name": "Stone",
          "bio": "Owns sales operations and outbound tooling.",
          "email": "avery@acme.com",
          "phone_number": "+14155552671",
          "title": "VP Sales",
          "linkedin_profile_url": "https://www.linkedin.com/in/averystone",
          "avatar_url": "https://cdn.example.com/avery.png",
          "personas": ["decision_maker", "champion"],
          "persona_rationale": "Owns outbound tooling and has executive influence over revenue systems.",
          "connection_paths": [
            {
              "userId": "usr_123",
              "source": "linkedin",
              "degree": "2nd",
              "context": "Connected through Morgan Lee"
            }
          ],
          "target": true
        }
      ]
    }
  ],
  "duplicateStrategy": "update-existing"
}
curl -X POST https://api.bigmind.ai/v1/lists/tbl_123/targetable-people \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_123",
    "accounts": [
      {
        "accountDomain": "acme.com",
        "people": [
          {
            "first_name": "Avery",
            "last_name": "Stone",
            "bio": "Owns sales operations and outbound tooling.",
            "email": "avery@acme.com",
            "phone_number": "+14155552671",
            "title": "VP Sales",
            "linkedin_profile_url": "https://www.linkedin.com/in/averystone",
            "avatar_url": "https://cdn.example.com/avery.png",
            "personas": ["decision_maker", "champion"],
            "persona_rationale": "Owns outbound tooling and has executive influence over revenue systems.",
            "connection_paths": [
              {
                "userId": "usr_123",
                "source": "linkedin",
                "degree": "2nd",
                "context": "Connected through Morgan Lee"
              }
            ],
            "target": true
          }
        ]
      }
    ],
    "duplicateStrategy": "update-existing"
  }'

#Example: Update People by Domain

Each update includes a match object to find the person and a patch object with the fields to change.

{
  "userId": "usr_123",
  "accounts": [
    {
      "accountDomain": "acme.com",
      "people": [
        {
          "match": {
            "email": "avery@acme.com"
          },
          "patch": {
            "title": "Chief Revenue Officer",
            "personas": ["economic_buyer", "decision_maker"],
            "persona_rationale": "Now owns revenue budget and final sign-off for GTM systems.",
            "connection_paths": [
              {
                "userId": "usr_456",
                "source": "relation",
                "degree": "1st",
                "context": "Former customer champion"
              }
            ],
            "target": true
          }
        }
      ]
    }
  ]
}
curl -X PATCH https://api.bigmind.ai/v1/lists/tbl_123/targetable-people \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_123",
    "accounts": [
      {
        "accountDomain": "acme.com",
        "people": [
          {
            "match": { "email": "avery@acme.com" },
            "patch": {
              "title": "Chief Revenue Officer",
              "personas": ["economic_buyer", "decision_maker"],
              "persona_rationale": "Now owns revenue budget and final sign-off for GTM systems.",
              "connection_paths": [
                {
                  "userId": "usr_456",
                  "source": "relation",
                  "degree": "1st",
                  "context": "Former customer champion"
                }
              ],
              "target": true
            }
          }
        ]
      }
    ]
  }'

#Example: Remove People by Domain

People can be matched by email, phone number, LinkedIn profile URL, or first name and last name.

{
  "userId": "usr_123",
  "accounts": [
    {
      "accountDomain": "acme.com",
      "people": [
        {
          "email": "avery@acme.com"
        }
      ]
    }
  ]
}
curl -X DELETE https://api.bigmind.ai/v1/lists/tbl_123/targetable-people \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_123",
    "accounts": [
      {
        "accountDomain": "acme.com",
        "people": [
          { "email": "avery@acme.com" }
        ]
      }
    ]
  }'
Updated 5/14/2026