Skip to main content
API docs by Redocly

MilMove Prime API (0.0.1)

Download OpenAPI specification:Download

E-mail: milmove-developers@caci.com License: MIT

The Prime API is a RESTful API that enables the Prime contractor to request information about upcoming moves, update the details and status of those moves, and make payment requests. It uses Mutual TLS for authentication procedures.

All endpoints are located at /prime/v1/.

moveTaskOrder

The moveTaskOrder represents a military move that has been sent to a contractor. It contains all the information about shipments, including service items, estimated weights, actual weights, requested and scheduled move dates, etc.

listMoves

Gets all moves that have been reviewed and approved by the TOO. The since parameter can be used to filter this list down to only the moves that have been updated since the provided timestamp. A move will be considered updated if the updatedAt timestamp on the move or on its orders, shipments, service items, or payment requests, is later than the provided date and time.

WIP: Include what causes moves to leave this list. Currently, once the availableToPrimeAt timestamp has been set, that move will always appear in this list.

query Parameters
since
string <date-time>

Only return moves updated since this time. Formatted like "2021-07-23T18:30:47.116Z"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getMoveTaskOrder

Functionality

This endpoint gets an individual MoveTaskOrder by ID.

It will provide information about the Customer and any associated MTOShipments, MTOServiceItems and PaymentRequests.

path Parameters
moveID
required
string

UUID or MoveCode of move task order to use.

Responses

Response samples

Content type
application/json
{
  • "id": "a502b4f1-b9c4-4faf-8bdd-68292501bf26",
  • "moveCode": "HYXFJF",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "orderID": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "order": {
    },
  • "referenceId": "1001-3456",
  • "availableToPrimeAt": "2019-08-24T14:15:22Z",
  • "approvedAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "primeCounselingCompletedAt": "2019-08-24T14:15:22Z",
  • "paymentRequests": [
    ],
  • "mtoServiceItems": [
    ],
  • "mtoShipments": [
    ],
  • "ppmType": "PARTIAL",
  • "ppmEstimatedWeight": 0,
  • "excessWeightQualifiedAt": "2019-08-24T14:15:22Z",
  • "excessWeightAcknowledgedAt": "2019-08-24T14:15:22Z",
  • "excessWeightUploadId": "a33d2f46-d8a5-4a8e-9807-9e677591c23a",
  • "eTag": "string"
}

createExcessWeightRecord

Uploads an excess weight record, which is a document that proves that the movers or contractors have counseled the customer about their excess weight. Excess weight counseling should occur after the sum of the shipments for the customer's move crosses the excess weight alert threshold.

path Parameters
moveTaskOrderID
required
string <uuid>

UUID of the move being updated.

Request Body schema: multipart/form-data
file
required
string <binary>

The file to upload.

Responses

Response samples

Content type
application/json
{
  • "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "url": "https://uploads.domain.test/dir/c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "filename": "filename.pdf",
  • "contentType": "application/pdf",
  • "bytes": 0,
  • "status": "INFECTED",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "moveId": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "moveExcessWeightQualifiedAt": "2019-08-24T14:15:22Z",
  • "moveExcessWeightAcknowledgedAt": "2019-08-24T14:15:22Z"
}

updateMTOPostCounselingInformation

Functionality

This endpoint updates the MoveTaskOrder to indicate that the Prime has completed Counseling. This update uses the moveTaskOrderID provided in the path, updates the move status and marks child elements of the move to indicate the update. No body object is expected for this request.

For Full/Partial PPMs: This action is required so that the customer can start uploading their proof of service docs.

For other move types: This action is required for auditing reasons so that we have a record of when the Prime counseled the customer.

path Parameters
moveTaskOrderID
required
string

ID of move task order to use.

header Parameters
If-Match
required
string

Optimistic locking is implemented via the If-Match header. If the ETag header does not match the value of the resource on the server, the server rejects the change with a 412 Precondition Failed error.

Responses

Response samples

Content type
application/json
{
  • "id": "a502b4f1-b9c4-4faf-8bdd-68292501bf26",
  • "moveCode": "HYXFJF",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "orderID": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "order": {
    },
  • "referenceId": "1001-3456",
  • "availableToPrimeAt": "2019-08-24T14:15:22Z",
  • "approvedAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "primeCounselingCompletedAt": "2019-08-24T14:15:22Z",
  • "paymentRequests": [
    ],
  • "mtoServiceItems": [
    ],
  • "mtoShipments": [
    ],
  • "ppmType": "PARTIAL",
  • "ppmEstimatedWeight": 0,
  • "excessWeightQualifiedAt": "2019-08-24T14:15:22Z",
  • "excessWeightAcknowledgedAt": "2019-08-24T14:15:22Z",
  • "excessWeightUploadId": "a33d2f46-d8a5-4a8e-9807-9e677591c23a",
  • "eTag": "string"
}

Downloads move order as a PDF

Functionality

This endpoint downloads all uploaded move order documentations into one download file by locator.

Errors

  • The move must be in need counseling state.
  • The move client's origin duty location must not currently have gov counseling.
path Parameters
locator
required
string

the locator code for move order to be downloaded

