API V1

Endpoint: check

/api/v1/check?card_id=cc-nnnn-x
Get-Parameter:
card_id

Latest Card Format:
cc-nnnn-x
Old Card Format:
nnnnx or nnnn
Digits:
cc = Company, 2 or 3 digits
nnnn = Customer number, i digits
x = Checknumber, 1 digit

Possible Result:

HTTP 200
card number is valid, returns expiry date as plain text, format:
yyyy-mm-dd
HTTP 400
card number not valid, returns error message in plain text:
card format not valid
HTTP 404
card number not found, returns error message in plain text:
card not found
HTTP 410
card number expired, returns plain text with date:
card expired at yyyy-mm-dd

Examples:

valid
/api/v1/check?card_id=80-12345-3
not found
/api/v1/check?card_id=54685464
expired
/api/v1/check?card_id=80-7654321-0

Endpoint: check_details

Same parameter and card formats as /api/v1/check, but returns a richer JSON payload including card details, dealer details, period information and basic user metadata.

Endpoint:
/api/v1/check_details?card_id=cc-nnnn-x
Get-Parameter:
card_id

Possible Result (check_details):

HTTP 200
Card found and not expired. Returns JSON with:
  • status = "ok"
  • message = "card is valid"
  • expiry_date = expiry timestamp string (example: 2026-04-26T00:00:00.000000Z)
  • old_format = boolean; true if the lookup used old-format fallback
  • details = card object
  • dealer = dealer object (or null if no dealer is linked)
  • periods = array of period objects sorted by end_date ascending
  • user = object with basic user metadata (fields may be null)
HTTP 404
Card not found. Returns JSON:
  • status = "error"
  • message = "card not found"
  • old_format = boolean
HTTP 410
Card found but expired. Returns JSON with the same keys as HTTP 200, but:
  • status = "error"
  • message = "card expired"

Response JSON keys (check_details):

Top-level keys:
  • status: "ok" or "error"
  • message: "card is valid", "card expired", "card not found"
  • old_format: boolean; indicates whether the input matched an older lookup style
  • expiry_date: card expiry timestamp (string)
  • details: card object (see fields below)
  • dealer: dealer object or null
  • periods: array of period objects
  • user: minimal user metadata object
details (card object):
Example fields (may vary with schema/model):
  • id, created_at, updated_at
  • activation_date
  • dealer_identifier, code, check_number
  • user_id
  • note, status, last_printed_at
dealer (dealer object):
Dealer meta such as name, contact data and location. Example fields:
  • id, identifier, name, email, web
  • address, postal_code, city, country, phone
  • latitude, longitude
  • certified fields, visible, card printing fields (card_name, card_contact, ...)
periods array:
Array of period objects (sorted by end_date ascending). Typical fields:
  • id, card_id
  • start_date (YYYY-MM-DD)
  • end_date (YYYY-MM-DD)
  • created_at, updated_at
user object:
Minimal user metadata (fields may be null when not linked):
  • id, created_at, updated_at
  • email_verified_at
  • last_seen_at
  • user_lab_id
  • external_customer_id

Examples (check_details):

valid (HTTP 200)
/api/v1/check_details?card_id=80-12345-3
not found (HTTP 404)
/api/v1/check_details?card_id=54685464
expired (HTTP 410)
/api/v1/check_details?card_id=80-7654321-0

Example success response (HTTP 200):

{
   "expiry_date":"2026-04-26T00:00:00.000000Z",
   "details":{
      "id":2676,
      "created_at":"2025-02-07T10:51:00.000000Z",
      "updated_at":"2025-07-22T12:51:46.000000Z",
      "activation_date":"2021-01-10T00:00:00.000000Z",
      "dealer_identifier":80,
      "code":"10480",
      "check_number":"3",
      "user_id":3,
      "note":"Test-Karte!",
      "status":null,
      "last_printed_at":null
   },
   "old_format":false,
   "dealer":{
      "id":6,
      "created_at":"2023-03-18T10:56:57.000000Z",
      "updated_at":"2025-07-24T04:47:56.000000Z",
      "name":"Fauna Marin GmbH",
      "contact":"Claude Schuhmacher",
      "email":"sales@faunamarin.de",
      "web":"https:\/\/www.faunamarincorals.de\/",
      "web_reefersclub":"https:\/\/www.faunamarincorals.de\/Reefers-Club\/REEFERSCLUBV",
      "address":"Gottlieb-Binder-Str. 9",
      "phone":"+49 (0) 7031 613 680 - 0",
      "latitude":48.6333,
      "longitude":9.0167,
      "certified":"2000-01-01",
      "certified_balling":"2000-01-01",
      "certified_bolus":"2024-01-01",
      "identifier":80,
      "description":null,
      "country":"DE",
      "postal_code":"71088",
      "city":"Holzgerlingen",
      "note":null,
      "logo_file":"faunamarincorals.png",
      "visible":1,
      "card_name":"Fauna Marin GmbH",
      "card_contact":"Gaby Hollmann",
      "card_email":"sales@faunamarin.de",
      "card_address":"Gottlieb-Binder-Str. 9",
      "card_phone":"+49 (0) 7031 613 680 - 0",
      "card_city":"Holzgerlingen",
      "card_postal_code":"71088",
      "card_country":"DE"
   },
   "periods":[
      {
         "id":512,
         "created_at":"2025-04-25T19:13:17.000000Z",
         "updated_at":"2025-04-25T19:13:17.000000Z",
         "card_id":2676,
         "start_date":"2021-01-10",
         "end_date":"2022-01-10"
      },
      {
         "id":513,
         "created_at":"2025-04-25T19:14:04.000000Z",
         "updated_at":"2025-04-25T19:14:04.000000Z",
         "card_id":2676,
         "start_date":"2022-08-25",
         "end_date":"2023-09-25"
      },
      {
         "id":688,
         "created_at":"2025-04-26T20:59:52.000000Z",
         "updated_at":"2027-04-26T19:46:50.000000Z",
         "card_id":2676,
         "start_date":"2025-04-26",
         "end_date":"2026-04-26"
      }
   ],
   "user":{
      "id":3,
      "created_at":"2023-01-26T13:11:54.000000Z",
      "updated_at":"2026-02-27T14:24:35.000000Z",
      "email_verified_at":"2025-05-22T05:08:33.000000Z",
      "last_seen_at":"2026-02-27 14:24:35",
      "user_lab_id":17,
      "external_customer_id":"C10480"
   },
   "status":"ok",
   "message":"card is valid"
}