ASCI API - Documentation

Overview

The ASCI API lets an external system exchange customs-broker documents with the ASCI back-office system. It is organized into per-document-type modules: ISF (Importer Security Filing), QP (In-Bond), BL (Import Billing), ACEQE (ACE Quick Entry), and LG (Log Book, read-only).

There are two directions of traffic, and you can use either or both:

• Inbound You push documents in. Your system POSTs a JSON document to /api/{Module}/Submit. The API validates it, accepts it, and hands it to the customs-broker back-office system for processing. You poll status (or subscribe to a webhook) to learn the outcome and the assigned reference number.
• Outbound The API delivers processed results back to you. When the back-office system produces or finalizes a document, the API makes it available to you in two ways: a webhook notification pushed to a URL you register, and/or a GET you can poll. There is no separate "outbound submit" endpoint you call - results flow to you.

Base URL & versioning

All requests are made to the ASCI production API base URL:

https://asci-api.asciofmiami.com

All client endpoints live under the /api path prefix (for example https://asci-api.asciofmiami.com/api/Isf/Submit). Endpoint paths in this document are written from /api/... onward; prepend the base URL above.

The API is versioned by deployment rather than by a URL version segment. Existing routes, verbs, request shapes, and the error contract are kept backward-compatible; new fields and endpoints may be added over time. Treat unknown JSON fields in responses as additive and ignore the ones you do not consume.

Authentication

Every request must include an ApiKey request header carrying the API key issued to your integration:

ApiKey: YOUR_API_KEY

Keys are issued per integration. The server derives your account (tenant) from the key itself - you never send a tenant identifier in the URL, query string, or body. Every list and lookup is automatically scoped to your own data; you cannot see or address another integration's records.

Authentication outcomes:

• A request with no key, or an unknown / revoked / expired key, returns 401 unauthenticated.
• A valid key that is not authorized for the operation returns 403 forbidden. Your key must be authorized for the operation you are calling (submitting documents, reading status, and managing webhooks are separate permissions). If you get a 403 on an operation you expect to use, ask your provider to authorize the key for it.

Request conventions

JSON

Requests and responses are JSON. Send Content-Type: application/json on every request that has a body.

The Submit envelope

Every POST /api/{Module}/Submit body wraps the document in a single document object:

{
  "document": {
    "reference_no": "NEW",
    "...": "module-specific fields"
  }
}

Reference numbers and "NEW"

Each document carries a reference_no. Set it to the string "NEW" (case-insensitive; an empty value is treated the same) to have the back-office system allocate the next consecutive reference number for you. The allocated number is reported back through the status and detail endpoints (field bbx_reference_no). You may also pass an explicit reference number; it is used verbatim.

metadata (optional key/value bag)

Every inbound document (ISF / QP / BL / ACEQE) accepts an optional metadata object at the top level of the document object, next to reference_no. It is a client-supplied JSON object of string→string key/value pairs: up to 50 entries, keys up to 40 characters, values up to 500 characters each; it is never required. The API stores it verbatim and echoes it back to you on the GET .../{submissionId}/Status response and on the document.status_changed webhook. It is never used to look up or deduplicate an entry — use submission_id for that.

{
  "document": {
    "reference_no": "NEW",
    "metadata": { "order_id": "A123", "warehouse": "MIA" },
    "...": "module-specific fields"
  }
}

Idempotency-Key (required on every Submit)

Every POST /Submit must include an Idempotency-Key header, 8 to 128 characters, unique per logical submission:

Idempotency-Key: 7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22

Replay semantics:

• Same key + same payload returns the original result (HTTP 200) with "duplicate": true and the original submission_id - no second document is created.
• Same key + a different payload is a conflict and returns 409 duplicate_idempotency_key; the extra.original_submission_id field points at the prior submission.

This makes it safe to retry a Submit after a network timeout: reuse the same key and you will never double-insert.

Trace id

Every response (success or error) carries an X-Trace-Id response header, and error bodies repeat it as trace_id. Quote that value when reporting an issue so support can correlate it with server logs.

Error responses

Every 4xx / 5xx response uses one uniform JSON shape:

{
  "status": 409,
  "code": "duplicate_idempotency_key",
  "message": "Idempotency-Key has already been used with a different payload.",
  "hint": "Submit with a fresh Idempotency-Key, or replay with the original payload.",
  "endpoint": "POST /api/Isf/Submit",
  "trace_id": "0HMXXXXXXXXX...",
  "timestamp": "2026-05-08T16:24:27.3078184Z",
  "field_errors": null,
  "extra": { "original_submission_id": "a9051bfa23dc4df8b38f3bc11c3a1411" }
}

Common error codes

field_errors

On validation failures (400 / 422), field_errors is an object mapping each offending field name to a reason string:

{
  "status": 422,
  "code": "invalid_payload",
  "message": "One or more fields are invalid.",
  "field_errors": {
    "document.header.scac_code": "scac_code must be exactly 4 uppercase letters.",
    "document.header.ior_qualifier": "ior_qualifier must be one of EI, SS, CN."
  }
}

Status lifecycle

After a successful Submit, a document moves through these states as the back-office system picks it up and processes it:

Processing model

Accepted documents are queued in the API and inserted into ASCI one at a time, in submission order (FIFO), serialized - never in parallel. Each entry runs through the lifecycle independently: queued → processing → processed | rejected. Its result is recorded in the API and a document.status_changed webhook is emitted per entry.

Webhook delivery is asynchronous with retries and does not hold up the queue: a slow or unavailable webhook endpoint never stalls legacy insertion of the next entry. Use polling (below) and/or the webhook to learn each entry's outcome.

Poll the thin status endpoint to track progress. It returns { submission_id, status, direction, metadata, entry_no, approval_status, updated_at } (metadata echoes back the object you supplied on Submit, if any). entry_no and approval_status carry the back-office-reported entry number and disposition once the entry is processed, and are returned on the Status response for every module (ISF, QP, BL, ACEQE); they are null until the back-office system reports them:

GET /api/{Module}/{submissionId}/Status

Rather than polling, you can register a webhook (see Webhooks) to be notified as documents are received and as their status changes.

Per-module endpoint reference

Each of ISF, QP, BL, and ACEQE exposes the same four client endpoints. Replace {Module} with the module route segment: Isf, Qp, Bl, or AceQe.

List query filters (GET /api/{Module})

GET /api/Isf?direction=inbound&reference_no=11160&status=processed&limit=50&offset=0

Detail envelope shape (GET /api/{Module}/{submissionId})

The detail endpoint returns an envelope describing one submission:

{
  "channel": "isf.create",
  "tenant_cid": "your-tenant",
  "idempotency_key": "7f3c1e9a-...",
  "submission_id": "3da64f8278c346ef922033414fe62be7",
  "payload": {
    "type": "ISF",
    "status": "ADDITION",
    "data": { "reference_no": "011160", "...": "all typed columns" },
    "formatted_message": [
      { "line_no": 0, "message": "..." },
      { "line_no": 1, "message": "..." }
    ]
  }
}

A 404 not_found is returned for an unknown id or one that belongs to another account.

ISF - Importer Security Filing

POST /api/Isf/Submit
ApiKey: YOUR_API_KEY
Idempotency-Key: 7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22
Content-Type: application/json

{
  "document": {
    "reference_no": "NEW",
    "header": {
      "submission_type": "1",
      "action_code": "A",
      "action_reason": "CT",
      "shipment_type": "01",
      "operator_code": "001",
      "ior_qualifier": "EI",
      "ior_number": "12-3456789",
      "importer_code": "ACME",
      "mode_of_transport": "11",
      "scac_code": "MAEU",
      "customer_ref": "CUST-REF-001"
    },
    "bills_of_lading": [
      { "seq_no": "001", "code_qualifier": "OB", "bol_ref_no": "MAEU123456789" }
    ],
    "containers": [ { "seq_no": "001", "container_no": "MAEU1234567" } ],
    "parties": [
      { "party_type": "IM", "name": "ACME IMPORTS INC",
        "identifier_qualifier": "EI", "identifier": "12-3456789" },
      { "party_type": "CN", "name": "ACME IMPORTS INC",
        "identifier_qualifier": "EI", "identifier": "12-3456789" },
      { "party_type": "BY", "name": "ACME IMPORTS INC", "address_1": "123 MAIN ST",
        "city": "MIAMI", "state": "FL", "postal_code": "33101", "country": "US" },
      { "party_type": "ST", "name": "ACME WAREHOUSE", "address_1": "123 MAIN ST",
        "city": "MIAMI", "state": "FL", "postal_code": "33101", "country": "US" },
      { "party_type": "SE", "name": "GLOBAL TRADING CO", "address_1": "12 HARBOUR RD",
        "city": "SHANGHAI", "country": "CN" },
      { "party_type": "LG", "name": "GLOBAL TRADING CO", "address_1": "12 HARBOUR RD",
        "city": "SHANGHAI", "country": "CN" },
      { "party_type": "CS", "name": "GLOBAL TRADING CO", "address_1": "12 HARBOUR RD",
        "city": "SHANGHAI", "country": "CN" },
      { "party_type": "MF", "name": "GLOBAL TRADING CO", "address_1": "12 HARBOUR RD",
        "city": "SHANGHAI", "country": "CN", "manufacturer_id": "CNGLOTRA12SHA" }
    ],
    "tariff": [
      { "seq_no": "001", "hts_number": "8471300100",
        "description": "PORTABLE COMPUTERS", "country_of_origin": "CN" }
    ],
    "bond": { "bond_type": "8", "activity_code": "01" },
    "additional_references": []
  }
}

{
  "submission_id": "3da64f8278c346ef922033414fe62be7",
  "document_type": "ISF",
  "status": "queued",
  "status_url": "https://asci-api.asciofmiami.com/api/ISF/Status/3da64f8278c346ef922033414fe62be7",
  "message": "Queued for processing. Poll the status_url for progress."
}

GET /api/Isf?direction=inbound&limit=100&offset=0
ApiKey: YOUR_API_KEY

{
  "count": 1,
  "rows": [
    {
      "submission_id": "3da64f8278c346ef922033414fe62be7",
      "reference_no": "011160",
      "status": "processed",
      "direction": "inbound",
      "created_at": "2026-05-08T22:37:06.443Z"
    }
  ]
}

GET /api/Isf/3da64f8278c346ef922033414fe62be7
ApiKey: YOUR_API_KEY

GET /api/Isf/3da64f8278c346ef922033414fe62be7/Status
ApiKey: YOUR_API_KEY

{
  "submission_id": "3da64f8278c346ef922033414fe62be7",
  "status": "processed",
  "direction": "inbound",
  "metadata": { "order_id": "A123", "warehouse": "MIA" },
  "entry_no": "26000009901",
  "approval_status": "APPROVED",
  "updated_at": "2026-05-08T22:37:11.002Z"
}

POST /api/Isf/Validate
ApiKey: YOUR_API_KEY
Content-Type: application/json

{ "document": { "header": { ... }, "bills_of_lading": [ ... ], "parties": [ ... ] } }

{
  "valid": false,
  "errors": [
    { "code": "isf_entity_country_required", "field": "parties.country",
      "line_ref": "SE", "message": "Entity SE  ISF-10+2: Missing Entity Country Code" },
    { "code": "isf_bol_required", "field": "bills_of_lading", "line_ref": null,
      "message": "At Least one B/L MUST be entered to complete the ISF Submission." }
  ],
  "warnings": [
    { "code": "isf_carrier_unverified", "field": "header.scac_code", "line_ref": null,
      "message": "ISF-10+2: SCAC Code 'MAEU' could not be verified against the Carrier File (no carrier data imported)" }
  ]
}

POST /api/Isf/3da64f8278c346ef922033414fe62be7/TransmitCbp
ApiKey: YOUR_API_KEY
Idempotency-Key: cbp-7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22

{
  "submission_id": "3da64f8278c346ef922033414fe62be7",
  "cbp_submission_id": "c9c1b2a3d4e5f60718293a4b5c6d7e8f",
  "status": "SENT",
  "reference_no": "011692",
  "environment": "CERT"
}

GET /api/Isf/3da64f8278c346ef922033414fe62be7/CbpStatus
ApiKey: YOUR_API_KEY

{
  "submission_id": "3da64f8278c346ef922033414fe62be7",
  "cbp_submission_id": "c9c1b2a3d4e5f60718293a4b5c6d7e8f",
  "status": "ACCEPTED",
  "validation_status": null,
  "isf_number": "S26-01234567890",
  "bill_no": "APLU123456789",
  "reference_no": "011692",
  "environment": "CERT",
  "transmitted_at": "2026-07-14T15:43:18.000Z",
  "last_reply_at": "2026-07-14T15:44:02.000Z",
  "error_message": null,
  "conditions": [
    { "code": "02", "severity": "I", "text": "DATA ACCEPTED",
      "received_at": "2026-07-14T15:44:02.000Z" }
  ]
}

QP - In-Bond

POST /api/Qp/Submit
ApiKey: YOUR_API_KEY
Idempotency-Key: qp-7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22
Content-Type: application/json

{
  "document": {
    "reference_no": "NEW",
    "header": {
      "in_bond_no": "QP260000099",
      "in_bond_type": "61",
      "customer_code": "ACME01",
      "initiation_port_code": "5201",
      "mode_of_transport": "10",
      "carrier_code": "MAEU",
      "us_port_of_destination": "1601",
      "log_number": "LOG12345678",
      "comments": ["line 1", "line 2"]
    },
    "conveyances": [
      { "seq_no": "01", "importing_carrier": "MAEU", "transportation_mode": "10",
        "conveyance_name": "EVER GIVEN", "port_of_unlading": "5201", "num_bls": 1 }
    ],
    "bills_of_lading": [
      { "conveyance_no": "01", "bl_line": "0001", "awb_bl_no": "MAEU2220000001",
        "consignee_code": "CNSG01", "quantity": 100, "weight": 2500,
        "containers": [
          { "container_line": "001", "container_number": "MAEU2222222",
            "harmonized_lines": [
              { "item_line": "001", "seq": "001", "harmonized_tariff": "8471300100", "value": 50000 }
            ] }
        ] }
    ],
    "parties": [
      { "conveyance_no": "01", "bl_line": "0001", "record_type": "C",
        "name": "ACME IMPORTS LLC", "party_code": "CNSG01" }
    ],
    "all_additional_references": [],
    "abi_status": []
  }
}

{
  "submission_id": "b1d4...e7",
  "document_type": "QP",
  "status": "queued",
  "status_url": "https://asci-api.asciofmiami.com/api/QP/Status/b1d4...e7"
}

BL - Import Billing

POST /api/Bl/Submit
ApiKey: YOUR_API_KEY
Idempotency-Key: bl-7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22
Content-Type: application/json

{
  "document": {
    "reference_no": "NEW",
    "additional_invoice_code": "",
    "header": {
      "invoice_no": "",
      "customer_code": "ACME",
      "customer_ref": "CUST-REF-100",
      "transaction_code": "I",
      "invoice_date": "20260424",
      "invoice_description": "Import billing - ocean freight",
      "shipper_consignee": "ACME / SHANGHAI EXPORTS",
      "origin_destination": "CN/US",
      "entry_number": "ENT-2026-001",
      "entry_date": "20260420",
      "airline_steamship": "MAEU",
      "arrival_departure_date": "20260501",
      "awb_bl_number": "MAEU123456789",
      "house_awb": "",
      "gl_division": "01",
      "num_pieces": "100",
      "invoice_value": 25000.00,
      "weight": 1500.5,
      "remarks": []
    },
    "charge_lines": [
      { "seq_no": "001", "company_code": "01", "vendor_code": "MAEU",
        "transaction_code": "I", "log_type_code": "OF", "charge_code": "FRT",
        "gl_number": "4100", "ap_gl_number": "2100", "prepaid_indicator": "P",
        "charge_description": "Ocean Freight", "awb_bl_number": "MAEU1234567",
        "pending_charge_ind": "N", "charge_amount": 3500.00, "ap_amount": 3200.00 },
      { "seq_no": "002", "company_code": "01", "vendor_code": "MAEU",
        "transaction_code": "I", "log_type_code": "OF", "charge_code": "DOC",
        "gl_number": "4110", "ap_gl_number": "2100", "prepaid_indicator": "C",
        "charge_description": "Documentation Fee", "awb_bl_number": "MAEU1234567",
        "pending_charge_ind": "N", "charge_amount": 75.00, "ap_amount": 0.00 }
    ]
  }
}

{
  "submission_id": "c8a2...f1",
  "document_type": "BL",
  "status": "queued",
  "status_url": "https://asci-api.asciofmiami.com/api/BL/Status/c8a2...f1"
}

ACEQE - ACE Quick Entry

ACE Quick Entry is a flat-header document with ACE-specific fields, structured commercial_entities, and a flat pga_indicators array. It anchors on a 6-byte reference number allocated when reference_no is "NEW".

POST /api/AceQe/Submit
ApiKey: YOUR_API_KEY
Idempotency-Key: aceqe-7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22
Content-Type: application/json

{
  "document": {
    "reference_no": "NEW",
    "filed_7501": "",
    "consignee_type_code": "EI ",
    "consignee_irs_number": "591234567   ",
    "rlf_indicator": " ",
    "default_country_code": "CN   ",
    "district_port_code": "52  ",
    "gsp_cbi_nafta": "N",
    "statement_status": "1",
    "broker_or_sales_rep": "AF1  ",
    "ach_indicator": "N",
    "port_of_entry": "5201",
    "firms_code": "ASCI",
    "firms_city": "MIAMI",
    "vessel_name": "EVER GOLDEN          ",
    "wh_indicator": "N",
    "goods_description": "MEN'S KNIT SHIRTS - COTTON/POLYESTER BLEND      ",
    "invoice_count": "   1",
    "team_code": "AF1",
    "purchased_indicator": "Y",
    "bond_notation": "BN",
    "importer_of_record": "ABCIM1",
    "ace_entry_type": "23",
    "tariff_lines": [
      { "bond_no": "00123456789", "ruling_no": "H317.00000000  ",
        "country_of_origin": "CN", "manufacturer_id": "CNSHGFACT001   ",
        "tariff_no": "6110202010  " }
    ],
    "bond_type_code": "9",
    "box29_lines": ["MSCU1234567                         ", ""],
    "remarks_line_1": "ACE QUICK ENTRY TEST - VESSEL CONSUMP",
    "i7": [0, 0, 0, 0],
    "i9": [0],
    "i10": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
    "commercial_entities": [
      { "role": "CN", "name": "ABC IMPORTS INC                    ",
        "type_qualifier": "EI ", "identifier": "591234567           ",
        "address_block": "1000 NW 42ND AVE                                                      ",
        "customer_division": "ABCIM1" },
      { "role": "MF", "name": "SHANGHAI GARMENT FACTORY           ",
        "type_qualifier": "MF ", "identifier": "CNSHGFACT001        ",
        "address_block": "123 PUJIANG RD SHANGHAI CHINA                                         ",
        "customer_division": "ABCIM1" }
    ],
    "pga_indicators": ["N", "N", "N", "N", "N"],
    "country_subdivision": "FL"
  }
}

{
  "submission_id": "5b77...c0",
  "document_type": "ACEQE",
  "status": "queued",
  "status_url": "https://asci-api.asciofmiami.com/api/ACEQE/Status/5b77...c0"
}

LG - Log Book (outbound / read-only)

LG is read-only. There is no LG Submit endpoint; LG records are produced by the back-office system and made available to you for reading. All LG list/lookup endpoints enforce direction=outbound.

GET /api/Lg?direction=outbound&limit=100&offset=0
ApiKey: YOUR_API_KEY

GET /api/Lg/3da64f8278c346ef922033414fe62be7
ApiKey: YOUR_API_KEY

GET /api/Lg/3da64f8278c346ef922033414fe62be7/Status
ApiKey: YOUR_API_KEY

CBP Communication (CBPCOM)

The CBP module transmits a built CATAIR message to U.S. Customs (CBP) over the ABI / ISF / Quick-Entry / AES / DIS channels and captures every reply. The legacy system builds the CATAIR (after inserting the entry and generating the reference); these endpoints perform the transmit and reply tracking. Certification is the active environment by default - switching to Production is a controlled, loopback-only operation. Scopes: cbp.submit (transmit), cbp.read (view).

{channel} is one of isf, qe, abi, aes, dis. Every response (success and failure) is recorded in two stages: a pre-transmit validation_status (blocks the send on failure) and the CBP outcome status (PENDING → SENT → ACCEPTED / REJECTED / WARNING / ERROR). Captured identifiers include entry_no (Quick Entry), isf_number (ISF Transaction Number), bill_no (bill of lading), and confirmation_no, plus the full list of CBP condition codes per reply.

POST /api/Cbp/isf/Transmit
ApiKey: YOUR_API_KEY
Idempotency-Key: 7b1f...e9
Content-Type: application/json

{
  "reference_no": "009125",
  "filer_code": "S38",
  "catair": "A5206S38ROBERT...SF\n..."
}

GET /api/Cbp/Submissions?channel=isf&status=ACCEPTED&limit=100
ApiKey: YOUR_API_KEY

GET /api/Cbp/isf/3da64f8278c346ef922033414fe62be7
ApiKey: YOUR_API_KEY

GET /api/Cbp/isf/3da64f8278c346ef922033414fe62be7/Status
ApiKey: YOUR_API_KEY

GET /api/Cbp/Environment
ApiKey: YOUR_API_KEY

Draft vs direct submit

Every POST /api/{Module}/Submit can either send the document straight through to the back-office system (the historical behaviour) or stage it as a draft that you edit, validate, and explicitly release later. The choice is made per request with an optional field on the envelope; the default is direct, so existing integrations are unaffected.

Selecting the mode

Set submit_mode to either "direct" or "draft" (case-insensitive). It is accepted in any of three places - under document, at the top level of the body, or under data - so it is easy to add wherever your builder assembles the request. As an alternative you may send a boolean draft (true = draft, false = direct).

{
  "document": {
    "reference_no": "NEW",
    "submit_mode": "draft",
    "...": "module-specific fields"
  }
}

Draft Submit response (202)

A draft Submit returns 202 with status: "draft" and, in addition to the usual status_url, a transmit_url plus an extra.actions array listing the next action you can take:

{
  "submission_id": "9b1c4f0a7e2d4c1f8a3b6e5d2c9f0a11",
  "document_type": "ISF",
  "status": "draft",
  "status_url":   "https://asci-api.asciofmiami.com/api/Isf/Status/9b1c4f0a...",
  "transmit_url": "https://asci-api.asciofmiami.com/api/Isf/9b1c4f0a.../Transmit",
  "message": "Staged as a draft. Edit and validate, then POST the transmit_url to send it.",
  "extra": { "actions": ["send_to_cbp"] }
}

Transmit a draft

Send a previously-staged draft to the back-office system. After a draft Submit, the draft sits in the API with status draft until you call its Transmit endpoint. ISF, QP, BL, and ACEQE all expose Transmit; the same key authorization as Submit is required.

The route is the same shape for every module:

POST /api/{Module}/{submissionId}/Transmit

Replace {Module} with Isf, Qp, Bl, or AceQe. On success returns 202 with status: "queued", transmitted: true, and a status_url. The new reference_no is allocated by the back-office system at Transmit/insert time, not at draft/copy time.

POST /api/Isf/9b1c4f0a7e2d4c1f8a3b6e5d2c9f0a11/Transmit
ApiKey: YOUR_API_KEY

{
  "submission_id": "9b1c4f0a7e2d4c1f8a3b6e5d2c9f0a11",
  "document_type": "ISF",
  "status": "queued",
  "transmitted": true,
  "status_url": "https://asci-api.asciofmiami.com/api/Isf/Status/9b1c4f0a..."
}

POST /api/Qp/9b1c4f0a7e2d4c1f8a3b6e5d2c9f0a11/Transmit
ApiKey: YOUR_API_KEY

POST /api/Bl/9b1c4f0a7e2d4c1f8a3b6e5d2c9f0a11/Transmit
ApiKey: YOUR_API_KEY

POST /api/AceQe/9b1c4f0a7e2d4c1f8a3b6e5d2c9f0a11/Transmit
ApiKey: YOUR_API_KEY

Transmit is tenant-scoped: an unknown id, or one belonging to another account, returns 404 not_found as the uniform error body.

Overview

The API holds your master data - customers, manufacturers, and products - in a persistent, tenant-scoped store. Every lookup and write is automatically scoped to your own account; you never address another integration's records. The data backs the platform forms and is what inbound documents validate against (for example, an ISF importer_code is checked against your imported customers).

This category is organized by entity. Each entity exposes the same two operations:

• Lookup GET - list / partial-match search (and, for customers, fetch one by exact code). Requires your key be authorized to read status (scope queue.read).
• Create / upsert POST - create or idempotently update one record. Requires submit authorization (scope ipjson.submit) and the same Idempotency-Key header as any document Submit.

All write endpoints synchronously upsert into the API store (so lookups resolve immediately) and enqueue a forward-compatible legacy write on the same FIFO pipeline the document modules use.

Customers

Your importer / customer master. Keyed by a client-supplied code. This is the list an inbound ISF importer_code is validated against.

GET /api/Customers?code=ACME&name=IMPORTS&limit=200
ApiKey: YOUR_API_KEY

GET /api/Customers/ACME
ApiKey: YOUR_API_KEY

POST /api/Customers
ApiKey: YOUR_API_KEY
Idempotency-Key: cust-7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22
Content-Type: application/json

{
  "code": "ACME",
  "id_qualifier": "EI",
  "id_number": "12-3456789",
  "name": "ACME IMPORTS INC",
  "address_1": "123 MAIN ST",
  "address_2": "",
  "city": "MIAMI",
  "state": "FL",
  "zip": "33101",
  "country": "US",
  "irs_no": "123456789",
  "surety": "BOND SURETY CO",
  "bond_type": "8",
  "continuous_bond_no": "9876543210",
  "manufacturer_no": "CNACM1234SHA"
}

Manufacturers

Your MID (manufacturer-id) master. Keyed by a client-supplied mid.

GET /api/Manufacturers?name=ACME&address=SHANGHAI&mid=CNACM&limit=200
ApiKey: YOUR_API_KEY

POST /api/Manufacturers
ApiKey: YOUR_API_KEY
Idempotency-Key: mfr-7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22
Content-Type: application/json

{
  "mid": "CNACM1234SHA",
  "name": "ACME MANUFACTURING CO",
  "address_1": "123 PUJIANG RD",
  "address_2": "",
  "city": "SHANGHAI",
  "state": "",
  "postal_code": "200120",
  "country": "CN"
}

Products

Your product (catalog item) master. A product may be linked to a manufacturer, but the link is optional - see the unlinked case below.

GET /api/Products?code=ABC&description=COTTON&manufacturer_id=CNACM1234SHA&limit=200
ApiKey: YOUR_API_KEY

POST /api/Products
ApiKey: YOUR_API_KEY
Idempotency-Key: prod-7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22
Content-Type: application/json

{
  "manufacturer_id": "CNACM1234SHA",
  "description": "MEN'S KNIT SHIRTS - COTTON/POLYESTER BLEND",
  "tariff_no": "6110202010",
  "product_code": "SHIRT-001"
}

POST /api/Products
ApiKey: YOUR_API_KEY
Idempotency-Key: prod-9a01-8c2f5b6d1e22-2b44-4d6e
Content-Type: application/json

{
  "description": "ASSORTED PROMOTIONAL GIFT ITEMS",
  "tariff_no": "9505900000"
}

Vendors (A/P)

Your accounts-payable vendor master - a first-class reference entity like customers / manufacturers / products. Keyed by a client-supplied code (the legacy AP_VEND_CODE). Source: legacy A/P vendor master APVE{CID}. The vendor master backs the Pending Charges billing module, which resolves its provider payee against these records.

GET /api/Vendors?code=CARGO&name=SPRINT&limit=200
ApiKey: YOUR_API_KEY

GET /api/Vendors/ACMEFRT
ApiKey: YOUR_API_KEY

POST /api/Vendors
ApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "code": "ACMEFRT",
  "name": "ACME FREIGHT LLC",
  "vendor_type": "AP",
  "address_1": "1 PROVIDER WAY",
  "city": "ATLANTA",
  "state": "GA",
  "zip": "30301",
  "country": "US",
  "terms_code": "NET30",
  "gl_acct_ap": "2000",
  "payto_name": "ACME FREIGHT LLC"
}