query Parameters
type
string
Default: "ALL"
Enum: "ALL" "ORDERS" "AMENDMENTS"

upload type

Responses

mtoShipment

A shipment is some (or all) of a customer's belongings picked up in one location and delivered to another location. All of the items in a shipment are weighed and transported as a discrete unit. One move may include multiple shipments. An mtoShipment, in particular, is a shipment that belongs to a moveTaskOrder.

The weights for all of the shipments in a move are combined and compared to the customer's weight allowance. If the sum of the shipments is greater, the customer is liable for paying excess weight cost. Both the customer and the contractor should keep this potential cost in mind when planning a move and the shipments within it.

createMTOShipment

[Deprecated: sunset on 2024-04-08] This endpoint is deprecated and will be removed in a future version. Please use the new endpoint at /prime/v2/createMTOShipment instead.

Creates a new shipment within the specified move. This endpoint should be used whenever the movers identify a need for an additional shipment. The new shipment will be submitted to the TOO for review, and the TOO must approve it before the contractor can proceed with billing.

WIP: The Prime should be notified by a push notification whenever the TOO approves a shipment connected to one of their moves. Otherwise, the Prime can fetch the related move using the getMoveTaskOrder endpoint and see if this shipment has the status "APPROVED".

Request Body schema: application/json
moveTaskOrderID
required
string <uuid>

The ID of the move this new shipment is for.

requestedPickupDate
string or null <date>

The customer's preferred pickup date. Other dates, such as required delivery date and (outside MilMove) the pack date, are derived from this date.

primeEstimatedWeight
integer or null >= 1

The estimated weight of this shipment, determined by the movers during the pre-move survey. This value can only be updated once. If there was an issue with estimating the weight and a mistake was made, the Prime contractor will need to contact the TOO to change it.

customerRemarks
string or null

The customer can use the customer remarks field to inform the services counselor and the movers about any special circumstances for this shipment. Typical examples:

  • bulky or fragile items,
  • weapons,
  • access info for their address.

Customer enters this information during onboarding. Optional field.

Array of objects (MTOAgents) <= 2 items

A list of the agents for a shipment. Agents are the people who the Prime contractor recognize as permitted to release (in the case of pickup) or receive (on delivery) a shipment.

Array of objects (MTOServiceItem)

A list of service items connected to this shipment.

object

The address where the movers should pick up this shipment.

object

Where the movers should deliver this shipment.

shipmentType
required
string (Shipment Type)
Enum: "BOAT_HAUL_AWAY" "BOAT_TOW_AWAY" "HHG" "HHG_INTO_NTS_DOMESTIC" "HHG_OUTOF_NTS_DOMESTIC" "INTERNATIONAL_HHG" "INTERNATIONAL_UB" "MOBILE_HOME" "PPM"

The type of shipment.

  • HHG = Household goods move
  • HHG_INTO_NTS_DOMESTIC = HHG into Non-temporary storage (NTS)
  • HHG_OUTOF_NTS_DOMESTIC = HHG out of Non-temporary storage (NTS Release)
  • PPM = Personally Procured Move also known as Do It Yourself (DITY)
  • BOAT_HAUL_AWAY = Boat shipment that requires additional equipment to haul it to it's destination
  • BOAT_TOW_AWAY = Boat shipment that has a road-worthy trailer
  • MOBILE_HOME = Mobile Home shipment that a customer may move.
diversion
boolean

This value indicates whether or not this shipment is part of a diversion. If yes, the shipment can be either the starting or ending segment of the diversion.

pointOfContact
string

Email or ID of the person who will be contacted in the event of questions or concerns about this update. May be the person performing the update, or someone else working with the Prime contractor.

counselorRemarks
string or null
object (CreatePPMShipment)

Creation object containing the PPM shipmentType specific data, not used for other shipment types.

Responses

Request samples

Content type
application/json
Example
{
  • "moveTaskOrderId": "5691c951-c35c-49a8-a1d5-a4b7ea7b7ad8",
  • "shipmentType": "HHG",
  • "requestedPickupDate": "2022-12-31",
  • "pickupAddress": {
    }
}

Response samples

Content type
application/json
{
  • "mtoServiceItems": [
    ],
  • "id": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "moveTaskOrderID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "approvedDate": "2019-08-24",
  • "requestedPickupDate": "2019-08-24",
  • "requestedDeliveryDate": "2019-08-24",
  • "scheduledPickupDate": "2019-08-24",
  • "actualPickupDate": "2019-08-24",
  • "firstAvailableDeliveryDate": "2019-08-24",
  • "requiredDeliveryDate": "2019-08-24",
  • "scheduledDeliveryDate": "2019-08-24",
  • "actualDeliveryDate": "2019-08-24",
  • "primeEstimatedWeight": 4500,
  • "primeEstimatedWeightRecordedDate": "2019-08-24",
  • "primeActualWeight": 4500,
  • "ntsRecordedWeight": 4500,
  • "customerRemarks": "handle with care",
  • "counselorRemarks": "handle with care",
  • "actualProGearWeight": 0,
  • "actualSpouseProGearWeight": 0,
  • "agents": [
    ],
  • "sitExtensions": [
    ],
  • "reweigh": {
    },
  • "pickupAddress": {
    },
  • "destinationAddress": {
    },
  • "destinationType": "OTHER_THAN_AUTHORIZED",
  • "secondaryPickupAddress": {
    },
  • "secondaryDeliveryAddress": {
    },
  • "storageFacility": {
    },
  • "shipmentType": "HHG",
  • "diversion": true,
  • "diversionReason": "string",
  • "status": "SUBMITTED",
  • "ppmShipment": {
    },
  • "deliveryAddressUpdate": {
    },
  • "eTag": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "pointOfContact": "string",
  • "originSitAuthEndDate": "2019-08-24",
  • "destinationSitAuthEndDate": "2019-08-24"
}

