ASCI API - Bulk Import

Bulk Import module page - how it works, an interactive test form, and the endpoint reference, all in one place. Set your tenant API Key in the Setup block below; every request sends the ApiKey header. See All Forms for the combined surface or Home for the module index.

How it works

Bulk master-data import.

Bulk Import

Bulk Import idempotently upserts master data into the API store: POST /api/Import/Entities. Choose a mode, select which entity groups (customers / manufacturers / products / vendors) to include, paste the JSON body, and Submit. The response is an ImportReport with inserted / updated / duplicate / error counts. Because it is idempotent, re-running the same payload is safe.

Setup

API key + base URL used by every request below.

Credentials

API Key

Base URL

Leave Base URL blank to call this same server with relative paths (the normal case). Set it (e.g. https://asci-api.asciofmiami.com) to point the forms at another host. Every request below sends the ApiKey header.

Idempotency Key

Sent on every create / submit POST. Click Generate for a fresh one, or a new one is auto-generated per submit if blank.

Test form

Interactive form - POSTs to the API and shows the JSON response + HTTP status.

Bulk-import master data into the API store: POST /api/Import/Entities (idempotent upsert). Choose a mode and which entity groups to include, paste the JSON body, and Submit. The response is an ImportReport (inserted / updated / duplicates / errors).

Mode

Customers Manufacturers Foreign Entities Vendors

The toggles control which top-level arrays are forwarded from the body below. Unchecked groups are stripped before POST so you can test partial imports without editing the JSON.

Request Body (JSON)

Endpoints

Import endpoint (api/Import). Full request & response schema below.

Import endpoints

Method	Path	Purpose
POST	`/api/Import/Entities`	Idempotent bulk upsert of customers / manufacturers / products / carriers / ref_codes / companies / vendors. Returns an ImportReport.

Schema

Request body for POST /api/Import/Entities. The boolean toggles select which entity sets to process; each toggle pairs with its own *_records array. Idempotent UPSERT: in add mode an existing key is recorded as a duplicate and skipped; in replace mode it is updated.

Request (envelope)

Field	Type	Req?	Description
`mode`	string	No	`add` (default) or `replace`.
`customers`	bool	No	Process the `customer_records` array.
`manufacturers`	bool	No	Process the `manufacturer_records` array.
`products`	bool	No	Process the `product_records` array.
`foreignEntities`	bool	No	DEPRECATED alias for `products` (either toggle enables the product import). Prefer `products`.
`carriers`	bool	No	Process the `carrier_records` array.
`ref_codes`	bool	No	Process the `ref_code_records` array.
`companies`	bool	No	Process the `company_records` array.
`vendors`	bool	No	Process the `vendors` array (A/P vendor master).
`customer_records`	array<Customer>	No	Customer profiles (see Customer below).
`manufacturer_records`	array<Manufacturer>	No	MID master records (see Manufacturer below).
`product_records`	array<Product>	No	Catalog products (see Product below).
`carrier_records`	array<Carrier>	No	SCAC / carrier master (see Carrier below).
`ref_code_records`	array<RefCode>	No	Generic reference codes (see RefCode below).
`company_records`	array<Company>	No	OSAS company master (see Company below).
`vendors`	array<Vendor>	No	A/P vendor master records (see Vendor below).

Customer record (customer_records[])
Field	Type	Req?	Max	Description
`code`	string	Yes	10	Customer / importer code (key).
`id_qualifier`	string	No	2	Importer ID qualifier.
`id_number`	string	No	15	Importer ID number.
`name`	string	No	35	Customer name.
`city` / `state` / `zip`	string	No	20 / 2 / 10	City, state, postal code.
`irs_no`	string	No	15	IRS number.
`surety`	string	No	35	Surety company.
`bond_type`	string	No	2	Bond type.
`continuous_bond_no`	string	No	15	Continuous bond number.
`manufacturer_no`	string	No	15	Linked manufacturer / MID number.
`address_1` / `address_2`	string	No	35	Address lines.
`country`	string	No	2	Country (ISO 2-char).
`defaults`	object	No	-	Opaque per-customer ISF defaults, stored verbatim.

Manufacturer record (manufacturer_records[])
Field	Type	Req?	Max	Description
`mid`	string	Yes	15	Manufacturer ID (key).
`name`	string	No	35	Manufacturer name.
`address_1` / `address_2`	string	No	35	Address lines.
`city`	string	No	35	City.
`state` / `postal_code` / `country`	string	No	2 / 10 / 2	State, postal code, country.

Product record (product_records[])
Field	Type	Req?	Max	Description
`product_code`	string	Yes	30	Product code (key).
`description`	string	No	70	Product description.
`tariff_no`	string	No	10	HTS tariff number.
`manufacturer_id`	string	No	15	Optional linked MID.

Carrier record (carrier_records[])
Field	Type	Req?	Description
`code`	string	Yes	SCAC / carrier code (key). Source: legacy IPZPCARRIER.
`name`	string	No	Carrier name.
`mode`	string	No	Transport mode (e.g. O=ocean, A=air, T=truck).

Reference-code record (ref_code_records[])
Field	Type	Req?	Description
`kind`	string	Yes	Lookup namespace (key), e.g. `country`, `foreign_port`, `equipment`, `firms_code`.
`code`	string	Yes	Code within the kind namespace (key).
`name`	string	No	Human-readable name / description.
`extra_json`	string	No	Opaque JSON for extra source fields, stored verbatim.

Company record (company_records[])
Field	Type	Req?	Description
`cid`	string	Yes	Company ID / CID (key). Source: legacy OSCOMP.
`name`	string	No	Company name.
`address_1` / `address_2`	string	No	Address lines.
`city` / `state` / `zip` / `country`	string	No	City, state, postal code, country.
`phone`	string	No	Phone.

Vendor record (vendors[])
Field	Type	Req?	Max	Description
`code`	string	Yes	15	Vendor code / `AP_VEND_CODE` (key). Source: legacy A/P master `APVE{CID}`.
`name`	string	No	-	Vendor name.
`vendor_type` / `contact`	string	No	-	Vendor type, contact name.
`address_1` / `address_2` / `address_3`	string	No	-	Address lines.
`city` / `state` / `zip` / `country` / `overseas`	string	No	-	Location.
`terms_code` / `form_code`	string	No	-	Payment terms + form code.
`gl_acct_ap` / `gl_acct_no` / `our_acct_no` / `recipient_id`	string	No	-	A/P + expense GL accounts, our account no., 1099 recipient id.
`payto_*`	string	No	-	Remit-to (pay-to) name / address / city / state / zip / country / attn / phone. Full field list on the Vendors page.

Response (ImportReport)

Field	Type	Description
`mode`	string	Echo of the request mode.
`customers` / `manufacturers` / `products` / `carriers` / `companies` / `vendors`	Entry	Per-entity-type result block (see below). Null when that set was not processed.
`ref_codes`	int	Scalar count of reference codes upserted (not an Entry block).

Entry block
Field	Type	Description
`inserted`	int	Records newly inserted.
`updated`	int	Records updated (replace mode).
`duplicates`	array<string>	Existing keys skipped (add mode), for manual reconciliation.
`errors`	array<string>	Records that could not be imported (missing key, etc.).