# Identifiers & Validators API

> Validate phone E.164 numbers, GTIN check digits, ISBN/ISSN check characters, and EORI shape from caller input. Pure structure checks — not directories or live registries.

Each paid operation uses a fixed USDC price on Base with the x402 exact scheme. Unpaid GET, HEAD, and POST return 402 payment terms (POST validates the body only after payment terms are satisfied). A request that carries payment-signature is not yet charged: settlement happens only after a successful (2xx) result. HTTP 4xx/5xx are not charged. Coverage bodies with status complete, partial, or failed all return HTTP 200 and are charged at the full listed price. Settled 2xx responses include a payment-response header; 4xx/5xx do not.

Follow https://www.brainiac.software/agent-instructions.txt for install, payment pins, idempotency, and billing rules.

- Product: https://www.brainiac.software/api/identifiers
- Docs: https://www.brainiac.software/api/identifiers/docs
- OpenAPI: https://www.brainiac.software/api/identifiers/openapi.json
- Contact: support@brainiac.software (https://www.brainiac.software/contact)

## Operations

### POST /api/v1/identifiers/phone-e164-validate

$0.02 USDC. Normalise and validate a phone number with bundled libphonenumber metadata. Returns validity, E.164, region, calling code, and number type when known. Not a live carrier lookup.

Inputs: phone, defaultRegion?

Docs: https://www.brainiac.software/api/identifiers/docs#identifiers-phone-e164-validate

Example request:

```json
{
  "phone": "+1 650-253-0000",
  "defaultRegion": "US"
}
```

Example response:

```json
{
  "retrievedAt": "2026-11-14T20:00:00.000Z",
  "input": "+1 650-253-0000",
  "defaultRegion": "US",
  "valid": true,
  "possible": true,
  "e164": "+16502530000",
  "region": "US",
  "countryCallingCode": "1",
  "nationalNumber": "6502530000",
  "type": "fixed_line_or_mobile",
  "sources": [
    {
      "source": "libphonenumber-js metadata (ITU/E.164)",
      "url": "https://github.com/catamphetamine/libphonenumber-js",
      "retrievedAt": "2026-11-14T20:00:00.000Z",
      "status": "ok"
    }
  ],
  "limitations": [
    "This validates structure against bundled libphonenumber metadata. It is not a live carrier lookup."
  ]
}
```

### POST /api/v1/identifiers/gtin-checksum-validate

$0.01 USDC. Validate GTIN-8, GTIN-12, GTIN-13, or GTIN-14 check digits with the published GS1 algorithm. Company prefix ownership is not looked up.

Inputs: gtin

Docs: https://www.brainiac.software/api/identifiers/docs#identifiers-gtin-checksum-validate

Example request:

```json
{
  "gtin": "5901234123457"
}
```

Example response:

```json
{
  "retrievedAt": "2026-11-14T20:00:00.000Z",
  "gtin": "5901234123457",
  "length": 13,
  "lengthOk": true,
  "formatOk": true,
  "expectedCheckDigit": 7,
  "observedCheckDigit": 7,
  "checksumOk": true,
  "valid": true,
  "sources": [
    {
      "source": "GS1 check digit algorithm",
      "url": "https://www.gs1.org/services/check-digit-calculator",
      "retrievedAt": "2026-11-14T20:00:00.000Z",
      "status": "ok"
    }
  ],
  "limitations": [
    "Only GTIN-8/12/13/14 check digits are validated."
  ]
}
```

### POST /api/v1/identifiers/isbn-issn-validate

$0.01 USDC. Validate ISBN-10, ISBN-13, or ISSN check characters after stripping spaces and hyphens. Bibliographic metadata is not looked up.

Inputs: value, kind?

Docs: https://www.brainiac.software/api/identifiers/docs#identifiers-isbn-issn-validate

Example request:

```json
{
  "value": "978-0-306-40615-7",
  "kind": "isbn"
}
```

Example response:

```json
{
  "retrievedAt": "2026-11-14T20:00:00.000Z",
  "kind": "isbn-13",
  "value": "9780306406157",
  "formatOk": true,
  "expectedCheckDigit": 7,
  "observedCheckDigit": 7,
  "checksumOk": true,
  "valid": true,
  "isbn13Equivalent": "9780306406157",
  "sources": [
    {
      "source": "ISBN-10 / ISBN-13 check digit rules",
      "url": "https://www.isbn-international.org/",
      "retrievedAt": "2026-11-14T20:00:00.000Z",
      "status": "ok"
    }
  ],
  "limitations": [
    "Title or publisher metadata is not looked up."
  ]
}
```

### POST /api/v1/identifiers/eori-format-validate

$0.01 USDC. Validate Economic Operators Registration and Identification (EORI) shape: ISO country prefix plus up to 15 alphanumeric characters. Does not confirm the number is issued.

Inputs: eori

Docs: https://www.brainiac.software/api/identifiers/docs#identifiers-eori-format-validate

Example request:

```json
{
  "eori": "GB123456789000"
}
```

Example response:

```json
{
  "retrievedAt": "2026-11-14T20:00:00.000Z",
  "eori": "GB123456789000",
  "country": "GB",
  "length": 14,
  "formatOk": true,
  "valid": true,
  "sources": [
    {
      "source": "EU EORI structure (country code + national identifier)",
      "url": "https://taxation-customs.ec.europa.eu/",
      "retrievedAt": "2026-11-14T20:00:00.000Z",
      "status": "ok"
    }
  ],
  "limitations": [
    "This checks EORI shape only. It does not confirm the number is issued."
  ]
}
```