Create Target Account

POST

target-accounts

curl -X POST https://api.clustr-ai.com/api/public/target-accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name": "Acme Corp", "linkedin_url": "https://www.linkedin.com/company/acme-corp", "tier": "Tier 1"}'

curl -X POST https://api.clustr-ai.com/api/public/target-accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_companies": [{"name": "Acme Corp", "linkedin_url": "linkedin.com/company/acme-corp"}, {"name": "Globex Inc", "linkedin_url": "linkedin.com/company/globex"}]}'

import requests

requests.post(
    "https://api.clustr-ai.com/api/public/target-accounts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"company_name": "Acme Corp", "linkedin_url": "https://www.linkedin.com/company/acme-corp"},
)

{
  "company_name": "Acme Corp",
  "linkedin_url": "https://www.linkedin.com/company/acme-corp",
  "tier": "Tier 1"
}

{
  "target_companies": [
    {
      "name": "Acme Corp",
      "linkedin_url": "https://www.linkedin.com/company/acme-corp",
      "tier": "Tier 1",
      "tag": "Strategic"
    },
    {
      "name": "Globex Inc",
      "linkedin_url": "https://www.linkedin.com/company/globex",
      "tier": "Tier 2"
    }
  ]
}

{
  "success": true,
  "data": {
    "message": "Target companies created successfully",
    "count": 1
  }
}

