Issue a brand recall

curl --request POST \
  --url https://www.closient.com/compliance/api/v1/recalls \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "gtin": "<string>",
  "reason": "<string>",
  "remedy": "<string>",
  "title": "",
  "scopes": [
    {
      "values": [
        "<string>"
      ],
      "start": "2023-12-25",
      "end": "2023-12-25"
    }
  ]
}
'

import requests

url = "https://www.closient.com/compliance/api/v1/recalls"

payload = {
    "gtin": "<string>",
    "reason": "<string>",
    "remedy": "<string>",
    "title": "",
    "scopes": [
        {
            "values": ["<string>"],
            "start": "2023-12-25",
            "end": "2023-12-25"
        }
    ]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    gtin: '<string>',
    reason: '<string>',
    remedy: '<string>',
    title: '',
    scopes: [{values: ['<string>'], start: '2023-12-25', end: '2023-12-25'}]
  })
};

fetch('https://www.closient.com/compliance/api/v1/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/recalls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'gtin' => '<string>',
    'reason' => '<string>',
    'remedy' => '<string>',
    'title' => '',
    'scopes' => [
        [
                'values' => [
                                '<string>'
                ],
                'start' => '2023-12-25',
                'end' => '2023-12-25'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/compliance/api/v1/recalls"

	payload := strings.NewReader("{\n  \"gtin\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"remedy\": \"<string>\",\n  \"title\": \"\",\n  \"scopes\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ],\n      \"start\": \"2023-12-25\",\n      \"end\": \"2023-12-25\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.closient.com/compliance/api/v1/recalls")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"gtin\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"remedy\": \"<string>\",\n  \"title\": \"\",\n  \"scopes\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ],\n      \"start\": \"2023-12-25\",\n      \"end\": \"2023-12-25\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/compliance/api/v1/recalls")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"gtin\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"remedy\": \"<string>\",\n  \"title\": \"\",\n  \"scopes\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ],\n      \"start\": \"2023-12-25\",\n      \"end\": \"2023-12-25\"\n    }\n  ]\n}"

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

{
  "id": "<string>",
  "title": "<string>",
  "created": "2023-11-07T05:31:56Z",
  "hazard": "",
  "remedy": "",
  "public_url": "",
  "company_name": "",
  "recall_date": "2023-12-25",
  "scopes": [
    {
      "values": [
        "<string>"
      ],
      "date_ai": "",
      "pack_date_start": "2023-12-25",
      "pack_date_end": "2023-12-25"
    }
  ]
}

{
  "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

Issue a brand recall

Issue a recall for one of your own products at any granularity: whole product (omit scopes or send []), a lot set (LOT_LIST), a serial set (SERIAL_SET), a printed-date window (DATE_WINDOW), or any mix — multiple scopes OR-combine, so a unit is affected if it matches any of them. Thin over the same issue_recall service the dashboard uses: it creates a BRAND_ISSUED recall, writes the scopes, links the brand-UI lot/serial pointers, and fires the consumer notification fan-out. Requires the contribute role on the product’s organization. Returns 422 if a value-set scope exceeds the configured cap or a date window is malformed.

POST

compliance

api

recalls

Issue a brand recall

curl --request POST \
  --url https://www.closient.com/compliance/api/v1/recalls \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "gtin": "<string>",
  "reason": "<string>",
  "remedy": "<string>",
  "title": "",
  "scopes": [
    {
      "values": [
        "<string>"
      ],
      "start": "2023-12-25",
      "end": "2023-12-25"
    }
  ]
}
'

import requests

url = "https://www.closient.com/compliance/api/v1/recalls"

payload = {
    "gtin": "<string>",
    "reason": "<string>",
    "remedy": "<string>",
    "title": "",
    "scopes": [
        {
            "values": ["<string>"],
            "start": "2023-12-25",
            "end": "2023-12-25"
        }
    ]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    gtin: '<string>',
    reason: '<string>',
    remedy: '<string>',
    title: '',
    scopes: [{values: ['<string>'], start: '2023-12-25', end: '2023-12-25'}]
  })
};

fetch('https://www.closient.com/compliance/api/v1/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/recalls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'gtin' => '<string>',
    'reason' => '<string>',
    'remedy' => '<string>',
    'title' => '',
    'scopes' => [
        [
                'values' => [
                                '<string>'
                ],
                'start' => '2023-12-25',
                'end' => '2023-12-25'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/compliance/api/v1/recalls"

	payload := strings.NewReader("{\n  \"gtin\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"remedy\": \"<string>\",\n  \"title\": \"\",\n  \"scopes\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ],\n      \"start\": \"2023-12-25\",\n      \"end\": \"2023-12-25\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.closient.com/compliance/api/v1/recalls")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"gtin\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"remedy\": \"<string>\",\n  \"title\": \"\",\n  \"scopes\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ],\n      \"start\": \"2023-12-25\",\n      \"end\": \"2023-12-25\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/compliance/api/v1/recalls")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"gtin\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"remedy\": \"<string>\",\n  \"title\": \"\",\n  \"scopes\": [\n    {\n      \"values\": [\n        \"<string>\"\n      ],\n      \"start\": \"2023-12-25\",\n      \"end\": \"2023-12-25\"\n    }\n  ]\n}"

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

{
  "id": "<string>",
  "title": "<string>",
  "created": "2023-11-07T05:31:56Z",
  "hazard": "",
  "remedy": "",
  "public_url": "",
  "company_name": "",
  "recall_date": "2023-12-25",
  "scopes": [
    {
      "values": [
        "<string>"
      ],
      "date_ai": "",
      "pack_date_start": "2023-12-25",
      "pack_date_end": "2023-12-25"
    }
  ]
}

{
  "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

Body

application/json

Request body to issue a brand recall at any granularity.

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}$

reason

string

required

The safety issue / hazard, shown to consumers and notified subscribers.

Minimum string length: 1

remedy

string

required

The action a consumer should take (return, discard, contact support).

Minimum string length: 1

title

string

default:""

Optional recall title. Defaults to a product + scope summary when blank.

scopes

RecallScopeIn · object[]

The recall's scope list. Omit or send an empty list for a whole-product recall. Multiple scopes OR-combine.

Maximum array length: 100

Show child attributes

Response

Created

A brand-issued recall including its scope list (C-4118).

A recall with an empty scopes list is a whole-product recall (every unit of the GTIN is affected). Otherwise the scopes OR-combine: a unit is affected if it matches any scope.

string<shortuuid>

required

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22

Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$

title

string

required

Recall headline.

Maximum string length: 1000

status

enum<string>

required

Lifecycle state. TERMINATED means withdrawn.

Available options:

ONGOING,

COMPLETED,

TERMINATED,

UNKNOWN

severity

enum<string>

required

Risk classification; UNKNOWN for brand recalls by default.

Available options:

CLASS_I,

CLASS_II,

CLASS_III,

UNKNOWN

created

string<date-time>

required

Server-side UTC timestamp of issuance.

hazard

string

default:""

The safety issue (maps to the issue-time reason).

remedy

string

default:""

What a consumer should do.

public_url

string

default:""

Link shown to consumers — the product's resolver page for brand recalls.

Maximum string length: 500

company_name

string

default:""

Issuing brand's organization name.

Maximum string length: 500

recall_date

string<date> | null

Date the recall was issued (YYYY-MM-DD).

scopes

RecallScopeOut · object[]

The recall's granularity. Empty == whole product; otherwise LOT_LIST / SERIAL_SET / DATE_WINDOW predicates.

Show child attributes

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

Issue a brand recall

Authorizations

Body

Response