Fetching BOLs via API

This guide describes how to retrieve Bills of Lading (BOLs) and associated documents from Vector using the REST API. Vector provides two methods: fetching a single document by UUID, or searching for documents with filters.

Authenticate

Bearer token required

Search Documents

Filter, sort, paginate

Download Files

CDN-hosted attachments

Authentication

All API requests require a Bearer token. Your token will be provided by Vector support during onboarding. Include it in the Authorization header of every request.

Base URL:https://api.withvector.com/1.0

Auth Header:Authorization: Bearer YOUR_TOKEN

Content Type:application/json (POST requests only)

Understanding Schemas

Vector uses a metadata-driven architecture based on JSON Schema (draft 4). Resources declare the schemas they implement through mixins, which define custom properties and required fields. Common schemas include:

Field	Type	Required	Description
entity.json	11111111-0000-0000-0000-000000000000	Optional	Abstract object model - base for all entities.
document.json	11111111-0000-0000-0000-000000000011	Optional	Abstract document model - base for all documents.
core_documents_shipment.json	2f9d88dc-f5d8-4a41-937b-df401d455131	Optional	Core shipment document type.

Note: When filtering for documents, use the Document mixin UUID 11111111-0000-0000-0000-000000000011

Get Single Document

Retrieve a single document by its UUID:

GET/1.0/entities/records/:uniqueId

Request

curl --request GET \
  --url https://api.withvector.com/1.0/entities/records/1e472093-e838-40d8-836f-ca576bd2a256 \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Document Search

The Document Search API (POST /1.0/entities/query) allows you to query documents stored in Vector using a flexible, structured request body. It accepts a set of parameters, performs a filtered search against the platform's entity store, and returns matching documents in a sorted, paginated order. Even if no results are found, the API always returns a 200 with an empty result set rather than an error.

POST/1.0/entities/query

Search Request Structure

The request body has three top-level sections — filters, orders, and metadata.

filters is an array of filter objects that narrow down which documents are returned. Each filter specifies a type (the operator), a path (the field being evaluated), and a value or values to match against. Filters can be scoped to a specific entity schema using entityType, and can include a human-readable label for display purposes. The full set of supported filter types is documented separately (match, containsEdge, range, prefix, exists, etc.).
orders controls the sort order of the response. Each order entry takes a path (field or edge to sort by), a type of either "ascending" or "descending", and a label. There's also a special _count path syntax for sorting grouped results by the count of entities in each group.
metadata controls pagination and result grouping. The key fields are size (max results per page), offset (for paging through results), maxSizePerGroup (max results per group for grouped queries), and shouldIncludeLeafEntities (a convenience flag to include entities as children of leaf groups, avoiding the need to manually add a group:Entity entry).

Example Request

Search for documents created within a date range, sorted by creation date:

cURL

curl --request POST \
  --url https://api.withvector.com/1.0/entities/query \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "filters": [
    {
      "type": "containsEdge",
      "path": "mixins.active",
      "values": [
        { "entityId": "11111111-0000-0000-0000-000000000011" }
      ]
    },
    {
      "type": "range",
      "path": "creationDate",
      "gte": "2024-01-01T00:00:00.000Z",
      "lte": "2024-01-31T23:59:59.999Z"
    }
  ],
  "orders": [
    {
      "path": "creationDate",
      "type": "descending",
      "label": "Posted Date"
    }
  ],
  "metadata": {
    "size": 80,
    "offset": 0,
    "shouldIncludeLeafEntities": true
  }
}'

Searchable Properties

The core_documents_shipment entity supports filtering on the searchable properties listed below. Use these paths in the filters array of the POST Document Search request body. Paths for nested objects use dot notation (e.g., core_documents_shipment.identification.bolNumber).

