API

Every ploid.api.* operation is listed below with parameter shapes and return types from the plugin Zod schemas.

New to Corsair? See API access, authentication, and error handling.

Account

credits

account.credits Read the workspace ACU balance and API key budget state Risk: read

await corsair.ploid.api.account.credits({});

Input: empty object Output

Name	Type	Required	Description
`data`	`object`	Yes	—
`meta`	`object`	Yes	—

data full type

{
  plan?: string,
  acu?: {
    included: number,
    purchased: number,
    used: number,
    available: number,
    overage: number
  }
}

meta full type

{
  request_id: string
}

usage

account.usage Read workspace ACU usage plus the calling key id and active key count Risk: read

await corsair.ploid.api.account.usage({});

Input: empty object Output

Name	Type	Required	Description
`data`	`object`	Yes	—
`meta`	`object`	Yes	—

data full type

{
  credits?: {
    plan?: string,
    acu?: {
      included: number,
      purchased: number,
      used: number,
      available: number,
      overage: number
    }
  },
  api_key?: {
    id?: string,
    active_keys?: number
  }
}

meta full type

{
  request_id: string
}

Contacts

enrich

contacts.enrich Resolve contact fields (work_email 1, personal_email 3, phone 10 ACU per hit) from a person_id, LinkedIn URL, email, or name plus company domain Risk: write

await corsair.ploid.api.contacts.enrich({
	identifier: { person_id: 'per_abc123' },
	fields: ['work_email', 'phone'],
});

Input

Name	Type	Required	Description
`identifier`	`object`	Yes	—
`fields`	`work_email \| personal_email \| phone[]`	Yes	—
`response_format`	`standard`	No	—

identifier full type

{
  linkedin_url: string
} | {
  person_id: string
} | {
  email: string
} | {
  name: string,
  company_domain: string
}

Output

Name	Type	Required	Description
`data`	`object`	Yes	—
`meta`	`object`	Yes	—

data full type

{
  work_email?: {
    value?: string | null,
    status: found | not_found | unavailable,
    confidence?: guess | strong | verified | null,
    source?: contact_network | linked_profile | public_code | public_web | null,
    last_seen?: string | null
  },
  personal_email?: {
    value?: string | null,
    status: found | not_found | unavailable,
    confidence?: guess | strong | verified | null,
    source?: contact_network | linked_profile | public_code | public_web | null,
    last_seen?: string | null
  },
  phone?: {
    value?: string | null,
    status: found | not_found | unavailable,
    confidence?: guess | strong | verified | null,
    source?: contact_network | linked_profile | public_code | public_web | null,
    last_seen?: string | null
  }
}

meta full type

{
  request_id: string
}

Person

cancelRun

person.cancelRun Cancel a queued or running person research run Risk: destructive

await corsair.ploid.api.person.cancelRun({ id: 'run_abc123' });

Input

Name	Type	Required	Description
`id`	`string`	Yes	—

Output

Name	Type	Required	Description
`data`	`object`	Yes	—
`meta`	`object`	Yes	—

data full type

{
  run_id: string,
  status: queued | running | cancelled,
  poll_url?: string
}

meta full type

{
  request_id: string
}

get

person.get Fetch a reviewed deep person profile (25 ACU first profile) or start a durable research run (202) Risk: write

await corsair.ploid.api.person.get({
	identifier: { person_id: 'per_abc123' },
});

Input

Name	Type	Required	Description
`identifier`	`object`	Yes	—

identifier full type

{
  person_id: string
} | {
  linkedin_url: string
} | {
  name: string,
  company_domain: string
}

Output: object

Output full type

{
  data: {
    run_id: string,
    status: queued | running | cancelled,
    poll_url?: string
  },
  meta: {
    request_id: string
  }
} | {
  data?: {
    person_id?: string,
    summary?: string | null,
    identity?: {
      name?: string,
      linkedin_url?: string | null,
      headline?: string | null,
      company?: string | null,
      location?: string | null,
      confidence?: number
    } | null
  } | null,
  meta: {
    request_id: string
  }
}

getRun

person.getRun Poll a person research run by id; returns run state or, once finished, the reviewed profile. 404 unknown, 410 expired Risk: read

await corsair.ploid.api.person.getRun({ id: 'run_abc123' });

Input

Name	Type	Required	Description
`id`	`string`	Yes	—

Output: object

Output full type

{
  data: {
    run_id: string,
    status: queued | running | cancelled,
    poll_url?: string
  },
  meta: {
    request_id: string
  }
} | {
  data?: {
    person_id?: string,
    summary?: string | null,
    identity?: {
      name?: string,
      linkedin_url?: string | null,
      headline?: string | null,
      company?: string | null,
      location?: string | null,
      confidence?: number
    } | null
  } | null,
  meta: {
    request_id: string
  }
}

