# identification

Build and validate identification documents

Canonical URL: https://docs.paradoc.dev/sdk/primitives/identification/

Build and validate identification document information. The Identification primitive captures ID document details like passports, driver's licenses, and national IDs.

## Examples

### Creating identifications

```ts
// Object pattern
const id = p.identification({
  type: 'passport',
  number: 'AB1234567'
})

// Builder pattern
const id = p.identification()
  .type('passport')
  .number('AB1234567')
  .issuer('US')
  .issueDate('2020-01-15')
  .expiryDate('2030-01-14')
  .build()

// Copy and modify
const renewed = p.identification()
  .from(id)
  .issueDate('2024-01-15')
  .expiryDate('2034-01-14')
  .build()
```

### Parsing external data

```ts
// Parse unknown input (throws on error)
const id = p.identification.parse(jsonData)

// Safe parsing (returns result object)
const result = p.identification.safeParse(jsonData)
if (result.success) {
  console.log(`${result.data.type}: ${result.data.number}`)
} else {
  console.error(result.error.message)
}
```

### Using with forms

```ts
const form = p.form({
  name: 'kyc',
  fields: {
    primaryId: { type: 'identification', label: 'Primary ID' },
    secondaryId: { type: 'identification', label: 'Secondary ID' }
  }
})

const filled = form.fill({
  fields: {
    primaryId: p.identification()
      .type('drivers_license')
      .number('D1234567')
      .issuer('CA')
      .expiryDate('2028-06-30')
      .build()
  }
})
```

## API

### Object Pattern

```ts
p.identification(input: Identification): Identification
```

Pass an Identification object for validation. Returns the validated Identification or throws on error.

```ts
const id = p.identification({
  type: 'national_id',
  number: '123-45-6789'
})
```

### Builder Pattern

Chain methods to build an Identification value incrementally:

Start with `p.identification()`. Each method returns `IdentificationBuilder` and can be chained.

| Method | Description |
| --- | --- |
| `type(val: string)` | Set document type (passport, drivers_license, etc.) |
| `number(val: string)` | Set document number |
| `issuer(val: string \| undefined)` | Set issuing authority or country |
| `issueDate(val: string \| undefined)` | Set issue date (YYYY-MM-DD) |
| `expiryDate(val: string \| undefined)` | Set expiry date (YYYY-MM-DD) |
| `from(value: Identification)` | Initialize from existing Identification |

Terminal methods return `Identification`.

| Method | Description |
| --- | --- |
| `build()` | Build and validate |

### Static Methods

| Method | Returns | Description |
| --- | --- | --- |
| `parse(input: unknown)` | `Identification` | Parse unknown input (throws on error) |
| `safeParse(input: unknown)` | `Result<Identification>` | Parse unknown input (returns result object) |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `type` | `string` | Type of identification document. |
| `number` | `string` | Document number or identifier. |
| `issuer` | `string?` | Issuing authority, country, or organization. |
| `issueDate` | `string?` | Date of issue in YYYY-MM-DD format. |
| `expiryDate` | `string?` | Expiration date in YYYY-MM-DD format. |

## Common ID Types

| Type              | Description                   |
| ----------------- | ----------------------------- |
| `passport`        | International travel passport |
| `drivers_license` | Driver's license              |
| `national_id`     | National identity card        |
| `ssn`             | Social Security Number (US)   |
| `tax_id`          | Tax identification number     |
| `voter_id`        | Voter registration card       |
| `military_id`     | Military identification       |

## Validation

The Identification primitive validates:

* `type` must be a non-empty string
* `number` must be a non-empty string
* `issueDate` and `expiryDate` must be valid dates if provided

```ts
// Valid
p.identification({ type: 'passport', number: 'AB123456' })
p.identification({
  type: 'drivers_license',
  number: 'D9876543',
  issuer: 'CA',
  expiryDate: '2028-12-31'
})

// Invalid - throws Error
p.identification({ type: 'passport' })

p.identification({ type: '', number: 'AB123456' })
```

## Related

* [Primitives Overview](/sdk/primitives) - All available primitives
* [Person](/sdk/primitives/person) - Person information
* [Identification Field](/sdk/artifacts/form/field#entity) - Identification field type
* [Identification Schema](/schemas/primitives/identification) - JSON Schema definition