API Documentation

The IsValid API is a REST API that returns JSON responses. All endpoints are available at the base URL:

https://api.isvalid.dev

All requests must include a valid API key in the Authorization header. Responses include a valid boolean field indicating whether the provided value passed validation.

API usage is limited based on your subscription plan. Rate limits reset at midnight UTC each day.

When you exceed your limit, the API returns HTTP 429. The response includes a Retry-After header indicating when your quota resets.

The API uses standard HTTP status codes. Error responses always include a JSON body with a message field describing the error.

Error Response Body

{
  "error": "Missing required query parameter: value"
}

Parses and validates boolean-like string values. Accepts common boolean representations including true, false, yes, no, 1, 0, on, off.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/boolean?value=yes"

Response Fields

Example Response

{
  "valid": true,
  "normalized": true
}

Validates and parses a CSS color string in hex, RGB, or HSL format. Automatically detects the input format and returns all three representations together with the alpha channel. Supports shorthand hex (#rgb), full hex (#rrggbb), hex with alpha (#rrggbbaa), rgb(), rgba(), hsl(), and hsla().

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/color?value=%23ff0000"

Response Fields

Example Response

{
  "valid": true,
  "format": "hex",
  "r": 255,
  "g": 0,
  "b": 0,
  "h": 0,
  "s": 100,
  "l": 50,
  "alpha": 1,
  "hex": "#ff0000"
}

Validates credit card numbers using the Luhn algorithm. Accepts cards from Visa, Mastercard, American Express, Discover, JCB, Diners Club, and UnionPay. The card number is sent in the request body to avoid logging sensitive data in server access logs.

Request Body

{
  "number": "4111111111111111"
}

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "4111111111111111"}' \
  "https://api.isvalid.dev/v0/credit-card"

Response Fields

Example Response

{
  "valid": true,
  "network": "Visa",
  "length": 16,
  "luhn": true
}

Validates date strings against multiple common formats. Checks both format correctness and logical validity (e.g., month 1-12, day within month bounds, leap year rules).

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/date?value=2026-02-19&format=YYYY-MM-DD"

Response Fields

Example Response

{
  "valid": true,
  "iso": "2026-02-19"
}

Validates email addresses. Checks RFC 5322 format compliance, domain structure, and optionally verifies that the domain has valid MX records.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/email?value=user@example.com&checkMx=true"

Response Fields

Example Response

{
  "valid": true,
  "local": "user",
  "domain": "example.com",
  "mxValid": true
}

Validates the structure of a JSON Web Token (JWT) and decodes its header and payload. Does not verify the signature — only the token format and structure are checked. Useful for inspecting token contents without a secret or public key.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/jwt?value=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

Response Fields

Example Response

{
  "valid": true,
  "algorithm": "HS256",
  "header": { "alg": "HS256", "typ": "JWT" },
  "payload": { "sub": "1234567890", "name": "John Doe", "iat": 1516239022 },
  "issuedAt": "2018-01-18T01:30:22.000Z",
  "expiresAt": null,
  "expired": null
}

Validates Polish National Court Register (Krajowy Rejestr Sądowy) numbers. A KRS number is a unique 10-digit sequential identifier assigned to entities registered in Poland. The input may be provided with or without leading zeros — the response always returns the canonical zero-padded 10-digit form. Optionally fetches live entity data from the official Polish government KRS API.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/pl/krs?value=0000896246&lookup=true"

Response Fields

Example Response

{
  "valid": true,
  "number": "0000896246",
  "krs": {
    "checked": true,
    "found": true,
    "krs": "0000896246",
    "rejestr": "P",
    "name": "CREACT.DEV SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ",
    "legalForm": "SPÓŁKA Z OGRANICZONĄ ODPOWIEDZIALNOŚCIĄ",
    "nip": "5252859428",
    "regon": "38877001300000",
    "hasOppStatus": false,
    "registeredAt": "21.04.2021",
    "dataAsOf": "15.01.2026",
    "lastEntryAt": "14.01.2026",
    "address": {
      "city": "WARSZAWA",
      "voivodeship": "MAZOWIECKIE",
      "street": "UL. ŚWIĘTOKRZYSKA",
      "houseNumber": "30",
      "flatNumber": "63",
      "postalCode": "00-116",
      "country": "POLSKA",
      "website": "HTTPS://CREACT.DEV/"
    }
  }
}