7501 entry (provisional)

POST /api/Entry7501/CreateFromQuickEntry
ApiKey: YOUR_API_KEY
Content-Type: application/json

{ "aceqe_reference_no": "011160" }

{
  "entry_7501_reference": "75-011160",
  "source_aceqe_reference_no": "011160",
  "status": "linked",
  "note": "provisional linkage; full 7501 entity pending design"
}

Pending Charges

The Pending Charges module is the API-side read-model of the legacy IPCHR pending charges (doc type PCHG), tenant-scoped and keyed by (ref_no, seq_no). Its payee resolves against the A/P Vendors master. Traffic flows in three directions: ASCI pushes charges in, the billing pipeline sends them to the payment provider for settlement, and the ASCI side polls a settlement feed to apply results back.

POST /api/Charges/Import
ApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "mode": "replace",
  "charges": [
    {
      "ref_no": "011160",
      "seq_no": "001",
      "vendor_code": "ACMEFRT",
      "charge_code": "FRT",
      "record_type": "C",
      "amount": 1250.00,
      "billed": "N",
      "customer_id": "ACME",
      "date": "2026-06-26",
      "vendor_name": "ACME FREIGHT LLC",
      "payment_type": "ACH",
      "awb_bl_no": "MAEU123456789"
    }
  ]
}

