Skip to content

Document Management

The Document Management API enables applications to submit and retrieve shipment documents through the Connect API. Documents are stored as images and associated with specific shipments and document types.

After reading this article you will understand:

  • How to submit documents to the TMS through the images endpoint
  • How to retrieve existing documents from the TMS
  • The available document types and contexts
  • How to query supported document types for a specific shipment
  • The difference between driver and non-driver document submissions
  • How to submit single documents or multiple documents as an array
  • Document metadata and location information structure
  • Best practices for implementing document management workflows

Overview

Document management in the Connect API centers around three main operations:

  • Querying Types: Discover which document types are supported and available
  • Submitting Documents: Upload documents to storage (AWS S3 or URL-accessible location) and notify the TMS with metadata
  • Retrieving Documents: Request document locations (S3 or public URL) and metadata from the TMS

Important Considerations:

  • Document format requirements vary by TMS (some require .tiff, others support multiple formats)
  • Documents are associated by a context (SHIPMENT) and an entity ID (e.g., shipment ID)
  • Document submissions can be tracked by submitter (driver vs. other users)
  • Multiple documents can be submitted as an array of images
  • Each document type serves a specific business purpose in the context (SHIPMENT) workflow

Document Types

The Connect API supports the following document types for shipment workflows:

Core Shipment Documents

  • BOL (Bill of Lading): Legal document between shipper and carrier detailing the type, quantity, and destination of goods being carried.
  • POD (Proof of Delivery): Document signed by the recipient confirming delivery of goods.
  • POP (Proof of Pickup): Document confirming that goods were picked up from the origin location.

Delay Documentation

  • DEL DELAY (Delivery Delay): Documentation explaining why a delivery was delayed beyond the scheduled time.
  • PU DELAY (Pickup Delay): Documentation explaining why a pickup was delayed beyond the scheduled time.

Equipment Documentation

  • TIR IN (Trailer Interchange Receipt - In): Equipment interchange receipt documenting condition when equipment is received. Also known as EIR (Equipment Interchange Receipt).
  • TIR OUT (Trailer Interchange Receipt - Out): Equipment interchange receipt documenting condition when equipment is returned.
  • CHAS TIR IN (Chassis Trailer Interchange Receipt - In): Chassis-specific interchange receipt when chassis is received.
  • CHAS TIR OUT (Chassis Trailer Interchange Receipt - Out): Chassis-specific interchange receipt when chassis is returned.
  • SEAL: Container seal documentation showing seal number and condition.
  • EQUIPMENT PRE (Pre-Trip Inspection): Pre-trip inspection documentation showing equipment condition before trip begins.
  • EQUIPMENT POST (Post-Trip Inspection): Post-trip inspection documentation showing equipment condition after trip completion.

Special Handling Documents

  • CUSTOMS: Customs paperwork required for international shipments.
  • HAZMAT: Hazardous materials documentation and certifications.
  • OVERWEIGHT: Permit documentation for overweight loads.
  • SCALE TICKET: Ticket from weighing the truck at a certified scale.
  • DAMAGES: Documentation detailing any damages to goods or equipment.
  • PRENOTE: Earliest information about a shipment, often preliminary shipping details.

Submitting Documents

Two submission methods are available:

  1. AWS S3: Upload to S3 and provide bucket and file key
  2. Public URL: Provide a URL where the TMS can download the document

Both methods support single documents and multi-page document arrays.

Choosing Between S3 and Public URL

When deciding which submission method to use, consider the following:

  • AWS S3: This approach is primarily intended for internal services or those operating within the same cloud compute environment. It is the most efficient method when applicable, but it requires the TMS to have explicit permissions to access the designated S3 bucket. Access to these buckets is usually restricted for security purposes.
  • Public URL: This approach is recommended for third-party integrations. Integrators should use public URL methods and implement their own security measures (such as presigned URLs) to ensure the TMS can retrieve the documents.

Submitting via S3 (Single Document)

For S3-based submissions (most suitable for internal services - see Choosing Between S3 and Public URL), first upload the document image to your AWS S3 bucket, then notify the TMS.

Step 1: Upload to AWS S3

Upload the document image to your AWS S3 bucket. The application submitting the document determines the location within S3. Ensure the document is in a format accepted by your TMS (consult your TMS documentation for supported formats).

Step 2: Notify the TMS

Send a POST request to the images endpoint with metadata about the uploaded document.

Endpoint:

POST /images

Request Payload (S3):

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL",
  "bucket": "images-bucket",
  "fileKey": "key/within/the/bucket.tiff"
}

