Introduction
The International Bridge Blue API allows developers to integrate shipping labels and fulfillment within their e-commerce businesses and online marketplaces. The API offers price comparison, label printing, manifest generation, transactions details and tracking features. The guideline below will help get you started. For additional help, please email us at support@myibservices.com.
To create an account, please visit https://blue.myib.com and sign up for a free account. You'll use the same email address and password to submit API requests (see below). Before you can start printing live labels, you'll need to (1) verify your email address, (2) verify your SMS, (3) fill in your full mailing address and (4) add a valid credit card to our system. In a short time, one of our agents will call you at the SMS number provided to verify your identity.
Carriers and Services
Currently the International Bridge Blue platform supports USPS, GSS (presorted and discounted USPS), FedEx and UPS services. We are in the process of adding more carriers and services.
eVS vs ePostage
International Bridge is certified for both USPS eVS and USPS ePostage. By default, accounts are set up with the ePostage configuration. If you'd like to switch your account to the eVS configuration, please email us at support@myibservices.com.
Discounts
For high volume shippers, please contact us for possible domestic and international rate discounts. If you are part of an organization that has USPS negotiated rates and/or if you'd like to manage organization users (for pricing and billing), some additional steps are required. Please email us at support@myibservices.com.
Billing
We support several payment methods. By default, accounts are set up for "meter" payments. You can add funds to your meter using different payment methods (credit card, ACH, wire transfer or by mailing us a check). As you print shipping labels via the Blue website or the Blue API, the cost of the label is deducted from your account/meter balance. You can turn on the meter auto-refill flag to ensure printing labels without any downtime. For high volume shippers who are also trusted and vetted partners, we offer invoice billing.
eVS accounts handle billing directly with the USPS including refunds and adjustments. A platform usage fee is applied to eVS accounts via invoice.
Manifesting
Manifesting can be performed explicitly (for one or all unmanifested mailpieces) via the manifesting API or by using the Blue website. International Bridge manifests "on behalf of the user" at the end of the day at 11:55PM PST based on the mailpiece's postmark date. For example, if a mailpiece is postmarked for 02/12/2020, it is automatically manifested on 02/11/2020 at 11:55PM PST (if it wasn't already manifested or refunded). The manifest response contains a collection of several SCAN (Shipment Confirmation Acceptance Notice) forms, each with its EFN (Electronic File Number); the number of the SCAN forms depends on the induction point, destination entry and other aggregation factors.
Refunds
You may explicitly request a refund for any USPS label within the 30-day period after it's creation. This is accomplished by the appropriate API call which includes the mailpiece tracking number. In addition to explicitly requested refunds, the International Bridge ePostage platform provides an Automatic Refunds service. This means that even if you forget to ask for refund directly, we will identify unused labels within 30 days of creation and submit the refund request on your behalf.
Once a refund is initiated, it typically takes about two weeks for USPS to finalize the refund request. After this time, if label doesn’t have any physical scans, you will be refunded the full label price. If you are on the Meter billing type, your account balance will be increased by the refunded amount. If you are on Invoice, we will credit you in the upcoming Invoice.
The refund notification (inlcuding the approved/rejected result) is done through a refunds report to your email address. This report is sent once a day for any requested refunds.
Adjustments
As a USPS-certified ePostage partner, International Bridge charges the user for any mailpiece adjustments incurred during the delivery.
Based on the information entered by the user when the label is created, and the data obtained by the sampling of mailpieces, USPS verifies if a shipper has paid the correct postage amount. If USPS detects any underpayment, they will deliver the package to the recipient and charge the shipper for the postage due.
All label cost adjustments for the previous months are charged after 21st of current month. For Meter users the account balance will be decreased for the postage due. For Invoiced users, the adjustments will be charged on the next invoice.
To notify you about the label cost adjustments, every 1st of the month we email you a monthly adjustments-report. The report includes the list and metadata for all mailpieces for which postage has been adjusted during the past month.
Sandbox
The Sandbox environment will help you get started, test your requests and the API responses before you generate Production labels. To create an account on the Sandbox environment, please visit https://blue-sandbox.myib.com. A full mailing address and credit card information is not required like it is in Production. You cannot induct mailpieces into the mailstream using labels generated in the Sandbox environment. There are no additional charges associated with requests in the Sandbox environment. When you are ready to generate live labels, switch the API Sandbox URL with the API Production URL. The requests (including headers) do not change.
API Endpoints
RESTful API
The API is a RESTful API that supports JSON requests and responses. HATEOAS is not supported. This documentation provides code samples and libraries for different platforms to help you get started.
Requests must include "Content-Type: application/json" in the headers. Successful responses return HTTP status code 200 and 201. Depending on the request, responses return a JSON body or not. Unsuccessful responses return HTTP status codes 4XX and 5XX with additional error details (code and message). Click here for details on the API errors.
Versioning
The API version is specified in the endpoint URL. The current API version is v1.
Authentication
All API calls must be authenticated. API uses basic HTTP authentication to authenticate user requests. The username and the password are the email and the password associated with the user's account created on the International Bridge Blue website (https://blue.myib.com).
Request-Response Structure and Multiple Carriers
The structure of the API has been designed to support multiple carriers, and to easily allow developers to switch between carriers while keeping common sections unchanged. For example, the address and dimensions sections are universal and their structure wouldn't change between carrier A and carrier B. Carrier specific data is passed in carrier specific attributes. For example, a USPS shipping label which includes signature confirmation is included in the usps attribute ("usps" : { ..., "services" : ["SignatureConfirmation"] }).
Responses follow the same structure. Shipping metadata which is carrier specific is returned in carrier specific attributes.
Pagination
The RESTful routes that return array of entities are paginated. The page_number
and page_size
parameters can be set in the URL query parameters or in the request headers. The response headers will contain the following pagination fields: page-count
, page-size
, total-count-of-items
, current-page
.
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/labels?request_id=123&page_number=2&page_size=10"
The above command returns a response with the following HTTP headers:
Current-Page: 2
Page-Count: 167
Page-Size: 10
Total-Count-Of-Items: 1667
Labels
Create a Shipping Label
curl -u user@email.com:password -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"request_id\": \"AQX90000000234\",
\"from_address\": {
\"first_name\": \"John\",
\"last_name\": \"Michaels\",
\"line1\": \"247 High St\",
\"city\": \"Palo Alto\",
\"state_province\": \"CA\",
\"postal_code\": \"94301\",
\"country_code\": \"US\"
},
\"to_address\": {
\"first_name\": \"Ted\",
\"last_name\": \"Resnick\",
\"line1\": \"350 5th Ave\",
\"line2\": \"Suite 7510\",
\"city\": \"New York\",
\"state_province\": \"NY\",
\"postal_code\": \"10118\",
\"country_code\": \"US\"
},
\"weight\": 2,
\"weight_unit\": \"lb\",
\"image_format\": \"png\",
\"usps\": {
\"mail_class\": \"Priority\",
\"shape\": \"Parcel\",
\"image_size\": \"4x6\",
\"services\": [
\"SignatureConfirmation\"
]
}
}" "https://api.myibservices.com/v1/labels"
The above command returns JSON structured like this:
{
"request_id" : "AQX90000000234",
"status" : "created",
"postmark_date":"2018-03-22T23:37:05-07:00",
"postage_amount" : 10.44,
"fees_amount" : 2.35,
"total_amount" : 12.79,
"usps": {
"tracking_numbers" : ["9210890188666700000058"],
"pricing" : "Commercial Plus",
"fees" : [{ "name" : "Signature Confirmation", "fee" : 2.35 }],
"zone": 1
},
"base64_labels" : ["iVBORw0KGgoAAAA..."]
}
HTTP Request
POST https://api.myibservices.com/v1/labels
Query Parameters
Parameter | Default | Description |
---|---|---|
request_id | (null/empty) | Request ID. Used by API developers to match requests and responses. Echoed back in the request_id tag of the response. |
metadata | (null/empty) | Metadata details like references and rubberstamps. See details here |
from_address | (required) | From shipping address. See details here. |
to_address | (required) | To shipping address. See details here. |
weight | (required) | Weight. |
weight_unit | (required) | Weight unit. One of oz, lb, g, kg. |
dimensions | (null/empty) | Dimensions. See details here. |
dimensions_unit | (required if dimensions provided) | Dimensions unit. One of in, ft, mm, cm, m. |
value | (null/empty) | Total package value. Required for most international (customs form) requests. |
non_delivery_option | Return | Non-delivery option. One of Abandon, Return. |
postmark_date | (UTC current date time) | UTC postmark date. Must be 30 days or less than the create date. |
image_format | (required) | Image format. One of png, pdf, svg, zpl, gif. |
image_resolution | 300 | Image resolution in DPI. One of 150, 203, 300, 600. |
page_width | (optional) | Pdf page width in inches. Available only for pdf. |
page_height | (optional) | Pdf page height in inches. Available only for pdf. |
left_margin | (optional) | Pdf page left margin in inches. Available only for pdf. |
top_margin | (optional) | Pdf page top margin in inches. Available only for pdf. |
customs_form | (null/empty) | Customs form for military (APO/FPO/DPO) and international shipping. See details here. |
usps | (null/empty) | USPS carrier data. See details here. |
gss | (null/empty) | GSS program data. See details here. |
ups | (null/empty) | UPS carrier data. See details here. |
fedex | (null/empty) | FedEx carrier data. See details here. |
metadata Query Parameters
Parameter | Default | Description |
---|---|---|
rubberstamp1 | (null/empty) | User defined rubberstamp. Prints at different locations depending on the label type and size. |
rubberstamp2 | (null/empty) | User defined rubberstamp. Prints at different locations depending on the label type and size. |
rubberstamp3 | (null/empty) | User defined rubberstamp. Prints at different locations depending on the label type and size. |
reference1 | (null/empty) | User defined reference. Becomes searchable field. |
reference2 | (null/empty) | User defined reference. Becomes searchable field. |
reference3 | (null/empty) | User defined reference. Becomes searchable field. |
address Query Parameters
Parameter | Default | Description |
---|---|---|
company_name | (conditional) | Company name. Required when first name and last name are not provided. |
first_name | (conditional) | First name. Required when company name is not provided. |
middle_name | (null/empty) | Middle name. |
last_name | (conditional) | Last name. Required when company name is not provided. |
phone_number | (null/empty) | Phone number. |
(null/empty) | Email. | |
sms | (null/empty) | Sms phone number. |
line1 | (required) | Address line 1. |
line2 | (null/empty) | Address line 2. |
line3 | (null/empty) | Address line 3. |
city | (conditional) | City. Required when postal code is not provided for domestic USPS labels. |
state_province | (conditional) | State/province. Required when postal code is not provided for domestic USPS labels. |
postal_code | (conditional) | Postal code. Zip code for USPS carrier. Required for USPS carrier. |
country_code | (required) | Iso country code. |
dimensions Query Parameters
Parameter | Default | Description |
---|---|---|
width | (required) | Width. |
length | (required) | Length. |
height | (required) | Height. |
usps Label Query Parameters
Parameter | Default | Description |
---|---|---|
mail_class | (required) | Mail class. One of Priority, Express, FirstClass, ParcelSelect, ParcelSelectLightweight, LibraryMail, MediaMail, BoundPrintedMatter, FirstClassInternational, PriorityInternational, PriorityExpressInternational. |
shape | (required) | One of Parcel, Flat, FlatRateEnvelope, LegalFlatRateEnvelope, PaddedFlatRateEnvelope, SmallFlatRateBox, MediumFlatRateBox, LargeFlatRateBox, RegionalRateBoxA, RegionalRateBoxB. The following shapes are valid only for PMOD: Sack, FullTrayBox, HalfTrayBox, FlatTubBox, ExtendedManagedMail (aka EMMTray) |
services | (null) | Services. If this field is present, it cannot be empty. One of OpenAndDistribute, Fragile, Perishable, LiveAnimal, HazMat, CrematedRemains, Certified, Restricted, Adult, COD, SignatureConfirmation, Insurance, Registered, ReturnReceipt, ReturnReceiptElectronic, ReturnReceiptMerchandise, HoldForPickup. |
image_size | 4x6 | Image size. One of 4x6, 6x4. |
po_zip_code | (see Description) | Induction zip code. If not provided, it defaults to the mailpiece from address postal code. |
presort_level | (conditional) | Presort level. If this field is present, it cannot be empty. Required for Library Mail, Media Mail, Parcel Select Destination Entry and Parcel Select Lightweight. One of None, 5-Digit, 3-Digit, SCF, NDC, MixedNDC, DDU, Basic. |
entry_facility | (conditional) | Entry facility. If this field is present, it cannot be empty. Required for Parcel Select Destination Entry and Parcel Select Lightweight. One of None, DNDC, DSCF, DDU. |
softpack | (conditional) | Boolean softpack indicator. Applies ONLY to Priority Mail cubic. |
open_and_distribute | (conditional) | Required when services includes OpenAndDistribute. See details here. |
USPS open_and_distribute Query Parameters
The Open and Distribute (PMOD) service is a special feature of Priority Mail. The first address line of a PMOD label must adhere to specifications found in Postal Bulletin 22507. Use the API's company_name field of the To-Address to specify this line.
For example, an SCF-destined PMOD container address format will start with "SCF" followed by the destination city, state, followed by the facility's NASS (National Air and Surface System) code. An example would be "SCF Royal Palm FL 330PM", where the "330PM" is the NASS code. A similar construct is used for NDC, ASF, and ADC PMOD labels.
For DDU-destined PMOD labels, the first line will be of the form "DDU" followed by city and state.
You must provide the full address of each facility, although for SCF, NDC, ASF and ADC labels only the first line will actually be printed on the label. DDU labels will have the complete address printed -- including street address and city, state, zip.
For more information, consult https://fast.usps.com/fast
Parameter | Default | Description |
---|---|---|
enclosed_mail_class | (required) | Enclosed mail class. One of MixedMail, PriorityMail, ParcelSelectMail, ParcelSelectLightweightMail, LibraryMail, MediaMail, BoundPrintedMatterMail, RetailGround, MarketingMail, ParcelReturnServiceMail, MatterForTheBlindMail, Periodicals. |
enclosed_shape | (required) | Enclosed mailpiece shape. One of Parcels, Letters, Flats. |
facility_type | (required) | Destination processing facility type. One of SCF, DDU, ADC, ASF, NDC. |
gss Label Query Parameters
Parameter | Default | Description |
---|---|---|
mail_class | (required) | Mail class. One of ePacket, PriorityInternational, PriorityExpressInternational, FirstClassInternational, InternationalPriorityAirmail, InternationalSurfaceAirLift. |
location_id | (required) | The location ID as provided by the GSS program. |
ups Label Query Parameters
Parameter | Default | Description |
---|---|---|
service | (required) | Service. One of 2Day, 2DayAM, ExpressSaver, Ground, GroundHomeDelivery, FirstOvernight, InternationalEconomy, InternationalFirst, InternationalPriority, PriorityOvernight, StandardOvernight. |
packaging_type | (required) | Packaging Type. One of Box, Envelope, Pak, Tube, Custom. |
dropoff_type | (required) | Dropoff Type. One of RegularPickup, RequestCourier, DropBox, BusinessServiceCenter, Station. |
cod_special_service | (null/empty) | COD special service. See details here. |
signature_special_service | (null/empty) | Signature special service. See details here. |
fedex Label Query Parameters
Parameter | Default | Description |
---|---|---|
service | (required) | Service. One of NextDayAir, 2ndDayAir, Ground, 3DaySelect, NextDayAirSaver, NextDayAirEarly, 2ndDayAirAM, WorldwideExpress, WorldwideExpedited, Standard, WorldwideExpressPlus, Saver. |
packaging_type | (required) | Packaging Type. One of Letter, Package, Tube, Pak, SmallExpressBox, MediumExpressBox, LargeExpressBox. |
cod_package_option | (null/empty) | COD package options. See details here. |
delcon_package_option | (null/empty) | Delivery Confirmation package options. See details here. |
customs_form Query Parameters
Parameter | Default | Description |
---|---|---|
contents_type | (required) | Contents type. One of "Documents", "Gift", "Merchandise", "ReturnedGoods", "Sample", "HumanitarianDonation", "DangerousGoods", "Other". |
restriction_type | (null/empty) | Restriction type. One of "Quarantine", "SanitaryInspection", "PhytosanitaryInspection", "Other", "None". |
restriction_comments | (null/empty) | Restriction comments. |
senders_customs_reference | (null/empty) | Sender's customs reference. |
importers_customs_reference | (null/empty) | Importer's customs reference. |
importers_customs_reference_type | (null/empty) | Importer's customs reference type. One of "TaxCode", "VATNumber", "ImporterCode". |
license_number | (null/empty) | License number. |
certificate_number | (null/empty) | Certificate number. |
invoice_number | (null/empty) | Invoice number. |
customs_signator | (required) | First and last name of person responsible for shipment. |
importers_contact | (null/empty) | Importer's contact phone number. |
pfc_itn | (null/empty) | Proof of filing citation ITN number. |
insured_number | (null/empty) | Insured reference number. |
customs_items | (required) | Customs items collection. See details here. |
customs_item Query Parameters
Parameter | Default | Description |
---|---|---|
description | (required) | Description. |
quantity | (required) | Quantity. |
weight | (required) | Weight. |
weight_unit | (required) | Weight unit. One of oz, lb, g, kg. |
value | (required) | Value. |
hs_tariff_number | (null/empty) | HTS code. |
origin_country_code | US | Origin iso country code. |
UPS cod_package_option Query Parameters
Parameter | Default | Description |
---|---|---|
type | (required) | Type. One of Cash, MoneyOrder, Check. |
value | (required) | Value. |
UPS delcon_package_option Query Parameters
Parameter | Default | Description |
---|---|---|
type | (required) | Type. One of Regular, SignatureRequired, AdultSignatureRequired. |
FedEx cod_special_service Query Parameters
Parameter | Default | Description |
---|---|---|
value | (required) | Value. |
type | (required) | Type. One of Any, Cash, CompanyCheck, GuaranteedFunds, PersonalCheck. |
FedEx signature_special_service Query Parameters
Parameter | Default | Description |
---|---|---|
type | (required) | Type. One of Adult, Direct, Indirect, NoSignatureRequired, ServiceDefault. |
Update a Shipping Label
Only certain mailpiece properties can be updated (e.g. postmark date, weight and dimensions). The properties that cannot change will remain the same as in the intial request (e.g. mail class). A label cannot be updated after it was manifested or refunded (must be in created status). The new price could be higher or lower than the initial price. For Metered accounts, we will increase/decrease the account balance based on the difference. For Invoiced accounts, we will adjust for the price difference in the next invoice. eVS accounts will not experience any price changes since USPS billing is done at manifest time.
curl -u user@email.com:password -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"postmark_date\" : \"2019-08-01T00:00:00+00:00\",
\"weight\": 1,
\"weight_unit\": "lb",
\"dimensions\" : { \"length\" : 5, \"height\" : 5, \"width\" : 5 },
\"dimensions_unit\" : \"in\"
}" "https://api.myibservices.com/v1/labels/9210890188666700000058"
The above command returns JSON structured like this:
{
"request_id" : "AQX90000000234",
"status" : "created",
"postmark_date":"2019-08-01T00:00:00+00:00",
"postage_amount" : 27.28,
"fees_amount" : 2.35,
"total_amount" : 12.79,
"usps": {
"tracking_numbers" : ["9210890188666700000058"],
"pricing" : "Commercial Plus",
"fees" : [{ "name" : "Signature Confirmation", "fee" : 2.35 }],
"zone": 1
},
"base64_labels" : ["iVBORw0KGgoAAAA..."]
}
HTTP Request
PUT https://api.myibservices.com/v1/labels/[tracking_number]
Query Parameters
Parameter | Default | Description |
---|---|---|
tracking_number | (required) | Tracking number. |
postmark_date | (optional) | UTC postmark date. Must be 30 days or less than the create date. |
weight | (optional) | Weight. |
weight_unit | (optional) | Weight unit. One of oz, lb, g, kg. |
dimensions | (optional) | Dimensions. |
dimensions_unit | (required if dimensions provided) | Dimensions unit. One of in, ft, mm, cm, m. |
Get (Reprint) a Shipping Label
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/labels/9210890188666700000058"
The above command returns JSON structured like this:
{
"request_id" : "AQX90000000234",
"status" : "created",
"postmark_date":"2018-03-22T23:37:05-07:00",
"postage_amount" : 10.44,
"fees_amount" : 2.35,
"total_amount" : 12.79,
"usps": {
"tracking_numbers" : ["9210890188666700000058"],
"pricing" : "Commercial Plus",
"fees" : [{ "name" : "Signature Confirmation", "fee" : 2.35 }],
"zone": 1
},
"base64_labels" : ["iVBORw0KGgoAAAA..."]
}
HTTP Request
GET https://api.myibservices.com/v1/labels/[tracking_number]
Query Parameters
Parameter | Default | Description |
---|---|---|
tracking_number | (required) | Tracking number. |
Delete (Void) a Shipping Label
curl -u user@email.com:password -X DELETE --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/labels/9210890188666700000058"
The above command does not return any JSON.
HTTP Request
DELETE https://api.myibservices.com/v1/labels/[tracking_number]
Query Parameters
Parameter | Default | Description |
---|---|---|
tracking_number | (required) | Tracking number. |
Get Shipping Labels
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/labels?start_date=2018-03-21T00:00:00-07:00&end_date=2018-03-23T00:00:00-07:00"
The above command returns JSON structured like this:
[
{
"request_id" : "AQX90000000234",
"status" : "created",
"postmark_date":"2018-03-22T23:37:05-07:00",
"postage_amount" : 10.44,
"fees_amount" : 2.35,
"total_amount" : 12.79,
"usps": {
"tracking_numbers" : ["9210890188666700000058"],
"pricing" : "Commercial Plus",
"fees" : [{ "name" : "Signature Confirmation", "fee" : 2.35 }],
"zone": 1
}
},
{
"request_id": null,
"status" : "voided",
"postmark_date":"2018-03-22T23:37:05-07:00",
"postage_amount": 5.6,
"fees_amount": 0,
"total_amount": 5.6,
"usps": {
"tracking_numbers": ["9205590188666700000406"],
"pricing": "Commercial Plus",
"fees": [{ "name": "USPS Tracking", "fee": 0 }],
"zone": 2
}
}
]
HTTP Request
GET https://api.myibservices.com/v1/labels?start_date=[start_date]&end_date=[end_date]
Query Parameters
Parameter | Default | Description |
---|---|---|
start_date | (conditional) | Start date. UTC format. Mutually exclusive with request_id and status. |
end_date | (conditional) | End date. UTC format. Mutually exclusive with request_id and status. |
request_id | (conditional) | Request ID (used when creating the label). Mutually exclusive with date range and status. |
status | (conditional) | Label status. Mutually exclusive with date range and request_id. |
page_size | 25 | Page size. |
page_number | 1 | Page number. |
Pagination Response Headers
Header | Example | Description |
---|---|---|
current-page | 1 | Current page of data in the response body. |
page-count | 1 | Total pages count. |
page-size | 25 | Page size. Items per page. |
total-count-of-items | 2 | Total items count. |
Price
Calculate Shipping Price
curl -u user@email.com:password -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"request_id\": \"PRIC920021-3AC\",
\"from_address\": {
\"first_name\": \"John\",
\"last_name\": \"Michaels\",
\"line1\": \"247 High St\",
\"city\": \"Palo Alto\",
\"state_province\": \"CA\",
\"postal_code\": \"94301\",
\"country_code\": \"US\"
},
\"to_address\": {
\"first_name\": \"Ted\",
\"last_name\": \"Resnick\",
\"line1\": \"350 5th Ave\",
\"line2\": \"Suite 7510\",
\"city\": \"New York\",
\"state_province\": \"NY\",
\"postal_code\": \"10118\",
\"country_code\": \"US\"
},
\"weight\": 2,
\"weight_unit\": \"lb\",
\"usps\": {
\"mail_class\": \"Priority\",
\"shape\": \"Parcel\",
\"services\": [
\"SignatureConfirmation\"
]
}
}" "https://api.myibservices.com/v1/price"
The above command returns JSON structured like this:
{
"request_id" : "PRIC920021-3AC",
"postage_amount" : 10.44,
"fees_amount" : 2.35,
"total_amount" : 12.79,
"usps": {
"pricing" : "Commercial Plus",
"fees" : [{ "name" : "Signature Confirmation", "fee" : 2.35 }]
}
}
HTTP Request
POST https://api.myibservices.com/v1/price
Query Parameters
Parameter | Default | Description |
---|---|---|
request_id | (null/empty) | Request ID. Used by API developers to match requests and responses. Echoed back in the request_id tag of the response. |
from_address | (required) | From shipping address. See details here. |
to_address | (required) | To shipping address. See details here. |
weight | (required) | Weight. |
weight_unit | (required) | Weight unit. One of oz, lb, g, kg. |
dimensions | (null/empty) | Dimensions. See details here. |
dimensions_unit | (required if dimensions provided) | Dimensions unit. One of in, ft, mm, cm, m. |
value | (null/empty) | Total package value. Required for most international (customs form) requests. |
non_delivery_option | Return | Non delivery option. One of Abandon, Return. |
postmark_date | (UTC current date time) | UTC postmark date. |
customs_form | (null/empty) | Customs form for military (APO/FPO/DPO) and international shipping. See details here. |
usps | (null/empty) | USPS carrier data. See details here. |
gss | (null/empty) | GSS program data. See details here. |
ups | (null/empty) | UPS carrier data. See details here. |
USPS Price Query Parameters
Parameter | Default | Description |
---|---|---|
mail_class | (required) | Mail class. One of Priority, Express, FirstClass, ParcelSelect, ParcelSelectLightweight, LibraryMail, MediaMail, BoundPrintedMatter, FirstClassInternational, PriorityInternational, PriorityExpressInternational. |
shape | (required) | One of Parcel, Flat, FlatRateEnvelope, LegalFlatRateEnvelope, PaddedFlatRateEnvelope, SmallFlatRateBox, MediumFlatRateBox, LargeFlatRateBox, RegionalRateBoxA, RegionalRateBoxB. Envelope, PaddedFlatRateEnvelope, SmallFlatRateBox, MediumFlatRateBox, LargeFlatRateBox, RegionalRateBoxA, RegionalRateBoxB. The following shapes are valid only for PMOD: Sack, FullTrayBox, HalfTrayBox, FlatTubBox, ExtendedManagedMail (aka EMMTray) |
pricing | (null/empty) | One of Retail, CommercialBase, CommercialPlus, Custom. Defaults to the least expensive. |
services | (null/empty) | Services. One of OpenAndDistribute, Fragile, Perishable, LiveAnimal, HazMat, CrematedRemains, Certified, Restricted, Adult, COD, SignatureConfirmation, Insurance, Registered, ReturnReceipt, ReturnReceiptElectronic, ReturnReceiptMerchandise, HoldForPickup. |
po_zip_code | (see Description) | Induction zip code. If not provided, it defaults to the mailpiece from address postal code. |
presort_level | (conditional) | Presort level. Required for Library Mail, Media Mail, Parcel Select Destination Entry and Parcel Select Lightweight. One of None, 5-Digit, 3-Digit, SCF, NDC, MixedNDC, DDU, Basic. |
entry_facility | (conditional) | Entry facility. Required for Parcel Select Destination Entry and Parcel Select Lightweight. One of None, DNDC, DSCF, DDU. |
softpack | (conditional) | Boolean softpack indicator. Applies to cubic. |
GSS Price Query Parameters
Parameter | Default | Description |
---|---|---|
mail_class | (required) | Mail class. One of ePacket, PriorityInternational, PriorityExpressInternational, FirstClassInternational, InternationalPriorityAirmail, InternationalSurfaceAirLift. |
location_id | (required) | The location ID as provided by the GSS program. |
UPS Price Query Parameters
Parameter | Default | Description |
---|---|---|
service | (required) | Service. One of NextDayAir, 2ndDayAir, Ground, 3DaySelect, NextDayAirSaver, NextDayAirEarly, 2ndDayAirAM, WorldwideExpress, WorldwideExpedited, ExpressStandard, WorldwideExpressPlus, WorldwideSaver. |
packaging_type | (required) | Packaging Type. One of Letter, Package, Tube, Pak, SmallExpressBox, MediumExpressBox, LargeExpressBox. |
cod_package_option | (null/empty) | COD package options. See details here. |
delcon_package_option | (null/empty) | Delivery Confirmation package options. See details here. |
Manifests
Create a Manifest
curl -u user@email.com:password -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"request_id\": \"MANX000000000C1\",
\"image_format\": \"png\",
\"image_resolution\" : 300,
\"usps\": { }
}" "https://api.myibservices.com/v1/manifests"
The above command returns JSON structured like this:
{
"request_id" : "MANX000000000C1",
"usps" : [
{
"manifest_number" : "9275090188665400000024",
"priority_count" : 1,
"express_count" : 0,
"pmi_count" : 0,
"emi_count" : 0,
"gxg_count" : 0,
"other_count" : 0,
"base64_manifest" : "iVBORw0KGgoAAA..."
},
]
}
HTTP Request
POST https://api.myibservices.com/v1/manifests
Query Parameters
Parameter | Default | Description |
---|---|---|
request_id | (null/empty) | Request ID. Used by API developers to match requests and responses. Echoed back in the request_id tag of the response. |
image_format | (required) | Image format. One of png, pdf, svg, zpl. |
image_resolution | 300 | Image resolution in DPI. One of 150, 203, 300, 600. |
usps | (null/empty) | USPS carrier data. See details here. |
USPS Manifest Query Parameters
Parameter | Default | Description |
---|---|---|
induction_address | (null/empty) | Induction address. Defaults to the user's account address. See details here. |
tracking_numbers | (null/empty) | Tracking numbers collection to be included in this manifest. If omitted, all tracking numbers not included in the previous manifest are returned. |
USPS Contact Address Query Parameters
Parameter | Default | Description |
---|---|---|
company_name | (conditional) | Company name. Required when first name and last name are not provided. |
first_name | (conditional) | First name. Required when company name is not provided. |
middle_name | (null/empty) | Middle name. |
last_name | (conditional) | Last name. Required when company name is not provided. |
phone_number | (null/empty) | Phone number. |
(null/empty) | Email. | |
sms | (null/empty) | Sms phone number. |
line1 | (required) | Address line 1. |
line2 | (null/empty) | Address line 2. |
line3 | (null/empty) | Address line 3. |
city | (required) | City. |
state_province | (conditional) | State/province. Required for USPS carrier. |
postal_code | (conditional) | Postal code. Zip code for USPS carrier. Required for USPS carrier. |
country_code | (required) | Iso country code. |
Get (Reprint) a Manifest
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/manifests/9275090188665400000024"
The above command returns JSON structured like this:
{
"request_id" : "MANX000000000C1",
"usps" :
{
"manifest_number" : "9275090188665400000024",
"priority_count" : 1,
"express_count" : 0,
"pmi_count" : 0,
"emi_count" : 0,
"gxg_count" : 0,
"other_count" : 0,
"base64_manifest" : "iVBORw0KGgoAAA..."
}
}
HTTP Request
GET https://api.myibservices.com/v1/manifests/[manifest_number]
Query Parameters
Parameter | Default | Description |
---|---|---|
manifest_number | (required) | Manifest number. |
Get Manifests
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/manifests?start_date=2018-03-21T00:00:00-07:00&end_date=2018-03-21T00:00:00-07:00"
The above command returns JSON structured like this:
[
{
"usps": [
{
"manifest_number": "9275090188665400000017",
"priority_count": 42,
"express_count": 1,
"pmi_count": 0,
"emi_count": 0,
"gxg_count": 0,
"other_count": 0
}
]
},
{
"usps": [
{
"manifest_number": "9275090188665400000024",
"priority_count": 1,
"express_count": 0,
"pmi_count": 0,
"emi_count": 0,
"gxg_count": 0,
"other_count": 0
}
]
}
]
HTTP Request
GET https://api.myibservices.com/v1/manifests?start_date=[start_date]&end_date=[end_date]
Query Parameters
Parameter | Default | Description |
---|---|---|
start_date | (conditional) | Start date. UTC format. Mutually exclusive with request_id and status. |
end_date | (conditional) | End date. UTC format. Mutually exclusive with request_id and status. |
request_id | (conditional) | Request ID (used when creating the label). Mutually exclusive with date range and status. |
status | (conditional) | Label status. Mutually exclusive with date range and request_id. |
page_size | 25 | Page size. |
page_number | 1 | Page number. |
Pagination Response Headers
Header | Example | Description |
---|---|---|
current-page | 1 | Current page of data in the response body. |
page-count | 1 | Total pages count. |
page-size | 25 | Page size. Items per page. |
total-count-of-items | 2 | Total items count. |
Tracking
Get tracking events
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/track/9210890188666700000058"
The above command returns JSON structured like this:
[
{
"status": "Delivered, In/At Mailbox",
"location": {
"city": "SANTA MONICA",
"state": "CA",
"zip": "90401",
"country": "USA"
},
"timestamp": "2019-06-26T11:30:00.000"
},
{
"status": "Out for Delivery",
"location": {
"city": "SANTA MONICA",
"state": "CA",
"zip": "90401",
"country": "USA"
},
"timestamp": "2019-06-26T09:27:00.000"
},
{
"status": "Arrived at Post Office",
"location": {
"city": "SANTA MONICA",
"state": "CA",
"zip": "90401",
"country": "USA"
},
"timestamp": "2019-06-26T08:02:00.000"
},
...
]
HTTP Request
GET https://api.myibservices.com/v1/track/[tracking_number]
Query Parameters
Parameter | Default | Description |
---|---|---|
tracking_number | (required) | Tracking number. |
USPS Services
Get USPS Services
curl -u user@email.com:password -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"request_id\": \"SVCXXC009282111\",
\"mail_class\": \"Priority\",
\"services\" : [\"COD\"]
}" "https://api.myibservices.com/v1/usps_services"
The above command returns JSON structured like this:
{
"request_id" : "SVCXXC009282111",
"services" : ["COD", "ReturnReceipt", "ReturnReceiptElectronic", "Restricted", "SignatureConfirmation"]
}
HTTP Request
POST https://api.myibservices.com/v1/usps_services
Query Parameters
Parameter | Default | Description |
---|---|---|
request_id | (null/empty) | Request ID. Used by API developers to match requests and responses. Echoed back in the request_id tag of the response. |
mail_class | (required) | Mail class. One of Priority, Express, FirstClass, ParcelSelect, ParcelSelectLightweight, LibraryMail, MediaMail, BoundPrintedMatter, FirstClassInternational, PriorityInternational, PriorityExpressInternational. |
services | (null/empty) | Services. One of OpenAndDistribute, Fragile, Perishable, LiveAnimal, HazMat, CrematedRemains, Certified, Restricted, Adult, COD, SignatureConfirmation, Insurance, Registered, ReturnReceipt, ReturnReceiptElectronic, ReturnReceiptMerchandise, HoldForPickup. |
value | 0 | Package insured value. |
waive_signature | true | Waive signature flag. Used for Express Mail. |
country_code | (null/empty) | Iso country code. Required for international mail classes. |
Address
Currently, only US addresses can be validated (country_code must be set to 'US').
Validation
curl -u user@email.com:password -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"line1\" : \"247 High St\",
\"city\" : \"Palo X\",
\"state_province\" : \"CA\",
\"postal_code\" : \"94301\",
\"country_code\": \"US\"
}" "https://api.myibservices.com/v1/address/validate"
The above command returns JSON structured like this:
{
"line1" : "247 HIGH ST",
"line2" : "",
"line3" : "",
"last_line" : "PALO ALTO CA 94301-1041",
"city" : "PALO ALTO",
"state_province" : "CA",
"zip5" : "94301",
"zip4" : "1041",
"dpbc" : "476",
"record_type" : "S",
"rdi" : "B",
"dpv" : "AABB",
"dpv_comment" : " ",
"carrier_route" : "C001",
"address_exists" : " "
}
HTTP Request
POST https://api.myibservices.com/v1/address/validate
Query Parameters
Parameter | Default | Description |
---|---|---|
company_name | (null/empty) | Company name. |
line1 | (required) | Address line 1. |
line2 | (null/empty) | Address line 2. |
line3 | (null/empty) | Address line 3. |
city | (null/empty) | City. |
state_province | (null/empty) | State/province. |
postal_code | (null/empty) | Postal code. |
country_code | (required) | Iso country code. |
Resolve Multiple
curl -u user@email.com:password -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"line1\" : \"525 University Ave\",
\"city\" : \"Palo Alto\",
\"state_province\" : \"CA\",
\"postal_code\" : \"94301\"
}" "https://api.myibservices.com/v1/address/resolve_multiple"
The above command returns JSON structured like this:
[
{
"primary_high" : "0000000525",
"primary_low" : "0000000525",
"secondary_high" : "A70",
"secondary_low" : "A70",
"secondary_name" : "",
"street_name" : "UNIVERSITY",
"pre_direction" : "",
"post_direction" : "",
"suffix" : "AVE",
"zip_code" : "94301",
"addon_low" : "1924",
"addon_high" : "1924",
"unit" : "STE",
"record_type" : "H",
"state_abbreviation" : null,
"county_number" : "085",
"carrier_route" : "C011"
},
{
"primary_high" : "0000000525",
"primary_low" : "0000000525",
"secondary_high" : "A100",
"secondary_low" : "A100",
"secondary_name" : "",
"street_name" : "UNIVERSITY",
"pre_direction" : "",
"post_direction" : "",
"suffix" : "AVE",
"zip_code" : "94301",
"addon_low" : "1925",
"addon_high" : "1925",
"unit" : "STE",
"record_type" : "H",
"state_abbreviation" : null,
"county_number" : "085",
"carrier_route" : "C011"
},
{
"primary_high" : "0000000525",
"primary_low" : "0000000525",
...
},
...
]
HTTP Request
POST https://api.myibservices.com/v1/address/resolve_multiple
Query Parameters
Parameter | Default | Description |
---|---|---|
line1 | (required) | Address line 1. |
line2 | (null/empty) | Address line 2. |
line3 | (null/empty) | Address line 3. |
city | (null/empty) | City. |
state_province | (null/empty) | State/province. |
postal_code | (null/empty) | Postal code. |
Get City
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/address/city?zip5=94301"
The above command returns JSON structured like this:
{
"city" : "Palo Alto",
"state" : "CA"
}
HTTP Request
GET https://api.myibservices.com/v1/address/city?zip5=[zip5]
Query Parameters
Parameter | Default | Description |
---|---|---|
zip5 | (required) | Zip 5. |
Get Streets
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/address/streets?zip5=94301"
The above command returns JSON structured like this:
[
"ADDISON AVE",
"ALMA ST",
"ANTON CT",
"ASHBY DR",
"BOYCE AVE",
"BRYANT CT",
"BRYANT ST",
"BYRON ST",
...
]
HTTP Request
GET https://api.myibservices.com/v1/address/streets?zip5=[zip5]
Query Parameters
Parameter | Default | Description |
---|---|---|
zip5 | (required) | Zip 5. |
Get Possible Addresses
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/address/possible_addresses?zip5=94301&primary=247&street_name=H"
The above command returns JSON structured like this:
[
"247 HAMILTON AVE",
"247 HAMILTON CT",
"247 HIGH ST"
]
HTTP Request
GET https://api.myibservices.com/v1/address/possible_addresses?zip5=[zip5]&primary=[primary]&street_name=[street_name]
Query Parameters
Parameter | Default | Description |
---|---|---|
zip5 | (required) | Zip 5. |
primary | (required) | Primary street number. |
street_name | (null/empty) | Street name. Could be null, incomplete (e.g. "H") or full (e.g. "High") |
Payment Methods
Create a Payment Method
To create a payment method, please visit https://blue.myib.com. It is not available via API.
Delete a Payment Method
curl -u user@email.com:password -X DELETE --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/payment_methods/97d391d0-03ed-4d67-93c4-98c4543"
HTTP Request
DELETE https://api.myibservices.com/v1/payment_methods/[payment_method_id]
Get Payment Methods
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/payment_methods"
The above command returns JSON structured like this:
[
{
"id": "2d663c19-2a8f-44ad-b92c-4723a25843d3",
"type": "ACH",
"bank_name": "FEDERAL RESERVE BANK",
"routing_no": "011000015",
"bank_account_last_4": "0000",
"account_type": "checking",
"ownership_type": "personal",
"payment_method_status": {
"id": 1,
"name": "Active",
"description": "Active."
}
},
{
"id": "2f1000c5-ecac-4c77-876c-9431551a5f92",
"type": "ACH",
"bank_name": "FEDERAL RESERVE BANK",
"routing_no": "011000015",
"bank_account_last_4": "0001",
"account_type": "checking",
"ownership_type": "personal",
"payment_method_status": {
"id": 3,
"name": "PendingMicrotransactions",
"description": "Pending bank account verification by micro transactions."
}
},
{
"id": "00a2ab65-53cc-4a1e-8532-0527f0ac26c6",
"type": "CreditCard",
"credit_card_type": "Discover",
"credit_card_last_4": 1117,
"credit_card_exp_month": 10,
"credit_card_exp_year": 2019,
"default": true,
"autofill": true,
"autofill_limit": 100,
"payment_method_status": {
"id": 1,
"name": "Active",
"description": "Active."
}
}
]
HTTP Request
GET https://api.myibservices.com/v1/payment_methods
Query Parameters
Parameter | Default | Description |
---|---|---|
page_size | 25 | Page size. |
page_number | 1 | Page number. |
Pagination Response Headers
Header | Example | Description |
---|---|---|
current-page | 1 | Current page of data in the response body. |
page-count | 1 | Total pages count. |
page-size | 25 | Page size. Items per page. |
total-count-of-items | 2 | Total items count. |
Payment Transactions
Buy
Add funds to your account balance by calling buy
on a payment method.
curl -u user@email.com:password -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"transaction_amount\" : 100
}" "https://api.myibservices.com/v1/payment_transactions/97d391d0-03ed-4d67-93c4-98c45439eadd/buy"
The above command returns JSON structured like this:
{
"id": "6493b8c1-5593-4631-b781-2321ea7c256b",
"amount": 100,
"status": "approved",
"completed": true,
"payment_method_id": "97d391d0-03ed-4d67-93c4-98c45439eadd",
"user_id": "880c7358-0223-438a-ab4e-815903d7d3a3",
"created_at": "2019-04-26T03:44:45.403-07:00",
"updated_at": "2019-04-26T03:44:46.318-07:00",
"processed_at": null,
"external_id": "k1z2et3f"
}
HTTP Request
POST https://api.myibservices.com/v1/payment_transactions/[payment_method_id]/buy
Query Parameters
Parameter | Default | Description |
---|---|---|
transaction_amount | (required) | Amount that will be charged from the payment method. When the transaction is approved your account balance will be increased by the amount. |
Get Payment Transactions
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/payment_transactions"
The above command returns JSON structured like this:
[
{
"id": "5b72442d-f72b-49f0-a8ad-0ad30469930b",
"amount": 20,
"completed": true,
"type": "BraintreeCreditCardPaymentTransaction",
"processed_at": "2018-10-30T08:14:55.674-07:00",
"comment": null,
"payment_method": {
"id": "844b1769-480a-4d64-a9e1-7a2d2cfa57f7",
"type": "CreditCard",
"credit_card_type": "Visa",
"credit_card_last_4": 3199,
"credit_card_exp_month": 7,
"credit_card_exp_year": 2022,
"default": true,
"autofill": true,
"autofill_limit": 10
}
},
...
]
HTTP Request
GET https://api.myibservices.com/v1/payment_transactions
Query Parameters
Parameter | Default | Description |
---|---|---|
page_size | 25 | Page size. |
page_number | 1 | Page number. |
Pagination Response Headers
Header | Example | Description |
---|---|---|
current-page | 1 | Current page of data in the response body. |
page-count | 1 | Total pages count. |
page-size | 25 | Page size. Items per page. |
total-count-of-items | 2 | Total items count. |
Pickups
Create (Schedule) a Pickup
Schedules a package pickup and provides the user a confirmation number for the scheduled pickup. Your carrier will pick up your packages on the next USPS delivery day (Monday through Saturday, excluding holidays) for free. There must be at least one Priority Mail Express package or one Priority Mail package or one international package or one returned merchandise package for a valid request.
curl -u user@email.com:password -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"pickup\": {
\"address\": {
\"first_name\": \"John\",
\"last_name\": \"Doe\",
\"line1\": \"247 High St\",
\"city\": \"Palo Alto\",
\"state_province\": \"CA\",
\"postal_code\": \"94301\",
\"email\": \"user@example.com\",
\"phone_number\": \"6503951916\"
\"country_code\": \"US\"
},
\"package_location\": \"Front Door\",
\"special_instructions\": \"Packages are behind the screen door\",
\"weight\": 3,
\"weight_unit\": \"lb\",
\"usps\": {
\"package_data\": [
{
\"mail_class\": \"Express\",
\"package_count\": 3
},
{
\"mail_class\": \"Priority\",
\"package_count\": 2
}
]
}
}
}" "https://api.myibservices.com/v1/pickups"
The above command returns JSON structured like this:
{
"id": "59bdc43c-ed18-4539-9bd7-77de802747b3",
"weight": 3.0,
"weight_unit": "lb",
"package_location": "Front Door",
"special_instructions": "Packages are behind the screen door",
"usps": {
"package_data": [
{
"mail_class": "Express",
"package_count": 3
},
{
"mail_class": "Priority",
"package_count": 2
}
],
"confirmation_number": "WTC271310058",
"pickup_date": "2019-06-20",
"carrier_route": "C001"
},
"address": {
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"company_name": null,
"line1": "247 High St",
"line2": null,
"line3": null,
"city": "Palo Alto",
"state_province": "CA",
"postal_code": "94301",
"email": "user@example.com",
"phone_number": "6503951916",
"iso_country_code": "US"
}
}
HTTP Request
POST https://api.myibservices.com/v1/pickups
Query Parameters
Parameter | Default | Description |
---|---|---|
address | (required) | Pickup address. See details here. |
package_location | (required) | Package location. One of "Front Door", "Back Door", "Side Door", "Knock on Door/Ring Bell", "Mail Room", "Office", "Reception", "In/At Mailbox", "Other". |
special_instructions | (null/empty/required) | Required when package_location is "Other". |
weight | (required) | Estimated aggregate weight of all packages being picked up. |
weight_unit | (required) | Weight unit. One of oz, lb, g, kg. |
usps | (required) | USPS carrier data. See details here. |
address Pickup Query Parameters
Parameter | Default | Description |
---|---|---|
company_name | (conditional) | Company name. Required when first name and last name are not provided. |
first_name | (conditional) | First name. Required when company name is not provided. |
middle_name | (null/empty) | Middle name. |
last_name | (conditional) | Last name. Required when company name is not provided. |
phone_number | (null/empty/required) | Phone number. Either phone_number or sms is required. |
(null/empty) | Email. | |
sms | (null/empty/required) | Sms phone number. Either sms or phone_number is required. |
line1 | (required) | Address line 1. |
line2 | (null/empty) | Address line 2. |
line3 | (null/empty) | Address line 3. |
city | (required) | City. |
state_province | (required) | State/province. |
postal_code | (required) | Zip code for USPS carrier. |
country_code | (required) | Iso country code. Only 'US' is supported. |
usps Pickup Query Parameters
Parameter | Default | Description |
---|---|---|
package_data | (required) | Package collection. See details here |
package_data Pickup Query Parameters
Parameter | Default | Description |
---|---|---|
mail_class | (required) | Mail class. One of Priority, Express, FirstClass, ParcelSelect, ParcelSelectLightweight, LibraryMail, MediaMail, BoundPrintedMatter, FirstClassInternational, PriorityInternational, PriorityExpressInternational. |
package_count | (required) | The number of packages for the accompanying mail_class . |
Get a Pickup
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/pickups/[id]"
The above command returns JSON structured like this:
{
"id": "59bdc43c-ed18-4539-9bd7-77de802747b3",
"weight": 3.0,
"weight_unit": "lb",
"package_location": "Front Door",
"special_instructions": "Packages are behind the screen door",
"usps": {
"package_data": [
{
"mail_class": "Express",
"package_count": 3
},
{
"mail_class": "Priority",
"package_count": 2
}
],
"confirmation_number": "WTC271310058",
"pickup_date": "2019-06-20",
"carrier_route": "C001"
},
"address": {
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"company_name": null,
"line1": "247 High St",
"line2": null,
"line3": null,
"city": "Palo Alto",
"state_province": "CA",
"postal_code": "94301",
"email": "user@example.com",
"phone_number": "6503951916",
"iso_country_code": "US"
}
}
HTTP Request
GET https://api.myibservices.com/v1/pickups/[id]
Query Parameters
Parameter | Default | Description |
---|---|---|
id | (required) | Pickup ID which was returned by the POST method. |
Delete (Cancel) a Pickup
curl -u user@email.com:password -X DELETE --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/pickups/[id]"
The above command does not return any JSON.
HTTP Request
DELETE https://api.myibservices.com/v1/pickups/[id]
Query Parameters
Parameter | Default | Description |
---|---|---|
id | (required) | Pickup ID which was returned by the POST method. |
Get Pickups
curl -u user@email.com:password -X GET --header "Content-Type: application/json" --header "Accept: application/json" "https://api.myibservices.com/v1/pickups"
The above command returns JSON structured like this:
[
{
"id": "34b0fe0f-79e9-404d-badf-e0e039f974e4",
"weight": 1.5,
"weight_unit": "lb",
"package_location": "Side Door",
"special_instructions": "",
"usps": {
"package_data": [
{
"mail_class": "Priority",
"package_count": 1
},
{
"mail_class": "Express",
"package_count": 1
}
],
"confirmation_number": "WTC59250868",
"pickup_date": "2019-07-16",
"carrier_route": "C001"
},
"address": {
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"company_name": null,
"line1": "247 High St",
"line2": null,
"line3": null,
"city": "PALO ALTO",
"state_province": "CA",
"postal_code": "94301",
"phone_number": "8641234567",
"email": "example@myib.com",
"sms": null,
"iso_country_code": "US"
}
},
{
"id": "b4344432-6c9c-4e2f-9f14-8cec1e80298d",
"weight": 40.0,
"weight_unit": "lb",
"package_location": "Other Door",
"special_instructions": "Packages are behind the screen door.",
"usps": {
"package_data": [
{
"mail_class": "Priority",
"package_count": 1
},
{
"mail_class": "FirstClass",
"package_count": 20
}
],
"confirmation_number": "WTC59250826",
"pickup_date": "2019-07-16",
"carrier_route": "C001"
},
"address": {
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"company_name": null,
"line1": "247 High St",
"line2": null,
"line3": null,
"city": "PALO ALTO",
"state_province": "CA",
"postal_code": "94301",
"phone_number": "8641234567",
"email": "example@myib.com",
"sms": null,
"iso_country_code": "US"
}
}
]
HTTP Request
GET https://api.myibservices.com/v1/pickups?page_size=[page_size]&page_number=[page_number]
Query Parameters
Parameter | Default | Description |
---|---|---|
page_size | 25 | Page size. |
page_number | 1 | Page number. |
Pagination Response Headers
Header | Example | Description |
---|---|---|
current-page | 1 | Current page of data in the response body. |
page-count | 1 | Total pages count. |
page-size | 25 | Page size. Items per page. |
total-count-of-items | 2 | Total items count. |
Label Statuses
Status | Post action |
---|---|
created | Label created by user |
manifested | Manifest requested by user (or automatically right before the postmark date) |
refund_requested | Label refund (delete) requested by user (meter refunds not yet approved) |
refund_approved | IB determined labels wasn't used (to become refunded within 15 minutes) |
refund_rejected | IB determined label was used (refund request rejected) |
refunded | For refund_approved labels; added refund amount back on the user's account meter |
refund_pending_review | Approx. 2 week period for IB to determine if label was used |
Errors
The RBAPI API uses the following error codes:
Error Code | HTTP Status Code | Meaning |
---|---|---|
S0001 | 422 | Failed schema validation |
S0002 | 400 | JSON format - unable to parse JSON |
X0001 | 500 | Internal server error |
M0002 | 404 | Empty manifest - no mailpieces found to be manifested |
V0001 | 422 | Invalid parameter |
V0002 | 422 | Invalid service parameters |
V0004 | 422 | UPS error |
V0005 | 422 | FedEx error |
V0006 | 422 | GSS error |
V0007 | 400 | Phone already confirmed |
V0007 | 422 | Account balance insufficient funds |
V0008 | 400 | Phone confirmation failed |
V0009 | 422 | No phone number |
A0001 | 401 | Authentication error - unauthenticated or/and unauthorized |
A0002 | 422 | User status |
AVS01 | 422 | Invalid address |
AVS02 | 422 | Invalid zip code |
AVS03 | 422 | Invalid state |
AVS04 | 422 | Invalid city |
AVS05 | 422 | Address not found |
AVS06 | 422 | Multiple addresses found |
AVS07 | 422 | Invalid street number |