Vendor

https://v2.cartage.ai/p/v2/vendor reads (GET) and creates (POST) vendors.

A vendor is a company you move freight with or buy from: a carrier, broker, forwarder, warehouse or supplier. A quote's vendorId points at one.

Authentication, the create envelope, error format and shared objects are in Shared rules.

GET /p/v2/vendor

Read one vendor by id. Names and emails are not unique, so id is the only lookup.

Parameter	Required	Description
orgId	Yes	Your organization ID
id	Yes	Vendor id, for example a quote's vendorId

curl "https://v2.cartage.ai/p/v2/vendor?orgId=<yourOrgId>&id=<vendorId>" \
  -H "X-API-Key: <yourApiKey>"

Returns the vendor (see Schema).

POST /p/v2/vendor

Create one vendor.

Required fields

Field	Required	If missing
name	Always	422 VENDOR_NAME
One contact you can reach	Always. At least one contacts[] entry with an email or a phone.	422 VENDOR_CONTACT
contacts[].role, contacts[].isPrimary	On every contact you send	400
supplierHandlingMode	Only when vendorType is supplier	422 VENDOR_SUPPLIER_HANDLING_MODE

Smallest valid vendor:

{
    "name": "Acme Trucking",
    "contacts": [
        { "email": "dispatch@acmetrucking.com", "role": "dispatch", "isPrimary": true }
    ]
}

A phone works in place of the email. Everything else is optional.

Example

curl -X POST "https://v2.cartage.ai/p/v2/vendor" \
  -H "X-API-Key: <yourApiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<yourOrgId>",
    "vendor": {
      "name": "Acme Trucking",
      "vendorType": "carrier",
      "mcNumber": "MC-765432",
      "contacts": [
        {
          "fullName": "Dana Reyes",
          "email": "dispatch@acmetrucking.com",
          "role": "dispatch",
          "isPrimary": true
        }
      ],
      "serviceTypes": ["ftl", "ltl"],
      "paymentTerms": "net30"
    }
  }'

{
    "status": "CREATED",
    "vendor": { "id": "vnd_123", "name": "Acme Trucking", "…": "…" }
}

Errors

Status	Code	Meaning and fix
400	—	Missing orgId or id on GET. On POST, a contact without role or isPrimary, an unknown enum value, or a field not in the Schema. issues[] names each one.
401	—	Missing or invalid API key
404	VENDOR_NOT_FOUND	No vendor with that id in your organization
422	REQUIRED_FIELDS_MISSING	A required field is missing. Each issues[] entry carries one of the codes in Required fields.

Schema

Optional unless marked Required. id, orgId, createdAt, updatedAt and activityLog are returned on every vendor and cannot be sent.

Field	Type	Description
name	string	Required. Common name
vendorType	enum	carrier (default) | broker | customsBroker | freightForwarder | warehouse | supplier | other
status	enum	active (default) | inactive | suspended | pending
contacts	object[]	At least one reachable contact required. See Contacts below.
supplierHandlingMode	enum	Required for suppliers. deliver if the supplier delivers to you, pickup if you collect
legalName / doingBusinessAsName	string	Registered and trading names
alternateNames	string[]	Other spellings to match this vendor by
taxId	string	Tax identifier
dotNumber / mcNumber	string	USDOT and MC numbers
carrierCodes	string[]	Your own codes or aliases for this carrier
website	string	Website
address	Address	Business address
serviceTypes	enum[]	ftl | ltl | drayage | rail | ocean | air | lastMile | parcel | willCall
equipmentTypes	enum[]	Equipment the carrier runs. Same values as a shipment's equipment.
insuranceExpiry	string	YYYY-MM-DD
insuranceAmount	Money	Coverage limit
authorityStatus	enum	active | inactive | revoked
paymentTerms	enum	net0 | net7 | net15 | net28 | net30 | net60 | net90
notes	string	Free-form notes
fileIds	string[]	Attached files

Contacts

Each contacts[] entry is a Contact (see Shared rules) plus:

Field	Type	Description
role	enum	Required. billing | dispatch | quoting | pickup | other
isPrimary	boolean	Required. Whether this is the main contact

Read-only fields

Field	Type	Description
primaryContact	Contact	The contact marked isPrimary
contactEmails	string[]	Every unique email across contacts