List recalls affecting a specific batch/lot

curl --request GET \
  --url https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "title": "<string>",
      "created": "2023-11-07T05:31:56Z",
      "description": "",
      "hazard": "",
      "remedy": "",
      "public_url": "",
      "company_name": "",
      "recall_date": "2023-12-25",
      "jurisdictions": [
        "<string>"
      ]
    }
  ],
  "pagination": {
    "page": 2,
    "page_size": 2,
    "total_count": 1,
    "total_pages": 2,
    "has_next": true,
    "has_previous": true
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

Compliance

List recalls affecting a specific batch/lot

Retrieve every open recall affecting a specific (GTIN, batch) pair, sourced from FDA, USDA FSIS, CPSC, and Health Canada. Where GET /products/{gtin}/recalls returns every open recall for the GTIN, this endpoint filters to recalls whose lot_codes field matches the supplied batch value — by exact match, by inclusion in a numeric range ("lots 20261001 through 20261015"), or by wildcard prefix ("LOT-2026-*"). Recalls that do not restrict to specific lots are always included (regulator did not narrow the scope, so every batch is considered affected). Same filter / ordering / pagination contract as the GTIN-only endpoint. Designed for consumer scans of GS1 Digital Link URIs encoding batch identity in AI 10: /01/{gtin}/10/{batch} — call this endpoint with the scanned GTIN and batch to answer ‘is this lot under recall?’ rather than ‘are any batches of this GTIN recalled?’.

GET

compliance

api

products

{gtin}

batches

{batch}

recalls

List recalls affecting a specific batch/lot

curl --request GET \
  --url https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/compliance/api/v1/products/{gtin}/batches/{batch}/recalls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "title": "<string>",
      "created": "2023-11-07T05:31:56Z",
      "description": "",
      "hazard": "",
      "remedy": "",
      "public_url": "",
      "company_name": "",
      "recall_date": "2023-12-25",
      "jurisdictions": [
        "<string>"
      ]
    }
  ],
  "pagination": {
    "page": 2,
    "page_size": 2,
    "total_count": 1,
    "total_pages": 2,
    "has_next": true,
    "has_previous": true
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "timestamp": "<string>",
  "retryable": false,
  "retry_after": 123,
  "owner_action_required": true,
  "details": "<unknown>"
}

Authorizations

X-API-Key

string

header

required

Path Parameters

gtin

string

required

GTIN-8, GTIN-12, GTIN-13, or GTIN-14 barcode digits (no spaces, no hyphens). Shorter forms are zero-left-padded to GTIN-14 server-side. Returns 404 if no product matches the normalized GTIN; 422 if the value is not a valid GTIN.

Required string length: 8 - 14

Pattern: ^\d{8,14}$

batch

string

required

Batch / lot identifier from GS1 AI 10 (e.g. BATCH-2026-042, LOT-A123). Matched case-insensitively against each recall's lot_codes field with three pattern kinds: exact, range (20261001-20261015), and wildcard suffix (LOT-2026-*). If a recall does not restrict to specific lots (empty lot_codes), every batch of the GTIN is considered affected and the recall is always returned. Maximum length 64 characters.

Required string length: 1 - 64

Query Parameters

status

enum<string>

Optional filter on the recall lifecycle state. Only ONGOING and UNKNOWN will ever return rows from this endpoint (others are excluded upstream); the parameter is exposed for completeness and forward compatibility.

Available options:

ONGOING,

COMPLETED,

TERMINATED,

UNKNOWN

severity

enum<string>

Optional filter on risk class. CLASS_I = highest risk (serious adverse health consequences or death). Useful for surfacing only the most dangerous open recalls.

Available options:

CLASS_I,

CLASS_II,

CLASS_III,

UNKNOWN

source_system

enum<string>

Optional filter on the regulator that issued the recall. One of FDA, FSIS, CPSC, or HEALTH_CANADA.

Available options:

FDA,

FSIS,

CPSC,

HEALTH_CANADA

ordering

string

Sort key. Allowed values: recall_date, -recall_date, severity, -severity. Prefix with - for descending. Omit to use the default -recall_date, -created ordering. Returns 400 for any other value.

Pattern: ^-?(recall_date|severity)$

page

integer

default:1

Page number (1-indexed).

Required range: x >= 1

page_size

integer

default:25

Number of items per page (max 100).

Required range: 1 <= x <= 100

Response

data

RecallOut · object[]

required

Items on the current page, each conforming to the endpoint's item schema. Empty when the result set is empty or page is past the end.

Show child attributes

pagination

PaginationMeta · object

required

Pagination envelope describing position within the full result set.

Show child attributes

Example:

{
  "has_next": true,
  "has_previous": false,
  "page": 1,
  "page_size": 25,
  "total_count": 342,
  "total_pages": 14
}

Overview

Account

Products

Brands

Locations

Retailers

Search

GS1 Digital Link

EPCIS 2.0

Integrations

Billing

Scanner

Compliance

Certifications

Sustainability

Notifications

Dashboard

Analytics

Agent

Substances

BYOS

Content

Signals

List recalls affecting a specific batch/lot

Authorizations

Path Parameters

Query Parameters

Response