Payload Fields:

  • context: Image context. Always SHIPMENT for shipment documents.
  • entityId: ID of the associated entity (shipment ID when context is SHIPMENT).
  • type: Document type from the supported types listed above.
  • bucket: AWS S3 bucket name where the image was uploaded.
  • fileKey: File key within the bucket (relative path to the file).

Response:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL"
}

The response confirms the document submission with a 202 Accepted status.

Tracking Submission Source

By default, document submissions are tracked as coming from a driver. To differentiate submissions from other users, include the submittedBy property:

Request with Submission Tracking:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL",
  "bucket": "images-bucket",
  "fileKey": "key/within/the/bucket.tiff",
  "submittedBy": "OTHER-USER or Service or Application"
}

Response:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL",
  "submittedBy": "OTHER-USER or Service or Application"
}

Submitting Multi-Page Documents

For multi-page documents, submit an array of file keys representing individual pages. This approach is useful when TMS systems require single-page images rather than multi-page TIFF files.

Request:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL",
  "bucket": "images-bucket",
  "fileKey": [
    "bol-page-1.jpg",
    "bol-page-2.jpg",
    "bol-page-3.jpg"
  ]
}

Key Differences:

  • fileKey is an array instead of a string
  • Each array element represents a single page
  • Pages are processed in the order provided
  • The TMS determines how to handle multi-page documents based on its configuration

Response:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL"
}

The response structure is identical whether submitting a single document or an array.

Submitting via URL (Single Document)

As an alternative to S3 bucket and key, documents can be submitted by providing a URL where the TMS can download the document:

Request:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL",
  "locationType": "url",
  "url": "http://example.com/documents/bol.tif"
}

Required Fields for URL Submission:

  • context: Image context (SHIPMENT)
  • entityId: Associated entity ID
  • type: Document type
  • locationType: Must be set to url
  • url: HTTP/HTTPS URL where the document can be downloaded

Response:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL"
}

Submitting via URL (Multi-Page Documents)

For multi-page documents, provide an array of URLs:

Request:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL",
  "locationType": "url",
  "url": [
    "http://example.com/documents/bol-page-1.jpg",
    "http://example.com/documents/bol-page-2.jpg",
    "http://example.com/documents/bol-page-3.jpg"
  ]
}

Key Differences:

  • url is an array instead of a string
  • Each array element represents a URL for a single page
  • Pages are processed in the order provided
  • All URLs must be accessible by the TMS

Response:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL"
}

Retrieving Documents

To retrieve a document from the TMS, request the document metadata and location information. The TMS can return the document location as either an AWS S3 location or a public URL.

Endpoint:

GET /images?context={context}&entityId={entityId}&type={type}

Query Parameters:

  • context (required): Image context (SHIPMENT)
  • entityId (required): ID of the associated entity (shipment ID when context is SHIPMENT)
  • type (required): Document type to retrieve
  • locationType (optional): Specify url to request URL-based location instead of S3

Choosing Retrieval Method

  • S3-Based Retrieval: Recommended for internal services within the same cloud environment. S3 retrieval is efficient but requires the requesting application to have AWS credentials with permission to access the TMS storage bucket.
  • URL-Based Retrieval: Recommended for third-party integrations. This method generates a temporary public or presigned URL, allowing access without direct AWS credentials.

S3-Based Retrieval

By default, the API returns S3 bucket and file key information.

Example Request:

GET /images?context=SHIPMENT&entityId=12345&type=BOL

Response:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL",
  "bucket": "my-s3-bucket",
  "fileKey": "SHIPMENT/12345/BOL.tiff"
}

Response Fields:

  • context: The context of the image
  • entityId: The associated entity ID
  • type: The document type
  • bucket: AWS S3 bucket containing the document
  • fileKey: File key within the bucket for accessing the document

You must download the document from S3 using your AWS credentials.

URL-Based Retrieval

Request a public URL by specifying locationType=url in the query parameters.

Example Request:

GET /images?context=SHIPMENT&entityId=12345&type=BOL&locationType=url

Response:

{
  "context": "SHIPMENT",
  "entityId": "12345",
  "type": "BOL",
  "locationType": "url",
  "url": "http://presigned-object-url.com"
}

Response Fields:

  • context: The context of the image
  • entityId: The associated entity ID
  • type: The document type
  • locationType: Always url when requesting URL-based retrieval
  • url: Public or presigned URL for accessing the document

Download directly using the provided URL (no AWS credentials required). Note that presigned URLs may have expiration times.

Error Responses:

