Loop artifacts-schema-validated API
The artifacts-schema-validated API from Loop — 6 operation(s) for artifacts-schema-validated.
OpenAPI Specification
openapi: 3.0.0
info:
title: Loop Onboarding artifacts artifacts-schema-validated API
description: HTTP REST API for Loop Payments Onboarding.
version: '1.0'
contact: {}
servers:
- url: https://onboarding.api.loop.com
security:
- bearerAuth: []
tags:
- name: artifacts-schema-validated
paths:
/v1/artifacts/cost-coding-table-entry-list:
post:
description: '
Creates a new cost coding table entries record artifact containing multiple entries for a specific cost coding table.
This API validates that:
- The specified cost coding table exists
- All required fields (as defined by the table''s field definitions) are present in each entry
- No extra fields are included that aren''t defined for the table
- The user has permission to modify the specified table
The entries will be processed according to the table''s merge strategy configuration:
- APPEND: New entries are added to the table
- INSERT_ONLY: New entries are added only if they don''t already exist (based on upsert keys)
- UPSERT: New entries are added or existing entries are updated (based on upsert keys)
For more information, please see our [public docs](https://docs.loop.com/how-loop-works/artifact-ingestion).
**Batching:** Send many entries per request rather than one entry per request. High volumes of small single-entry uploads to the same table may be rate-limited with a `429 Too Many Requests` response; batching your entries into fewer, larger requests avoids this.
**Note:** This endpoint is in development and subject to change.
'
operationId: CostCodingTableEntryListArtifact_create
parameters:
- name: expand
required: false
in: query
schema:
type: array
items:
type: string
enum:
- tags
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCostCodingTableEntryListArtifactInput'
examples:
shipperAccountMapping:
summary: Shipper Account to GL Code Mapping
description: Example mapping shipper accounts to default GL codes
value:
tableQid: qid:cost_coding_table:abc123
entries:
- shipperAccountNumber: FEDEX-12345
glCodeDefault: 5000-1000-2000
shipperAccountName: FedEx Primary Account
- shipperAccountNumber: UPS-67890
glCodeDefault: 5000-1000-3000
shipperAccountName: UPS Secondary Account
artifactTags:
source: erp-system
uploadBatch: 2025-01-batch-001
locationMapping:
summary: Location to GL Segment Mapping
description: Example mapping location IDs to GL code segments
value:
tableQid: qid:cost_coding_table:def456
entries:
- locationId: DC-001
glSegmentCostCenterCode: '1000'
glSegmentDoorCode: '100'
locationType: distribution-center
- locationId: STORE-123
glSegmentCostCenterCode: '2000'
glSegmentDoorCode: '200'
locationType: retail-store
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Artifact'
'429':
description: Too many small (single/low-entry) uploads to this cost coding table within the rate-limit window. Batch more entries per request and retry.
summary: Create a cost coding table entries record artifact. Please reach out to Loop for initial table set up.
tags:
- artifacts-schema-validated
/v1/artifacts/organization-factor-assignment-record:
post:
description: "Creates a new OrganizationFactorAssignment record artifact.\n\nThe OrganizationFactorAssignment record artifact is a structured, schema-enforced object that \ncarries the information needed to validate a factoring relationship between two orgs."
operationId: OrganizationFactorAssignmentRecordArtifacts_create
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrganizationFactorAssignmentRecordArtifactInput'
examples:
'1':
value:
carrierOrganizationQid: qid::organization:ad894a60-34a6-49e0-b3f4-a6cbab0f47b6
factorInfo:
name: ACME Factoring, Inc.
primaryAddress:
addressLine1: 123 Main St
addressLine2: Suite 100
city: San Diego
state: CA
postalCode: '92101'
country: USA
remittanceAddress:
addressLine1: 123 Main St
addressLine2: Suite 100
city: San Diego
state: CA
postalCode: '92101'
country: USA
additionalInfo:
phone: 858-555-1212
last4AccountNumber: '1234'
arContact:
name: John Doe
role: Accountant
email: jd@acme.com
phone: '7708820124'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Artifact'
summary: Create a OrganizationFactorAssignment record artifact
tags:
- artifacts-schema-validated
/v1/artifacts/payable-invoice-record:
post:
description: Creates a payable invoice record artifact from provided invoice data. The payable invoice record artifact is a structured, schema-enforced object that represents a payable invoice at a point in time. This artifact is used to generate a normalized representation of a payable invoice in Loop. Non-unique invoices will not be assigned to the payable invoice and simply return the created artifact. The generated artifact will be assigned to the payable invoice entity. The payor, payee, and vendor organizations are all required; each may be identified by either its QID or a tag. For more information, please see our [public docs](https://docs.loop.com/how-loop-works/artifact-ingestion). **Note:** This endpoint is in development and subject to change.
operationId: CreatePayableInvoiceRecordArtifact_create
parameters:
- name: expand
required: false
in: query
schema:
type: array
items:
type: string
enum:
- tags
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePayableInvoiceRecordArtifactInput'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Artifact'
summary: Create a payable invoice record artifact
tags:
- artifacts-schema-validated
/v1/artifacts/purchase-order-record:
post:
description: '
Creates a new purchase order record artifact.
The purchase order record artifact is a structured, schema-enforced object that represents a purchase order or an individual component of a purchase order.
The purchase order number is used as the primary identifier for the document, and is used to assign the record.
For more information, please see our [public docs](https://docs.loop.com/how-loop-works/artifact-ingestion).
**Note:** This endpoint is in development and subject to change.
'
operationId: PurchaseOrderRecordArtifact_create
parameters:
- name: expand
required: false
in: query
schema:
type: array
items:
type: string
enum:
- tags
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePurchaseOrderRecordArtifactInput'
examples:
basicExample:
summary: Basic Purchase Order
description: Example purchase order record with all fields
value:
purchaseOrderNumber: PO-2025-001234
createdDate: '2025-01-15'
supplierName: ACME Manufacturing Corp
supplierOrganizationTag:
tagType: supplierNumber
tagValue: '12345'
artifactTags: {}
minimalExample:
summary: Minimal Purchase Order
description: Example with only required fields
value:
purchaseOrderNumber: PO-MIN-5678
supplierOrganizationTag:
tagType: supplierNumber
tagValue: '12345'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Artifact'
summary: Create a purchase order record artifact
tags:
- artifacts-schema-validated
/v1/artifacts/receivable-invoice-record:
post:
description: 'Creates a new receivable invoice record artifact.
The receivable invoice record artifact is a structured, schema-enforced object
that represents a receivable invoice at a point in time. This artifact is
used to generate a normalized representation of a receivable invoice in Loop.
Asynchronously, Loop will normalize the receivable invoice entity and link
the invoice to a shipment.
For more information on artifacts, please see our
[public docs](https://docs.loop.com/how-loop-works/artifact-ingestion).
**Note:** This endpoint is in development and subject to change.'
operationId: ReceivableInvoiceRecordArtifact_create
parameters:
- name: expand
required: false
in: query
schema:
type: array
items:
type: string
enum:
- tags
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateReceivableInvoiceRecordArtifactInput'
responses:
'201':
description: The record has been successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/Artifact'
'400':
description: Request body validation failed.
summary: Create a receivable invoice record artifact
tags:
- artifacts-schema-validated
/v1/artifacts/shipment-record:
post:
description: 'Creates a new shipment record artifact.
The shipment record artifact is a structured, schema-enforced object that represents a set of logistics activity at a point in time. This artifact is extracted and merged downstream with other artifacts from various sources (TMS, Email, etc) in different formats (PDF, PNG, JSON, etc) to form normalized shipment and job entities.
A shipment record is expected to have a single unique external identifier that matches the identifier used for the shipment in the source system. This identifier is used to assign the shipment record.
For more information, please see our [public docs](https://docs.loop.com/how-loop-works/artifact-ingestion).
**Note:** This endpoint is in development and subject to change.'
operationId: ShipmentRecordArtifacts_create
parameters:
- name: expand
required: false
in: query
schema:
type: array
items:
type: string
enum:
- tags
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateShipmentRecordArtifactInput'
examples:
FTL:
summary: FTL example
description: A simple FTL shipment job with a single pickup, dropoff and expected charges.
value:
jobs:
- jobType: FTL
jobTypeInfo:
jobType: FTL
freightChargeTerms: COLLECT
carrierOrganizationTag:
tagType: externalCarrierUuid
tagValue: 304fb3dd-1f4a-404b-9f9e-c9134584915b
stops:
- address:
addressLine1: 123 Main Street
city: Anytown
state: CA
postalCode: '12345'
country: US
date: '2023-01-01'
organizationQid: qid::organization:b309f6cf-cc13-4c4c-a55b-da71a7405d04
organizationTag:
tagType: externalShipperUuid
tagValue: 304fb3dd-1f4a-404b-9f9e-c9134584915b
stopType: PICK_UP
articles:
- dimensions:
height: '12'
length: '12'
unit: INCH
width: '12'
grossWeight:
amount: '387'
unit: POUND
nmfcClass: '50'
packageCount:
amount: 11
unit: CARTON
- address:
addressLine1: 123 Second Street
city: Anytown
state: CA
postalCode: '12345'
country: US
date: '2023-01-06'
organizationQid: qid::organization:92fc8b83-459c-450c-8f92-47bd5b7063f8
stopType: DROP_OFF
articles:
- dimensions:
height: '12'
length: '12'
unit: INCH
width: '12'
grossWeight:
amount: '387'
unit: POUND
nmfcClass: '50'
packageCount:
amount: 11
unit: CARTON
expectedCharges:
- code: '240'
description: Linehaul Charge
category: LINEHAUL
amount:
amount: '1200.56'
currencyCode: USD
- code: '872'
description: California Fuel Surcharge
category: FUEL_SURCHARGE
amount:
amount: '450.56'
currencyCode: USD
- code: '950'
description: Loading Fee
category: OTHER
amount:
amount: '100.23'
currencyCode: USD
LTL:
summary: LTL example
description: A simple LTL shipment with associated charges.
value:
jobs:
- jobType: LTL
jobTypeInfo:
jobType: LTL
freightChargeTerms: PREPAID
originAddress:
addressLine1: 123 Main Street
addressLine2: Suite 456
city: Chicago
state: IL
postalCode: '60601'
country: USA
pickupDate: '2023-01-01'
destinationAddress:
addressLine1: 123 Main Street
addressLine2: Suite 456
city: Chicago
state: IL
postalCode: '60601'
country: USA
deliveryDate: '2023-01-06'
articles:
- dimensions:
height: '12'
length: '12'
unit: INCH
width: '12'
grossWeight:
amount: '387'
unit: POUND
nmfcClass: '50'
packageCount:
amount: 11
unit: CARTON
expectedCharges:
- code: '240'
description: Linehaul Charge
category: LINEHAUL
amount:
amount: '350.12'
currencyCode: USD
- code: '872'
description: California Fuel Surcharge
category: FUEL_SURCHARGE
amount:
amount: '100.56'
currencyCode: USD
- code: '950'
description: Liftgate Service Fee
category: OTHER
amount:
amount: '50.23'
currencyCode: USD
TONU:
summary: FTL with TONU example
value:
jobs:
- jobType: FTL
jobTypeInfo:
jobType: FTL
freightChargeTerms: COLLECT
carrierOrganizationTag:
tagType: externalCarrierUuid
tagValue: 304fb3dd-1f4a-404b-9f9e-c9134584915b
stops:
- address:
addressLine1: 123 Main Street
city: Anytown
state: CA
postalCode: '12345'
country: US
date: '2023-01-01'
organizationQid: qid::organization:b309f6cf-cc13-4c4c-a55b-da71a7405d04
organizationTag:
tagType: externalShipperUuid
tagValue: 304fb3dd-1f4a-404b-9f9e-c9134584915b
stopType: PICK_UP
articles:
- dimensions:
height: '12'
length: '12'
unit: INCH
width: '12'
grossWeight:
amount: '387'
unit: POUND
nmfcClass: '50'
packageCount:
amount: 11
unit: CARTON
- address:
addressLine1: 123 Second Street
city: Anytown
state: CA
postalCode: '12345'
country: US
date: '2023-01-06'
organizationQid: qid::organization:92fc8b83-459c-450c-8f92-47bd5b7063f8
stopType: DROP_OFF
articles:
- dimensions:
height: '12'
length: '12'
unit: INCH
width: '12'
grossWeight:
amount: '387'
unit: POUND
nmfcClass: '50'
packageCount:
amount: 11
unit: CARTON
expectedCharges:
- code: '240'
description: Linehaul Charge
category: LINEHAUL
amount:
amount: '1200.56'
currencyCode: USD
- code: '872'
description: California Fuel Surcharge
category: FUEL_SURCHARGE
amount:
amount: '450.56'
currencyCode: USD
- code: '950'
description: Loading Fee
category: OTHER
amount:
amount: '100.23'
currencyCode: USD
- jobType: TONU
jobTypeInfo:
jobType: TONU
carrierOrganizationQid: qid::organization:f541be44-57d3-4559-a974-6808a45eebd0
carrierOrganizationTag:
tagType: externalCarrierUuid
tagValue: 3e5ebd1f-cb2b-42d4-8d60-70e9f63ff9e2
expectedCharges:
- code: '780'
description: TONU
category: OTHER
amount:
amount: '150.23'
currencyCode: USD
Ocean:
summary: Ocean FCL example
description: An ocean freight shipment with FCL consolidation, container details, and route locations.
value:
jobs:
- jobType: OCEAN
jobTypeInfo:
jobType: OCEAN
freightChargeTerms: PREPAID
carrierOrganizationTag:
tagType: externalCarrierUuid
tagValue: 8a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
forwarderOrganizationTag:
tagType: externalForwarderUuid
tagValue: f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d
consolidationType: FCL
addresses:
- type: ORIGIN
name: Shanghai Warehouse
address:
addressLine1: 123 Port Road
city: Shanghai
state: Shanghai
postalCode: '200000'
country: CN
- type: DESTINATION
name: Los Angeles Distribution Center
address:
addressLine1: 456 Harbor Blvd
city: Los Angeles
state: CA
postalCode: '90001'
country: US
routeLocations:
- type: PORT_OF_LOADING
unlocode: CNSHA
name: Port of Shanghai
- type: PORT_OF_DISCHARGE
unlocode: USLAX
name: Port of Los Angeles
containers:
- containerNumber: MSKU1234567
containerType: HC40
- containerNumber: MSKU7654321
containerType: HC40
totalVolume:
value: '135.5'
unit: CUBIC_METER
dates:
- dateType: LADEN_ON_BOARD
date: '2026-01-15'
unlocode: CNSHA
- dateType: ESTIMATED_ARRIVAL
date: '2026-02-10'
unlocode: USLAX
expectedCharges:
- code: OFR
description: Ocean Freight
category: LINEHAUL
amount:
amount: '3500'
currencyCode: USD
- code: THC
description: Terminal Handling Charge
category: OTHER
amount:
amount: '450'
currencyCode: USD
- code: DOC
description: Documentation Fee
category: OTHER
amount:
amount: '75'
currencyCode: USD
Air:
summary: Air freight example
description: An air freight shipment with airport route locations, addresses, and chargeable weight.
value:
jobs:
- jobType: AIR
jobTypeInfo:
jobType: AIR
freightChargeTerms: PREPAID
carrierOrganizationTag:
tagType: externalCarrierUuid
tagValue: a1b2c3d4-e5f6-7890-abcd-ef1234567890
forwarderOrganizationTag:
tagType: externalForwarderUuid
tagValue: 12345678-abcd-ef01-2345-67890abcdef0
addresses:
- name: Frankfurt Shipper Facility
type: ORIGIN
address:
addressLine1: 100 Cargo Strasse
city: Frankfurt
state: Hessen
postalCode: '60549'
country: DE
- name: Chicago Consignee Warehouse
type: DESTINATION
address:
addressLine1: 500 Air Cargo Way
city: Chicago
state: IL
postalCode: '60666'
country: US
chargeableWeight:
amount: '1250'
unit: KILOGRAM
routeLocations:
- type: ORIGIN_AIRPORT
canonicalAirportQid: qid::canonical_airport:c1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6
- type: DESTINATION_AIRPORT
canonicalAirportQid: qid::canonical_airport:a9b8c7d6-e5f4-a3b2-c1d0-e9f8a7b6c5d4
dates:
- dateType: FLIGHT_DEPARTURE
date: '2026-01-15'
iataCode: FRA
- dateType: FLIGHT_ARRIVAL
date: '2026-01-16'
iataCode: ORD
expectedCharges:
- code: AFR
description: Air Freight
category: LINEHAUL
amount:
amount: '2800'
currencyCode: USD
- code: FSC
description: Fuel Surcharge
category: FUEL_SURCHARGE
amount:
amount: '320'
currencyCode: USD
- code: AWB
description: Air Waybill Fee
category: OTHER
amount:
amount: '50'
currencyCode: USD
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Artifact'
summary: Create a shipment record artifact
tags:
- artifacts-schema-validated
components:
schemas:
CreateShipmentRecordArtifactInput:
type: object
properties:
source:
type: string
description: The source of the shipment data.
jobs:
type: array
items:
$ref: '#/components/schemas/CreateShipmentRecordJobInput'
artifactTags:
type: object
description: Entity tags assigned to the artifact
required:
- jobs
ShipmentRecordArtifactJobFtlInfo:
type: object
properties:
freightChargeTerms:
allOf:
- $ref: '#/components/schemas/FreightChargeTerms'
carrierOrganizationQid:
type: string
description: Qualified unique identifier.
example: qid::organization:0ca6f700-4137-4d09-b44a-43bb8d7900c4
format: qid
nullable: true
carrierOrganizationTag:
example:
tagType: externalCarrierUuid
tagValue: 304fb3dd-1f4a-404b-9f9e-c9134584915b
description: A tag used to identify the carrier organization. Must be specified if carrierOrganizationQid is not specified.
nullable: true
type: object
allOf:
- $ref: '#/components/schemas/RawEntityTag'
stops:
type: array
items:
$ref: '#/components/schemas/ShipmentRecordArtifactJobFtlStop'
required:
- freightChargeTerms
- stops
Weight:
type: object
properties:
amount:
type: string
format: decimal-string
example: '1.5'
unit:
type: string
enum:
- KILOGRAM
- OUNCE
- POUND
- SHORT_TON
example: POUND
required:
- amount
- unit
CreatePayableInvoiceLineItemInput:
type: object
properties:
description:
type: string
description: The description of the line item.
amount:
example:
amount: '3.50'
currencyCode: USD
description: The amount charged for this line item.
allOf:
- $ref: '#/components/schemas/Money'
category:
type: string
description: The category of the line item.
enum:
- LINEHAUL
- FUEL_SURCHARGE
- DISCOUNT
- OTHER
required:
- description
- amount
- category
RawSparseAddressValue:
type: object
properties:
addressLine1:
type: string
example: 123 Main Street
addressLine2:
type: string
example: Suite 456
city:
type: string
example: Chicago
state:
type: string
description: Any variation of state. For example, "IL" or "Illinois" or something else.
example: IL
postalCode:
type: string
example: '60601'
country:
type: string
description: Any variation of a country name or country ISO 2 code. For example, it could be empty, "US", "USA", "United States", "United States of America", "America", etc.
example: USA
ArtifactExpanded:
type: object
properties:
qid:
type: string
description: Qualified unique identifier.
example: qid::artifact:0ca6f700-4137-4d09-b44a-43bb8d7900c4
format: qid
artifactType:
type: string
description: Domain-specific type of the artifact.
enum:
- ACCOUNT_STATEMENT
- BILL_OF_LADING
- CUSTOMER_RATE_CONFIRMATION
- DELIVERY_ORDER
- DELIVERY_RECEIPT
- EXTERNAL_SHIPMENT_NOTE
- INVOICE
- IN_OUT_GATE
- LUMPER_RECEIPT
- OTHER
- PACKET
- PACKING_LIST
- RATE_CONFIRMATION
- SCALE_TICKET
- SHIPMENT_RECORD
- UNKNOWN
- WASHOUT_RECEIPT
- WEIG
# --- truncated at 32 KB (104 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/loop/refs/heads/main/openapi/loop-artifacts-schema-validated-api-openapi.yml