Kargoplex Logo Dark
Developers

Kargoplex APIv1.1.0

The Kargoplex public API: parties, quotes, jobs, document requests and invoices for your own company. Authenticate with an API key from Settings → Developers (Authorization: Bearer kp_live_…). Each key carries scopes, and each plan sets calls a minute per company and calls a month. Every response is { success, data } or { success: false, error, code }.

Base URL: https://server.kargoplex.com/kargoplex/api/public/v1
Download OpenAPI specGet an API key

Authentication

Send your API key as a bearer token in the Authorization header. Scheme: bearer (kp_live_<prefix>_<secret>).

A secret API key. Scopes: parties:read, parties:write, quotes:read, quotes:write, jobs:read, jobs:write, documents:read, documents:write, invoices:read. Never use one in a browser.

curl -H "Authorization: Bearer kp_live_..." https://server.kargoplex.com/kargoplex/api/public/v1/parties

Rate limits

Each plan sets how many calls a minute a key and a company can make, and how many calls a month. The per-key limit and the per-company limit both apply, and the monthly quota is shared across the company.

When you go over a limit the API answers with status 429 and a Retry-After header: wait that many seconds before calling again. When the monthly quota is used up the API answers 402.

  • RateLimit: Remaining calls in the current window (IETF draft-7 combined header: limit, remaining, reset).
  • RateLimit-Policy: The limit and window that apply.
  • Retry-After: Seconds until the window resets.

Errors

Failed calls return an error body. Successful calls return { success: true, data }.

Error body fields
FieldRequiredType
successYesfalse
errorYesstring
codeNostring
detailNoany
Response status codes
StatusMeaning
200OK
400The input failed validation.
401Missing, malformed, revoked or expired API key (one message for all).
402The plan's monthly API calls are used up.
403The key lacks this scope, or the plan lacks the API feature.
404Not found among your company's records.
429Too many calls: the per-key or the per-company limit a minute. Wait for Retry-After seconds.

API reference

Parties

Customers, consignees, agents and carriers in your directory.

get/parties

List parties Scope: parties:read

List your parties (customers, consignees, agents, carriers). Filter by q, role, status; paginate with page/limit.

Requires the parties:read scope and the plan's apiRead feature.

Parameters
Parameters for parties_list
NameInRequiredType
qqueryNostring
rolequeryNoCUSTOMER, SHIPPER, CONSIGNEE, NOTIFY, AGENT, CARRIER, TRUCKER, BROKER, WAREHOUSE, OTHER
groupIdqueryNostring
statusqueryNoACTIVE, ARCHIVED
linkedqueryNotrue, false
pagequeryNointeger
limitqueryNointeger

post/parties

Create a party Scope: parties:write

Create a party. Only name is required.

Requires the parties:write scope and the plan's apiWrite feature.

Request body (JSON, required)
Request body fields for parties_create
FieldRequiredType
nameYesstring
kindNoCOMPANY, PERSON
rolesNoarray of: CUSTOMER, SHIPPER, CONSIGNEE, NOTIFY, AGENT, CARRIER, TRUCKER, BROKER, WAREHOUSE, OTHER
codeNostring
legalNameNostring
websiteNostring
notesNostring
contactsNoarray of object
contacts[]._idNostring
contacts[].nameNostring
contacts[].emailNostring
contacts[].phoneNostring
contacts[].titleNostring
contacts[].isPrimaryNoboolean
addressesNoarray of object
addresses[]._idNostring
addresses[].labelNostring
addresses[].typeNoBILLING, OFFICE, PICKUP, DELIVERY
addresses[].line1Nostring
addresses[].line2Nostring
addresses[].cityNostring
addresses[].stateNostring
addresses[].postalCodeNostring
addresses[].countryCodeNostring
addresses[].isDefaultNoboolean
taxIdsNoarray of object
taxIds[].typeYesVAT, GST, HST, TIN, EIN, BN, EORI, OTHER
taxIds[].valueYesstring
taxIds[].countryCodeNostring
billingNoobject
billing.currencyNostring
billing.paymentTermsDaysNointeger
billing.creditLimitNoobject
billing.onHoldNoboolean
billing.taxCodeIdNostring
billing.withholdingTaxCodeIdNostring
billing.statementMonthlyNoboolean
groupIdsNoarray of string
tagsNoarray of string

get/parties/{id}

Get a party Scope: parties:read

Get one party by id.

Requires the parties:read scope and the plan's apiRead feature.

Parameters
Parameters for parties_get
NameInRequiredType
idpathYesstring

Quotes

Quotes to your customers.

get/quotes

List quotes Scope: quotes:read

List your quotes. Filter by status, customerPartyId, q, from/to; paginate with page/limit.

Requires the quotes:read scope and the plan's apiRead feature.

Parameters
Parameters for quotes_list
NameInRequiredType
statusqueryNoDRAFT, SENT, ACCEPTED, DECLINED, LOST, EXPIRED, WITHDRAWN
shipmentRequestIdqueryNostring
sourceTypequeryNoMANUAL, RFQ, WEBSITE, MARKETPLACE, EMAIL, AI
customerPartyIdqueryNostring
branchIdqueryNostring
qqueryNostring
fromqueryNostring
toqueryNostring
pagequeryNointeger
limitqueryNointeger

post/quotes

Create a draft quote Scope: quotes:write

Create a DRAFT quote for a customer party. Lines are priced by your pricing rules.

Requires the quotes:write scope and the plan's apiWrite feature.

