Retrieving Documents

In return events including shipments, the documents property is an array of document data as shown below.

Document Data

Attribute Name	Type	Description
images	array	Ordered list of image files associated with the document. Format is: { filename: contentType: url: } The contentType is typically "image/jpg". Use the url to download the image file. The filename is just a suggestion.
createdByUserId	string	User Id that created the document (typically the driver)
createdByUserName	string	User name that created the document, formatted ,
createdOn	string	Timestamp when the document was created, in ISO8601 format YYYY-MM-DDThh:mm:ss.SSSZ
documentType	string	The type of the document. Possible values are: "bill-of-lading" "delivery-receipt" "shipment-photo" "signature"
totalImages	number	The total number of images expected in the document. This may be greater than the length of the images array if some of the images have not yet been uploaded yet. In this case, the "status" field will be "pending".
status	string	Status of the document. Possible values are: "uploaded" -- meaning all the document images have been uploaded and are ready to be retrieved. "pending" -- meaning that some of the images have not yet been uploaded and are not yet ready to be retrieved.
updatedByUserId	string	User Id that created the document (typically the driver)
updatedByUserName	string	User name that created the document, formatted ,
updatedOn	string	Timestamp when the document was updated, in ISO8601 format YYYY-MM-DDThh:mm:ss.SSSZ

An example documents property looks like this:

{
  "documents": [
    {
      "createdByUserId": "12345",
      "createdByUserName": "Smith, John",
      "createdOn": "2023-09-13T17:28:18.000Z",
      "documentType": "delivery-receipt",
      "images": [
        {
          "contentType": "image/jpg",
          "filename": "mavenDocImage-delivery-receipt-1694626035209-0.jpg",
          "url": "https://maven-documents-development.s3.amazonaws.com/44044044858c5339-0124-4488-bd13-570e97a2d777"
        }
      ],
      "status": "uploaded",
      "totalImages": 1,
      "updatedByUserId": "12345",
      "updatedByUserName": "Smith, John",
      "updatedOn": "2023-09-13T17:28:20.000Z"
    },
    {
      "createdByUserId": "12345",
      "createdByUserName": "Smith, John",
      "createdOn": "2023-09-13T17:28:18.000Z",
      "documentType": "shipment-photo",
      "images": [
        {
          "contentType": "image/jpg",
          "filename": "mavenDocImage-shipment-photo-1694626087165-0.jpg",
          "url": "https://maven-documents-development.s3.amazonaws.com/540440456209a638-aec3-4e4a-9711-842126ecb2e0"
        }
      ],
      "status": "uploaded",
      "totalImages": 1,
      "updatedByUserId": "12345",
      "updatedByUserName": "Smith, John",
      "updatedOn": "2023-09-13T17:28:20.000Z"
    },
    {
      "createdByUserId": "12345",
      "createdByUserName": "Smith, John",
      "createdOn": "2023-09-13T17:28:18.000Z",
      "documentType": "signature",
      "images": [
        {
          "contentType": "image/jpg",
          "filename": "mavenDocImage-signature-1694626009150-0.jpg",
          "url": "https://maven-documents-development.s3.amazonaws.com/6404404688dab12a-f91e-4920-a286-546e49e53028"
        }
      ],
      "status": "uploaded",
      "totalImages": 1,
      "updatedByUserId": "12345",
      "updatedByUserName": "Smith, John",
      "updatedOn": "2023-09-13T17:28:19.000Z"
    }
  ]
}

Handling Pending Documents

Sometimes, a document may not be uploaded from the Maven app by the time the return event is generated. In this case, the document's status will be "pending". Later, when an image of the document finishes uploading, the original return event will be amended with the new image data, and re-inserted into the return event queue with a new event ID and timestamp. A property is added isModified: true to indicate that this is an amended version of a previous return event. If there are multiple pending document images, multiple amended return events may be generated for the same original return event.

Sample Payload of Pending Documents

{
  "timestamp": "2023-09-13T17:28:18.000Z",
  "id": "11cbf1da-0760-4e9a-8db6-2a5810683471",
  "eventType": "stopComplete",
  "data": {
    // ... stopComplete data
    "documents": [
      {
        "createdByUserId": "12345",
        "createdByUserName": "Smith, John",
        "createdOn": "2023-09-13T17:28:09.000Z",
        "documentType": "delivery-receipt",
        "status": "pending",
        "totalImages": 1,
        "updatedByUserId": "12345",
        "updatedByUserName": "Smith, John",
        "updatedOn": "2023-09-13T17:28:09.000Z"
      }
    ]
  }
}

Sample Payload of Modified Event After Late Upload

{
  "timestamp": "2023-09-13T18:00:00.000Z", // <-- new timestamp
  "id": "95ab1f80-3f50-4409-b046-14b414ffe5f4", // <-- new event ID
  "isModified": true, // <-- modified event indicator
  "eventType": "stopComplete",
  "data": {
     // ... stopComplete data
    "documents": [
      {
        "createdByUserId": "12345",
        "createdByUserName": "Smith, John",
        "createdOn":  "2023-09-13T17:28:09.000Z",
        "documentType": "delivery-receipt",
        "images": [
          {
            "contentType": "image/jpg",
            "filename": "mavenDocImage-delivery-receipt-1694626035209-0.jpg",
            "url": "https://maven-documents-development.s3.amazonaws.com/44044044858c5339-0124-4488-bd13-570e97a2d777"
          }
        ],
        "status": "uploaded",
        "totalImages": 1,
        "updatedByUserId": "12345",
        "updatedByUserName": "Smith, John",
        "updatedOn": "2023-09-13T18:00:00.000Z",
      }
    ]
  }
}

📘
Note
Pending documents is currently only supported by the stopComplete return event type.

Downloading images

When processing return events, here are some suggestions to download the associated documents:

For each item in the documents array, check if the status = "uploaded"
If it is uploaded, for each item in the images array:
- Check if you have already downloaded this file. You can use the URL as a unique key.
- If you have not yet downloaded the file, download it and save it to a file of your choosing. You can use the filename property as a suggestion, or create your own. Here is a sample of how you might do this

using (HttpClient httpClient = new HttpClient())  
{  
    try  
    {  
        // Send a GET request to the S3 URL and retrieve the image as binary data  
        byte[]Here is a sample in C# of how you might do this: imageData = await httpClient.GetByteArrayAsync(image.url);  
        // Use the downloaded image data as per your requirement  
        // For example, you can save it to a file using File.WriteAllBytes  
         File.WriteAllBytes(image.filename, imageData);  
    }  
    catch (HttpRequestException ex)  
    {  
        Console.WriteLine($"Error occurred while downloading image: {ex.Message}");  
    }  
}

Document Data

Handling Pending Documents

📘Note

Downloading images

📘
Note