updateMTOShipment Deprecated

[Deprecated: this endpoint was deprecated on August 5th, 2024] Please use the new endpoint at /prime/v3/updateMTOShipment instead.

path Parameters
mtoShipmentID
required
string <uuid>

UUID of the shipment being updated.

Responses

deleteMTOShipment

Functionality

This endpoint deletes an individual shipment by ID.

Errors

  • The mtoShipment should be associated with an MTO that is available to prime.
  • The mtoShipment must be a PPM shipment.
  • Counseling should not have already been completed for the associated MTO.
path Parameters
mtoShipmentID
required
string <uuid>

UUID of the shipment to be deleted

Responses

updateMTOShipmentAddress

Functionality

This endpoint is used to update the pickup, secondary, and destination addresses on an MTO Shipment. mto-shipments/{mtoShipmentID}/shipment-address-updates is for updating a delivery address. The address details completely replace the original, except for the UUID. Therefore a complete address should be sent in the request. When a destination address on a shipment is updated, the destination SIT service items address ID will also be updated so that shipment and service item final destinations match.

This endpoint cannot create an address. To create an address on an MTO shipment, the caller must use updateMTOShipment as the parent shipment has to be updated with the appropriate link to the address.

Errors

The address must be associated with the mtoShipment passed in the url. In other words, it should be listed as pickupAddress, destinationAddress, secondaryPickupAddress or secondaryDeliveryAddress on the mtoShipment provided. If it is not, caller will receive a Conflict Error.

The mtoShipment should be associated with an MTO that is available to prime. If the caller requests an update to an address, and the shipment is not on an available MTO, the caller will receive a NotFound Error.

path Parameters
mtoShipmentID
required
string <uuid>

UUID of the shipment associated with the address

addressID
required
string <uuid>

UUID of the address being updated

header Parameters
If-Match
required
string

Optimistic locking is implemented via the If-Match header. If the ETag header does not match the value of the resource on the server, the server rejects the change with a 412 Precondition Failed error.

Request Body schema: application/json
id
string <uuid>
streetAddress1
required
string (Street address 1)
streetAddress2
string or null (Street address 2)
streetAddress3
string or null (Address Line 3)
city
required
string (City)
state
required
string (State)
Enum: "AL" "AK" "AR" "AZ" "CA" "CO" "CT" "DC" "DE" "FL" "GA" "HI" "IA" "ID" "IL" "IN" "KS" "KY" "LA" "MA" "MD" "ME" "MI" "MN" "MO" "MS" "MT" "NC" "ND" "NE" "NH" "NJ" "NM" "NV" "NY" "OH" "OK" "OR" "PA" "RI" "SC" "SD" "TN" "TX" "UT" "VA" "VT" "WA" "WI" "WV" "WY"
postalCode
required
string <zip> (ZIP) ^(\d{5}([\-]\d{4})?)$
country
string or null (Country)
Default: "USA"
county
string or null (County)

Responses

Request samples

Content type
application/json
{
  • "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "streetAddress1": "123 Main Ave",
  • "streetAddress2": "Apartment 9000",
  • "streetAddress3": "Montmârtre",
  • "city": "Anytown",
  • "state": "AL",
  • "postalCode": "90210",
  • "country": "USA",
  • "county": "LOS ANGELES"
}

Response samples

Content type
application/json
{
  • "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "streetAddress1": "123 Main Ave",
  • "streetAddress2": "Apartment 9000",
  • "streetAddress3": "Montmârtre",
  • "city": "Anytown",
  • "eTag": "string",
  • "state": "AL",
  • "postalCode": "90210",
  • "country": "USA",
  • "county": "LOS ANGELES"
}

updateShipmentDestinationAddress

Functionality

This endpoint is used so the Prime can request an update for the destination address on an MTO Shipment, after the destination address has already been approved.

This endpoint and operation only supports the following shipment types:

  • HHG
  • NTSR

For HHG shipments, if automatically approved or TOO approves, this will update the final destination address values for destination SIT service items to be the same as the changed destination address that was approved.

Address updates will be automatically approved unless they change:

  • The service area
  • Mileage bracket for direct delivery
  • the address and the distance between the old and new address is > 50
  • Domestic Short Haul to Domestic Line Haul or vice versa
    • Shipments that start and end in one ZIP3 use Short Haul pricing
    • Shipments that start and end in different ZIP3s use Line Haul pricing