Request body (JSON, required)
Request body fields for quotes_create
FieldRequiredType
customerPartyIdNostring
contactNameNostring
contactEmailNostring
sourceNoobject
source.typeNoMANUAL, RFQ, WEBSITE, MARKETPLACE, EMAIL, AI
source.shipmentRequestIdNostring
source.websiteQuoteRequestIdNostring
source.referenceNostring
laneNoobject
lane.originNoobject
lane.destinationNoobject
lane.transportModeNostring
lane.loadTypeNostring
lane.incotermNostring
lane.serviceLevelNostring
lane.carrierNameNostring
lane.transitDaysNoobject
cargoNoobject
cargo.rowsNoarray of object
cargo.containerTypesNoarray of string
cargo.containersNonumber
cargo.commodityNostring
cargo.dangerousGoodsNoboolean
currencyYesstring
validFromNostring | string (date-time)
validToNostring | string (date-time)
linesNoarray of object
lines[]._idNostring
lines[].chargeCodeNostring
lines[].descriptionYesstring
lines[].categoryNoFREIGHT, ORIGIN, DESTINATION, SURCHARGE, CUSTOMS, INSURANCE, STORAGE, DISBURSEMENT, PROFIT_SHARE, OTHER
lines[].unitYesPER_KG, PER_100KG, PER_CBM, PER_CONTAINER, PER_SHIPMENT, FLAT, PER_LM, PER_DAY, PER_STOP, PER_KM, PER_MILE, PER_PALLET, PER_CWT, PER_ULD
lines[].qtySourceNoLOAD, MANUAL
lines[].weightBasisNoCHARGEABLE, GROSS
lines[].quantityNonumber
lines[].buyYesobject
lines[].sellOverrideNoobject
lines[].uldNoobject
lines[].taxCodeIdNostring
lines[].withholdingTaxCodeIdsNoarray of string
lines[].hiddenNoboolean
lines[].notesNostring
customerNotesNostring
internalNotesNostring
termsNostring

get/quotes/{id}

Get a quote Scope: quotes:read

Get one quote by id, with buy and sell lines.

Requires the quotes:read scope and the plan's apiRead feature.

Parameters
Parameters for quotes_get
NameInRequiredType
idpathYesstring

post/quotes/{id}/send

Send a draft quote Scope: quotes:write

Send a DRAFT quote: freezes the version the customer sees. Needs a visible line and a valid-until date.

Requires the quotes:write scope and the plan's apiWrite feature.

Parameters
Parameters for quotes_send
NameInRequiredType
idpathYesstring

Jobs

Your jobs (shipments you run).

get/jobs

List jobs Scope: jobs:read

List your jobs. Filter by jobStatus, customerPartyId, q; paginate with page/limit.

Requires the jobs:read scope and the plan's apiRead feature.

Parameters
Parameters for jobs_list
NameInRequiredType
jobStatusqueryNoOPEN, BOOKED, IN_TRANSIT, ARRIVED, DELIVERED, CLOSED, CANCELLED
customerPartyIdqueryNostring
branchIdqueryNostring
qqueryNostring
pagequeryNointeger
limitqueryNointeger

post/jobs/from-quote/{quoteId}

Open the job for an accepted quote Scope: jobs:write

Open the job for an ACCEPTED quote (idempotent: returns the existing job). Refused when the customer is over its credit limit or on hold.

Requires the jobs:write scope and the plan's apiWrite feature.

Parameters
Parameters for jobs_create_from_quote
NameInRequiredType
quoteIdpathYesstring

get/jobs/{id}

Get a job Scope: jobs:read

Get one job by id.

Requires the jobs:read scope and the plan's apiRead feature.

Parameters
Parameters for jobs_get
NameInRequiredType
idpathYesstring

Document requests

Requests for documents, with an upload link.

get/document-requests

List document requests Scope: documents:read

List your document requests. Filter by status, subjectType, subjectId, toPartyId.

Requires the documents:read scope and the plan's apiRead feature.

Parameters
Parameters for document_requests_list
NameInRequiredType
statusqueryNoOPEN, COMPLETE, CANCELLED
subjectTypequeryNoJOB, CLEARANCE, QUOTE, PARTY_KYC, PARTNER_DD
subjectIdqueryNostring
toPartyIdqueryNostring
pagequeryNointeger
limitqueryNointeger

post/document-requests

Request documents from a party Scope: documents:write

Ask a party for documents about a job/quote. Emails the upload link unless send is false.

Requires the documents:write scope and the plan's apiWrite feature.

Request body (JSON, required)
Request body fields for document_requests_create
FieldRequiredType
subjectYesobject
subject.typeYesJOB, CLEARANCE, QUOTE, PARTY_KYC, PARTNER_DD
subject.idYesstring
toPartyIdNostring
recipientNoobject
recipient.nameNostring
recipient.emailNostring
templateIdNostring
itemsNoarray of object
items[].typeKeyYesstring
items[].labelYesstring
items[].requiredNoboolean
items[].noteNostring
dueDateNostring (date-time)
messageNostring
sendNoboolean

get/document-requests/{id}

Get a document request Scope: documents:read

Get one document request by id.

Requires the documents:read scope and the plan's apiRead feature.

Parameters
Parameters for document_requests_get
NameInRequiredType
idpathYesstring

Invoices

Your customer invoices (read only).

get/invoices

List customer invoices Scope: invoices:read

List your customer invoices (built from job charge lines). Filter by status or jobId.

Requires the invoices:read scope and the plan's apiRead feature.

Parameters
Parameters for invoices_list
NameInRequiredType
statusqueryNoDRAFT, SENT, ACCEPTED, REJECTED, PARTIAL, PAID, OVERDUE, WITHDRAWN, CANCELLED, WRITTEN_OFF
jobIdqueryNostring
pagequeryNointeger
limitqueryNointeger

get/invoices/{id}

Get a customer invoice Scope: invoices:read

Get one customer invoice by id.

Requires the invoices:read scope and the plan's apiRead feature.

Parameters
Parameters for invoices_get
NameInRequiredType
idpathYesstring