Create a scan form

POST

/shipping/api/v1/scan_forms/{sub_carrier_id}

• Veeqo API Production Server

Create a scan form (manifest) for a specific carrier. A scan form groups together all shipments from a collection address into a single document that can be scanned by the carrier during pickup, rather than scanning each package individually.

The response may include multiple manifests depending on the shipments associated with the collection address.

Parameters

Path Parameters

sub_carrier_id

required

string

The sub-carrier identifier (e.g., USPS, UPS)

Example

USPS

Request Body ^required

object

collection_address

required

The collection/pickup address where packages will be collected from. You can provide either a saved address ID or the full address fields.

object

address_id

Veeqo Address Service ID for a saved address

string

b8b3e7b6-3adc-417f-963b-dd9851947ac2

name

Contact name at the collection address

string

My Warehouse

company

Company name

string

Acme Corp

phone

Phone number

string

+12065551234

email

Email address

string format: email

line1

Address line 1

string

410 Terry Ave N

line2

Address line 2

string

town

City/town

string

Seattle

postcode

Postal/ZIP code

string

98109

country_code

ISO 3166-1 alpha-2 country code

string

US

county

State/region/county

string

WA

Examples

Create scan form with full collection address

{
  "collection_address": {
    "name": "My Warehouse",
    "company": "Acme Corp",
    "phone": "+12065551234",
    "line1": "410 Terry Ave N",
    "town": "Seattle",
    "postcode": "98109",
    "country_code": "US",
    "county": "WA"
  }
}

Create scan form using a saved address

{
  "collection_address": {
    "address_id": "b8b3e7b6-3adc-417f-963b-dd9851947ac2"
  }
}

Responses

200

Scan form created successfully

object

manifests

List of created scan form manifests

Array<object>

A created scan form. The document is returned inline as base64 rather than as a link, and no identifier is returned on creation, so a newly created form cannot be reprinted by ID directly. Use the history endpoint to obtain its collection_form_id.

One entry is returned per seller registration the form was requested for, so the manifests array can contain more than one entry for a single request.

object

status

Generation status of the scan form.

• COMPLETED — the document was generated and is present on this entry
• IN_PROGRESS — the request was accepted but the document is not ready yet. The entry is returned without document and document_format, and the form becomes available through the history endpoint once generated.
• FAILED — the carrier reported a failure for this registration and returned no document. A failure that carries a reason is reported in error_messages instead of as an entry here.

string

Allowed values: COMPLETED IN_PROGRESS FAILED

COMPLETED

document

Base64-encoded scan form document. Present only when status is COMPLETED, and omitted entirely otherwise.

string

JVBERi0xLjQKJeLjz9MKMyAwIG9iago8P...

document_format

MIME type of the document, as returned by the carrier. Omitted when document is absent.

string

application/pdf

error_messages

Any error messages from failed manifest requests

Array<string>

400

Bad request - missing or invalid collection address, or manifest creation failed

object

error_messages

required

List of error messages

Array<string>

[
  "to_address is required"
]

{
  "error_messages": [
    "Invalid request parameters"
  ]
}