{ "openapi": "3.1.0", "info": { "title": "Boxmile Public API", "version": "1.0.0-alpha.1", "description": "The Boxmile API for your own integrations: rate shipments, track parcels, check addresses and read your balance, with an API key. JSON fields are lowerCamelCase; money is integer US cents in ...Cents fields; timestamps are RFC 3339 UTC. Errors are RFC 9457 problem+json with a stable code. Every answer carries X-Request-Id, and every keyed answer the IETF RateLimit-Policy and RateLimit headers. Within v1, changes are additive only." }, "servers": [ { "url": "https://api.boxmile.com", "description": "The Boxmile API." } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Catalog", "description": "This API's own document and the carrier services a key can rate." }, { "name": "Rates", "description": "Prices for a parcel from the same pipeline as the web app. Nothing is bought." }, { "name": "Tracking", "description": "Delivery status and carrier scans of your workspace's parcels." }, { "name": "Addresses", "description": "Address checks. Nothing is stored and no carrier is asked." }, { "name": "Balance", "description": "Your workspace's wallet totals. Read only." } ], "paths": { "/v1/openapi": { "get": { "operationId": "getOpenApi", "tags": [ "Catalog" ], "security": [], "summary": "Read this API's OpenAPI document", "description": "The reviewed OpenAPI 3.1 document of this API. It needs no key; reads count against a limit per client address.", "x-permission": "public", "responses": { "200": { "description": "The OpenAPI document.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "type": "object" }, "example": { "openapi": "3.1.0", "info": { "title": "Boxmile Public API", "version": "1.0.0" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/services": { "get": { "operationId": "listServices", "tags": [ "Catalog" ], "summary": "List the carrier services a key can rate", "description": "Every carrier service this deployment offers, in its configured order. Services name the carrier and the carrier's service, never the account or partner that fulfils it. The list has no further page.", "x-permission": "rates.read", "responses": { "200": { "description": "The services.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceList" }, "example": { "object": "list", "items": [ { "object": "service", "code": "USPS_GROUND_ADVANTAGE", "carrier": "usps", "carrierName": "USPS", "serviceName": "USPS Ground Advantage" } ], "nextCursor": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Rating is not configured on this deployment.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "This feature is not available yet. Try again later.", "status": 503, "code": "service.unavailable", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } } } } }, "/v1/rates": { "post": { "operationId": "createRateRequest", "tags": [ "Rates" ], "summary": "Rate a parcel", "description": "Rates one parcel to one destination, from fromAddress or else your workspace's default origin, for the services named (default: every service in GET /v1/services). Each price comes from the same rating and pricing pipeline as the Boxmile web app, and nothing is bought. The server waits a few seconds: a finished request answers 201, one still rating answers 202 with a Location to poll. A service with no price is listed under unavailable with a reason. Each rate's id is the quote, and its price holds until expiresAt (15 minutes). Test keys can rate.", "x-permission": "rates.write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateRequestInput" }, "example": { "toAddress": { "name": "Ada Lovelace", "line1": "34 Example Road", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US", "residential": true }, "parcel": { "weightOz": 12, "lengthIn": 6, "widthIn": 4, "heightIn": 2 }, "services": [ "USPS_GROUND_ADVANTAGE", "UPS_GROUND" ] } } } }, "responses": { "201": { "description": "Rated. Location is this rate request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateRequest" }, "example": { "object": "rate_request", "id": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f", "status": "completed", "failureReason": null, "createdAt": "2026-10-20T03:00:00Z", "rates": [ { "object": "rate", "id": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e01", "service": "USPS_GROUND_ADVANTAGE", "carrier": "usps", "carrierName": "USPS", "serviceName": "USPS Ground Advantage", "amountCents": 725, "currency": "usd", "expiresAt": "2026-10-20T03:15:00Z" } ], "unavailable": [ { "service": "UPS_GROUND", "reason": "no_rate" } ] } } } }, "202": { "description": "Still rating after the server's wait (a few seconds). Poll Location; Retry-After is a hint in seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateRequest" }, "example": { "object": "rate_request", "id": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f", "status": "pending", "failureReason": null, "createdAt": "2026-10-20T03:00:00Z", "rates": [], "unavailable": [] } } } }, "400": { "description": "The body is not valid JSON, has a field this API does not know, misses a required field, has a value out of range, or names a service the catalog does not offer.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Check the request and try again.", "status": 400, "code": "request.invalid", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Rating is not configured on this deployment.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "This feature is not available yet. Try again later.", "status": 503, "code": "service.unavailable", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } } } } }, "/v1/rate-requests/{id}": { "get": { "operationId": "getRateRequest", "tags": [ "Rates" ], "summary": "Read a rate request", "description": "A rate request this API key made, as it stands now; another key, even of the same workspace, gets 404. While status is pending, poll again after Retry-After seconds.", "x-permission": "rates.read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The rate request's id.", "schema": { "type": "string", "format": "uuid" }, "example": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } ], "responses": { "200": { "description": "The rate request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateRequest" }, "example": { "object": "rate_request", "id": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f", "status": "completed", "failureReason": null, "createdAt": "2026-10-20T03:00:00Z", "rates": [ { "object": "rate", "id": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e01", "service": "USPS_GROUND_ADVANTAGE", "carrier": "usps", "carrierName": "USPS", "serviceName": "USPS Ground Advantage", "amountCents": 725, "currency": "usd", "expiresAt": "2026-10-20T03:15:00Z" } ], "unavailable": [ { "service": "UPS_GROUND", "reason": "no_rate" } ] } } } }, "400": { "description": "The id is not a UUID.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Check the request and try again.", "status": 400, "code": "request.invalid", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No rate request with this id was made by your workspace's API keys.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "The requested resource was not found.", "status": 404, "code": "resource.not_found", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Rating is not configured on this deployment.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "This feature is not available yet. Try again later.", "status": 503, "code": "service.unavailable", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } } } } }, "/v1/tracking/{trackingNumber}": { "get": { "operationId": "getTracking", "tags": [ "Tracking" ], "summary": "Track a parcel", "description": "The delivery status and carrier scans, newest first, of the parcel with this tracking number that your workspace shipped. A parcel of another workspace, a voided label and an unknown number all answer 404. Test keys can track.", "x-permission": "labels.read", "parameters": [ { "name": "trackingNumber", "in": "path", "required": true, "description": "The carrier tracking number, exactly as on the label (letters and digits).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9]{4,64}$" }, "example": "1Z999AA10123456784" } ], "responses": { "200": { "description": "The parcel's tracking.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tracking" }, "example": { "object": "tracking", "trackingNumber": "1Z999AA10123456784", "carrier": "ups", "carrierName": "UPS", "status": "in_transit", "events": [ { "id": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e10", "occurredAt": "2026-10-20T02:10:00Z", "status": "In transit", "description": "Departed facility", "location": "Louisville, KY" } ] } } } }, "400": { "description": "The tracking number is not 4 to 64 letters and digits.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Check the request and try again.", "status": 400, "code": "request.invalid", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Your workspace has no live parcel with this tracking number.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "The requested resource was not found.", "status": 404, "code": "resource.not_found", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Tracking is not configured on this deployment, or its store is busy. Try again later.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "This feature is not available yet. Try again later.", "status": 503, "code": "service.unavailable", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } } } } }, "/v1/addresses/validate": { "post": { "operationId": "createAddressValidation", "tags": [ "Addresses" ], "summary": "Validate an address", "description": "Checks one address's form and answers it standardized. Every address needs line1 and city, and a country Boxmile recognizes and may ship to (sanctioned countries and regions are refused). A US-domestic address (US and the USPS-domestic territories) also needs a USPS state, by code or name, and a 5- or 9-digit ZIP. The state becomes its code, a 9-digit ZIP is written 12345-6789 and runs of spaces become one. No carrier is asked, so carrierVerified is false: a valid address is unverified, or standardized when its form changed. An address that fails a check is a 200 with status invalid and each field's reason. Nothing is stored. Test keys can validate.", "x-permission": "addresses.read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" }, "example": { "line1": "34 Example Road", "city": "New York", "state": "new york", "postalCode": "100011234" } } } }, "responses": { "200": { "description": "The address's validation.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidation" }, "example": { "object": "address_validation", "status": "standardized", "carrierVerified": false, "address": { "line1": "34 Example Road", "line2": null, "city": "New York", "state": "NY", "postalCode": "10001-1234", "country": "US" }, "errors": [], "notices": [ "review_formatting", "not_verified" ] } } } }, "400": { "description": "The body is not an Address: not JSON, an unknown field, a value that is not text, text over 200 characters, or a country that is not two letters.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Check the request and try again.", "status": 400, "code": "request.invalid", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/balance": { "get": { "operationId": "getBalance", "tags": [ "Balance" ], "summary": "Read your balance", "description": "Your workspace's wallet totals, the same figures the Boxmile web app's billing summary shows. availableCents is what label purchases can spend from: the balance less what is reserved and, while it is on, the carrier-adjustment reserve; it can be negative. reservedCents is the total held for purchases and disputes in flight. No hold by order, payment method or funding reference is shown. Test keys can read the balance.", "x-permission": "balance.read", "responses": { "200": { "description": "The balance.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "object": "balance", "availableCents": 12345, "reservedCents": 300, "currency": "usd" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "The wallet could not be read in time. Try again later.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "This feature is not available yet. Try again later.", "status": 503, "code": "service.unavailable", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "boxmile_sk_{live|test}_", "x-postman-variable": "apiKey", "description": "Send Authorization: Bearer . A key belongs to one workspace, and every request acts for that workspace only. Live keys (boxmile_sk_live_) act on real data and money; test keys (boxmile_sk_test_) are read-only. A missing, malformed, unknown, revoked or expired key gets 401; a key without the operation's scope (x-permission), or whose workspace is not active, gets 403. Refused keys count against a limit of 30 per minute per client address. Scopes: rates.read (the service catalog and rate requests), rates.write (rate a parcel; nothing is bought), labels.read (tracking), addresses.read (address validation), balance.read (the balance); * grants every scope.", "x-scopes": [ "rates.read", "rates.write", "labels.read", "addresses.read", "balance.read" ] } }, "headers": { "RequestId": { "description": "This request's ID: a valid inbound X-Request-Id is echoed, otherwise a new one. Problems repeat it as instance.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" } }, "ContentLanguage": { "description": "The language of the problem title.", "schema": { "type": "string" } }, "RateLimitPolicy": { "description": "IETF RateLimit-Policy: the bucket this operation counts against, its burst q and the seconds w it takes to refill.", "schema": { "type": "string" }, "example": "\"reads\";q=50;w=2" }, "RateLimit": { "description": "IETF RateLimit: requests r left in the bucket now and seconds t until it is full.", "schema": { "type": "string" }, "example": "\"reads\";r=49;t=1" }, "RetryAfter": { "description": "Seconds to wait before the bucket holds a request again.", "schema": { "type": "integer", "minimum": 1 } }, "WWWAuthenticate": { "description": "Always Bearer.", "schema": { "type": "string", "const": "Bearer" } }, "Location": { "description": "The rate request to poll.", "schema": { "type": "string" }, "example": "/v1/rate-requests/0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } }, "schemas": { "Problem": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "status", "code", "params", "locale" ], "description": "RFC 9457 problem details. Branch on code and status; title is localized plain text. params is {} on every v1 answer. Internal exceptions and partner diagnostics are never exposed.", "properties": { "type": { "type": "string", "format": "uri", "const": "about:blank" }, "title": { "type": "string", "minLength": 1 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "type": "string", "pattern": "^[a-z0-9_]+(\\.[a-z0-9_]+)+$" }, "params": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "locale": { "type": "string" }, "instance": { "type": "string", "pattern": "^urn:boxmile:request:" } } }, "Service": { "type": "object", "additionalProperties": false, "required": [ "object", "code", "carrier", "carrierName", "serviceName" ], "properties": { "object": { "const": "service" }, "code": { "type": "string", "pattern": "^[A-Z0-9]+(_[A-Z0-9]+)+$", "description": "The service code rate requests name." }, "carrier": { "type": "string", "description": "The carrier's code, such as usps, ups, fedex or dhl." }, "carrierName": { "type": "string" }, "serviceName": { "type": "string" } }, "examples": [ { "object": "service", "code": "USPS_GROUND_ADVANTAGE", "carrier": "usps", "carrierName": "USPS", "serviceName": "USPS Ground Advantage" } ] }, "Address": { "type": "object", "additionalProperties": false, "description": "A postal address. Give postalCode, or city and state. A destination without line1 is rated at a placeholder street, which does not change a price.", "properties": { "name": { "type": "string", "maxLength": 200, "description": "Defaults to Recipient (destination) or Shipping Dept (origin)." }, "company": { "type": "string", "maxLength": 200, "description": "Company name." }, "line1": { "type": "string", "maxLength": 200, "description": "Street line 1." }, "line2": { "type": "string", "maxLength": 200, "description": "Street line 2." }, "city": { "type": "string", "maxLength": 200, "description": "City or town." }, "state": { "type": "string", "maxLength": 200, "description": "State, province or region code." }, "postalCode": { "type": "string", "maxLength": 200, "description": "ZIP or postal code." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "default": "US", "description": "ISO 3166-1 alpha-2 country code." }, "phone": { "type": "string", "maxLength": 200, "description": "Phone number." }, "email": { "type": "string", "maxLength": 200, "description": "Email address." }, "residential": { "type": [ "boolean", "null" ], "default": false, "description": "Whether the address is a residence." } } }, "Parcel": { "type": "object", "additionalProperties": false, "required": [ "weightOz" ], "properties": { "weightOz": { "type": "number", "exclusiveMinimum": 0, "maximum": 2400, "description": "Weight in ounces." }, "lengthIn": { "type": "number", "exclusiveMinimum": 0, "maximum": 120, "description": "Length in inches." }, "widthIn": { "type": "number", "exclusiveMinimum": 0, "maximum": 120, "description": "Width in inches." }, "heightIn": { "type": "number", "exclusiveMinimum": 0, "maximum": 120, "description": "Height in inches." } } }, "RateRequestInput": { "type": "object", "additionalProperties": false, "required": [ "toAddress", "parcel" ], "properties": { "toAddress": { "$ref": "#/components/schemas/Address" }, "fromAddress": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "Leave out to ship from your workspace's default origin." }, "parcel": { "$ref": "#/components/schemas/Parcel" }, "services": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 64, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Z0-9]+(_[A-Z0-9]+)+$" }, "description": "Service codes from GET /v1/services. Leave out to rate every service." } } }, "Rate": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "service", "carrier", "carrierName", "serviceName", "amountCents", "currency", "expiresAt" ], "properties": { "object": { "const": "rate" }, "id": { "type": "string", "format": "uuid", "description": "The quote. Its price holds until expiresAt." }, "service": { "type": "string", "description": "The service code." }, "carrier": { "type": "string" }, "carrierName": { "type": "string" }, "serviceName": { "type": "string" }, "amountCents": { "type": "integer", "minimum": 1, "description": "Your price in US cents." }, "currency": { "const": "usd" }, "expiresAt": { "type": "string", "format": "date-time" } }, "examples": [ { "object": "rate", "id": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e01", "service": "USPS_GROUND_ADVANTAGE", "carrier": "usps", "carrierName": "USPS", "serviceName": "USPS Ground Advantage", "amountCents": 725, "currency": "usd", "expiresAt": "2026-10-20T03:15:00Z" } ] }, "RateRequest": { "type": "object", "additionalProperties": false, "required": [ "object", "id", "status", "failureReason", "createdAt", "rates", "unavailable" ], "properties": { "object": { "const": "rate_request" }, "id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "pending", "completed", "failed" ], "description": "pending while rating; completed when every service has finished; failed when the request stopped (see failureReason)." }, "failureReason": { "enum": [ "access", "expired", "inputs", null ], "description": "Why a failed request stopped: the key or workspace lost access, the request outlived its 15 minutes, or its inputs could not be rated." }, "createdAt": { "type": "string", "format": "date-time" }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/Rate" }, "description": "One rate per priced service, in the order asked." }, "unavailable": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "service", "reason" ], "properties": { "service": { "type": "string" }, "reason": { "enum": [ "missing_measurements", "invalid_measurements", "missing_address", "invalid_address", "no_rate", "pricing", "failed" ] } } }, "description": "Each finished service with no price, and why." } } }, "Balance": { "type": "object", "additionalProperties": false, "required": [ "object", "availableCents", "reservedCents", "currency" ], "properties": { "object": { "const": "balance" }, "availableCents": { "type": "integer", "description": "What label purchases can spend from, in US cents. Can be negative." }, "reservedCents": { "type": "integer", "minimum": 0, "description": "Held for purchases and disputes in flight, in US cents." }, "currency": { "const": "usd" } }, "examples": [ { "object": "balance", "availableCents": 12345, "reservedCents": 300, "currency": "usd" } ] }, "AddressValidation": { "type": "object", "additionalProperties": false, "required": [ "object", "status", "carrierVerified", "address", "errors", "notices" ], "properties": { "object": { "const": "address_validation" }, "status": { "enum": [ "unverified", "standardized", "invalid" ], "description": "invalid when any check failed (see errors); standardized when the address passed and its form changed; unverified when it passed unchanged." }, "carrierVerified": { "const": false, "description": "Whether a carrier confirmed the address is deliverable. Always false: no carrier is asked." }, "address": { "type": "object", "additionalProperties": false, "required": [ "line1", "line2", "city", "state", "postalCode", "country" ], "description": "The address standardized; null where empty.", "properties": { "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "errors": { "type": "array", "description": "Each failed check, in field order.", "items": { "type": "object", "additionalProperties": false, "required": [ "field", "reason" ], "properties": { "field": { "enum": [ "line1", "line2", "city", "state", "postalCode", "country" ] }, "reason": { "enum": [ "missing", "invalid_state", "invalid_postal_code", "unknown_country", "sanctioned_destination", "unreadable" ] } } } }, "notices": { "type": "array", "items": { "enum": [ "review_formatting", "not_verified", "unsupported_country" ] }, "description": "review_formatting: check the standardized form; not_verified: no carrier confirmed it; unsupported_country: outside the US domestic area, so the state and postal code are not checked." } }, "examples": [ { "object": "address_validation", "status": "standardized", "carrierVerified": false, "address": { "line1": "34 Example Road", "line2": null, "city": "New York", "state": "NY", "postalCode": "10001-1234", "country": "US" }, "errors": [], "notices": [ "review_formatting", "not_verified" ] } ] }, "Tracking": { "type": "object", "additionalProperties": false, "required": [ "object", "trackingNumber", "carrier", "carrierName", "status", "events" ], "properties": { "object": { "const": "tracking" }, "trackingNumber": { "type": "string" }, "carrier": { "type": [ "string", "null" ], "description": "The carrier's code, null when Boxmile does not know it." }, "carrierName": { "type": [ "string", "null" ] }, "status": { "enum": [ "awaiting", "in_transit", "delivered", "exception", "voided" ], "description": "awaiting until the carrier has the parcel; in_transit includes out for delivery." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/TrackingEvent" }, "description": "Carrier scans, newest first." } }, "examples": [ { "object": "tracking", "trackingNumber": "1Z999AA10123456784", "carrier": "ups", "carrierName": "UPS", "status": "in_transit", "events": [ { "id": "0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e10", "occurredAt": "2026-10-20T02:10:00Z", "status": "In transit", "description": "Departed facility", "location": "Louisville, KY" } ] } ] }, "TrackingEvent": { "type": "object", "additionalProperties": false, "required": [ "id", "occurredAt", "status", "description", "location" ], "properties": { "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "The status the scan names." }, "description": { "type": "string", "description": "The carrier's description of the scan." }, "location": { "type": "string", "description": "The carrier's location text; empty when none." } } }, "ServiceList": { "type": "object", "additionalProperties": false, "required": [ "object", "items", "nextCursor" ], "properties": { "object": { "const": "list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "nextCursor": { "type": [ "string", "null" ] } } } }, "responses": { "Unauthorized": { "description": "The key is missing, malformed, unknown, revoked or expired.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Sign in to continue.", "status": 401, "code": "authentication.required", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } }, "Forbidden": { "description": "The key lacks this operation's scope, or its workspace is not active.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "You do not have permission to perform this action.", "status": 403, "code": "access.denied", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } }, "RateLimited": { "description": "The bucket is empty. Wait Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Content-Language": { "$ref": "#/components/headers/ContentLanguage" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Too many requests. Wait the number of seconds in the Retry-After header, then try again.", "status": 429, "code": "api.rate_limited", "params": {}, "locale": "en", "instance": "urn:boxmile:request:0192f7a0-5c1e-7d3a-9b2e-4f6a8c0d1e2f" } } } } } } }