For those, changes will require TOO approval.

path Parameters
mtoShipmentID
required
string <uuid>

UUID of the shipment associated with the address

header Parameters
If-Match
required
string

Needs to be the eTag of the mtoShipment. Optimistic locking is implemented via the If-Match header. If the ETag header does not match the value of the resource on the server, the server rejects the change with a 412 Precondition Failed error.

Request Body schema: application/json
required
object (Address)

A postal address

contractorRemarks
required
string

This is the remark the Prime has entered, which would be the reason there is an address change.

Responses

Request samples

Content type
application/json
{
  • "newAddress": {
    },
  • "contractorRemarks": "Customer reached out to me this week and let me know they want to move somewhere else."
}

Response samples

Content type
application/json
{
  • "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "contractorRemarks": "This is a contractor remark",
  • "officeRemarks": "This is an office remark",
  • "status": "REQUESTED",
  • "shipmentID": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "originalAddress": {
    },
  • "newAddress": {
    },
  • "sitOriginalAddress": {
    },
  • "oldSitDistanceBetween": 50,
  • "newSitDistanceBetween": 88
}

createMTOAgent

Functionality

This endpoint is used to create and add agents for an existing MTO Shipment. Only the fields being modified need to be sent in the request body.

Errors

The agent must always have a name and at least one method of contact (either email or phone).

The agent must be associated with the MTO shipment passed in the url.

The shipment should be associated with an MTO that is available to the Pime. If the caller requests a new agent, and the shipment is not on an available MTO, the caller will receive a NotFound response.

path Parameters
mtoShipmentID
required
string <uuid>

UUID of the shipment associated with the agent