Property Label	API Filter Path	Supported Filter Types
BOL Number	`core_documents_shipment.identification.bolNumber`	`match, prefix`
Delivery Number	`core_documents_shipment.identification.deliveryNumber`	`match, prefix`
Delivery Numbers	`core_documents_shipment.identification.deliveryNumbers`	`contains`
Load Number	`core_documents_shipment.identification.loadNumber`	`match, prefix`
Lot Number	`core_documents_shipment.identification.lotNumber`	`match, prefix`
Order Number	`core_documents_shipment.identification.orderNumber`	`match, prefix`
PO Numbers	`core_documents_shipment.identification.purchaseOrderNumbers`	`contains`
Pro Number	`core_documents_shipment.identification.proNumber`	`match, prefix`
Cargo	`core_documents_shipment.cargo`	`match, prefix`
Carrier	`core_documents_shipment.carrier`	`matchEdge`
Carrier SCAC	`core_documents_shipment.carrierCode`	`match, prefix`
Carrier Name	`core_documents_shipment.carrierName`	`match, prefix`
Check-In Time	`core_documents_shipment.checkinTime`	`range`
Check-Out Time	`core_documents_shipment.checkoutTime`	`range`
Customer	`core_documents_shipment.customer`	`matchEdge`
Customer ID	`core_documents_shipment.customerId`	`match, prefix`
Customer Name	`core_documents_shipment.customerName`	`match, prefix`
Destination	`core_documents_shipment.destinationLocation`	`matchEdge`
Driver Signed	`core_documents_shipment.driverSigned`	`match`
Driver Will Provide Physical Copy	`core_documents_shipment.driverWillProvidePhysicalCopy`	`match`
Current Facility	`core_documents_shipment.facility`	`matchEdge`
OS&D	`core_documents_shipment.hasOsd`	`match`
Ignore For Automation Audit	`core_documents_shipment.ignoreForAutomationAudit`	`match`
Archived	`core_documents_shipment.isArchived`	`match`
Assigned	`core_documents_shipment.isAssigned`	`match`
Dispatched	`core_documents_shipment.isDispatched`	`match`
Priority	`core_documents_shipment.isPriority`	`match`
Voided	`core_documents_shipment.isVoided`	`match`
Origin Location	`core_documents_shipment.originLocation`	`matchEdge`
Receiver	`core_documents_shipment.receiver`	`match, prefix`
Receiver ID	`core_documents_shipment.receiverId`	`match, prefix`
Receiver Signed	`core_documents_shipment.receiverOfficeSigned`	`match`
Seal Number	`core_documents_shipment.seal.number`	`match, prefix`
Set Temperature	`core_documents_shipment.setTemperature`	`match, prefix`
Shipment Date	`core_documents_shipment.shipmentDate`	`range`
Shipment Number	`core_documents_shipment.shipmentNumber`	`match, prefix`
Shipment Status	`core_documents_shipment.shipmentStatus`	`match`
Shipper	`core_documents_shipment.shipper`	`match, prefix`
Shipper ID	`core_documents_shipment.shipperId`	`match, prefix`
Shipper Signed	`core_documents_shipment.shipperSigned`	`match`
Trailer	`core_documents_shipment.trailer`	`matchEdge`
Trailer Number	`core_documents_shipment.trailerNumber`	`match, prefix`
TMS ID	`core_documents_shipment.tmsId`	`match, prefix`
Truck Number	`core_documents_shipment.truckNumber`	`match, prefix`
Gross Weight	`core_documents_shipment.weightGross`	`match, prefix`
Net Weight	`core_documents_shipment.weightNet`	`match, prefix`

Filter Types

Filter Types are the core operators of Vector's EQL (Entity Query Language) that determine how a field is evaluated when searching for documents. Every filter object includes a type field that specifies which operator to apply, along with a path pointing to the field being filtered.

Exact Matching

For matching exact field values. match is the most common type.

Field	Type	Required	Description
match	object	Optional	Exact field value match. Supports single value or values array for multi-select. Also supports wildcard * (e.g., 805123).
multipleMatch	object	Optional	Match a single value across multiple paths using orPaths.
matchEdge	object	Optional	Match on edge fields, resolving on entityId.
matchEntity	object	Optional	Match on entity fields, resolving on uniqueId.
matchLane	object	Optional	Match on lane-based fields.
matchLanePoint	object	Optional	Match on lane point fields.

Array Membership