GET /api/Charges?status=pending&vendor_code=ACMEFRT&limit=500
ApiKey: YOUR_API_KEY

GET /api/Charges/011160/001
ApiKey: YOUR_API_KEY

GET /api/Charges/Settlements?limit=500
ApiKey: YOUR_API_KEY

{
  "count": 1,
  "rows": [
    {
      "ref_no": "011160",
      "seq_no": "001",
      "status": "paid",
      "provider_payment_id": "SP-9988",
      "paid_amount": 1250.00,
      "paid_date": "2026-06-26",
      "settlement_status": "settled",
      "settlement_raw": "{...}",
      "updated_at": "2026-06-26T14:30:00Z"
    }
  ]
}

Webhooks

Register one or more URLs to be notified whenever a document is accepted for your account. This is how processed/outbound results reach you in near-real time without polling. Managing webhooks requires that your key be authorized for webhook management.

Register

POST /api/Webhook/register
ApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://your-server.example.com/hooks/asci",
  "event_type": "document.received",
  "secret": "your-shared-hmac-secret"
}

List

GET /api/Webhook/list
ApiKey: YOUR_API_KEY

Unregister

DELETE /api/Webhook/unregister/42
ApiKey: YOUR_API_KEY

Notification body

On each event, the API POSTs a JSON notification to every active registration. The body carries the event metadata plus the full typed document under data, so you can consume it directly:

