Check agency filings (Comply) | border.bot API docs

POST https://api.border.bot/v1/comply

Requires an access token from an API client (Authorization: Bearer <access_token>).

For each item, what each government agency that flags its tariff line needs for it to clear: file a certificate (with the regulations it certifies to, the certificate kind and any testing exemptions) or disclaim (the waiver and intended-use code), from the agency’s own files (for the US, CPSC’s eFiling HTS list, citation and exception codes and disclaim guidance) and the customs PGA flags. Each regulation cited comes with what complying takes besides meeting it: testing by a third party the agency accepts (for CPSC, a children’s product’s rules listed in 16 CFR 1112.15, with the test methods and the laboratory search) and labelling (the rule’s marking, labelling and warning sections). Agencies flagged but without rules loaded come back flagged; agencies limits the answer to the ones named (CPSC, FDA). Whether a regulation applies is decided per product and returned with its probability; answers below the review threshold have needsReview. An item without an hsCode is classified for the destination first (returned as its classification). Each check is kept as your evidence (GET /comply lists them). Costs the Comply price per item in credits (GET /pricing lists it), plus a classification in classifyMode for each item without a code; each is refunded if it fails. Limited to 10 checks per minute per workspace (up to 100 items each). Destinations without coverage return 422 unsupported_country.

API client scope: compliance.

Headers#

Name	Type	Required	Description
`idempotency-key`	string	no	Make retries safe: a repeat with the same key returns the original result without charging again (keys are scoped to your workspace).

Request body (JSON)#

Name	Type	Required	Description
`destinationCountry`	string	yes	Ship-to country: its agencies are checked. ISO 3166-1 alpha-2, case-insensitive.
`originCountry`	string	no	Where the goods ship from (kept with the check). ISO 3166-1 alpha-2, case-insensitive.
`items`	ComplyItem[]	yes	1–100 items.
`reference`	string	no	Your reference (an order or entry id), kept with the check as evidence.
`agencies`	string[]	no	Only these agencies: a full name or its initials (`CPSC`, `FDA`, `EPA`, `APHIS`). Omitted: every agency that flags each line.
`classifyMode`	string	no	The classification mode for items without an `hsCode` (omitted: the default mode). Each classification is charged its mode’s price.

Responses#

200: One answer per agency per item (an empty filings list: no agency flags the line). (ComplyResponse)
400: Invalid input (invalid_input). (Error)
401: Missing, invalid or expired access token, or a revoked or expired API client (unauthorized). (Error)
402: Not enough credits (insufficient_credits). Nothing was charged. (Error)
403: Workspace suspended, action disabled, or the client lacks the scope (org_suspended, action_disabled, forbidden). (Error)
409: A request with this Idempotency-Key is still in progress (conflict). (Error)
422: Agency filing checks are not available for this destination (unsupported_country). (Error)
429: Rate limited (rate_limited). Retry after Retry-After seconds; RateLimit says which limit was hit (r=0, t seconds until its window ends) and RateLimit-Policy its quota. (Error)
500: Unexpected error (internal). (Error)
502: The engine failed (upstream_error). The credits are refunded automatically. (Error)
504: The engine timed out (upstream_timeout). The credits are refunded automatically. (Error)

Example request#

curl -X POST https://api.border.bot/v1/comply \
  -H "Authorization: Bearer $BORDERBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destinationCountry": "US",
    "items": [
      {
        "sku": "TOY-STACK-01",
        "title": "Wooden stacking toy for ages 3+",
        "hsCode": "9503.00.0073"
      },
      {
        "sku": "BEAR-01",
        "title": "Plush teddy bear",
        "description": "Polyester fill, for toddlers aged 1 and up"
      }
    ]
  }'

const response = await fetch('https://api.border.bot/v1/comply', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BORDERBOT_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "destinationCountry": "US",
    "items": [
      {
        "sku": "TOY-STACK-01",
        "title": "Wooden stacking toy for ages 3+",
        "hsCode": "9503.00.0073"
      },
      {
        "sku": "BEAR-01",
        "title": "Plush teddy bear",
        "description": "Polyester fill, for toddlers aged 1 and up"
      }
    ]
  }),
});
const data = await response.json();

