> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> API reference for Ploid: every `ploid.api.*` operation with input and output types.

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

> [!NOTE]
>
> **New to Corsair?** See [API access](/concepts/api), [authentication](/concepts/auth), and [error handling](/concepts/error-handling).

## Account

### credits

`account.credits`

Read the workspace ACU balance and API key budget state

**Risk:** `read`

```ts theme={null}
await corsair.ploid.api.account.credits({});
```

**Input:** *empty object*

**Output**

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

> **data full type**
>
> ```ts theme={null}
> {
>   plan?: string,
>   acu?: {
>     included: number,
>     purchased: number,
>     used: number,
>     available: number,
>     overage: number
>   }
> }
> ```

> **meta full type**
>
> ```ts theme={null}
> {
>   request_id: string
> }
> ```

***

### usage

`account.usage`

Read workspace ACU usage plus the calling key id and active key count

**Risk:** `read`

```ts theme={null}
await corsair.ploid.api.account.usage({});
```

**Input:** *empty object*

**Output**

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

> **data full type**
>
> ```ts theme={null}
> {
>   credits?: {
>     plan?: string,
>     acu?: {
>       included: number,
>       purchased: number,
>       used: number,
>       available: number,
>       overage: number
>     }
>   },
>   api_key?: {
>     id?: string,
>     active_keys?: number
>   }
> }
> ```

> **meta full type**
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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**
>
> ```ts theme={null}
> {
>   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**
>
> ```ts theme={null}
> {
>   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**
>
> ```ts theme={null}
> {
>   request_id: string
> }
> ```

***

## Person

### cancelRun

`person.cancelRun`

Cancel a queued or running person research run

**Risk:** `destructive`

```ts theme={null}
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**
>
> ```ts theme={null}
> {
>   run_id: string,
>   status: queued | running | cancelled,
>   poll_url?: string
> }
> ```

> **meta full type**
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.ploid.api.person.get({
	identifier: { person_id: 'per_abc123' },
});
```

**Input**

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

> **identifier full type**
>
> ```ts theme={null}
> {
>   person_id: string
> } | {
>   linkedin_url: string
> } | {
>   name: string,
>   company_domain: string
> }
> ```

**Output:** `object`

> **Output full type**
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
await corsair.ploid.api.person.getRun({ id: 'run_abc123' });
```

**Input**

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

**Output:** `object`

> **Output full type**
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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**
>
> ```ts theme={null}
> {
>   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**
>
> ```ts theme={null}
> {
>   request_id: string
> }
> ```

***

## Search

### candidates

`search.candidates`

Find candidate identities in the people index for 1 ACU, including zero matches

**Risk:** `write`

```ts theme={null}
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**
>
> ```ts theme={null}
> {
>   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**
>
> ```ts theme={null}
> {
>   request_id: string
> }
> ```

***

### search

`search.search`

Search people by semantic query and hard filters; synchronous, at most 150 results

**Risk:** `write`

```ts theme={null}
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**
>
> ```ts theme={null}
> {
>   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**
>
> ```ts theme={null}
> {
>   max_age_days: number
> }
> ```

> **contents full type**
>
> ```ts theme={null}
> {
>   fields?: linkedin | title | company | location | name[]
> }
> ```

**Output:** `object`

> **Output full type**
>
> ```ts theme={null}
> {
>   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
>   }
> }
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.