The Package Tracking “Fields” API is similar to the Package Track API except for the request fields, API name, and the return information. Data returned still contains the detail and summary information, but this information is broken down into fields instead of having only one line of text. Up to 10 tracking IDs may be contained in each API request to the Web Tools server.
Here you can find all information for developers presented by USPS
| SERVICE | SAMPLE NUMBER |
|---|---|
| USPS Tracking® | 9400 1000 0000 0000 0000 00 |
| Priority Mail® | 9205 5000 0000 0000 0000 00 |
| Certified Mail® | 9407 3000 0000 0000 0000 00 |
| Collect On Delivery Hold For Pickup | 9303 3000 0000 0000 0000 00 |
| Global Express Guaranteed® | 82 000 000 00 |
| Priority Mail Express International® | EC 000 000 000 US |
| Priority Mail Express® | 9270 1000 0000 0000 0000 00 & EA 000 000 000 US |
| Priority Mail International® | CP 000 000 000 US |
| Registered Mail™ | 9208 8000 0000 0000 0000 00 |
| Signature Confirmation™ | 9202 1000 0000 0000 0000 00 |
- You need to be registered for the U.S.Postal Service's Web Tools Application Programming Interfaces (APIs). *1
- As a result, you will have a UserID (Username) and Password.
- You need to be registered as a USPS user for Mailer ID (MID).
- To obtain Package Tracking API (API=TrackV2) access, users will need to contact the USPS Web Tools Program Office to request access and supply additional information for customer verification. *2
Step-by-Step Instructions for All USPS Web Tools (HTM | PDF)
| Tag Name | Occurs | Descriptions | Type | Validation |
|---|---|---|---|---|
| TrackFieldRequest | Required | API=TrackV2 | (Alias) | |
| TrackFieldRequest / USERID | Required | This attribute specifies your Web Tools ID. See the Developers Guide for information on obtaining your USERID. For Example: <USERID=”XXXXXXXXXXXX”> | String | |
| TrackFieldRequest / Revision | Required | This is for versioning of the API's and for triggering response tags for future versions. In this API use a value of 1 to return all available response tags and trigger new functionality. For example: 1 | Integer | minOccurs="0" |
| TrackFieldRequest / ClientIp | Optional | User IP address. Required when TrackFieldRequest[Revision='1']. For example: 137.0.0.1 Note: Web Tools will always collect the physical IP address from the system generating the API call. This will be passed on the backend to a separate internal package tracking system. | String | minOccurs="0" |
| TrackFieldRequest / SourceId | Required | External integrators should pass company name. For example: XYZ Corp | String | minOccurs="0" Pattern="[0-9]{5}" |
| TrackFieldRequest / TrackID | Required | Package Tracking ID. Must be alphanumeric characters. For example: | String | minOccurs="1" |
| TrackFieldRequest / TrackID / DestinationZipCode | Optional | 5 digit destination zip code. For example: 12345 | String | minOccurs="0" |
| TrackFieldRequest / TrackID / MailingDate | Optional | Mailing date of package. Format: YYYY-MM-DD For example: 2010-01-01 | String | minOccurs="0" |
| TrackFieldRequest | Required | (Alias) |
<TrackFieldRequest USERID= "XXXXXXXXXXXX">
<Revision>1</Revision>
<ClientIp>122.3.3</ClientIp>
<SourceId>XYZ Corp</SourceId>
<TrackID ID="XXXXXXXXXXXXXXXX"/>
</TrackFieldRequest>
| Tag Name | Occurs | Descriptions | Type | Validation |
|---|---|---|---|---|
| TrackResults/ RequestSeqNumber | Required max 1 | A unique identification number for a request. The same number that was provided in the request. For example: 122 | Integer | |
| TrackResults / TrackInfo ID | Required max 10 | The tracking number ID submitted through the request For example: EA123456795US 12887393000019 | String | |
| TrackResults / TrackInfo / AdditionalInfo | Optional | Additional package information | String | |
| TrackResults / TrackInfo / ADPScripting | Optional | Additional ADP scripting specific to the ADP Type code | String | |
| TrackResults / TrackInfo / ArchiveRestoreInfo | Optional | Information regarding availability of Restore service function For example Yes | String | |
| TrackResults / TrackInfo / AssociatedLabel | Optional | Additional Label on the mail piece For example: EA123456785US This is not currently populated. | String | |
| TrackResults / TrackInfo / CarrierRelease | Optional | True/False field indicating the item qualifies for the customer to electronically authorize shipment release. | String | |
| TrackResults / TrackInfo / Class | Optional | Mail Class of the mail piece (human readable). This will also include the service standard message if it exists. No Default of False. | String | Enumerations= · True · False |
| TrackResults / TrackInfo / ClassofMailCode | Optional | Mail Class of the mail piece (code). For example:EX, PM, CP, IP | String | |
| TrackResults / TrackInfo / DestinationCity | Optional | The destination city. For example: Rochester | String | |
| TrackResults / TrackInfo / DestinationCountryCode | Optional | The destination country code. For example:MX, CA | String | |
| TrackResults / TrackInfo / DestinationState | Optional | The destination State. For example: NY | String | |
| TrackResults / TrackInfo / DestinationZip | Optional | The destination ZIP code. For example:20024 | String | |
| TrackResults / TrackInfo / EditedLabelID | Optional | Edited Label ID or Full Label ID. Used only when Source ID is IVR For example:EA123456795US | String | Enumerations= · True · False |
| TrackResults / TrackInfo / EmailEnabled | Optional | Signifies if USPS Tracking by Email service is enabled. | Boolean | |
| TrackResults / TrackInfo / EndOfDay | Optional, used only when end of day condition is met | Populated with the end of day time provided by TRP when TRP API indicates the window is “End of Day” or when the piece is eligible for the PTR default end of day. For example: by 5:00pm Note: an end of day scenario occurs when the TRP API response indicates a 0 length window. | String | |
| TrackResults / TrackInfo / eSOFEligible | Optional | Signifies if the mailpiece is eSOF eligibile. | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / ExpectedDeliveryDate | Optional | Expected delivery date. For example:December 31, 2013 | String | |
| TrackResults / TrackInfo / ExpectedDeliveryTime | Optional | Expected Delivery Time. For example: 3:00 PM | String | |
| TrackResults / TrackInfo / ExpectedDeliveryType | Optional | Populates “Expected Delivery by” if there is an EDD. For example: Expected Delivery by | String | |
| TrackResults / TrackInfo / GuaranteedDeliveryDate | Optional | Guaranteed Delivery Date – Global Express Mail only: certain countries provide a guarantee delivery. For example: April 15, 2011 or 3 Business Days | String | |
| TrackResults / TrackInfo / GuaranteedDeliveryTime | Optional | Guaranteed Delivery Time provided for Priority Mail Express. For example: 3:00 PM | String | |
| TrackResults / TrackInfo / GuaranteedDeliveryType | Optional | Populates “Scheduled Delivery by” if there is a GDD. For example: Scheduled Delivery by | String | |
| TrackResults / TrackInfo / GuaranteedDetails | Optional | Special messaging related to the guarantee. For example: “Loss Only Guarantee” | String | |
| TrackResults / TrackInfo / ItemShape | Optional | Indicates the shape of the item. | String | Enumerations= · Letter · Flat · Parcel · Unknown |
| TrackResults / TrackInfo / KahalaIndicator | Optional | Boolean | Enumerations= · True · False | |
| TrackResults / TrackInfo / MailTypeCode | Optional | String | ||
| TrackResults / TrackInfo / MPDATE | Optional | Internal date stamp. | String | |
| TrackResults / TrackInfo / MPSUFFIX | Optional | Internal suffix. 2010-03-30 19:30:48.224343 | Integer | |
| TrackResults / TrackInfo / OnTime | Optional | Field indicating if the item will be delivered on time as specified in the Expected or Guaranteed delivery date. | String | Enumerations= · True · False |
| TrackResults / TrackInfo / OriginCity | Optional | The origin city. | String | |
| TrackResults / TrackInfo / OriginCountryCode | Optional | The origin country code. | String | |
| TrackResults / TrackInfo / OriginState | Optional | The origin state. | String | |
| TrackResults / TrackInfo / OriginZip | Optional | The origin ZIP code. | String | |
| TrackResults / TrackInfo / PodEnabled | Optional | Signifies if Proof of Delivery service is enabled. | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / PredictedDeliveryDate | Optional | Predicted delivery date. December 30, 2013 | String | |
| TrackResults / TrackInfo / PredictedDeliveryTime | Optional | Predicted Delivery Time 3:00 PM or blank. | String | |
| TrackResults / TrackInfo / PredictedDeliveryType | Optional | Populates “Expected Delivery ‘by or on’”, if the source of the PDD is TRP API. Populates “Expected Delivery on” if the source of the PDD is a PTR calculated date. For example: Expected Delivery by or Expected Delivery on | String | |
| TrackResults / TrackInfoPredictedDeliverySource | Optional | States which system provided the Predicted Delivery prediction. TRP, AA | String | |
| TrackResults / TrackInfo / PDWStart | Optional | Predicted Delivery Window start time in am/pm format. In an EndOfDay scenario, the PDWStart tag is null. 11:00am For example: (null) | String | |
| TrackResults / TrackInfo / PDWEnd | Optional | Predicted Delivery Window end time in am/pm format. In an EndOfDay scenario, the PDWEnd tag is null. 1:00pm For example: (null) | String | |
| TrackResults / TrackInfo / PurgeByDate | Optional | Contains the Purge By Date of the mail piece. Example: December 31, 2024 | String | |
| TrackResults / TrackInfo / RelatedRRID | Optional | The related label ID between a tracking barcode, the core product, and a PS3811, Green Card Return Reciept. This field can contain either the core product label ID or the Green Card label ID. There is only a one to one relationship. Core Product ID: EA123456795US Or Green Card ID; 9590940112345671234567 | String | |
| TrackResults / TrackInfo / RedeliveryEnabled | Optional | Field indicating if the item qualifies for redelivery. | String | Enumerations= · True · False |
| TrackResults / TrackInfo / RestoreEnabled | Optional | Signifies if Restore tracking information service is enabled Values: | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / ReturnDateNotice | Optional | Field indicating the date the item will be Returned to Sender. | String | |
| TrackResults / TrackInfo / PodEnabled | Optional | Signifies if Proof of Delivery service is enabled | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / TpodEnabled | Optional | Signifies if Tracking Proof of Delivery service is enabled | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / RRAMenabled | Optional | Signifies if RRAM service is enabled | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / RreEnabled | Optional | Signifies if Return Receipt Electronic service is enabled | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / Service | Optional unbounded | Additional services purchased | String | |
| TrackResults / TrackInfo / ServiceTypeCode | Optional max 1 | Service Type Code of the mail piece M, AD, VI, 03, 70, 716 | String | |
| TrackResults / TrackInfo / Status | Optional | For example: Delivered | String | |
| TrackResults / TrackInfo / StatusCategory | Optional | For example: In Transit | String | |
| TrackResults / TrackInfo / StatusSummary | Optional | Status summary For example: Your item was delivered at 12:55 pm on April 05, 2010 in FALMOUTH, MA 02540 | String | |
| TrackResults / TrackInfo / TABLECODE | Optional | Internal description of mail piece as it relates to PTR (live, history, or archived piece) T, H, A (CMC830 V3 – T is the only value defined) | String | |
| TrackResults / TrackInfo / ValueofArticle | Optional | Value of Article for when the Source ID is PIN | String | |
| TrackResults / TrackInfo / TrackSummary | Optional max 1 | Tracking Summary Information. | (Group) | |
| TrackResults / TrackInfo / TrackSummary / EventTime | Optional | The time of the event. | String | |
| TrackResults / TrackInfo / TrackSummary / EventDate | Optional | The date of the event. | String | |
| TrackResults / TrackInfo / TrackSummary / Event | Optional | The event type | String | |
| TrackResults / TrackInfo / TrackSummary / EventCity | Optional | The city where the event occurred. | String | |
| TrackResults / TrackInfo / TrackSummary / EventState | Optional | The state where the event occurred. | String | |
| TrackResults / TrackInfo / TrackSummary / EventZIPCode | Optional | The ZIP Code of the event. | String | |
| TrackResults / TrackInfo / TrackSummary / EventCountry | Optional | The country where the event occurred. | String | |
| TrackResults / TrackInfo / TrackSummary / FirmName | Optional | The company name if delivered to a company. | String | |
| TrackResults / TrackInfo / TrackSummary / Name | Optional | The first initial and last name of the person signing for delivery (if available). | String | |
| TrackResults / TrackInfo / TrackSummary / EventCode | Optional | String | ||
| TrackResults / TrackInfo / TrackSummary / ActionCode | Optional max 1 | String | ||
| TrackResults / TrackInfo / TrackSummary / ReasonCode | Optional | String | ||
| TrackResults / TrackInfo / TrackSummary / GeoCertified | Optional | Only eligible to display with delivery (01) events. | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / TrackDetail | Optional max 99 | Tracking Detail Information. This group is repeatable. | (Group) | |
| TrackResults / TrackInfo / TrackDetail / DeliveryAttributeCode | Optional | Used to provide additional information regarding an event posted to a mail piece. | String | Enumerations= · 32 |
| TrackResults / TrackInfo / TrackDetail / EventTime | Optional | The time of the event. | String | |
| TrackResults / TrackInfo / TrackDetail / EventDate | Optional | The date of the event. | String | |
| TrackResults / TrackInfo / TrackDetail / Event | Optional | The event type. | String | |
| TrackResults / TrackInfo / TrackDetail / EventCity | Optional | The city where the event occurred. | String | |
| TrackResults / TrackInfo / TrackDetail / EventState | Optional | The state where the event occurred. | String | |
| TrackResults / TrackInfo / TrackDetail / EventStatusCategory | Optional | The status of a posted event on a mail piece. | String | |
| TrackResults / TrackInfo / TrackDetail / EventPartner | Optional | Stores the name of the shipping partner associated to a posted shipping partner event (80,81,82). | String | |
| TrackResults / TrackInfo / TrackDetail / EventZIPCode | Optional | The ZIP Code of the event. | String | |
| TrackResults / TrackInfo / TrackDetail / EventCountry | Optional | The country where the event occurred. | String | |
| TrackResults / TrackInfo / TrackDetail / FirmName | Optional | The company name if delivered to a company. | String | |
| TrackResults / TrackDetail / Name | Optional | The name of the persons signing for delivery (if available). | String | |
| TrackResults / TrackInfo / TrackDetail / AuthorizedAgent | Optional | True/False field indicating the person signing as an Authorized Agent. | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / TrackDetail / EventCode | Optional | String | ||
| TrackResults / TrackInfo / TrackDetail / ActionCode | Optional max 1 | String | ||
| TrackResults / TrackInfo / TrackDetail / ReasonCode | Optional | String | ||
| TrackResults / TrackInfo / TrackDetail / GeoCertified | Optional | Only eligible to display with delivery (01) events. | Boolean | Enumerations= · True · False |
| TrackResults / TrackInfo / Error | Optional | (Group) | ||
| TrackResults / TrackInfo / Error / Number | Optional | Assigned number for the type of error message. | String | |
| TrackResults / TrackInfo / Error / ErrorDescription | Optional | Descriptions of error message. Duplicate or 4 items were also tied to your 3849 ID but exceeded the maximum number of tracking number inquiries supported on this site. This 3849 ID was used on a large volume shipment and cannot be used for tracking on this site. | String | |
| TrackResults / TrackInfo / Error | Optional | (Group) | ||
| TrackResponse | Required | (Alias) |