resolve

person.resolve Identify one person from a name plus a clue and return the permanent person_id; 2 ACU when found, free when not Risk: write

await corsair.ploid.api.person.resolve({ name: 'Jane Doe', company: 'acme.com' });

Input

Name	Type	Required	Description
`name`	`string`	Yes	—
`company`	`string`	No	—
`role`	`string`	No	—
`location`	`string`	No	—
`address`	`string`	No	—
`work_email`	`string`	No	—
`personal_email`	`string`	No	—
`phone`	`string`	No	—

Output

Name	Type	Required	Description
`data`	`object`	Yes	—
`meta`	`object`	Yes	—

data full type

{
  found: boolean,
  person?: {
    person_id: string,
    name: string,
    headline?: string | null,
    company?: string | null,
    location?: string | null,
    profiles?: {
      linkedin?: string,
      github?: string,
      x?: string
    },
    identity_verified?: boolean
  } | null,
  confidence: number,
  summary?: string,
  sources?: string[]
}

meta full type

{
  request_id: string
}

Search

candidates

search.candidates Find candidate identities in the people index for 1 ACU, including zero matches Risk: write

await corsair.ploid.api.search.candidates({ name: 'Jane Doe', company: 'Acme', limit: 5 });

Input

Name	Type	Required	Description
`name`	`string`	Yes	—
`company`	`string`	No	—
`location`	`string`	No	—
`title`	`string`	No	—
`limit`	`number`	No	—

Output

Name	Type	Required	Description
`data`	`object`	Yes	—
`meta`	`object`	Yes	—

data full type

{
  matches: {
    person_id: string,
    name: string,
    title?: string | null,
    company?: string | null,
    location?: string | null,
    linkedin_url?: string | null,
    profile_url?: string | null
  }[],
  returned: number
}

meta full type

{
  request_id: string
}

search

search.search Search people by semantic query and hard filters; synchronous, at most 150 results Risk: write

await corsair.ploid.api.search.search({ query: 'venture-backed founders in Berlin', num_results: 25 });

Input

Name	Type	Required	Description
`query`	`string`	No	—
`type`	`instant \| fast \| auto \| deep`	No	—
`category`	`people`	No	—
`num_results`	`number`	No	—
`criteria`	`string[]`	No	—
`async`	`boolean`	No	—
`webhook_url`	`string`	No	—
`filters`	`object`	No	—
`freshness`	`object`	No	—
`contents`	`object`	No	—

filters full type

{
  title?: string | {
    any_of?: string[],
    none_of?: string[]
  },
  seniority?: string | {
    any_of?: string[],
    none_of?: string[]
  },
  company?: string | {
    any_of?: string[],
    none_of?: string[],
    employee_count?: {
      gte?: number,
      lte?: number
    },
    funding_stage?: {
      in: pre_seed | seed | series_a | series_b | series_c | series_d_plus | public | bootstrapped[]
    }
  },
  industry?: string | {
    any_of?: string[],
    none_of?: string[]
  },
  location?: string | {
    any_of?: string[],
    none_of?: string[],
    countries?: string[],
    cities?: string[]
  },
  company_size?: {
    min?: number,
    max?: number
  },
  experience?: {
    past_companies: {
      any_of: string[]
    }
  },
  education?: {
    schools: {
      any_of: string[]
    }
  }
}

freshness full type

{
  max_age_days: number
}

contents full type

{
  fields?: linkedin | title | company | location | name[]
}

Output: object

Output full type

{
  data: {
    results: {
      url?: string | null,
      title?: string | null,
      score?: number | null,
      person: {
        person_id: string,
        name?: string | null,
        title?: string | null,
        company?: string | null,
        location?: string | null,
        linkedin_url?: string | null,
        profile_url?: string | null,
        confidence?: number | null,
        identity_verified?: boolean
      }
    }[]
  },
  meta: {
    request_id: string
  }
} | {
  data: {
    mode: async,
    set_id: string,
    status?: string,
    items_url?: string,
    events_url?: string
  },
  meta: {
    request_id: string
  }
}

Overview

Plugins

Account

credits

usage

Contacts

enrich

Person

cancelRun

get

getRun

resolve

Search

candidates

search

​Account

​credits

​usage

​Contacts

​enrich

​Person

​cancelRun

​get

​getRun

​resolve

​Search

​candidates

​search

Account

credits

usage

Contacts

enrich

Person

cancelRun

get

getRun

resolve

Search

candidates

search