Check whether a value exists within an array field. Note: this is not a string-contains operation.

Field	Type	Required	Description
contains	object	Optional	Check if a value exists within an array field (membership check, not string-contains).
containsEdge	object	Optional	Same as contains but for arrays of edge objects.

Partial Text Matching

For partial string matching. Note: prefix wildcards are expensive and discouraged for performance.

Field	Type	Required	Description
prefix	object	Optional	Match the beginning of a string field (e.g., names starting with "Proctor").
fuzzy	object	Optional	Typo-tolerant matching. Useful for carrier names; not recommended for numeric fields.

Existence Checks

Filter based on whether a field has any value at all.

Field	Type	Required	Description
exists	object	Optional	Filter for fields that have any value.
notExists	object	Optional	Filter for fields that have no value.

Range

For numeric or date fields using comparison operators.

Field	Type	Required	Description
range	object	Optional	Numeric or date filtering using gt, gte, lt, lte. Can be open-ended on either side.

Geo Types

Spatial filter types for location-based queries.

Field	Type	Required	Description
geoBounds	object	Optional	Rectangular bounding box filter.
geoPolygon	object	Optional	Arbitrary polygon shape (3+ points).
geoDistance	object	Optional	Radius from a point (supports miles, km, yards, meters).
geoIntersect	object	Optional	Planar intersection with a region (e.g., zip code).

Negation & Composition

Combine or negate filters for complex queries.

Field	Type	Required	Description
orFilter	object	Optional	Combine multiple filters with OR logic.
isNegation	boolean	Optional	Set to true on any filter to negate it.

Filter Examples

match - Exact field value (with multi-select):

{
  "type": "match",
  "path": "document.name",
  "values": ["131187", "131188"]
}

match - Wildcard search:

{
  "type": "match",
  "path": "document.name",
  "value": "*805123*"
}

containsEdge - Filter by document type:

{
  "type": "containsEdge",
  "path": "mixins.active",
  "values": [{ "entityId": "11111111-0000-0000-0000-000000000011" }]
}

range - Date range (open-ended on one side):

{
  "type": "range",
  "path": "creationDate",
  "gte": "2024-01-01T00:00:00.000Z"
}

geoDistance - Radius search:

{
  "type": "geoDistance",
  "path": "document.address.geolocation",
  "distance": 50,
  "unit": "miles",
  "lat": 37.781085,
  "lon": -122.397096
}

Negated filter:

{
  "type": "match",
  "path": "document.processed",
  "value": true,
  "isNegation": true
}

Pagination (metadata)

Control pagination and grouping with the metadata object:

Field	Type	Required	Description
size	integer	Optional	Count of items to return for top level group.
offset	integer	Optional	Offset of items to return from for top level group.
maxSizePerGroup	integer	Optional	Count of items to return for nested groups.
shouldIncludeLeafEntities	boolean	Optional	Indication to add entities as children to leaf groups.

Sorting (orders)

Control the sort order of results:

"orders": [
  {
    "path": "creationDate",
    "type": "descending",
    "label": "Posted Date"
  }
]

Available types: ascending or descending

Response Structure

The response returns a children array where each item contains a data object — a fully hydrated entity in the same shape as the Get Single Document response, including uniqueId, owner details, address, image file locations, processing state, and attachments. A count of total matched documents is included at the end of the response.

Each document object in the response contains the following fields:

Field	Type	Required	Description
uniqueId	string	Required	UUID of the document in Vector.
mixins	object	Required	Active and inactive schema mixins (Entity, Document, Bill of Lading, etc.).
owner	object	Required	Owner information including user and firm details.
status.state	string	Required	Processing state: "idle" (ready) or "busy" (operations cannot be performed).
createdBy	object	Required	User who created the document (entityId and displayName).
creationDate	string	Required	ISO 8601 timestamp when the document was created.
modifiedBy	object	Required	User who last modified the document.
modifiedDate	string	Required	ISO 8601 timestamp when the document was last modified.
document.name	string	Required	Document name/identifier.
document.address	object	Optional	Resolved address with region, locality, postalCode, streetAddress, geolocation.
document.processed	boolean	Required	Whether the document has been processed.
document.uploadDate	string	Required	ISO 8601 timestamp when the document was uploaded.
document.attachments	object	Required	Files array and aggregate PDF with download URIs.
core_documents_shipment.proofOfShipmentAttachment	object	Optional	Proof of shipment document with files array and aggregate PDF.
core_documents_shipment.proofOfDeliveryAttachment	object	Optional	Proof of delivery document with files array and aggregate PDF.

