SmartWay™ API Docs

Required Header

x-smartway-api-key: YOUR_API_KEY
Content-Type: application/json

Business Partners

Business Partner records are staged before processing. During processing, SmartWay resolves the partner, creates role assignments, and creates customer relationships.

• Matches existing Business Partners.
• Creates new Business Partners when necessary.
• Creates Partner Role Assignments.
• Creates Customer Relationships.
• Prevents duplicate relationships.
• Maintains complete processing history and audit records.

Endpoint

POST /api/external/v1/import/business-partners

Required Fields

• partnerName
• taxID
• taxTypeID
• website
• relationshipDirection — Source or Target
• relationshipTypeID
• relationshipStatusID
• partnerRoleIDs

Relationship Direction

Use Source when the imported Business Partner is the source of the relationship. Use Target when the imported Business Partner is the target of the relationship.

Sample Request

{
  "sourceSystem": "TestERP",
  "externalBatchID": "BP-REL-001",
  "records": [
    {
      "externalPartnerID": "VEND-1001",
      "partnerName": "ABC Industrial Supply",
      "addressLine1": "123 Main St",
      "city": "Laredo",
      "stateProvince": "TX",
      "postalCode": "78040",
      "country": "USA",
      "taxID": "123456789",
      "taxTypeID": 1,
      "website": "abcindustrial.com",
      "accountNum": "ABC-1001",
      "scopeDescription": "Primary warehouse supplier",
      "relationshipDirection": "Target",
      "relationshipTypeID": 7,
      "relationshipStatusID": 1,
      "relationshipStartDate": "2026-06-29T00:00:00",
      "relationshipEndDate": null,
      "cxInternalTrackingID": "ERP-VEND-1001",
      "isCriticalRelationship": true,
      "isOnSiteAccessGranted": false,
      "isLimitedDataAccessGranted": true,
      "isSensitiveDataAccessGranted": false,
      "isSubjectToCerts": true,
      "isSubjectToRegulatedControl": true,
      "isPermitControls": false,
      "isEscalated": false,
      "escalatedAt": null,
      "isIndirect": false,
      "isCustomer": false,
      "isSubjectToContractRenewal": false,
      "lastContractRenewalAt": null,
      "partnerRoleIDs": [2, 5, 7]
    }
  ]
}

Business Partner Contacts

Business Partner Contacts are staged after Business Partners. These records must include externalPartnerID so SmartWay can link the contact to the resolved Business Partner.

• Resolves the associated Business Partner.
• Matches existing contacts.
• Creates new contacts when required.
• Associates contacts with one or more Partner Roles.
• Creates Customer Contact Relationships.
• Prevents duplicate contact assignments.

Endpoint

POST /api/external/v1/import/business-partner-contacts

Required Fields

• externalPartnerID
• partnerContactTypeID
• At least one of: firstName, lastName, or emailPrimary

Optional Fields

• externalContactID
• parentExternalContactID
• title
• emailOther
• phoneMobile
• phoneOffice
• phoneOther
• phoneOtherDesc
• isPrimary
• acceptedAt

Sample Request

    {
    "sourceSystem": "TestERP",
    "externalBatchID": "BP-CON-001",
    "records": [
    {
    "externalPartnerID": "VEND-1001",
    "externalContactID": "CONT-2001",
    "partnerContactTypeID": 1,
    "title": "Export Manager",
    "emailPrimary": "maria.garcia@vendor.com",
    "phoneOffice": "956-555-4000",
    "firstName": "Maria",
    "lastName": "Garcia",
    "isPrimary": true,
    "acceptedAt": "2026-06-29T00:00:00"
    }
    ]
    }

Business Partner Processing

Business Partner Flow

Business Partner API
        │
        ▼
SWPartnerImportStage
        │
        ▼
Partner Validation
        │
        ▼
Partner Resolution
        │
        ▼
SWPartners
        │
        ▼
Partner Role Assignments
        │
        ▼
Customer Relationships

Business Partner Contact Flow

Business Partner Contact API
        │
        ▼