{
  "success": true,
  "data": {
    "message": "Target companies created successfully",
    "count": 1,
    "rejected": [
      {
        "index": 1,
        "name": "Globex Inc",
        "reason": "A LinkedIn company URL is required, like linkedin.com/company/acme."
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "message": "A LinkedIn company URL is required, like linkedin.com/company/acme.",
    "code": "invalid_linkedin_url"
  }
}

{
  "success": false,
  "error": {
    "message": "No target companies provided",
    "code": "BAD_REQUEST"
  }
}

{
  "success": false,
  "error": {
    "message": "No tier named \"Platinum\" in this workspace (entry at index 3). Tiers are named per workspace; list them at GET /public/tenant-tiers",
    "code": "BAD_REQUEST"
  }
}

{
  "success": false,
  "error": {
    "message": "No account tag named \"Strategc\" in this workspace (entry at index 0). Tags are never created by an import",
    "code": "BAD_REQUEST"
  }
}

{
  "success": false,
  "error": {
    "message": "Invalid or missing API key",
    "code": "UNAUTHORIZED"
  }
}

Two formats supported, and both are additive:

Format	Behavior
Single object	Adds one account, keeps existing
Batch array	Adds all of them, keeps existing

LinkedIn URL

Every new account needs its LinkedIn company page URL: linkedin.com/company/acme, or the company’s numeric id, linkedin.com/company/1035. With or without https://www., a trailing slash or a query string. A person’s profile, a school page or a showcase page is refused. Clustr checks the URL’s shape only. To find it, search the company on LinkedIn and copy the address of its page.

Single object: a missing or invalid URL answers 422 with code invalid_linkedin_url and the reason, and nothing is added.
Batch: an entry without a valid URL is not added and is listed in rejected with its position in the request and the reason. The other entries are added. When no entry is left to add, the call answers 422.

Accounts already on your list are unchanged, with or without a URL.

Tier

Either format accepts a tier per account: the name your workspace uses for it, from List Account Tiers. An unknown tier name rejects the whole request rather than creating the tier or quietly dropping it. A typo in a 500-row import would otherwise become a permanent tier nobody chose, and a dropped one loses data you believed you sent. The error names both the tier you sent and the row it was on. A tier belongs to the company behind an account, and a brand-new account has usually not been matched to one yet. When that happens the tier is queued on the account and applied automatically as soon as the match happens, so nothing is lost in the gap. You do not have to poll or re-send it.

Tag

Either format accepts a tag per account: one of your account tags, as your workspace spells it, from List Tags. The tag is added to the account, also when the company is already on your list. An unknown tag name rejects the whole request. Tags are never created this way.

curl -X POST https://api.clustr-ai.com/api/public/target-accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name": "Acme Corp", "linkedin_url": "https://www.linkedin.com/company/acme-corp", "tier": "Tier 1"}'

curl -X POST https://api.clustr-ai.com/api/public/target-accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_companies": [{"name": "Acme Corp", "linkedin_url": "linkedin.com/company/acme-corp"}, {"name": "Globex Inc", "linkedin_url": "linkedin.com/company/globex"}]}'

import requests

requests.post(
    "https://api.clustr-ai.com/api/public/target-accounts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"company_name": "Acme Corp", "linkedin_url": "https://www.linkedin.com/company/acme-corp"},
)

{
  "company_name": "Acme Corp",
  "linkedin_url": "https://www.linkedin.com/company/acme-corp",
  "tier": "Tier 1"
}

{
  "target_companies": [
    {
      "name": "Acme Corp",
      "linkedin_url": "https://www.linkedin.com/company/acme-corp",
      "tier": "Tier 1",
      "tag": "Strategic"
    },
    {
      "name": "Globex Inc",
      "linkedin_url": "https://www.linkedin.com/company/globex",
      "tier": "Tier 2"
    }
  ]
}

{
  "success": true,
  "data": {
    "message": "Target companies created successfully",
    "count": 1
  }
}

{
  "success": true,
  "data": {
    "message": "Target companies created successfully",
    "count": 1,
    "rejected": [
      {
        "index": 1,
        "name": "Globex Inc",
        "reason": "A LinkedIn company URL is required, like linkedin.com/company/acme."
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "message": "A LinkedIn company URL is required, like linkedin.com/company/acme.",
    "code": "invalid_linkedin_url"
  }
}

{
  "success": false,
  "error": {
    "message": "No target companies provided",
    "code": "BAD_REQUEST"
  }
}

{
  "success": false,
  "error": {
    "message": "No tier named \"Platinum\" in this workspace (entry at index 3). Tiers are named per workspace; list them at GET /public/tenant-tiers",
    "code": "BAD_REQUEST"
  }
}

{
  "success": false,
  "error": {
    "message": "No account tag named \"Strategc\" in this workspace (entry at index 0). Tags are never created by an import",
    "code": "BAD_REQUEST"
  }
}

{
  "success": false,
  "error": {
    "message": "Invalid or missing API key",
    "code": "UNAUTHORIZED"
  }
}

Authorizations

Authorization

string

header

required

The API key you created on the API settings page of the Clustr app.

Body

application/json

Accepts two formats:

Single object: {"company_name": "...", "linkedin_url": "...", "tier": "..."} adds one account.
Batch array: {"target_companies": [...]} adds every account in the list and skips the ones already present.

Every new account needs its LinkedIn company page URL, such as linkedin.com/company/acme or linkedin.com/company/1035. An entry without a valid one is listed in rejected instead of being added.

company_name

string

The company name, in the single object format.

Example:

"Acme Corp"

linkedin_url

string

The company's LinkedIn page URL, in the single object format. Required for a new account.

Example:

"https://www.linkedin.com/company/acme-corp"

tier

string

The tier name, spelled the way your workspace spells it, in the single object format. An unknown tier name is rejected.

Example:

"Tier 1"

tag

string

An account tag name, spelled the way your workspace spells it, in the single object format. The tag is added to the account. An unknown tag name is rejected.

Example:

"Strategic"

target_companies

object[]

The batch format: a list of accounts to add to your existing ones. Accounts already present are skipped.

Show child attributes

Response

Target accounts created

success

boolean

required

Example:

true

data

object

required

Show child attributes

curl -X POST https://api.clustr-ai.com/api/public/target-accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name": "Acme Corp", "linkedin_url": "https://www.linkedin.com/company/acme-corp", "tier": "Tier 1"}'

curl -X POST https://api.clustr-ai.com/api/public/target-accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_companies": [{"name": "Acme Corp", "linkedin_url": "linkedin.com/company/acme-corp"}, {"name": "Globex Inc", "linkedin_url": "linkedin.com/company/globex"}]}'

import requests

requests.post(
    "https://api.clustr-ai.com/api/public/target-accounts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"company_name": "Acme Corp", "linkedin_url": "https://www.linkedin.com/company/acme-corp"},
)

{
  "company_name": "Acme Corp",
  "linkedin_url": "https://www.linkedin.com/company/acme-corp",
  "tier": "Tier 1"
}

{
  "target_companies": [
    {
      "name": "Acme Corp",
      "linkedin_url": "https://www.linkedin.com/company/acme-corp",
      "tier": "Tier 1",
      "tag": "Strategic"
    },
    {
      "name": "Globex Inc",
      "linkedin_url": "https://www.linkedin.com/company/globex",
      "tier": "Tier 2"
    }
  ]
}

{
  "success": true,
  "data": {
    "message": "Target companies created successfully",
    "count": 1
  }
}

{
  "success": true,
  "data": {
    "message": "Target companies created successfully",
    "count": 1,
    "rejected": [
      {
        "index": 1,
        "name": "Globex Inc",
        "reason": "A LinkedIn company URL is required, like linkedin.com/company/acme."
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "message": "A LinkedIn company URL is required, like linkedin.com/company/acme.",
    "code": "invalid_linkedin_url"
  }
}

{
  "success": false,
  "error": {
    "message": "No target companies provided",
    "code": "BAD_REQUEST"
  }
}

{
  "success": false,
  "error": {
    "message": "No tier named \"Platinum\" in this workspace (entry at index 3). Tiers are named per workspace; list them at GET /public/tenant-tiers",
    "code": "BAD_REQUEST"
  }
}

{
  "success": false,
  "error": {
    "message": "No account tag named \"Strategc\" in this workspace (entry at index 0). Tags are never created by an import",
    "code": "BAD_REQUEST"
  }
}

{
  "success": false,
  "error": {
    "message": "Invalid or missing API key",
    "code": "UNAUTHORIZED"
  }
}

API Reference

Import

Search

Jobs

Network

Opportunities

Owners

Accounts

Account States

Saved Views

Workflows

Intro Requests

Notes

Record Activity

Tags

Target Accounts

Client Companies

Excluded Companies

Buyer Titles

ICP

Competitor Monitoring

Connector Refresh

Notifications

Create Target Account

LinkedIn URL

Tier

Tag

Authorizations

Body

Response

​LinkedIn URL

​Tier

​Tag

Authorizations

Body

Response

LinkedIn URL

Tier

Tag