Addresses

Every shipment includes a recipient address and a return address. Corvo validates both, but it treats them differently.

Address object

Name	Type	Required	Description
name	string	No	Full name. At least one of `name` or `company` is required.
company	string	No	Company name. At least one of `name` or `company` is required.
street1	string	Yes	Street address line 1.
street2	string	No	Street address line 2.
city	string	Yes	City.
state	string	Yes	State or province.
zip	string	Yes	Postal code.
country	string	No	Two-letter country code. Defaults to "US".
phone	string	No	Phone number.
email	string	No	Email address.

Name or company is required

Corvo requires at least one of name or company on both addresses.

Recipient address verification

Corvo hard-verifies the to_address during shipment creation. If the carrier verification step cannot verify or normalize the address, shipment creation fails.

Recipient verification is blocking

An unverified or malformed recipient address can return an ADDRESS_VERIFICATION_FAILED error from shipment creation.

Return address verification

Corvo soft-verifies the from_address. If verification succeeds, the corrected address is stored. If it fails, Corvo still creates the shipment using the original return address and leaves the response field verified as false.

Default return address

If you omit from_address, Corvo uses the organization default return address configured in the dashboard. If no default exists, shipment creation fails with VALIDATION_ERROR.

Corrected addresses in responses

Shipment creation responses can include an address_corrections object that shows the original and corrected address components.

Response201Address correction metadata

{
  "data": {
    "address_corrections": {
      "to_address": {
        "was_changed": true,
        "original": {
          "street1": "123 Main Street",
          "street2": null,
          "city": "Austin",
          "state": "TX",
          "zip": "7870",
          "country": "US"
        },
        "corrected": {
          "street1": "123 MAIN ST",
          "street2": null,
          "city": "AUSTIN",
          "state": "TX",
          "zip": "78701",
          "country": "US"
        },
        "warnings": [],
        "verified": true
      },
      "from_address": {
        "was_changed": false,
        "original": {
          "street1": "500 Congress Ave",
          "street2": null,
          "city": "Austin",
          "state": "TX",
          "zip": "78701",
          "country": "US"
        },
        "corrected": {
          "street1": "500 Congress Ave",
          "street2": null,
          "city": "Austin",
          "state": "TX",
          "zip": "78701",
          "country": "US"
        },
        "warnings": [],
        "verified": false
      }
    }
  }
}

Verified address shape

Response200Address inside a shipment response

{
  "to_address": {
    "name": "Jordan Reed",
    "company": null,
    "street1": "123 MAIN ST",
    "street2": null,
    "city": "AUSTIN",
    "state": "TX",
    "zip": "78701",
    "country": "US",
    "phone": null,
    "email": null,
    "verified": true,
    "residential": true
  }
}