Validates Polish national identification numbers (PESEL). Checks the checksum digit, extracts the birth date and gender encoded in the number.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/pl/pesel?value=90090515836"

Response Fields

Example Response

{
  "valid": true,
  "birthDate": "1990-09-05",
  "gender": "male",
  "isOver15": true,
  "isOver18": true,
  "isOver21": true
}

Validates phone numbers for 200+ countries. Returns the country, calling code, national number, line type, and formatted representations (E.164, national, international). Accepts numbers in E.164 format (+48600123456) or in national format when a countryCode hint is provided.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/phone?value=%2B48600123456"

Response Fields

Example Response — valid

{
  "valid": true,
  "countryCode": "PL",
  "callingCode": "48",
  "nationalNumber": "600123456",
  "type": "MOBILE",
  "e164": "+48600123456",
  "national": "600 123 456",
  "international": "+48 600 123 456"
}

Example Response — valid (US toll-free)

{
  "valid": true,
  "countryCode": "US",
  "callingCode": "1",
  "nationalNumber": "8005550100",
  "type": "TOLL_FREE",
  "e164": "+18005550100",
  "national": "(800) 555-0100",
  "international": "+1 800-555-0100"
}

Example Response — invalid

{
  "valid": false
}

Validates Polish statistical identification numbers (REGON). Supports both the 9-digit format used by legal entities and the 14-digit format used by local units. Verification is based on the official checksum algorithm.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/pl/regon?value=590096454"

Response Fields

Example Response

{
  "valid": true,
  "type": "entity"
}

Validates a semantic version string according to the Semver 2.0.0 specification and parses it into its components: major, minor, patch, pre-release identifiers, and build metadata.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/semver?value=1.2.3-alpha.1%2Bbuild.456"

Response Fields

Example Response

{
  "valid": true,
  "major": 1,
  "minor": 2,
  "patch": 3,
  "prerelease": ["alpha", "1"],
  "build": ["build", "456"]
}

Validates and parses a URL, breaking it down into its individual components: protocol, domain, path, and query parameters. Uses the WHATWG URL Standard for parsing. Returns valid: false for any string that cannot be parsed as a URL.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/url?value=https://example.com/path?foo=bar"

Response Fields

Example Response

{
  "valid": true,
  "protocol": "https",
  "domain": "example.com",
  "path": "/path",
  "query": { "foo": "bar" },
  "port": null,
  "hash": null
}

Validates Universally Unique Identifiers (UUIDs) as defined by RFC 4122. Checks the standard 8-4-4-4-12 hexadecimal format and, when a version is specified, additionally verifies the version nibble and the RFC 4122 variant bits.

Query Parameters

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/uuid?value=550e8400-e29b-41d4-a716-446655440000&version=4"

Response Fields

Example Response

{
  "valid": true,
  "version": 4
}

Validates VAT identification numbers (VATIN) for EU and selected non-EU countries. Checks format compliance per country-specific rules. The value may include the country prefix (e.g. DE123456789) or consist of the number only (e.g. 123456789). Spaces, hyphens, and dots are stripped automatically.

Query Parameters

Supported Countries

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/vat?value=DE123456789&countryCode=DE&checkVies=true"

Response Fields

The vies object

When the VIES check was skipped or failed (checked: false):

When the VIES check succeeded (checked: true):

Example Response

{
  "valid": true,
  "countryCode": "DE",
  "countryName": "Germany",
  "isEU": true,
  "vies": {
    "checked": true,
    "valid": true,
    "name": "EXAMPLE GMBH",
    "address": "MUSTERSTRASSE 1\n10115 BERLIN"
  }
}