Attachment Fields

Each file in document.attachments.files, core_documents_shipment.proofOfShipmentAttachment.files, and core_documents_shipment.proofOfDeliveryAttachment.files contains:

Field	Type	Required	Description
uri	string	Required	Direct download URL for the file (hosted on cdn.loaddocs.co).
name	string	Required	Original filename (e.g., "131187.pdf").
type	string	Required	File type (e.g., "pdf", "image").
pages	integer	Optional	Number of pages in the document.
uniqueId	string	Required	UUID of the file attachment.
preview	array	Optional	Array of preview images at different resolutions (1650x1650, 640x480, 64x64).

Example Response

A successful GET response returns the document with all metadata and file URLs:

Response

{
  "core_documents_shipment": {
    "appointment": {
      "displayName": "12345678 - Outbound",
      "entityId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "carrier": {
      "denormalizedProperties": {
        "business.legalName": "ACME LOGISTICS"
      },
      "displayName": "ACME LOGISTICS",
      "entityId": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    },
    "carrierCode": "ACME",
    "customer": {
      "denormalizedProperties": {
        "business.sourceId": "DEMO"
      },
      "displayName": "DEMO",
      "entityId": "c3d4e5f6-a7b8-9012-cdef-345678901234"
    },
    "customerName": "DEMO",
    "driver": {
      "denormalizedProperties": {
        "owner.firm": {
          "displayName": "Sample Transport Inc.",
          "entityId": "d4e5f6a7-b8c9-0123-def0-456789012345"
        },
        "person.phoneNumbers": [
          {
            "isVerified": true,
            "label": "Primary Phone",
            "value": {
              "phone": "+1 555-123-4567"
            }
          }
        ]
      },
      "displayName": "John Driver",
      "entityId": "e5f6a7b8-c9d0-1234-ef01-567890123456"
    },
    "driverSignature": {
      "signature": {
        "height": 159,
        "name": "signature.jpg",
        "source": [
          {
            "height": 159,
            "uri": "https://cdn.loaddocs.co/.../signature.jpg",
            "width": 500
          }
        ],
        "type": "image",
        "uniqueId": "f6a7b8c9-d0e1-2345-f012-678901234567",
        "uri": "https://cdn.loaddocs.co/.../signature.jpg",
        "width": 500
      },
      "signatureType": "pad",
      "signed": true,
      "signedBy": {
        "firm": {
          "displayName": "Demo Warehouse",
          "entityId": "a7b8c9d0-e1f2-3456-0123-789012345678"
        },
        "user": {
          "displayName": "Warehouse User",
          "entityId": "b8c9d0e1-f2a3-4567-1234-890123456789"
        }
      },
      "signedDate": "2024-02-18T21:16:51.551Z",
      "signer": "Warehouse User"
    },
    "facility": {
      "denormalizedProperties": {
        "location.address": {
          "countryName": "United States",
          "geolocation": {
            "latitude": 34.0522,
            "longitude": -118.2437
          },
          "locality": "Los Angeles",
          "postalCode": "90001",
          "region": "CA",
          "streetAddress": "123 Warehouse Blvd",
          "timezoneId": "America/Los_Angeles"
        },
        "location.name": "Los Angeles DC"
      },
      "displayName": "Los Angeles DC",
      "entityId": "c9d0e1f2-a3b4-5678-2345-901234567890"
    },
    "identification": {
      "bolNumber": "BOL123456789",
      "proNumber": "12345678"
    },
    "isArchived": false,
    "isAssigned": false,
    "isDispatched": false,
    "isPriority": false,
    "isVoided": false,
    "originLocation": {
      "denormalizedProperties": {
        "location.address": {
          "countryName": "United States",
          "geolocation": {
            "latitude": 34.0522,
            "longitude": -118.2437
          },
          "locality": "Los Angeles",
          "postalCode": "90001",
          "region": "CA",
          "streetAddress": "123 Warehouse Blvd",
          "timezoneId": "America/Los_Angeles"
        }
      },
      "displayName": "Los Angeles DC",
      "entityId": "c9d0e1f2-a3b4-5678-2345-901234567890"
    },
    "packingList": {
      "aggregate": {
        "name": "aggregate.pdf",
        "pages": 0,
        "type": "pdf",
        "uniqueId": "d0e1f2a3-b4c5-6789-3456-012345678901",
        "uri": "https://cdn.loaddocs.co/.../packingList/aggregate.pdf"
      },
      "files": [
        {
          "name": "packing-list-001.pdf",
          "pages": 1,
          "preview": [
            {
              "height": 2135,
              "name": "page_1",
              "type": "image",
              "uniqueId": "e1f2a3b4-c5d6-7890-4567-123456789012",
              "uri": "https://cdn.loaddocs.co/.../page_1.jpg",
              "width": 1650
            }
          ],
          "type": "pdf",
          "uniqueId": "f2a3b4c5-d6e7-8901-5678-234567890123",
          "uri": "https://cdn.loaddocs.co/.../packing-list-001.pdf"
        }
      ]
    },
    "pickupTrailerNumber": "TR-001",
    "proofOfShipmentAttachment": {
      "aggregate": {
        "name": "aggregate.pdf",
        "type": "pdf",
        "uniqueId": "a3b4c5d6-e7f8-9012-6789-345678901234",
        "uri": "https://cdn.loaddocs.co/.../proofOfShipment.pdf"
      },
      "files": [
        {
          "name": "proofOfShipment.pdf",
          "pages": 3,
          "preview": [
            {
              "height": 2587,
              "name": "page_1",
              "type": "image",
              "uniqueId": "b4c5d6e7-f8a9-0123-7890-456789012345",
              "uri": "https://cdn.loaddocs.co/.../pos_page_1.jpg",
              "width": 1650
            }
          ],
          "type": "pdf",
          "uniqueId": "c5d6e7f8-a9b0-1234-8901-567890123456",
          "uri": "https://cdn.loaddocs.co/.../proofOfShipment.pdf"
        }
      ]
    },
    "proofOfDeliveryAttachment": {
      "aggregate": {
        "name": "aggregate.pdf",
        "type": "pdf",
        "uniqueId": "d6e7f8a9-b0c1-2345-9012-678901234567",
        "uri": "https://cdn.loaddocs.co/.../proofOfDelivery.pdf"
      },
      "files": [
        {
          "name": "proofOfDelivery.pdf",
          "pages": 2,
          "preview": [
            {
              "height": 2135,
              "name": "page_1",
              "type": "image",
              "uniqueId": "e7f8a9b0-c1d2-3456-0123-789012345678",
              "uri": "https://cdn.loaddocs.co/.../pod_page_1.jpg",
              "width": 1650
            }
          ],
          "type": "pdf",
          "uniqueId": "f8a9b0c1-d2e3-4567-1234-890123456789",
          "uri": "https://cdn.loaddocs.co/.../proofOfDelivery.pdf"
        }
      ]
    },
    "receiverOfficeSigned": false,
    "seal": {
      "number": "SEAL123456"
    },
    "shipmentDate": "2024-02-04T12:00:00.000Z",
    "shipmentNumber": "12345678",
    "shipmentStatus": "Picked up by Driver"
  }
}

Response Codes

Field	Type	Required	Description
200	Success	Optional	Request successful. Entity returned in response body.
404	Not Found	Optional	Document with the specified UUID was not found.
401	Unauthorized	Optional	Missing or invalid Bearer token.

Note: Search requests return 200 even with 0 results. Check the response body for the count of returned documents.

Document State

The status.state field indicates the processing state of a document:

idleDocument is ready. Operations can be performed.

busyDocument is being processed. Wait before performing operations.