SWPartnerContactImportStage
        │
        ▼
Partner Resolution
        │
        ▼
SWPartnerContacts
        │
        ▼
CXPartnerContacts

Business Partner and Business Partner Contact imports are asynchronous. Records are staged first and then processed by SmartWay to perform validation, duplicate detection, partner resolution, and relationship creation.

Direct Import Services

Direct import endpoints insert records after API key validation and basic payload checks. These records belong to the customer identified by the API key. Equipment, Catalog, Seals, and Packaging may also be linked to an existing Business Partner relationship.

Business Partner Relationship Linking

Catalog, Equipment, Seals, and Packaging use the same optional partnerInternalTrackingID field in API records and CSV rows.

This customer-defined Business Partner tracking ID links the imported record to the matching Business Partner relationship belonging to the customer identified by the API key.

• For customer-owned records without a Business Partner link, omit the field or leave it blank.
• When supplied, the value must match the Internal Tracking ID of an existing Business Partner relationship in your customer account.
• Complete Business Partner import processing and relationship creation before importing records that reference the relationship. A staged Business Partner import is not yet a completed relationship.
• The value identifies an existing relationship; it does not create a new Business Partner or relationship.
• If a supplied tracking ID cannot be matched, the entire import batch is rejected and no records in that batch are imported. Correct the ID or complete relationship processing before retrying.
• For CSV imports, use partnerInternalTrackingID as the first column in the examples. Leave its cell empty for a row that does not need a Business Partner link.

Catalog Import Process

1. SmartWay validates the API key and identifies the customer account.
2. Each record must include productName.
3. A blank or omitted partnerInternalTrackingID imports the item for the customer without a Business Partner relationship.
4. A supplied ID is resolved to an existing Business Partner relationship within that customer account and the catalog item is linked to it.
5. The batch completes only when all records succeed; an unmatched supplied ID rejects the whole batch.

API Request Examples

Each example is sent to its service endpoint. To import a customer-owned record without a relationship link, omit partnerInternalTrackingID or set it to an empty string.

Catalog

POST /api/external/v1/import/catalog

{
  "sourceSystem": "TestERP",
  "externalBatchID": "CATALOG-001",
  "records": [
    {
      "partnerInternalTrackingID": "QB-VEND-10025",
      "sku": "SKU-1001",
      "productName": "Steel Bracket"
    }
  ]
}

Equipment

POST /api/external/v1/import/equipment

{
  "sourceSystem": "TestERP",
  "externalBatchID": "EQUIPMENT-001",
  "records": [
    {
      "partnerInternalTrackingID": "QB-VEND-10025",
      "equipmentName": "Trailer 1001",
      "assetTagID": "AT1001"
    }
  ]
}

Seals

POST /api/external/v1/import/seals

{
  "sourceSystem": "TestERP",
  "externalBatchID": "SEALS-001",
  "records": [
    {
      "partnerInternalTrackingID": "QB-VEND-10025",
      "sealName": "Bolt Seal Blue",
      "sealType": "Bolt Seal"
    }
  ]
}

Packaging

POST /api/external/v1/import/packaging

{
  "sourceSystem": "TestERP",
  "externalBatchID": "PACKAGING-001",
  "records": [
    {
      "partnerInternalTrackingID": "QB-VEND-10025",
      "packagingSpecID": "PKG-1001",
      "packagingMaterial": "Corrugated cardboard"
    }
  ]
}

See CSV Imports for field definitions and CSV examples for all four services.

Standard Success Responses

Direct Import Response

{
  "status": "Completed",
  "recordsImported": 1,
  "insertedIds": [1001],
  "sourceSystem": "TestERP",
  "externalBatchId": "TEST-001",
  "message": "Records imported successfully."
}

Staged Import Response

{
  "status": "Staged",
  "recordsStaged": 1,
  "stagedIds": [101],
  "sourceSystem": "TestERP",
  "externalBatchId": "BP-001",
  "message": "Records staged for SmartWay validation and relationship processing."
}

Error Responses