Integration Guide For Carriers
Integration Guide For Carriers

Status Updates & PODs

This guide covers how carriers can send tracking status updates and proof of delivery (POD) documents to MachShip for consignments.

Overview

Carriers can send status updates and PODs using multiple delivery methods:

  • API: Direct HTTP POST to MachShip endpoints (recommended for real-time updates)
  • XML File: Upload XML files via FTP/SFTP or push to MachShip
  • CSV File: Upload CSV files via FTP/SFTP or push to MachShip
  • FTP/SFTP: MachShip reads from carrier’s FTP/SFTP server on a schedule

All methods use the same underlying data structure. Choose the method that best fits your system’s capabilities.

Authentication

All API requests require authentication using a carrier-specific token provided by MachShip. Include this token in the request header:

api-token: YOUR_CARRIER_TOKEN

Contact MachShip support to obtain your carrier-specific API token.

Status Updates

API Method (Recommended)

Endpoint: POST https://live.machship.com/api/CarrierInformation/AddStatuses

Headers:

Content-Type: application/json
api-token: YOUR_CARRIER_TOKEN

Request Body:

[
  {
    "TrackingStatusCode": "InTransit",
    "TrackingStatusName": "In Transit",
    "TrackingTimeLocal": "2019-11-20T08:30:00",
    "NewCarrierConsignmentReference": "optional",
    "NewEtaLocal": "2019-11-20T12:30:00",
    "NewEtaUtc": "2019-11-20T02:30:00",
    "NewDespatchLocal": "2019-11-20T12:30:00",
    "NewDespatchUtc": "2019-11-20T02:30:00",
    "ConsignmentId": 3123456,
    "MachshipConsignmentId": "3123456",
    "CarrierConsignmentReference": "CON12345"
  },
  {
    "TrackingStatusCode": "Complete",
    "TrackingStatusName": "Completed",
    "TrackingTimeLocal": "2019-11-20T11:30:00",
    "CarrierConsignmentReference": "CON12345"
  }
]

Status Update Fields

FieldTypeRequiredDescription
TrackingStatusCodeStringYesStatus code (see Status Codes below)
TrackingStatusNameStringYesHuman-readable status description
TrackingTimeLocalDateTimeYesLocal timestamp when status occurred (ISO 8601)
CarrierConsignmentReferenceStringYes*Carrier’s consignment reference number
MachshipConsignmentIdStringYes*MachShip’s consignment identifier

* Either CarrierConsignmentReference OR MachshipConsignmentId must be provided to identify the consignment.

Optional Status Update Fields

The following fields can be included to update consignment details or provide additional tracking information:

FieldTypeDescription
ConsignmentIdIntegerLegacy MachShip consignment ID
NewCarrierConsignmentReferenceStringUpdated carrier reference (if changed)
NewEtaLocalDateTimeUpdated ETA in local time (ISO 8601)
NewEtaUtcDateTimeUpdated ETA in UTC (ISO 8601)
NewDespatchLocalDateTimeUpdated despatch time in local time (ISO 8601)
NewDespatchUtcDateTimeUpdated despatch time in UTC (ISO 8601)

Status Codes

Common tracking status codes:

  • Pending – Consignment created, awaiting pickup
  • PickedUp – Picked up from sender
  • InTransit – In transit to destination
  • OutForDelivery – Out for delivery
  • Complete – Delivered successfully
  • Failed – Delivery failed
  • Cancelled – Consignment cancelled
  • OnHold – Held at depot/warehouse
  • Exception – Exception occurred

XML Format for Status Updates

Status updates can be provided as XML files uploaded to FTP/SFTP or pushed to MachShip:

<?xml version="1.0" encoding="utf-8"?>
<StatusUpdates>
  <StatusUpdate>
    <TrackingStatusCode>InTransit</TrackingStatusCode>
    <TrackingStatusName>In Transit</TrackingStatusName>
    <TrackingTimeLocal>2019-11-20T08:30:00</TrackingTimeLocal>
    <CarrierConsignmentReference>CON12345</CarrierConsignmentReference>
    <NewEtaLocal>2019-11-20T12:30:00</NewEtaLocal>
  </StatusUpdate>
  <StatusUpdate>
    <TrackingStatusCode>Complete</TrackingStatusCode>
    <TrackingStatusName>Completed</TrackingStatusName>
    <TrackingTimeLocal>2019-11-20T11:30:00</TrackingTimeLocal>
    <CarrierConsignmentReference>CON12345</CarrierConsignmentReference>
  </StatusUpdate>
</StatusUpdates>

CSV Format for Status Updates

Status updates can be provided as CSV files with the following columns:

TrackingStatusCode,TrackingStatusName,TrackingTimeLocal,CarrierConsignmentReference,MachshipConsignmentId,NewEtaLocal,NewEtaUtc,NewDespatchLocal,NewDespatchUtc
InTransit,In Transit,2019-11-20T08:30:00,CON12345,,2019-11-20T12:30:00,2019-11-20T02:30:00,,
Complete,Completed,2019-11-20T11:30:00,CON12345,,,,,
OutForDelivery,Out for Delivery,2019-11-20T09:00:00,CON45678,,2019-11-20T14:00:00,2019-11-20T04:00:00,,

Proof of Delivery (POD)

API Method (Recommended)

Endpoint: POST https://live.machship.com/api/CarrierInformation/AddAttachments

Headers:

Content-Type: application/json
api-token: YOUR_CARRIER_TOKEN

Request Body:

[
  {
    "AttachmentBytes": "VGhpcyBpcyBhIHRlc3QgZmlsZQ==",
    "Filename": "CON12345.POD.pdf",
    "MachshipConsignmentId": "3987654",
    "CarrierConsignmentReference": "CON12345"
  },
  {
    "AttachmentBytes": "VGhpcyBpcyBhIHRlc3QgZmlsZQ==",
    "Filename": "CON45678.POD.pdf",
    "MachshipConsignmentId": "3123456",
    "CarrierConsignmentReference": "CON45678"
  }
]

