---
title: "PreClearance Request API"
slug: "preclearance-request-api"
updated: 2023-09-14T12:02:19Z
published: 2023-09-14T12:02:19Z
canonical: "mercurydocs.landmarkglobal.com/preclearance-request-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://mercurydocs.landmarkglobal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PreClearance Request API

The following details the method of declaring shipments travelling together as part of a PreClearance to Mercury via an [**API request**](https://mercurydocs.landmarkglobal.com/docs/api-specifications).

#### Overview

The protocol is based on XML data exchange with HTTP used as a transport. A non-validating parser is used and hence no internal or external DTD needs to be specified. The data must be well formed and all validation is handled at the application (not parser) level. Error handling will be done by always including the <Errors> container in the response. The Errors element will not be returned if no errors are found.

#### **Connection**

To connect to the site use the following HTTPS URL via regular POST method with the parameter RQXML=<your xml document> **[https://api.landmarkglobal.com/v2/PreClearance.php](https://api.landmarkglobal.com/v2/PreClearance.php)**

#### **Encoding**

Mercury uses UTF-8 for character encoding. If your system outputs in an encoding other than UTF-8, please include an encoding flag in your XML header.

Example: <?xml version="1.0" encoding="UTF-8"?>

Example: <?xml version="1.0" encoding="ISO-8859-1"?>

#### Test Mode

When first given access to the API, the client will be placed in Test mode. Requests made while in test mode will not act on live data. After approval has been received to go live from Landmark, all requests are active unless the <Test> flag is passed. During a test API call, orders will not be cancelled but errors will be reported when appropriate.

During a test API call, validation will be very basic, focusing on fields being required and passing sane values. Assuming the request passes the basic validation, **responses are randomized**. Some requests will succeed and some will fail with different error messages. This is done so that the programmer has an opportunity to see a wide variety of responses and can be prepared to handle many potential results.

#### **Troubleshooting**

If you receive a <Response> error with the message "Required element login not found", then please ensure you are properly including the login nodes and credentials. Additionally, the API will return this error when it could not parse the XML.

#### **PreClearanceRequest**

This request will assign a MAWB number and International Airport Code to a set of shipments travelling together on the given MAWB. This is required for shipments utilizing Landmark's PreClearance services.

----------

<PreClearanceRequest>

<Login>

<Username>demoapi</Username>

<Password>demo123</Password>

</Login>

<Test>true</Test> *<!-- Optional. Defaults to true before account activation, false afterwards -->*

<ClientID>218</ClientID> *<!-- Required if more than one client under user, otherwise Optional -->*

<MAWB>1234</MAWB>

<OriginAirport>SHG</OriginAirport> *<!-- Use 3-digit airport codes -->*

<TransportType>AIR</TransportType> *<!-- Can be AIR, GROUND or NCTS -->*

<Shipments>

<Shipment>

<Reference>123123123</Reference> *<!-- Should be the same Reference field passed in the ImportRequest -->*

</Shipment>

<Shipment>

<Reference>454545454</Reference>

</Shipment>

<Shipment> *<!-- LTN value as received from Import API response -->*

<LTN>LTN12345678</LTN>

</Shipment>

</Shipments>

</PreClearanceRequest>

#### **PreClearanceResponse**

<PreClearanceResponse>

<Result>

<Success>true</Success>

</Result>

<PreClearanceId>36</PreClearanceId>

</PreClearanceResponse>

### 

#### PreClearanceResponse with <PreClearanceNotNeeded> element

In some corner cases, some shipments included in a preclearance request might not actually require preclearance (for example, some shipments are routed to a DDU service code). When this happens, a new element <PreClearanceNotNeeded> will be added to the response. This element will have a list of <Reference> elements each containing a reference of a shipment that does not need pre-clearance. In the example below, shipment 123123123 did not need preclearance. Note that the PreClearanceResponse will still return a PreClearance ID for shipments that need them, and the <Result> element will contain <Success>true</Success>, indicating that this is not a failure.

<?xml version="1.0"?>

<PreClearanceResponse>

**<PreClearanceNotNeeded>**

**<Reference>123123123</Reference> *<!-- This shipment did not require preclearance -->***

**</PreClearanceNotNeeded>**

<Result>

<Success>true</Success>

</Result>

<PreClearanceId>462</PreClearanceId> *<!-- This contains shipments 454545454 and LTN12345678 -->*

</PreClearanceResponse>

#### **Possible Errors**

This table lists all errors that may be returned by the PreClearance Request API endpoint. [Brackets] in the ErrorMessage are used to represent to the value passed for the related element. An example is provided when an ErrorMessage is variable.

| Related Element(s) | ErrorMessage | Details/Action |
| --- | --- | --- |
| General Errors |
| User, API | User [username] does not have permissions to this API |  |
| Failure authenticating user |  |
| User is not available. Check your username/password |  |
| N/A | Unable to parse characters | Ensure that special characters are properly encoded and an encoding flag is included in your XML header. *Example:* <?xml version=""1.0"" encoding=""UTF-8""?> *Example:* <?xml version=""1.0"" encoding=""ISO-8859-1""?> |
| <Login> Errors |
| Login | Required element Login not found | Provide login credentials and verify the XML can be parsed |
| Login name not provided |
| User, ClientID | Request is missing client ID |  |
| Unable to authenticate the user credentials |  |
| Client is inactive |  |
| Client has been deactivated. Permission denied |  |
| User [username] does not have permissions to client: [clientID] |  |
| Unable to determine desired client for this user | If user has access to more than one client, the ClientID is required |
| Username, password | The username/password combination provided is invalid |  |
| The username/password combination provided is disabled |  |
| Password not provided |  |
| Missing Element Errors |
| Varies by API | *Format:* Required element [Missing Element] not found *Example:* Required element Reference not found | Required elements for PreClearance API include MAWB, OriginAirport, Shipments, Shipment |
| Errors Specific to PreClearance API |
| OriginAirport | OriginAirport required | Use 3-digit airport code |
| MAWB | Due to limitations of CBSA, you can only send 1200 shipments per MAWB number. You will need to create multiple clearance requests with distinct MAWBs |  |
| Airline code is not set up for pre-clearances with CanData and eManifest, please contact Landmark Trade Services with the MAWB number |  |
| TransportType | Transport Type must be one of [supported types] |  |
| Shipment | Shipment LTN [LTN number] not found |  |
| [LTN number] is not a valid LTN |  |
| Reference | *Format:* Shipment [reference] already in [preclearance id] *Example:* Shipment 17 already in PC23 | Returned when a shipment has already been precleared |
| No shipment references found |  |
| Shipment with reference [reference] not found | Value should be the same Reference field passed in the ImportRequest |
| Could not find appropriate broker. Please contact Landmark IT |  |
| N/A | *Format:* Failed sending pre-clearance: [detail message] *Example:* Unknown preclearance ID | Contact Integration Manager |

A MAWB (Master Airway Billed) number is an 11-digit number that identifies the airline and the shipments involved.

A unique 3-letter combination that identifies an airport. For a list of airports and their codes, visit http://www.airportcodes.org/.

Delivery Duty Unpaid. For orders sent by DDU service, the buyer is responsible to settle duty fees with customs. This means that the cost paid at checkout may not be representative of the total final cost.

A unique 3-letter combination that identifies an airport. For a list of airports and their codes, visit http://www.airportcodes.org/.