If the requested document does not exist, the API returns 404 Not Found:

{
  "status": 404,
  "description": "Not Found",
  "data": {
    "uri": "/images?context=SHIPMENT&entityId=12345&type=BOL"
  }
}

If required parameters are missing, the API returns 400 Bad Request:

{
  "status": 400,
  "description": "Bad Request",
  "data": {
    "object_name": "FSImageData",
    "prop_name": "context"
  }
}

Querying Document Types

Supported Types (May vary by TMS/Customer)

To discover which document types are configured and supported in the customer's TMS, query the image types endpoint.

Endpoint:

GET /images/types

Response:

{
  "shipment": ["BOL", "POD", "CUSTOMS", "SEAL"]
}

The response groups document types by context. The shipment array contains all document types configured for shipment documents in the TMS.

Shipment-Specific Document Types

To retrieve the list of document types that exist for a specific shipment, use the shipment images endpoint.

Endpoint:

GET /shipments/{shipmentId}/images

Example Request:

GET /shipments/12345/images

Response:

{
  "id": "12345",
  "self": "/shipments/12345/images",
  "items": ["BOL", "POD"]
}

Response Fields:

  • id: The shipment ID
  • self: URI reference to this resource
  • items: Array of document types that currently exist for this shipment

If the shipment has no documents, the items array will be empty:

{
  "id": "12345",
  "self": "/shipments/12345/images",
  "items": []
}

If the shipment does not exist, the API returns 404 Not Found:

{
  "status": 404,
  "description": "Not Found",
  "data": {
    "uri": "/shipments/12345/images"
  },
  "message": "Resource at /shipments/12345/images not found"
}

Workflow Examples

Complete Document Submission Workflow

Option A: S3-Based Submission

  1. Capture document (take photo, scan, etc.)
  2. Convert to TMS-supported format (check TMS requirements)
  3. Split multi-page documents into single pages if required by TMS
  4. Upload to AWS S3 bucket
  5. Notify TMS via POST /images with bucket and fileKey (single or array)
  6. Receive confirmation from API

Option B: URL-Based Submission

  1. Capture document (take photo, scan, etc.)
  2. Convert to TMS-supported format (check TMS requirements)
  3. Upload to accessible location (web server, CDN, etc.)
  4. Notify TMS via POST /images with URL(s) and locationType=url
  5. Receive confirmation from API
  6. TMS downloads from provided URL(s)

Complete Document Retrieval Workflow

Option A: S3-Based Retrieval

  1. Query available types for shipment via GET /shipments/{id}/images
  2. Request specific document via GET /images with context, entityId, and type
  3. Receive document location (bucket and fileKey)
  4. Download from S3 using AWS credentials
  5. Display or process the document

Option B: URL-Based Retrieval

  1. Query available types for shipment via GET /shipments/{id}/images
  2. Request specific document via GET /images with context, entityId, type, and locationType=url
  3. Receive document URL (public or presigned)
  4. Download from URL via HTTP request
  5. Display or process the document

Best Practices

Image Format

  • Verify supported image formats with your TMS (common formats include .tiff, .jpg, .png)
  • For multi-page documents, check if the TMS requires single-page arrays or supports multi-page files
  • Ensure images are clear and legible
  • Compress images appropriately to balance quality and file size
  • Use consistent file naming conventions for multi-page documents (e.g., bol-page-1.tiff, bol-page-2.tiff)

Error Handling

  • Validate all required parameters before making requests
  • Handle 404 Not Found responses gracefully when documents don't exist
  • Retry failed uploads with exponential backoff
  • Log submission attempts for troubleshooting

Performance

  • Query supported types once at application startup and cache results
  • Query shipment-specific documents only when needed
  • Download documents on-demand rather than preemptively
  • Use asynchronous operations for uploads to avoid blocking user interfaces

Security

  • Ensure S3 buckets have appropriate access controls
  • Use HTTPS for all API communications
  • Validate document content before submission
  • Sanitize file paths and keys to prevent injection attacks

User Experience

  • Provide clear feedback during upload progress
  • Show which documents are required vs. optional
  • Allow users to preview documents before submission
  • Cache downloaded documents locally for offline access

Conclusion

You should now understand:

  • How to submit and retrieve documents through the images endpoint
  • The available document types, contexts, and how to query them for specific shipments
  • The difference between driver and non-driver document submissions
  • How to submit single documents or multiple documents as an array
  • The document metadata and location information structure
  • Best practices for implementing document management workflows

Follow the outlined best practices and workflow examples to implement a reliable solution that meets your specific TMS requirements.