NAV Navbar
shell

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.
email (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.
email (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.
email (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