> ## 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.

# GenderAPI.io API reference

> API reference for the GenderAPI.io plugin in Corsair: every `genderapiio.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

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

## Account

### capabilities

`account.capabilities`

Read the deployment version, the AI availability and the batch limit. This route is free

**Risk:** `read`

```ts theme={null}
await corsair.genderapiio.api.account.capabilities({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `version` | `string` | Yes | — |
| `documentation` | `string` | No | — |
| `capabilities` | `object` | No | — |
| `billing_consistency` | `string` | No | — |

> [accordion] capabilities full type
>
> ```ts theme={null}
> {
>   ai?: boolean,
>   forceToGenderize?: boolean,
>   max_batch_items?: number,
>   shared_v1_keys_and_credits?: boolean,
>   ip_trial?: {
>     credits: number,
>     period_hours: number
>   },
>   default_ai_mode?: {
>     single: string,
>     batch: string
>   }
> }
> ```

***

### errorCatalog

`account.errorCatalog`

Read every error code with the statuses it uses and what a caller should do about it. This route is free

**Risk:** `read`

```ts theme={null}
await corsair.genderapiio.api.account.errorCatalog({});
```

**Input:** *empty object*

**Output**

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

> [accordion] errors full type
>
> ```ts theme={null}
> Record<string, {
>   code: string,
>   http_statuses: number[],
>   action: string,
>   description: string
> }>
> ```

***

### usage

`account.usage`

Read the shared balance, the trial reset time and whether this call used a key or the IP trial. This route is free

**Risk:** `read`

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

**Input:** *empty object*

Free, and `meta.access.mode` tells an IP trial from a keyed call.

**Output**

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

> [accordion] data full type
>
> ```ts theme={null}
> {
>   remaining_credits: number,
>   expires_at: string | null,
>   resets_at?: string | null,
>   limit?: number | null,
>   period_seconds?: number | null
> }
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   request_id: string,
>   duration_ms?: number,
>   access?: {
>     mode: string,
>     reason?: string | null
>   },
>   usage?: {
>     charged_credits?: number | null,
>     remaining_credits?: number | null,
>     billing_status?: string,
>     resets_at?: string | null,
>     limit?: number | null,
>     period_seconds?: number | null
>   }
> }
> ```

***

## Gender

### batch

`gender.batch`

Infer gender for up to 50 names, emails or usernames in one request. An item can fail on its own, and only successful items are billed

**Risk:** `read`

```ts theme={null}
await corsair.genderapiio.api.gender.batch({ items: [{ type: 'name', value: 'Sophia' }, { type: 'name', value: 'Michael', country: 'US' }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | Items to infer, answered in the same order, each with its own charge. An item can fail without failing the batch |
| `ai_mode` | `off \| fallback \| always` | No | Applies to every item without its own `ai_mode`. A batch defaults to `off`, where a single request defaults to `fallback` |

Up to 50 items (10 on the IP trial); defaults to `ai_mode: off`, unlike a single request.

> [accordion] items full type
>
> ```ts theme={null}
> {
>   id?: string,
>   type: name | email | username,
>   value: string,
>   country?: string,
>   forceToGenderize?: boolean,
>   ai_mode?: off | fallback | always
> }[]
> ```

**Output**

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

> [accordion] data full type
>
> ```ts theme={null}
> {
>   index: number,
>   id?: string,
>   charged_credits?: number,
>   data?: {
>     input: {
>       type: name | email | username,
>       value: string,
>       country?: string | null,
>       forceToGenderize?: boolean
>     },
>     name: string | null,
>     gender: string | null,
>     country: string | null,
>     confidence: number | null,
>     confidence_kind: string | null,
>     sample_count: number | null,
>     source: string,
>     result_status?: string | null,
>     reason?: string | null,
>     country_source?: string | null,
>     match?: {
>       name: string | null,
>       method: string | null,
>       scope: string | null,
>       country: string | null
>     }
>   },
>   error?: {
>     code?: string,
>     status?: number,
>     title?: string,
>     detail?: string,
>     action?: string,
>     errors?: {
>       pointer?: string,
>       message?: string
>     }[]
>   }
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   request_id: string,
>   duration_ms?: number,
>   access?: {
>     mode: string,
>     reason?: string | null
>   },
>   usage?: {
>     charged_credits?: number | null,
>     remaining_credits?: number | null,
>     billing_status?: string,
>     resets_at?: string | null,
>     limit?: number | null,
>     period_seconds?: number | null
>   },
>   summary?: {
>     total: number,
>     succeeded: number,
>     identified: number,
>     unknown: number,
>     failed: number
>   }
> }
> ```

***

### infer

`gender.infer`

Infer gender from a name, an email address or a username, with a confidence, the source that answered (dataset or AI) and the credits it cost

**Risk:** `read`

```ts theme={null}
await corsair.genderapiio.api.gender.infer({ type: 'name', value: 'Sophia', country: 'US' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `name \| email \| username` | Yes | What the value is: a first or full name, an email address, or a username or nickname |
| `value` | `string` | Yes | The name, email address or username to infer from |
| `country` | `string` | No | Scopes the lookup to one country, which changes the answer for names such as Kim |
| `ai_mode` | `off \| fallback \| always` | No | `fallback` lets AI answer when the dataset cannot (1 credit in total); `off` is dataset only; `always` forces AI (2 credits) |
| `forceToGenderize` | `boolean` | No | Resolves more names by falling back to nickname-based AI. A dataset hit costs 1 credit, an AI one 2. Cannot be combined with `ai_mode` `off` or `always` |

`ai_mode` defaults to `fallback` here (1 credit in total); `always` costs 2.

**Output**

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

> [accordion] data full type
>
> ```ts theme={null}
> {
>   input: {
>     type: name | email | username,
>     value: string,
>     country?: string | null,
>     forceToGenderize?: boolean
>   },
>   name: string | null,
>   gender: string | null,
>   country: string | null,
>   confidence: number | null,
>   confidence_kind: string | null,
>   sample_count: number | null,
>   source: string,
>   result_status?: string | null,
>   reason?: string | null,
>   country_source?: string | null,
>   match?: {
>     name: string | null,
>     method: string | null,
>     scope: string | null,
>     country: string | null
>   }
> }
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   request_id: string,
>   duration_ms?: number,
>   access?: {
>     mode: string,
>     reason?: string | null
>   },
>   usage?: {
>     charged_credits?: number | null,
>     remaining_credits?: number | null,
>     billing_status?: string,
>     resets_at?: string | null,
>     limit?: number | null,
>     period_seconds?: number | null
>   }
> }
> ```

***

## Phone

### validate

`phone.validate`

Validate and format a phone number, returning its E.164 form, country and calling code

**Risk:** `read`

```ts theme={null}
await corsair.genderapiio.api.phone.validate({ number: '+14155552671', country: 'US' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `number` | `string` | Yes | The phone number, with or without a country calling code |
| `country` | `string` | No | The country to parse the number in, when it has no calling code |

Returns the E.164 form, or null when the number cannot be formatted.

**Output**

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

> [accordion] data full type
>
> ```ts theme={null}
> {
>   valid: boolean,
>   possible: boolean,
>   e164: string | null,
>   country: string | null,
>   country_calling_code: number | null
> }
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   request_id: string,
>   duration_ms?: number,
>   access?: {
>     mode: string,
>     reason?: string | null
>   },
>   usage?: {
>     charged_credits?: number | null,
>     remaining_credits?: number | null,
>     billing_status?: string,
>     resets_at?: string | null,
>     limit?: number | null,
>     period_seconds?: number | null
>   }
> }
> ```

***


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