POD Fields

FieldTypeRequiredDescription
AttachmentBytesStringYesBase64-encoded file content
FilenameStringYesFilename including extension (e.g., CON12345.POD.pdf)
CarrierConsignmentReferenceStringYes*Carrier’s consignment reference number
MachshipConsignmentIdStringYes*MachShip’s consignment identifier

* Either CarrierConsignmentReference OR MachshipConsignmentId must be provided to identify the consignment.

Supported POD File Formats

  • PDF: .pdf (recommended)
  • Images: .jpg, .jpeg, .png, .gif, .tiff
  • Documents: .txt, .doc, .docx

FTP/SFTP for POD Files

POD files can be uploaded to an FTP/SFTP location where MachShip will retrieve them on a schedule. MachShip applies a regex pattern to extract the consignment reference from the filename.

Filename Pattern:

{CarrierConsignmentReference}.POD.{extension}
CON12345.POD.pdf
ABC-98765.POD.jpg
2024-12345.POD.png

MachShip uses regex rules configured for your carrier integration to extract the consignment reference from filenames. Contact MachShip support to configure your regex pattern.

XML Format for PODs

PODs can be provided as XML files with base64-encoded attachments:

<?xml version="1.0" encoding="utf-8"?>
<PODs>
  <POD>
    <AttachmentBytes>VGhpcyBpcyBhIHRlc3QgZmlsZQ==</AttachmentBytes>
    <Filename>CON12345.POD.pdf</Filename>
    <CarrierConsignmentReference>CON12345</CarrierConsignmentReference>
  </POD>
  <POD>
    <AttachmentBytes>QW5vdGhlciBQT0QgZmlsZQ==</AttachmentBytes>
    <Filename>CON45678.POD.pdf</Filename>
    <MachshipConsignmentId>3123456</MachshipConsignmentId>
  </POD>
</PODs>

CSV Format for PODs

PODs can be provided as CSV files with base64-encoded content:

AttachmentBytes,Filename,CarrierConsignmentReference,MachshipConsignmentId
VGhpcyBpcyBhIHRlc3QgZmlsZQ==,CON12345.POD.pdf,CON12345,
QW5vdGhlciBQT0QgZmlsZQ==,CON45678.POD.pdf,CON45678,3123456

Delivery Methods

1. API Push (Recommended)

Send status updates and PODs directly to MachShip API endpoints as they occur. This provides real-time visibility and immediate customer notifications.

Advantages:

  • Real-time updates
  • Immediate error feedback
  • No file management required
  • Lower latency for customer notifications

2. FTP/SFTP Pull

Carrier uploads files to their FTP/SFTP server. MachShip connects and retrieves files on a schedule (typically every 15-30 minutes).

Advantages:

  • No API integration required
  • Works with existing file export processes
  • Batch processing of multiple updates

Setup Requirements:

  • Provide FTP/SFTP connection details to MachShip
  • Configure regex pattern for POD filename extraction
  • Define file naming conventions
  • Specify polling schedule

3. Push to MachShip FTP/SFTP

Carrier pushes XML or CSV files to MachShip-provided FTP/SFTP location. MachShip processes files on arrival or on schedule.

Advantages:

  • MachShip manages FTP/SFTP infrastructure
  • Simple file upload process
  • Batch processing support

Contact MachShip support to obtain push credentials and location details.

Best Practices

Status Updates

  • Send updates promptly: Update statuses as events occur for real-time tracking
  • Include all required fields: Always provide TrackingStatusCode, TrackingStatusName, TrackingTimeLocal, and consignment identifier
  • Use consistent status codes: Map your internal statuses to MachShip’s standard codes
  • Update ETAs when known: Provide NewEtaLocal and NewEtaUtc when delivery time estimates change
  • Send final status: Always send a Complete or Failed status to close the consignment lifecycle

POD Documents

  • Use PDF format: PDFs provide the best compatibility and preserve formatting
  • Clear filenames: Include carrier consignment reference in filename for easy identification
  • Reasonable file sizes: Keep POD files under 5MB when possible for faster uploads
  • Send promptly: Upload PODs as soon as delivery is completed
  • Include signature images: Ensure signature capture is visible in POD documents

File-Based Integration

  • Use atomic writes: Write files to temporary location then move to final location to avoid partial reads
  • Unique filenames: Include timestamp in filenames to prevent overwrites (e.g., statuses_20231120_143025.xml)
  • Archive processed files: Move or rename processed files to prevent reprocessing
  • Monitor for errors: Check for error files or logs that MachShip may generate

Error Handling

API Errors

The API returns standard HTTP status codes:

  • 200 OK – Request processed successfully
  • 400 Bad Request – Invalid request body or missing required fields
  • 401 Unauthorized – Invalid or missing api-token
  • 404 Not Found – Consignment not found (invalid reference)
  • 500 Internal Server Error – Server-side error (contact support)

Error responses include details in the response body:

{
  "error": "Invalid consignment reference",
  "details": "Consignment CON12345 not found"
}

Retry Strategy

For transient errors (network issues, 5xx errors), implement exponential backoff retry:

  • Retry 1: Wait 5 seconds
  • Retry 2: Wait 15 seconds
  • Retry 3: Wait 45 seconds
  • After 3 failures, alert operations team

Support

For integration assistance, configuration of FTP/SFTP access, regex patterns, or API tokens, contact MachShip carrier support:

  • Get In Touch: via our carrier form here.
  • Documentation: Additional technical documentation available on request

© 2026 MachShip Documentation