{
  "event_type":    "document.received",
  "document_type": "ISF",
  "reference_no":  "011160",
  "submission_id": "3da64f8278c346ef922033414fe62be7",
  "tenant_domain": "your-tenant",
  "received_at":   "2026-05-08T22:37:06.443Z",
  "data": {
    "channel": "isf.create",
    "tenant_cid": "your-tenant",
    "idempotency_key": "7f3c1e9a-...",
    "submission_id": "3da64f8278c346ef922033414fe62be7",
    "payload": {
      "type": "ISF",
      "status": "ADDITION",
      "data": { "reference_no": "011160", "...": "all typed columns" },
      "formatted_message": [ { "line_no": 0, "message": "..." } ]
    }
  }
}

data may be null if the typed document is not available for an event. For ACEQE events, data.payload.data nests the child arrays (tariff_lines, box29_lines, containers, commercial_entities, pga_indicators).

Status-change notifications (document.status_changed)

As each queued entry is processed by the back-office system (see Processing model), the API emits a document.status_changed webhook for that entry. In addition to the existing reference_no, status, and error_message fields, the payload carries the back-office-reported results - both as top-level envelope fields and under data:

{
  "event_type":      "document.status_changed",
  "document_type":   "ISF",
  "reference_no":    "011160",
  "submission_id":   "3da64f8278c346ef922033414fe62be7",
  "status":          "processed",
  "error_message":   null,
  "metadata":        { "order_id": "A123", "warehouse": "MIA" },
  "entry_no":        "26000009901",
  "approval_status": "APPROVED",
  "tenant_domain":   "your-tenant",
  "received_at":     "2026-05-08T22:37:11.002Z",
  "data": {
    "status":          "processed",
    "reference_no":    "011160",
    "metadata":        { "order_id": "A123", "warehouse": "MIA" },
    "entry_no":        "26000009901",
    "approval_status": "APPROVED",
    "error_message":   null
  }
}