import os, uuid

import requests

response = requests.post(
    "https://api.border.bot/v1/comply",
    headers={"Authorization": f"Bearer {os.environ['BORDERBOT_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "destinationCountry": "US",
        "items": [
            {
                "sku": "TOY-STACK-01",
                "title": "Wooden stacking toy for ages 3+",
                "hsCode": "9503.00.0073",
            },
            {
                "sku": "BEAR-01",
                "title": "Plush teddy bear",
                "description": "Polyester fill, for toddlers aged 1 and up",
            },
        ],
    },
)
data = response.json()

<?php
$ch = curl_init('https://api.border.bot/v1/comply');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BORDERBOT_TOKEN'),
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'destinationCountry' => 'US',
        'items' => [
            [
                'sku' => 'TOY-STACK-01',
                'title' => 'Wooden stacking toy for ages 3+',
                'hsCode' => '9503.00.0073',
            ],
            [
                'sku' => 'BEAR-01',
                'title' => 'Plush teddy bear',
                'description' => 'Polyester fill, for toddlers aged 1 and up',
            ],
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Example response (200)#

JSON

{
  "data": {
    "destination": "US",
    "items": [
      {
        "sku": "BEAR-01",
        "title": "Plush teddy bear",
        "hsCode": "9503000090",
        "classification": {
          "hsCode": "9503000090",
          "hsCodeFormatted": "9503.00.00.90",
          "description": "Other",
          "confidence": "high",
          "probability": 0.91,
          "mode": "pro"
        },
        "filings": [
          {
            "country": "US",
            "agency": "U.S. Consumer Product Safety Commission",
            "outcome": "file",
            "requirement": "may_be_required",
            "flags": [
              {
                "flag": "CP1",
                "requirement": "may_be_required",
                "source": "agency",
                "code": "9503000090"
              },
              {
                "flag": "CP1",
                "requirement": "may_be_required",
                "source": "border",
                "code": "9503000090"
              }
            ],
            "category": "Toys",
            "certificate": {
              "kind": "children",
              "code": "CPC"
            },
            "citations": [
              {
                "code": "1278a",
                "title": "15 USC 1278a: Total Lead Content for Children’s Products",
                "probability": 0.93,
                "testing": [
                  {
                    "code": "1112.15(b)(30)",
                    "title": "Limits on Total Lead in Children’s Products: Nonmetal Children’s Products",
                    "summary": "A children’s product certified to this rule is tested by a CPSC-accepted third-party laboratory (16 CFR 1112.15(b)(30)). The laboratory’s accepted scope names one of these test methods: CPSC Test Method CPSC-CH-E1002-08, “Standard Operating Procedure for Determining Total Lead (Pb) in Nonmetal Children’s Products”.",
                    "link": "https://www.cpsc.gov/cgi-bin/labsearch/",
                    "sourceUrl": "https://www.ecfr.gov/current/title-16/section-1112.15",
                    "regulation": "1278a",
                    "labs": [
                      {
                        "id": "1002",
                        "name": "Centre Testing International Group Co., Ltd.",
                        "country": "CN",
                        "locality": "Shenzhen, Guangdong",
                        "website": "http://www.cti-cert.com/",
                        "accreditation": "CNAS (China National Accreditation Service for Conformity Assessment) - L1910",
                        "body": {
                          "kind": "independent",
                          "label": "Independent Conformity Assessment Body"
                        },
                        "scopes": [
                          "Lead in Non-Metal Children’s Products - CPSC-CH-E1002-08 and/or CPSC-CH-E1002-08.1 and/or CPSC-CH-E1002-08.2 and/or CPSC-CH-E1002-08.3"
                        ]
                      },
                      {
                        "id": "1004",
                        "name": "TÜV Rheinland Hong Kong Limited",
                        "country": "CN",
                        "locality": "Hong Kong, Guangdong",
                        "website": "http://www.tuv.com/",
                        "accreditation": "A2LA (American Association for Lab Accreditation) - 5047.02",
                        "body": {
                          "kind": "independent",
                          "label": "Independent Conformity Assessment Body"
                        },
                        "scopes": [
                          "Lead in Non-Metal Children’s Products - CPSC-CH-E1002-08 and/or CPSC-CH-E1002-08.1 and/or CPSC-CH-E1002-08.2 and/or CPSC-CH-E1002-08.3"
                        ]
                      },
                      {
                        "id": "1005",
                        "name": "UL VS Hong Kong Limited",
                        "country": "HK",
                        "locality": "Kwai Chung, N.T.",
                        "website": "http://www.ul.com/",
                        "accreditation": "HKAS (Hong Kong Accreditation Service) - HOKLAS 036",
                        "body": {
                          "kind": "independent",
                          "label": "Independent Conformity Assessment Body"
                        },
                        "scopes": [
                          "Lead in Non-Metal Children’s Products - CPSC-CH-E1002-08 and/or CPSC-CH-E1002-08.1 and/or CPSC-CH-E1002-08.2 and/or CPSC-CH-E1002-08.3"
                        ]
                      }
                    ],
                    "labCount": 560
                  }
                ],
                "labelling": []
              },
              {
                "code": "4.27",
                "title": "ASTM F963: Stuffed and Beanbag-Type Toys",
                "probability": 0.9,
                "testing": [
                  {
                    "code": "1112.15(b)(32)(ii)(BB)",
                    "title": "Stuffed and Beanbag-Type Toys",
                    "summary": "A children’s product certified to this rule is tested by a CPSC-accepted third-party laboratory (16 CFR 1112.15(b)(32)(ii)(BB)).",
                    "link": "https://www.cpsc.gov/cgi-bin/labsearch/",
                    "sourceUrl": "https://www.ecfr.gov/current/title-16/section-1112.15",
                    "regulation": "4.27",
                    "labs": [
                      {
                        "id": "1002",
                        "name": "Centre Testing International Group Co., Ltd.",
                        "country": "CN",
                        "locality": "Shenzhen, Guangdong",
                        "website": "http://www.cti-cert.com/",
                        "accreditation": "CNAS (China National Accreditation Service for Conformity Assessment) - L1910",
                        "body": {
                          "kind": "independent",
                          "label": "Independent Conformity Assessment Body"
                        },
                        "scopes": [
                          "Stuffed and Beanbag-Type Toys - 4.27 (ASTM F963-23)"
                        ]
                      },
                      {
                        "id": "1004",
                        "name": "TÜV Rheinland Hong Kong Limited",
                        "country": "CN",
                        "locality": "Hong Kong, Guangdong",
                        "website": "http://www.tuv.com/",
                        "accreditation": "A2LA (American Association for Lab Accreditation) - 5047.02",
                        "body": {
                          "kind": "independent",
                          "label": "Independent Conformity Assessment Body"
                        },
                        "scopes": [
                          "Stuffed and Beanbag-Type Toys - 4.27 (ASTM F963-23)"
                        ]
                      },
                      {
                        "id": "1005",
                        "name": "UL VS Hong Kong Limited",
                        "country": "HK",
                        "locality": "Kwai Chung, N.T.",
                        "website": "http://www.ul.com/",
                        "accreditation": "HKAS (Hong Kong Accreditation Service) - HOKLAS 036",
                        "body": {
                          "kind": "independent",
                          "label": "Independent Conformity Assessment Body"
                        },
                        "scopes": [
                          "Stuffed and Beanbag-Type Toys - 4.27 (ASTM F963-23)"
                        ]
                      }
                    ],
                    "labCount": 292
                  }
                ],
                "labelling": []
              }
            ],
            "exemptions": [],
            "waiver": null,
            "intendedUse": null,
            "program": null,
            "productCode": null,
            "declarations": [],
            "priorNotice": null,
            "probability": 0.9,
            "audience": {
              "kind": "children",
              "probability": 0.96
            },
            "alternates": [
              {
                "code": "4.6",
                "title": "ASTM F963: Small Objects",
                "probability": 0.41
              },
              {
                "code": "1501",
                "title": "16 CFR 1501: Method for Identifying Toys and Other Articles Intended For Use By Children Under 3 Years of Age Which Present Choking Aspiration, Or Ingestion Hazards Because of Small Parts",
                "probability": 0.38
              }
            ],
            "labelling": [
              {
                "code": "2063(a)(5)",
                "title": "Children’s product tracking label (CPSA section 14(a)(5))",
                "summary": "Effective 1 year after August 14, 2008, the manufacturer of a children’s product shall place permanent, distinguishing marks on the product and its packaging, to the extent practicable, that will enable— (i) the manufacturer to ascertain the location and date of production of the product, cohort information (including the batch, run number, or other identifying characteristic), and any other information determined by the manufacturer to facilitate ascertaining the specific source of the product by reference to those marks; and (ii) the ultimate purchaser to ascertain the manufacturer or private labeler, location and date of production of the product, and cohort information (including the batch, run number, or other identifying characteristic).",
                "link": null,
                "sourceUrl": "https://www.govinfo.gov/link/uscode/15/2063?link-type=html",
                "regulation": null,
                "text": null,
                "placement": "On the product and its packaging, to the extent practicable."
              }
            ],
            "needsReview": false,
            "why": [
              "U.S. Consumer Product Safety Commission flags the line: CP1 (data may be needed) on the agency’s list for 9503000090, product category “Toys”.",
              "It is the U.S. Consumer Product Safety Commission’s product (97% likely), a children’s product.",
              "2 regulations apply: 1278a, 4.27, certified on a CPC."
            ],
            "sources": [
              "https://www.cpsc.gov/eFiling-Document-Library",
              "https://www.ecfr.gov/current/title-16/section-1112.15",
              "https://www.govinfo.gov/link/uscode/15/2063?link-type=html"
            ]
          },
          {
            "country": "US",
            "agency": "U.S. Environmental Protection Agency",
            "outcome": "flagged",
            "requirement": "may_be_required",
            "flags": [
              {
                "flag": "EP7",
                "requirement": "may_be_required",
                "source": "border",
                "code": "9503000090"
              }
            ],
            "category": null,
            "certificate": null,
            "citations": [],
            "exemptions": [],
            "waiver": null,
            "intendedUse": null,
            "program": null,
            "productCode": null,
            "declarations": [],
            "priorNotice": null,
            "probability": null,
            "audience": null,
            "alternates": [],
            "needsReview": true,
            "why": [
              "U.S. Environmental Protection Agency flags the line: EP7 (data may be needed) on the border’s flags for 9503000090.",
              "border.bot holds no rules for this agency yet: file its data, or check whether a disclaim applies."
            ],
            "sources": []
          }
        ]
      },
      {
        "sku": "SYR-5ML",
        "title": "Sterile single-use hypodermic syringe, 5 ml, Luer lock",
        "hsCode": "9018310040",
        "classification": null,
        "filings": [
          {
            "country": "US",
            "agency": "Food and Drug Administration",
            "outcome": "file",
            "requirement": "required",
            "flags": [
              {
                "flag": "FD2",
                "requirement": "required",
                "source": "border",
                "code": "9018310040"
              }
            ],
            "category": null,
            "certificate": null,
            "citations": [],
            "exemptions": [],
            "waiver": null,
            "intendedUse": {
              "code": "081.001",
              "title": "Standard import of a foreign manufactured device, accessories, or components regulated as a finished device; Import of refurbished device; Import of a reprocessed device",
              "probability": 0.92
            },
            "program": {
              "code": "NED",
              "title": "Non-Radiation Emitting Device",
              "parent": {
                "code": "DEV",
                "title": "Medical Device"
              },
              "probability": 0.96
            },
            "productCode": {
              "code": "80FMF",
              "scheme": "us-fda",
              "codeName": "FDA product code",
              "parts": [
                {
                  "level": "industry",
                  "label": "Industry",
                  "code": "80",
                  "description": "General Hospital & Personal Use"
                }
              ],
              "product": {
                "code": "FMF",
                "description": "Syringe, Piston"
              },
              "validated": true,
              "probability": 0.9
            },
            "declarations": [
              {
                "codes": [
                  "DEV"
                ],
                "title": "Device Foreign Manufacturer Registration Number",
                "status": "mandatory",
                "applies": true,
                "probability": null,
                "valueRequired": true
              },
              {
                "codes": [
                  "DFE"
                ],
                "title": "Device Foreign Exporter Registration Number",
                "status": "mandatory",
                "applies": true,
                "probability": null,
                "valueRequired": true
              },
              {
                "codes": [
                  "LST"
                ],
                "title": "Device Listing Number",
                "status": "mandatory",
                "applies": true,
                "probability": null,
                "valueRequired": true
              },
              {
                "codes": [
                  "IRC"
                ],
                "title": "Device Impact Resistance Lens Certification",
                "status": "conditional",
                "applies": false,
                "probability": 0.02,
                "valueRequired": false
              },
              {
                "codes": [
                  "LWC"
                ],
                "title": "Device Electrode Lead Wire or Patient Cable",
                "status": "conditional",
                "applies": false,
                "probability": 0.03,
                "valueRequired": false
              },
              {
                "codes": [
                  "PM#"
                ],
                "title": "Device Premarket Number",
                "status": "conditional",
                "applies": true,
                "probability": 0.94,
                "valueRequired": true
              },
              {
                "codes": [
                  "DI"
                ],
                "title": "Device Identifier (part of the Unique Device Identifier, UDI)",
                "status": "optional",
                "applies": null,
                "probability": null,
                "valueRequired": true
              },
              {
                "codes": [
                  "ERR"
                ],
                "title": "Entry Review Requested",
                "status": "optional",
                "applies": null,
                "probability": null,
                "valueRequired": false
              }
            ],
            "priorNotice": {
              "required": false,
              "probability": 0.96
            },
            "probability": 0.9,
            "needsReview": false,
            "why": [
              "Food and Drug Administration flags the line: FD2 (data required) on the border’s flags for 9018310040.",
              "FDA product code 80FMF (Syringe, Piston).",
              "Filed under Medical Device: Non-Radiation Emitting Device (DEV NED, 96% likely).",
              "Intended use 081.001: Standard import of a foreign manufactured device, accessories, or components regulated as a finished device; Import of refurbished device; Import of a reprocessed device (92% likely).",
              "Declarations: DEV, DFE, LST, PM#."
            ],
            "sources": [
              "https://www.cbp.gov/document/technical-documentation/ace-appendix-pga",
              "https://www.fda.gov/media/191441/download",
              "https://www.fda.gov/media/191434/download"
            ]
          }
        ]
      }
    ],
    "fileCount": 2,
    "disclaimCount": 0,
    "reviewCount": 1,
    "engine": "borderbot",
    "checkId": "01a15ac1-27f7-796d-9bf7-a3022ef8f829",
    "dataSource": {
      "version": null,
      "importedAt": null,
      "datasets": [
        {
          "dataset": "US:agency",
          "seq": 2,
          "releaseId": "01a15adc-52e0-7c4c-b7f1-d6a7bd829ff9",
          "version": null,
          "liveSince": "2026-10-20T19:55:20.000Z"
        },
        {
          "dataset": "US:restrictions",
          "seq": 4,
          "releaseId": "01a14456-ba75-793b-bfc2-a0dd0b9c0361",
          "version": null,
          "liveSince": "2026-10-16T08:40:26.156Z"
        },
        {
          "dataset": "US:regulator",
          "seq": 1,
          "releaseId": "01a16a02-1c3e-7f40-9d2b-5b8e2f61c7a4",
          "version": null,
          "liveSince": "2026-10-21T09:00:00.000Z"
        }
      ]
    }
  },
  "credits": {
    "charged": 4,
    "remaining": 94,
    "usageId": "usg_01m5dc29tdkdmpffnd43jmg1w5"
  },
  "replayed": false
}