Request Body schema: application/json
firstName
string or null
lastName
string or null
email
string or null <x-email> ^([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{...
phone
string or null <telephone> ^([2-9]\d{2}-\d{3}-\d{4})?$
agentType
string (Agent Type)
Enum: "RELEASING_AGENT" "RECEIVING_AGENT"

The type for this agent. RELEASING means they have authority on pickup, RECEIVING means they can receive the shipment on delivery.

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "agentType": "RELEASING_AGENT"
}

Response samples

Content type
application/json
{
  • "id": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "mtoShipmentID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "agentType": "RELEASING_AGENT",
  • "eTag": "string"
}

updateMTOAgent

Functionality

This endpoint is used to update the agents for an MTO Shipment. Only the fields being modified need to be sent in the request body.

Errors:

The agent must always have a name and at least one method of contact (either email or phone).

The agent must be associated with the MTO shipment passed in the url.

The shipment should be associated with an MTO that is available to the Prime. If the caller requests an update to an agent, and the shipment is not on an available MTO, the caller will receive a NotFound response.

path Parameters
mtoShipmentID
required
string <uuid>

UUID of the shipment associated with the agent

agentID
required
string <uuid>

UUID of the agent being updated

header Parameters
If-Match
required
string

Optimistic locking is implemented via the If-Match header. If the ETag header does not match the value of the resource on the server, the server rejects the change with a 412 Precondition Failed error.

Request Body schema: application/json
firstName
string or null
lastName
string or null
email
string or null <x-email> ^([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{...
phone
string or null <telephone> ^([2-9]\d{2}-\d{3}-\d{4})?$
agentType
string (Agent Type)
Enum: "RELEASING_AGENT" "RECEIVING_AGENT"

The type for this agent. RELEASING means they have authority on pickup, RECEIVING means they can receive the shipment on delivery.

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "agentType": "RELEASING_AGENT"
}

Response samples

Content type
application/json
{
  • "id": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "mtoShipmentID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "phone": "string",
  • "agentType": "RELEASING_AGENT",
  • "eTag": "string"
}

updateReweigh

Functionality

This endpoint can be used to update a reweigh with a new weight or to provide the reason why a reweigh did not occur. Only one of weight or verificationReason should be sent in the request body.

A reweigh is the second recorded weight for a shipment, as validated by certified weight tickets. Applies to one shipment. A reweigh can be triggered automatically, or requested by the customer or transportation office. Not all shipments are reweighed, so not all shipments will have a reweigh weight.

path Parameters
mtoShipmentID
required
string <uuid>

UUID of the shipment associated with the reweigh

reweighID
required
string <uuid>

UUID of the reweigh being updated

header Parameters
If-Match
required
string

Optimistic locking is implemented via the If-Match header. If the ETag header does not match the value of the resource on the server, the server rejects the change with a 412 Precondition Failed error.

Request Body schema: application/json
weight
integer or null >= 1

The total reweighed weight for the shipment in pounds.

verificationReason
string or null

In lieu of a document being uploaded indicating why a reweigh did not occur.

Responses

Request samples

Content type
application/json
{
  • "weight": 2000,
  • "verificationReason": "The reweigh was not performed because the shipment was already delivered"
}

Response samples

Content type
application/json
{
  • "id": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "requestedAt": "2019-08-24T14:15:22Z",
  • "requestedBy": "CUSTOMER",
  • "verificationProvidedAt": "2019-08-24T14:15:22Z",
  • "verificationReason": "The reweigh was not performed due to some justification provided by the Prime",
  • "weight": 2000,
  • "shipmentID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "eTag": "string"
}

createSITExtension

Functionality

This endpoint creates a storage in transit (SIT) extension request for a shipment. A SIT extension request is a request an increase in the shipment day allowance for the number of days a shipment is allowed to be in SIT. The total SIT day allowance includes time spent in both origin and destination SIT.

path Parameters
mtoShipmentID
required
string <uuid>

UUID of the shipment associated with the agent

Request Body schema: application/json
requestReason
required
string
Enum: "SERIOUS_ILLNESS_MEMBER" "SERIOUS_ILLNESS_DEPENDENT" "IMPENDING_ASSIGNEMENT" "DIRECTED_TEMPORARY_DUTY" "NONAVAILABILITY_OF_CIVILIAN_HOUSING" "AWAITING_COMPLETION_OF_RESIDENCE" "OTHER"
contractorRemarks
required
string
requestedDays
required
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "requestReason": "SERIOUS_ILLNESS_MEMBER",
  • "contractorRemarks": "We need SIT additional days. The customer has not found a house yet.",
  • "requestedDays": 30
}

Response samples

Content type
application/json
{
  • "id": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "mtoShipmentID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "requestReason": "SERIOUS_ILLNESS_MEMBER",
  • "contractorRemarks": "We need SIT additional days. The customer has not found a house yet.",
  • "requestedDays": 30,
  • "status": "PENDING",
  • "approvedDays": 30,
  • "decisionDate": "2019-08-24T14:15:22Z",
  • "officeRemarks": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "eTag": "string"
}

updateMTOShipmentStatus

Functionality

This endpoint should be used by the Prime to confirm the cancellation of a shipment. It allows the shipment status to be changed to "CANCELED." Currently, the Prime cannot update the shipment to any other status.

path Parameters
mtoShipmentID
required
string <uuid>

UUID of the shipment associated with the agent

header Parameters
If-Match
required
string

Optimistic locking is implemented via the If-Match header. If the ETag header does not match the value of the resource on the server, the server rejects the change with a 412 Precondition Failed error.

Request Body schema: application/json
status
string
Value: "CANCELED"

Responses

Request samples

Content type
application/json
{
  • "status": "CANCELED"
}

Response samples

Content type
application/json
{
  • "mtoServiceItems": [
    ],
  • "id": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "moveTaskOrderID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "approvedDate": "2019-08-24",
  • "requestedPickupDate": "2019-08-24",
  • "requestedDeliveryDate": "2019-08-24",
  • "scheduledPickupDate": "2019-08-24",
  • "actualPickupDate": "2019-08-24",
  • "firstAvailableDeliveryDate": "2019-08-24",
  • "requiredDeliveryDate": "2019-08-24",
  • "scheduledDeliveryDate": "2019-08-24",
  • "actualDeliveryDate": "2019-08-24",
  • "primeEstimatedWeight": 4500,
  • "primeEstimatedWeightRecordedDate": "2019-08-24",
  • "primeActualWeight": 4500,
  • "ntsRecordedWeight": 4500,
  • "customerRemarks": "handle with care",
  • "counselorRemarks": "handle with care",
  • "actualProGearWeight": 0,
  • "actualSpouseProGearWeight": 0,
  • "agents": [
    ],
  • "sitExtensions": [
    ],
  • "reweigh": {
    },
  • "pickupAddress": {
    },
  • "destinationAddress": {
    },
  • "destinationType": "OTHER_THAN_AUTHORIZED",
  • "secondaryPickupAddress": {
    },
  • "secondaryDeliveryAddress": {
    },
  • "storageFacility": {
    },
  • "shipmentType": "HHG",
  • "diversion": true,
  • "diversionReason": "string",
  • "status": "SUBMITTED",
  • "ppmShipment": {
    },
  • "deliveryAddressUpdate": {
    },
  • "eTag": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "pointOfContact": "string",
  • "originSitAuthEndDate": "2019-08-24",
  • "destinationSitAuthEndDate": "2019-08-24"
}

mtoServiceItem

A service item is a service that the contractor can bill for. For example, if the movers pack and/or unpack a customer's belongings, those are billable services (packing and unpacking). All mtoServiceItems must be approved by the TOO before payment can be requested.

There are three types of service items: accessorial, MTO-level, and standard.

WIP: Add an external link to an article that explains the different types of service items in more detail.

createMTOServiceItem

Creates one or more MTOServiceItems. Not all service items may be created, please see details below.

This endpoint supports different body definitions. In the modelType field below, select the modelType corresponding to the service item you wish to create and the documentation will update with the new definition.

Upon creation these items are associated with a Move Task Order and an MTO Shipment. The request must include UUIDs for the MTO and MTO Shipment connected to this service item. Some service item types require additional service items to be autogenerated when added - all created service items, autogenerated included, will be returned in the response.

To update a service item, please use updateMTOServiceItem endpoint.

MTOServiceItemOriginSIT

MTOServiceItemOriginSIT is a subtype of MTOServiceItem.

This model type describes a domestic origin SIT service item. Items can be created using this model type with the following codes:

DOFSIT

1st day origin SIT service item. When a DOFSIT is requested, the API will auto-create the following group of service items:

  • DOFSIT - Domestic origin 1st day SIT
  • DOASIT - Domestic origin Additional day SIT
  • DOPSIT - Domestic origin SIT pickup
  • DOSFSC - Domestic origin SIT fuel surcharge

DOASIT

Addt'l days origin SIT service item. This represents an additional day of storage for the same item. Additional DOASIT service items can be created and added to an existing shipment that includes a DOFSIT service item.

MTOServiceItemDestSIT

MTOServiceItemDestSIT is a subtype of MTOServiceItem.

This model type describes a domestic destination SIT service item. Items can be created using this model type with the following codes:

DDFSIT

1st day destination SIT service item.

These additional fields are optional for creating a DDFSIT:

  • firstAvailableDeliveryDate1
    • string
    • First available date that Prime can deliver SIT service item.
    • firstAvailableDeliveryDate1, dateOfContact1, and timeMilitary1 are required together
  • dateOfContact1
    • string
    • Date of attempted contact by the prime corresponding to timeMilitary1
    • dateOfContact1, timeMilitary1, and firstAvailableDeliveryDate1 are required together
  • timeMilitary1
    • string\d{4}Z
    • Time of attempted contact corresponding to dateOfContact1, in military format.
    • timeMilitary1, dateOfContact1, and firstAvailableDeliveryDate1 are required together
  • firstAvailableDeliveryDate2
    • string
    • Second available date that Prime can deliver SIT service item.
    • firstAvailableDeliveryDate2, dateOfContact2, and timeMilitary2 are required together
  • dateOfContact2
    • string
    • Date of attempted contact delivery by the prime corresponding to timeMilitary2
    • dateOfContact2, timeMilitary2, and firstAvailableDeliveryDate2 are required together
  • timeMilitary2
    • string\d{4}Z
    • Time of attempted contact corresponding to dateOfContact2, in military format.
    • timeMilitary2, dateOfContact2, and firstAvailableDeliveryDate2 are required together

When a DDFSIT is requested, the API will auto-create the following group of service items:

  • DDFSIT - Domestic destination 1st day SIT
  • DDASIT - Domestic destination Additional day SIT
  • DDDSIT - Domestic destination SIT delivery
  • DDSFSC - Domestic destination SIT fuel surcharge

NOTE When providing the sitEntryDate value in the payload, please ensure that the date is not BEFORE firstAvailableDeliveryDate1 or firstAvailableDeliveryDate2. If it is, you will receive an error response.

DDASIT

Addt'l days destination SIT service item. This represents an additional day of storage for the same item. Additional DDASIT service items can be created and added to an existing shipment that includes a DDFSIT service item.

Request Body schema: application/json
moveTaskOrderID
required
string <uuid>

The ID of the move for this service item.

mtoShipmentID
string <uuid>

The ID of the shipment this service is for, if any. Optional.

modelType
required
string (MTOServiceItemModelType)

Describes all model sub-types for a MTOServiceItem model.

Using this list, choose the correct modelType in the dropdown, corresponding to the service item type.

  • DOFSIT, DOASIT - MTOServiceItemOriginSIT
  • DDFSIT, DDASIT - MTOServiceItemDestSIT
  • DOSHUT, DDSHUT - MTOServiceItemShuttle
  • DCRT, DUCRT - MTOServiceItemDomesticCrating

The documentation will then update with the supported fields.

Array of objects (ServiceRequestDocuments)
reServiceCode
required
string (ReServiceCode)
Enum: "CS" "DBHF" "DBTF" "DCRT" "DDASIT" "DDDSIT" "DDFSIT" "DDP" "DDSHUT" "DLH" "DMHF" "DNPK" "DOASIT" "DOFSIT" "DOP" "DOPSIT" "DOSHUT" "DPK" "DSH" "DUCRT" "DUPK" "FSC" "IBHF" "IBTF" "ICOLH" "ICOUB" "ICRT" "ICRTSA" "IDASIT" "IDDSIT" "IDFSIT" "IDSHUT" "IHPK" "IHUPK" "INPK" "IOASIT" "IOCLH" "IOCUB" "IOFSIT" "IOOLH" "IOOUB" "IOPSIT" "IOSHUT" "IUBPK" "IUBUPK" "IUCRT" "MS" "NSTH" "NSTUB"

This is the full list of service items that can be found on a shipment. Not all service items may be requested by the Prime, but may be returned in a response.

Documentation of all the service items will be provided.

Responses

Request samples

Content type
application/json
Example
{
  • "moveTaskOrderID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "mtoShipmentID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "modelType": "MTOServiceItemBasic",
  • "serviceRequestDocuments": [],
  • "reServiceCode": "CS"
}

Response samples

Content type
application/json
[
  • {
    }
]

updateMTOServiceItem

Updates MTOServiceItems after creation. Not all service items or fields may be updated, please see details below.

This endpoint supports different body definitions. In the modelType field below, select the modelType corresponding to the service item you wish to update and the documentation will update with the new definition.

  • Addresses: To update a destination service item's SIT destination final address, update the shipment destination address. For approved shipments, please use updateShipmentDestinationAddress. For shipments not yet approved, please use updateMTOShipmentAddress.

  • SIT Service Items: Take note that when updating sitCustomerContacted, sitDepartureDate, or sitRequestedDelivery, we want those to be updated on DOASIT (for origin SIT) and DDASIT (for destination SIT). If updating those values in other service items, the office users will not have as much attention to those values.

To create a service item, please use createMTOServiceItem) endpoint.

  • Resubmitting rejected SIT service items: This endpoint will handle the logic of changing the status of rejected SIT service items from REJECTED to SUBMITTED. Please provide the requestedApprovalsRequestedStatus: true when resubmitting as this will give attention to the TOO to review the resubmitted SIT service item. Another note, updateReason must have a different value than the current reason value on the service item. If this value is not updated, then an error will be sent back.

The following SIT service items can be resubmitted following a rejection:

  • DDASIT
  • DDDSIT
  • DDFSIT
  • DOASIT
  • DOPSIT
  • DOFSIT
  • DDSFSC
  • DOSFSC

At a MINIMUM, the payload for resubmitting a rejected SIT service item must look like this:

{
  "reServiceCode": "DDFSIT",
  "updateReason": "A reason that differs from the previous reason",
  "modelType": "UpdateMTOServiceItemSIT",
  "requestApprovalsRequestedStatus": true
}
path Parameters
mtoServiceItemID
required
string

UUID of service item to update.

header Parameters
If-Match
required
string

Optimistic locking is implemented via the If-Match header. If the ETag header does not match the value of the resource on the server, the server rejects the change with a 412 Precondition Failed error.

Request Body schema: application/json
id
string <uuid>

ID of the service item. Must match path.

modelType
required
string (UpdateMTOServiceItemModelType)

Using this list, choose the correct modelType in the dropdown, corresponding to the service item type.

  • DDDSIT - UpdateMTOServiceItemSIT
  • DDFSIT - UpdateMTOServiceItemSIT
  • DDASIT - UpdateMTOServiceItemSIT
  • DOPSIT - UpdateMTOServiceItemSIT
  • DOASIT - UpdateMTOServiceItemSIT
  • DOFSIT - UpdateMTOServiceItemSIT
  • DOSFSC - UpdateMTOServiceItemSIT
  • DDSFSC - UpdateMTOServiceItemSIT
  • DDSHUT - UpdateMTOServiceItemShuttle
  • DOSHUT - UpdateMTOServiceItemShuttle

The documentation will then update with the supported fields.

actualWeight
integer or null

Provided by the movers, based on weight tickets. Relevant for shuttling (DDSHUT & DOSHUT) service items.

estimatedWeight
integer or null

An estimate of how much weight from a shipment will be included in a shuttling (DDSHUT & DOSHUT) service item.

reServiceCode
string
Enum: "DDSHUT" "DOSHUT"

Service code allowed for this model type.

Responses

Request samples

Content type
application/json
Example
{
  • "id": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "modelType": "UpdateMTOServiceItemShuttle",
  • "actualWeight": 4000,
  • "estimatedWeight": 4200,
  • "reServiceCode": "DDSHUT"
}

Response samples

Content type
application/json
Example
{
  • "id": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "moveTaskOrderID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "mtoShipmentID": "1f2270c7-7166-40ae-981e-b200ebdf3054",
  • "reServiceName": "string",
  • "status": "SUBMITTED",
  • "rejectionReason": "item was too heavy",
  • "modelType": "MTOServiceItemBasic",
  • "serviceRequestDocuments": [],
  • "eTag": "string",
  • "reServiceCode": "CS"
}

createServiceRequestDocumentUpload

Functionality

This endpoint uploads a Service Request document for a ServiceItem.

The ServiceItem should already exist.

ServiceItems are created with the createMTOServiceItem endpoint.

path Parameters
mtoServiceItemID
required
string

UUID of the service item to use.

Request Body schema: multipart/form-data
file
required
string <binary>

The file to upload.

Responses

Response samples

Content type
application/json
{}

paymentRequest

The contractor submits a paymentRequest to the TIO for approval in order to be reimbursed for 1 or more mtoServiceItems on a moveTaskOrder. A service item can be on multiple payment requests if necessary.

Proof of service documentation may be uploaded for each mtoServiceItem in a paymentRequest after the payment request is created via the endpoint createUpload.

All weight entered should be in pounds and no other unit of measurement.

createPaymentRequest

Creates a new instance of a paymentRequest and is assigned the status PENDING. A move task order can have multiple payment requests, and a final payment request can be marked using boolean isFinal.

If a PENDING payment request is recalculated, a new payment request is created and the original request is marked with the status DEPRECATED.

NOTE: In order to create a payment request for most service items, the shipment must be updated with the PrimeActualWeight value via updateMTOShipment.

FSC - Fuel Surcharge service items require ActualPickupDate to be updated on the shipment.

A service item can be on several payment requests in the case of partial payment requests and payments.

In the request, if no params are necessary, then just the serviceItem id is required. For example:

{
  "isFinal": false,
  "moveTaskOrderID": "uuid",
  "serviceItems": [
    {
      "id": "uuid",
    },
    {
      "id": "uuid",
      "params": [
        {
          "key": "Service Item Parameter Name",
          "value": "Service Item Parameter Value"
        }
      ]
    }
  ],
  "pointOfContact": "string"
}

SIT Service Items & Accepted Payment Request Parameters:

If WeightBilled is not provided then the full shipment weight (PrimeActualWeight) will be considered in the calculation.

NOTE: Diversions have a unique calcuation for payment requests without a WeightBilled parameter.

If you created a payment request for a diversion and WeightBilled is not provided, then the following will be used in the calculation:

  • The lowest shipment weight (PrimeActualWeight) found in the diverted shipment chain.
  • The lowest reweigh weight found in the diverted shipment chain.

The diverted shipment chain is created by referencing the diversion boolean, divertedFromShipmentId UUID, and matching destination to pickup addresses. If the chain cannot be established it will fall back to the PrimeActualWeight of the current shipment. This is utilized because diverted shipments are all one single shipment, but going to different locations. The lowest weight found is the true shipment weight, and thus we search the chain of shipments for the lowest weight found.

DOFSIT - Domestic origin 1st day SIT

  "params": [
    {
      "key": "WeightBilled",
      "value": "integer"
    }
  ]

DOASIT - Domestic origin add'l SIT (SITPaymentRequestStart & SITPaymentRequestEnd are REQUIRED) To create a paymentRequest for this service item, the SITPaymentRequestStart and SITPaymentRequestEnd dates must not overlap previously requested SIT dates.

  "params": [
    {
      "key": "WeightBilled",
      "value": "integer"
    },
    {
      "key": "SITPaymentRequestStart",
      "value": "date"
    },
    {
      "key": "SITPaymentRequestEnd",
      "value": "date"
    }
  ]

DOPSIT - Domestic origin SIT pickup

  "params": [
    {
      "key": "WeightBilled",
      "value": "integer"
    }
  ]

DOSHUT - Domestic origin shuttle service

  "params": [
    {
      "key": "WeightBilled",
      "value": "integer"
    }
  ]

DDFSIT - Domestic destination 1st day SIT

  "params": [
    {
      "key": "WeightBilled",
      "value": "integer"
    }
  ]

DDASIT - Domestic destination add'l SIT (SITPaymentRequestStart & SITPaymentRequestEnd are REQUIRED) To create a paymentRequest for this service item, the SITPaymentRequestStart and SITPaymentRequestEnd dates must not overlap previously requested SIT dates.

  "params": [
    {
      "key": "WeightBilled",
      "value": "integer"
    },
    {
      "key": "SITPaymentRequestStart",
      "value": "date"
    },
    {
      "key": "SITPaymentRequestEnd",
      "value": "date"
    }
  ]

DDDSIT - Domestic destination SIT delivery To create a paymentRequest for this service item, it must first have a final address set via updateMTOServiceItem.

  "params": [
    {
      "key": "WeightBilled",
      "value": "integer"
    }
  ]

DDSHUT - Domestic destination shuttle service

  "params": [
    {
      "key": "WeightBilled",
      "value": "integer"
    }
  ]
Request Body schema: application/json
isFinal
boolean
Default: false
moveTaskOrderID
required
string <uuid>
required
Array of objects (ServiceItem) non-empty
pointOfContact
string

Email or id of a contact person for this update.

Responses

Request samples

Content type
application/json
{
  • "isFinal": false,
  • "moveTaskOrderID": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "serviceItems": [
    ],
  • "pointOfContact": "string"
}

Response samples

Content type
application/json
{
  • "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "isFinal": false,
  • "moveTaskOrderID": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "rejectionReason": "documentation was incomplete",
  • "status": "PENDING",
  • "paymentRequestNumber": "1234-5678-1",
  • "recalculationOfPaymentRequestID": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  • "proofOfServiceDocs": [],
  • "paymentServiceItems": [
    ],
  • "eTag": "string"
}

createUpload

Functionality

This endpoint uploads a Proof of Service document for a PaymentRequest.

The PaymentRequest should already exist.

Optional key of isWeightTicket indicates if the document is a weight ticket or not. This will be used for partial and full deliveries and makes it easier for the Task Invoicing Officers to locate and review service item documents. If left empty, it will assume it is NOT a weight ticket.

The formdata in the body of the POST request that is sent should look like this if it IS a weight ticket being attached to an existing payment request:

{
  "file": "filePath",
  "isWeightTicket": true
}

If the proof of service doc is NOT a weight ticket, it will look like this - or you can leave it empty:

{
  "file": "filePath",
  "isWeightTicket": false
}

{
  "file": "filePath",
}

PaymentRequests are created with the createPaymentRequest endpoint.

path Parameters
paymentRequestID
required
string

UUID of payment request to use.

Request Body schema: multipart/form-data
file
required
string <binary>

The file to upload.

isWeightTicket
boolean

Indicates whether the file is a weight ticket.

Responses

Response samples

Content type
application/json
{}