Push vs pull consumer patterns

• Push consumer: read data directly from the notification body. No follow-up call needed.
• Pull consumer: ignore data, treat the webhook purely as a signal, and call GET /api/{Module}/{submissionId} to fetch the document when you are ready.

Both patterns work from the same notification.

Signature verification (HMAC-SHA256)

If you registered the webhook with a secret, every delivery includes a signature header computed over the exact raw request body:

X-Webhook-Signature: sha256=<HMAC-SHA256 hex of the raw body, keyed with your secret>

On receipt, recompute the HMAC-SHA256 of the raw body bytes using your secret, hex-encode it, prefix sha256=, and compare against the header using a constant-time comparison before trusting the payload.

// Node.js example
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery & retry policy

Deliveries are fire-and-forget with a 10-second timeout. There is no automatic retry in this version: if your endpoint returns a non-2xx status or times out, that delivery is recorded as failed and not re-sent. Make your receiver fast and idempotent, return 2xx quickly, and use the submission_id to de-duplicate. If you miss a notification, you can always reconcile by listing or polling the relevant module endpoint.

Quick start

1. Get your API key from your ASCI integration contact, and the base URL for your environment. Confirm the key is authorized for the operations you need (submitting, reading status, managing webhooks).
2. Submit a document with an Idempotency-Key:

   curl -X POST "https://asci-api.asciofmiami.com/api/Isf/Submit" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Idempotency-Key: 7f3c1e9a-2b44-4d6e-9a01-8c2f5b6d1e22" \
     -H "Content-Type: application/json" \
     -d '{ "document": { "reference_no": "NEW", "header": {
           "ior_qualifier": "EI", "ior_number": "12-3456789",
           "importer_code": "ACME", "mode_of_transport": "10",
           "scac_code": "MAEU" } } }'

   The response is 202 with a submission_id and a status_url.
3. Poll status until it reaches processed (with a reference number) or rejected:

   curl "https://asci-api.asciofmiami.com/api/Isf/3da64f8278c346ef922033414fe62be7/Status" \
     -H "ApiKey: YOUR_API_KEY"

   (For ACEQE the status path is /api/AceQe/Status/{id}.)
4. Optionally, register a webhook so you are notified automatically instead of polling:

   curl -X POST "https://asci-api.asciofmiami.com/api/Webhook/register" \
     -H "ApiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "url": "https://your-server.example.com/hooks/asci",
           "event_type": "document.received",
           "secret": "your-shared-hmac-secret" }'

   Verify the X-Webhook-Signature on every delivery and read the document straight from the notification's data field, or use GET /api/{Module}/{submissionId} to fetch it.