country_short
{
"type": "string",
"example": "CA",
"description": "The country of the address. Will be returned as a 2 letter country short-name code (ISO 3166)."
}
county
{
"type": "string",
"description": "County name of the address city."
}
county_fips
{
"type": "string",
"pattern": "\\d{5}",
"description": "A 5-digit <a href=\"https://en.wikipedia.org/wiki/FIPS_county_code\" target=\"_blank\">FIPS county code</a> which uniquely identifies `components[county]`. It consists of a 2-digit state code and a 3-digit county code.\n"
}
creative
{
"allOf": [
{
"$ref": "#/components/schemas/lob_base"
},
{
"$ref": "#/components/schemas/returned_resource"
},
{
"type": "object",
"required": [
"id",
"description",
"from",
"resource_type",
"details",
"metadata",
"template_preview_urls",
"template_previews",
"campaigns",
"date_created",
"date_modified",
"object",
"deleted"
],
"properties": {
"id": {
"$ref": "#/components/schemas/crv_id"
},
"object": {
"enum": [
"creative"
],
"type": "string",
"default": "creative",
"description": "Value is resource type."
},
"deleted": {
"type": "boolean",
"description": "Whether the resource has been deleted."
},
"campaigns": {
"$ref": "#/components/schemas/campaign_list"
},
"template_previews": {
"type": "array",
"items": {
"type": "object"
},
"title": "Template Previews",
"description": "A list of template preview objects if the creative uses HTML template(s) as artwork asset(s). An empty array will be returned if no `template_preview`s have been generated for the creative."
},
"template_preview_urls": {
"type": "object",
"title": "Template Preview URLs",
"description": "Preview URLs associated with a creative's artwork asset(s) if the creative uses HTML templates as assets. An empty object will be returned if no `template_preview`s have been generated."
}
}
}
]
}
creative_base
{
"type": "object",
"properties": {
"from": {
"$ref": "#/components/schemas/from_attribute"
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"description": {
"$ref": "#/components/schemas/resource_description"
}
}
}
creative_writable
{
"oneOf": [
{
"allOf": [
{
"title": "Postcard Creative",
"required": [
"front",
"back",
"campaign_id",
"resource_type",
"details"
],
"properties": {
"back": {
"$ref": "#/components/schemas/crv_back"
},
"front": {
"$ref": "#/components/schemas/crv_front"
},
"details": {
"$ref": "#/components/schemas/writable"
},
"campaign_id": {
"$ref": "#/components/schemas/cmp_id"
},
"resource_type": {
"enum": [
"postcard"
],
"type": "string",
"description": "Mailpiece type for the creative"
}
}
},
{
"$ref": "#/components/schemas/creative_base"
}
]
},
{
"allOf": [
{
"title": "Letter Creative",
"required": [
"file",
"from",
"campaign_id",
"resource_type",
"details"
],
"properties": {
"file": {
"$ref": "#/components/schemas/crv_file"
},
"details": {
"$ref": "#/components/schemas/letter_details_writable"
},
"campaign_id": {
"$ref": "#/components/schemas/cmp_id"
},
"resource_type": {
"enum": [
"letter"
],
"type": "string",
"description": "Mailpiece type for the creative"
}
}
},
{
"$ref": "#/components/schemas/creative_base"
}
]
},
{
"allOf": [
{
"title": "Self Mailer Creative",
"required": [
"inside",
"outside",
"campaign_id",
"resource_type",
"details"
],
"properties": {
"inside": {
"$ref": "#/components/schemas/crv_inside"
},
"details": {
"$ref": "#/components/schemas/self_mailer_details_writable"
},
"outside": {
"$ref": "#/components/schemas/crv_outside"
},
"campaign_id": {
"$ref": "#/components/schemas/cmp_id"
},
"resource_type": {
"enum": [
"self_mailer"
],
"type": "string",
"description": "Mailpiece type for the creative"
}
}
},
{
"$ref": "#/components/schemas/creative_base"
}
]
}
]
}
crv_back
{
"oneOf": [
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"$ref": "#/components/schemas/local_file_path"
}
],
"description": "The artwork to use as the back of your postcard creative.\n\nNotes:\n- HTML merge variables should not include delimiting whitespace.\n- PDF, PNG, and JPGs must be sized at 4.25\"x6.25\", 6.25\"x9.25\", or 6.25\"x11.25\" at 300 DPI, while supplied HTML template will be rendered to the specified `size`.\n- Be sure to leave room for address and postage information by following the templates provided here:\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/4x6_postcard.pdf\" target=\"_blank\">4x6 template</a>\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/6x9_postcard.pdf\" target=\"_blank\">6x9 template</a>\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/6x11_postcard.pdf\" target=\"_blank\">6x11 template</a>\n\n\nSee [here](#section/HTML-Examples) for HTML examples.\n"
}
crv_file
{
"oneOf": [
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"$ref": "#/components/schemas/local_file_path"
}
],
"description": "Notes:\n- HTML merge variables should not include delimiting whitespace.\n- All pages of a supplied PDF file must be sized at 8.5\"x11\", while supplied HTML will be rendered and trimmed to as many 8.5\"x11\" pages as necessary.\n- For design specifications, please see our <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_template.pdf\" target=\"_blank\">PDF</a> and [HTML](#section/HTML-Examples) templates.\n- If a `custom_envelope` is used, follow <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_custom_envelope.pdf\" target=\"_blank\">this template</a>.\n- For domestic destinations, the file limit is 60 pages single-sided or 120 pages double-sided. For international destinations, the file limit is 6 pages single-sided or 12 pages double-sided. PDFs that surpass the file limit will error, while HTML that renders more pages than the file limit will be trimmed.\n- Any letters over 6 pages single-sided or 12 pages double-sided will be placed in a <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_flat_template.pdf\" target=\"_blank\">flat envelope</a> instead of the standard double window envelope.\n\nSee <a href=\"https://lob.com/pricing/print-mail#compare\" target=\"_blank\">pricing</a> for extra costs incurred."
}
crv_front
{
"oneOf": [
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"$ref": "#/components/schemas/local_file_path"
}
],
"description": "The artwork to use as the front of your postcard.\n\nNotes:\n- HTML merge variables should not include delimiting whitespace.\n- PDF, PNG, and JPGs must be sized at 4.25\"x6.25\", 6.25\"x9.25\", or 6.25\"x11.25\" at 300 DPI, while supplied HTML template will be rendered to the specified `size`.\n\nSee [here](#section/HTML-Examples) for HTML examples.\n"
}
crv_id
{
"type": "string",
"example": "crv_2a3b096c409b32c",
"pattern": "^crv_[a-zA-Z0-9]+$",
"description": "Unique identifier prefixed with `crv_`."
}
crv_inside
{
"oneOf": [
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"$ref": "#/components/schemas/local_file_path"
}
],
"description": "The artwork to use as the inside of your self mailer creative.\nNotes:\n- HTML merge variables should not include delimiting whitespace.\n- PDF, PNG, and JPGs must be sized at 6.25\"x18.25\", 12.25\"x9.25\" or 11.25\"x9.25\" at 300 DPI, while supplied HTML template will be rendered to the specified `size`.\n- Be sure to leave room for address and postage information by following the templates provided here:\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/6x18_sfm_bifold_template.pdf\" target=\"_blank\">6x18 bifold template</a>\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/11x9_sfm_bifold_template.pdf\" target=\"_blank\">11x9 bifold template</a>\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/12x9_sfm_bifold_template.pdf\" target=\"_blank\">12x9 bifold template</a>\n\n\nSee [here](#section/HTML-Examples) for HTML examples.\n"
}
crv_outside
{
"oneOf": [
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"$ref": "#/components/schemas/local_file_path"
}
],
"description": "The artwork to use as the outside of your self mailer creative.\nNotes:\n- HTML merge variables should not include delimiting whitespace.\n- PDF, PNG, and JPGs must be sized at 6.25\"x18.25\", 12.25\"x9.25\" or 11.25\"x9.25\" at 300 DPI, while supplied HTML template will be rendered to the specified `size`.\n- Be sure to leave room for address and postage information by following the templates provided here:\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/6x18_sfm_bifold_template.pdf\" target=\"_blank\">6x18 bifold template</a>\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/11x9_sfm_bifold_template.pdf\" target=\"_blank\">11x9 bifold template</a>\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/12x9_sfm_bifold_template.pdf\" target=\"_blank\">12x9 bifold template</a>\n\n\nSee [here](#section/HTML-Examples) for HTML examples.\n"
}
custom_envelope_returned
{
"type": "object",
"nullable": true,
"required": [
"id",
"url",
"object"
],
"properties": {
"id": {
"type": "string",
"maxLength": 40,
"description": "The unique identifier of the custom envelope used."
},
"url": {
"type": "string",
"description": "The url of the envelope asset used."
},
"object": {
"enum": [
"envelope"
],
"type": "string",
"default": "envelope"
}
},
"description": "A nested custom envelope object containing more information about the custom envelope used or `null` if a custom envelope was not used."
}
customized_redirect_url
{
"type": "string",
"description": "Redirect all mail receipients to a unique URL per mailpiece. Add an extra column in the [audience file](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide) with a unique link against each address row and map that row using the merge variable mapping while creating an upload."
}
date_created
{
"type": "string",
"format": "date-time",
"description": "A timestamp in ISO 8601 format of the date the resource was created."
}
date_filter
{
"type": "object",
"description": "Filter by ISO-8601 date or datetime, e.g. `{ \"gt\": \"2012-01-01\", \"lt\": \"2012-01-31T12:34:56Z\" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤.",
"additionalProperties": {
"type": "string"
}
}
date_modified
{
"type": "string",
"format": "date-time",
"description": "A timestamp in ISO 8601 format of the date the resource was last modified."
}
deleted
{
"type": "boolean",
"description": "Only returned if the resource has been successfully deleted."
}
deliverability_analysis
{
"type": "object",
"required": [
"dpv_confirmation",
"dpv_cmra",
"dpv_vacant",
"dpv_active",
"dpv_inactive_reason",
"dpv_throwback",
"dpv_non_delivery_day_flag",
"dpv_non_delivery_day_values",
"dpv_no_secure_location",
"dpv_door_not_accessible",
"dpv_footnotes",
"ews_match",
"lacs_indicator",
"lacs_return_code",
"suite_return_code"
],
"properties": {
"dpv_cmra": {
"enum": [
"Y",
"N",
""
],
"type": "string",
"example": "N",
"description": "Indicates whether or not the address is <a href=\"https://en.wikipedia.org/wiki/Commercial_mail_receiving_agency\" target=\"_blank\">CMRA-authorized</a>. Possible values are:\n* `Y` –– Address is CMRA-authorized.\n* `N` –– Address is not CMRA-authorized.\n* `''` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string).\n"
},
"ews_match": {
"type": "boolean",
"example": false,
"description": "Indicates whether or not an address has been flagged in the <a href=\"https://docs.informatica.com/data-engineering/data-engineering-quality/10-4-0/address-validator-port-reference/postal-carrier-certification-data-ports/early-warning-system-return-code.html\" target=\"_blank\">Early Warning System</a>, meaning the address is under development and not yet ready to receive mail. However, it should become available in a few months.\n"
},
"dpv_active": {
"enum": [
"Y",
"N",
""
],
"type": "string",
"example": "Y",
"description": "Corresponds to the USPS field `dpv_no_stat`. Indicates that an address has been vacated in the recent past, and is no longer receiving deliveries. If it's been unoccupied for 90+ days, or temporarily vacant, this will be flagged. Possible values are:\n* `Y` –– Address is active.\n* `N` –– Address is not active.\n* `''` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string).\n"
},
"dpv_vacant": {
"enum": [
"Y",
"N",
""
],
"type": "string",
"example": "N",
"description": "Indicates that an address was once deliverable, but has become vacant and is no longer receiving deliveries. Possible values are:\n* `Y` –– Address is vacant.\n* `N` –– Address is not vacant.\n* `''` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string).\n"
},
"dpv_footnotes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/dpv_footnote"
},
"example": [
"AA",
"BB"
],
"description": "An array of 2-character strings that gives more insight into how `deliverability_analysis[dpv_confirmation]` was determined. Will always include at least 1 string, and can include up to 3. For details, see [US Verification Details](#tag/US-Verification-Types).\n"
},
"dpv_throwback": {
"enum": [
"Y",
"N",
""
],
"type": "string",
"example": "N",
"description": "Indicates a street address for which mail is delivered to a PO Box. Possible values are:\n* `Y` –– Address is a PO Box throwback delivery point.\n* `N` –– Address is not a PO Box throwback delivery point.\n* `''` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string).\n"
},
"lacs_indicator": {
"enum": [
"Y",
"N",
""
],
"type": "string",
"example": "",
"description": "Indicates whether this address has been converted by\n<a href=\"https://postalpro.usps.com/address-quality/lacslink\" target=\"_blank\">LACS<sup>Link</sup></a>.\nLACS<sup>Link</sup> corrects outdated addresses into their modern counterparts.\nPossible values are:\n* `Y` –– New address produced with a matching record in LACS<sup>Link</sup>.\n* `N` –– New address could not be produced with a matching record in LACS<sup>Link</sup>.\n* `''` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string).\n"
},
"dpv_confirmation": {
"enum": [
"Y",
"S",
"D",
"N",
""
],
"type": "string",
"example": "Y",
"description": "Result of Delivery Point Validation (DPV), which determines whether or not the address is deliverable by the USPS. Possible values are:\n* `Y` –– The address is deliverable by the USPS.\n* `S` –– The address is deliverable by removing the provided secondary unit designator. This information may be incorrect or unnecessary.\n* `D` –– The address is deliverable to the building's default address but is missing a secondary unit designator and/or number.\n There is a chance the mail will not reach the intended recipient.\n* `N` –– The address is not deliverable according to the USPS, but parts of the address are valid (such as the street and ZIP code).\n* `''` –– This address is not deliverable. No matching street could be found within the city or ZIP code.\n"
},
"lacs_return_code": {
"type": "string",
"example": "",
"description": "A code indicating how `deliverability_analysis[lacs_indicator]` was determined.\nPossible values are:\n* `A` — A new address was produced because a match was found in LACS<sup>Link</sup>.\n* `92` — A LACS<sup>Link</sup> record was matched after dropping secondary information.\n* `14` — A match was found in LACS<sup>Link</sup>, but could not be converted to a deliverable address.\n* `00` — A match was not found in LACS<sup>Link</sup>, and no new address was produced.\n* `''` — LACS<sup>Link</sup> was not attempted.\n"
},
"suite_return_code": {
"enum": [
"A",
"00",
""
],
"type": "string",
"example": "",
"description": "A return code that indicates whether the address was matched and corrected by\n<a href=\"https://postalpro.usps.com/address-quality-solutions/suitelink\" target=\"_blank\">Suite<sup>Link</sup></a>.\nSuite<sup>Link</sup> attempts to provide secondary information to business addresses.\nPossible values are:\n* `A` –– A Suite<sup>Link</sup> match was found and secondary information was added.\n* `00` –– A Suite<sup>Link</sup> match could not be found and no secondary information was added.\n* `''` –– Suite<sup>Link</sup> lookup was not attempted.\n"
},
"dpv_inactive_reason": {
"enum": [
"01",
"02",
"03",
"04",
"05",
"06",
""
],
"type": "string",
"example": "06",
"description": "Indicates the reason why an address is vacant or no longer receiving deliveries. Possible values are:\n* `01` –– Address does not receive mail from the USPS directly, but is serviced by a drop address.\n* `02` –– Address not yet deliverable.\n* `03` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string).\n* `04` –– Address is a College, Military Zone, or other type.\n* `05` –– Address no longer receives deliveries.\n* `06` –– Address is missing required secondary information.\n* `''` –– A DPV match is not made or the address is active.\n"
},
"dpv_no_secure_location": {
"enum": [
"Y",
"N",
""
],
"type": "string",
"example": "N",
"description": "Indicates packages to this address will not be left due to security concerns. Possible values are:\n* `Y` –– Address does not have a secure mailbox.\n* `N` –– Address has a secure mailbox.\n* `''` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string).\n"
},
"dpv_door_not_accessible": {
"enum": [
"Y",
"N",
""
],
"type": "string",
"example": "N",
"description": "Indicates the door of the address is not accessible for mail delivery. Possible values are:\n* `Y` –– Door is not accessible.\n* `N` –– Door is accessible.\n* `''` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string).\n"
},
"dpv_non_delivery_day_flag": {
"enum": [
"Y",
"N",
""
],
"type": "string",
"example": "N",
"description": "Indicates whether deliveries are not performed on one or more days of the week at an address. Possible values are:\n* `Y` –– Mail delivery does not occur on some days of the week.\n* `N` –– Mail delivery occurs every day of the week.\n* `''` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string).\n"
},
"dpv_non_delivery_day_values": {
"type": "string",
"example": "YNNNNNN",
"description": "Indicates days of the week (starting on Sunday) deliveries are not performed at an address. For example:\n* `YNNNNNN` –– Mail delivery does not occur on Sunday's.\n* `NYNNNYN` –– Mail delivery does not occur on Monday's or Friday's.\n* `''` –– A DPV match is not made (`deliverability_analysis[dpv_confirmation]` is `N` or an empty string) or address receives mail every day of the week (`deliverability_analysis[dpv_non_delivery_day_flag]` is `N` or an empty string).\n"
}
},
"description": "A nested object containing a breakdown of the deliverability of an address."
}
domain
{
"type": "string",
"description": "The registered domain/hostname."
}
domain_response
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for a domain."
},
"domain": {
"type": "string",
"description": "The registered domain/hostname."
},
"account_id": {
"type": "string",
"description": "Unique identifier associated with the account the domain is registered for."
}
}
}
domains
{
"type": "object",
"required": [
"domain"
],
"properties": {
"domain": {
"$ref": "#/components/schemas/domain"
}
}
}
domains_response
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/domain_response"
},
"description": "List of domains."
}
}
}
double_sided
{
"type": "boolean",
"default": true,
"description": "Set this attribute to `true` for double sided printing, or `false` for for single sided printing. Defaults to `true`."
}
dpv_footnote
{
"enum": [
"AA",
"A1",
"BB",
"CC",
"N1",
"F1",
"G1",
"U1",
"M1",
"M3",
"P1",
"P3",
"R1",
"R7",
"RR"
],
"type": "string",
"example": "AA"
}
editable
{
"type": "object",
"properties": {
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"mail_type": {
"$ref": "#/components/schemas/mail_type"
},
"send_date": {
"$ref": "#/components/schemas/send_date"
},
"description": {
"$ref": "#/components/schemas/resource_description"
},
"merge_variables": {
"$ref": "#/components/schemas/merge_variables"
}
}
}
editable_no_mailtype
{
"type": "object",
"properties": {
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"send_date": {
"$ref": "#/components/schemas/send_date"
},
"description": {
"$ref": "#/components/schemas/resource_description"
},
"merge_variables": {
"$ref": "#/components/schemas/merge_variables"
}
}
}
engine
{
"enum": [
"legacy",
"handlebars"
],
"type": "string",
"default": "legacy",
"nullable": true,
"description": "The engine used to combine HTML template with merge variables.\n * `legacy` - Lob's original engine\n * `handlebars`\n"
}
error
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"message",
"status_code",
"code"
],
"properties": {
"code": {
"enum": [
"bad_request",
"conflict",
"feature_limit_reached",
"internal_server_error",
"invalid",
"not_deletable",
"not_found",
"request_timeout",
"service_unavailable",
"unrecognized_endpoint",
"unsupported_lob_version",
"address_length_exceeds_limit",
"bank_account_already_verified",
"bank_error",
"billing_address_required",
"custom_envelope_inventory_depleted",
"deleted_bank_account",
"failed_deliverability_strictness",
"file_pages_below_min",
"file_pages_exceed_max",
"file_size_exceeds_limit",
"foreign_return_address",
"inconsistent_page_dimensions",
"invalid_bank_account",
"invalid_bank_account_verification",
"invalid_check_international",
"invalid_country_covid",
"invalid_file",
"invalid_file_dimensions",
"invalid_file_download_time",
"invalid_file_url",
"invalid_image_dpi",
"invalid_international_feature",
"invalid_perforation_return_envelope",
"invalid_template_html",
"mail_use_type_can_not_be_null",
"merge_variable_required",
"merge_variable_whitespace",
"payment_method_unverified",
"pdf_encrypted",
"special_characters_restricted",
"unembedded_fonts",
"email_required",
"invalid_api_key",
"publishable_key_not_allowed",
"rate_limit_exceeded",
"unauthorized",
"unauthorized_token"
],
"type": "string",
"description": "A pre-defined string identifying an error. Error codes fall into three categories:\n\n**GENERIC**\n* `bad_request` - 422: an invalid request was made. See error message for details.\n* `conflict` - 409/422: this operation would leave data in a conflicted state.\n* `feature_limit_reached` - 403: the account has reached its resource limit and requires upgrading to add more.\n* `internal_server_error` - 500: an error has occured on Lob's servers. Please try request again.\n* `invalid` - 422: an invalid request was made. See error message for details.\n* `not_deletable` - 422: an attempt was made to delete a resource, but the resource cannot be deleted.\n* `not_found` - 404: the requested resource was not found.\n* `request_timeout` - 408: the request took too long. Please try again.\n* `service_unavailable` - 503: the Lob servers are temporarily unavailable. Please try agian.\n* `unrecognized_endpoint` - 404: the requested endpoint doesn't exist.\n* `unsupported_lob_version` - 422: an unsupported Lob API version was requested.\n\n**ADVANCED**\n* `address_length_exceeds_limit` - 422: the sum of to.address_line1 and to.address_line2 cannot surpass 50 characters.\n* `bank_account_already_verified` - 422: the bank account has already been verified.\n* `bank_error` - 422: there's an issue with the bank account.\n* `billing_address_required` - 403: in order to create a live mail piece, your account needs to set up a billing address.\n* `custom_envelope_inventory_depleted` - 422: custom envelope inventory is depleted, and more will need to be ordered.\n* `deleted_bank_account` - 404: checks cannot be created with a deleted bank account.\n* `failed_deliverability_strictness` - 422: the `to` address doesn't meet strictness requirements. See <a href=\"https://dashboard.lob.com/#/settings/account\" target=\"_blank\">Account Settings</a> to configure strictness.\n* `file_pages_below_min` - 422: not enough pages.\n* `file_pages_exceed_max` - 422: too many pages.\n* `file_size_exceeds_limit` - 422: the file size is too large. See description for details.\n* `foreign_return_address` - 422: the `from` address must be a US address.\n* `inconsistent_page_dimensions` - 422: all pages of the input file must have the same dimensions.\n* `invalid_bank_account` - 422: the provided bank routing number is invalid.\n* `invalid_bank_account_verification` - 422: verification amounts do not match.\n* `invalid_check_international` - 422: checks cannot be sent internationally.\n* `invalid_country_covid` - 422: the postal service in the specified country is currently unable to process the request due to COVID-19 restrictions.\n* `invalid_file` - 422: the file is invalid.\n* `invalid_file_dimensions` - 422: file dimensions are incorrect for the selected mail type.\n* `invalid_file_download_time` - 422: file download from remote server took too long.\n* `invalid_file_url` - 422: the file URL when creating a resource is invalid.\n* `invalid_image_dpi` - 422: DPI must be at least 300.\n* `invalid_international_feature` - 422: the specified product cannot be sent to the destination.\n* `invalid_perforation_return_envelope` - 422: both `return_envelope` and `perforation` must be used together.\n* `invalid_template_html` - 422: the provided HTML is invalid.\n* `mail_use_type_can_not_be_null` - 422: use_type must be one of \"marketing\" or \"operational\". Alternatively, an admin can set the account default use type in Account Settings.\n* `merge_variable_required` - 422: a required merge variable is missing.\n* `merge_variable_whitespace` - 422: merge variable names cannot contain whitespace.\n* `payment_method_unverified` - 401: you must have a verified bank account or credit card to submit live requests.\n* `pdf_encrypted` - 422: an encrypted PDF was provided.\n* `special_characters_restricted` - 422: cannot use special characters for merge variable names.\n* `unembedded_fonts` - 422: the provided PDF contains non-standard unembedded fonts. See description for details.\n\n**AUTHENTICATION**\n* `email_required` - 401: account must have a verified email address before creating live resources.\n* `invalid_api_key` - 401/403: the API key is invalid.\n* `publishable_key_not_allowed` - 403: the requested operation needs a secret key, not a publishable key. See [API Keys](#section/API-Keys) for more information.\n* `rate_limit_exceeded` - 429: requests were sent too quickly and must be slowed down.\n* `unauthorized` - 401: the request isn't authorized.\n* `unauthorized_token` - 401: token isn't authorized.\n"
},
"message": {
"type": "string",
"example": "Rate limit exceeded. Please wait 5 seconds and try your request again.",
"description": "A human-readable message with more details about the error"
},
"status_code": {
"$ref": "#/components/schemas/failure_status_code"
}
}
}
},
"description": "Lob uses RESTful HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end."
}
event_type
{
"type": "object",
"required": [
"id",
"enabled_for_test",
"resource",
"object"
],
"properties": {
"id": {
"oneOf": [
{
"$ref": "#/components/schemas/postcard_types"
},
{
"$ref": "#/components/schemas/self_mailer_types"
},
{
"$ref": "#/components/schemas/letter_types"
},
{
"$ref": "#/components/schemas/check_types"
},
{
"$ref": "#/components/schemas/address_types"
},
{
"$ref": "#/components/schemas/bank_account_types"
}
]
},
"object": {
"enum": [
"event_type"
],
"type": "string",
"default": "event_type",
"description": "Value is resource type."
},
"resource": {
"enum": [
"postcards",
"self mailers",
"letters",
"checks",
"addresses",
"bank accounts"
],
"type": "string"
},
"enabled_for_test": {
"type": "boolean",
"description": "Value is `true` if the event type is enabled in both the test and live environments and `false` if it is only enabled in the live environment."
}
}
}
events
{
"type": "object",
"required": [
"id",
"body",
"reference_id",
"event_type",
"date_created",
"object"
],
"properties": {
"id": {
"type": "string",
"pattern": "^evt_[a-zA-Z0-9_]+$",
"description": "Unique identifier prefixed with `evt_`."
},
"body": {
"type": "object",
"description": "The body of the associated resource as they were at the time of the event, i.e. the [postcard object](#operation/postcard_retrieve), [the letter object](#operation/letter_retrieve), [the check object](#operation/check_retrieve), [the address object](#operation/address_retrieve), or [the bank account object](#operation/bank_account_retrieve). For `.deleted` events, the body matches the response for the corresponding delete endpoint for that resource (e.g. the [postcard delete response](#operation/postcard_delete))."
},
"object": {
"enum": [
"event"
],
"type": "string",
"default": "event",
"description": "Value is resource type."
},
"event_type": {
"$ref": "#/components/schemas/event_type"
},
"date_created": {
"$ref": "#/components/schemas/date_created"
},
"reference_id": {
"type": "string",
"description": "Unique identifier of the related resource for the event."
}
}
}
evnt_id
{
"type": "string",
"pattern": "^evnt_[a-zA-Z0-9]+$",
"description": "Unique identifier prefixed with `evnt_`."
}
ex_id
{
"type": "string",
"pattern": "^ex_[a-zA-Z0-9]+$",
"description": "Unique identifier prefixed with `ex_`."
}
expected_delivery_date
{
"type": "string",
"format": "date",
"description": "A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`."
}
extra_service
{
"enum": [
"certified",
"certified_return_receipt",
"registered",
null
],
"type": "string",
"nullable": true,
"description": "Add an extra service to your letter. Can only be non-`null` if `mail_type` isn't `usps_standard`. See <a href=\"https://www.lob.com/pricing/print-mail#compare\" target=\"_blank\">pricing</a> for extra costs incurred.\n * `certified` - track and confirm delivery for domestic destinations. An extra sheet (1 PDF page single-sided or 2 PDF pages double-sided) is added to the beginning of your letter for address and barcode information. See here for templates: <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_template.pdf\" target=\"_blank\">#10 envelope</a> and <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_flat_template.pdf\" target=\"_blank\">flat envelope</a> (used for letters over 6 pages single-sided or 12 pages double-sided). You will not be charged for this extra sheet.\n * `certified_return_receipt` - request an electronic copy of the recipient's signature to prove delivery of your certified letter\n * `registered` - provides tracking and confirmation for international addresses\n \nNot available for `us_legal` letter size.\n"
}
failure_reason
{
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/failure_reason_error"
},
"nullable": true
},
"remediation": {
"type": "string",
"description": "Instructions on how to resolve the error"
},
"failure_reason": {
"type": "string",
"description": "Reason failure occurred"
}
},
"description": "An object describing the reason for failure if the resource failed to render."
}
failure_reason_error
{
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": true,
"description": "Failed URL of asset"
},
"host": {
"type": "string",
"nullable": true,
"description": "URL host"
},
"path": {
"type": "string",
"nullable": true,
"description": "URL path"
},
"protocol": {
"type": "string",
"nullable": true,
"description": "Network protocol"
},
"error_type": {
"type": "string",
"nullable": true,
"description": "HTTP response status code message or service defined error"
},
"remediation": {
"type": "string",
"nullable": true,
"description": "Instructions on how to resolve the error"
},
"status_code": {
"type": "number",
"nullable": true,
"description": "HTTP response status codes if the error is asset related"
}
},
"description": "Failure error details"
}
failure_status_code
{
"enum": [
401,
403,
404,
413,
422,
429,
500
],
"type": "integer",
"description": "A conventional HTTP status code:\n * `401` - Authorization error with your API key or account\n * `403` - Forbidden error with your API key or account\n * `404` - The requested item does not exist\n * `413` - Payload too large\n * `422` - The query or body parameters did not pass validation\n * `429` - Too many requests have been sent with an API key in a given amount of time\n * `500` - An internal server error occurred, please contact support@lob.com\n"
}
from
{
"type": "object",
"properties": {
"from": {
"$ref": "#/components/schemas/address"
}
}
}
from_attribute
{
"oneOf": [
{
"$ref": "#/components/schemas/adr_id"
},
{
"$ref": "#/components/schemas/inline_address_us"
}
],
"title": "From",
"description": "Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification."
}
from_us
{
"type": "object",
"properties": {
"from": {
"$ref": "#/components/schemas/address_us"
}
}
}
generated
{
"type": "object",
"required": [
"to",
"carrier"
],
"properties": {
"to": {
"$ref": "#/components/schemas/address"
},
"carrier": {
"enum": [
"USPS"
],
"type": "string",
"default": "USPS"
},
"deleted": {
"$ref": "#/components/schemas/deleted"
},
"thumbnails": {
"type": "array",
"items": {
"$ref": "#/components/schemas/thumbnail"
}
},
"date_created": {
"$ref": "#/components/schemas/date_created"
},
"date_modified": {
"$ref": "#/components/schemas/date_modified"
},
"expected_delivery_date": {
"$ref": "#/components/schemas/expected_delivery_date"
}
}
}
html_string
{
"type": "string",
"pattern": "<",
"maxLength": 10000,
"description": "An HTML string of under 10,000 characters."
}
identity_validation
{
"oneOf": [
{
"$ref": "#/components/schemas/recipient_validation"
},
{
"$ref": "#/components/schemas/company_validation"
}
]
}
identity_validation_company
{
"type": "string",
"nullable": true,
"maxLength": 500,
"description": "The name of the company or firm."
}
identity_validation_id
{
"type": "string",
"pattern": "^id_validation_[a-zA-Z0-9_]+$",
"description": "Unique identifier prefixed with `id_validation_`."
}
identity_validation_recipient
{
"type": "string",
"nullable": true,
"maxLength": 500,
"description": "The name of the person whose identity is being validated."
}
identity_validation_writable
{
"oneOf": [
{
"$ref": "#/components/schemas/recipient_input"
},
{
"$ref": "#/components/schemas/company_input"
}
]
}
inline_address
{
"oneOf": [
{
"$ref": "#/components/schemas/inline_address_us"
},
{
"$ref": "#/components/schemas/inline_address_intl"
}
]
}
inline_address_intl
{
"allOf": [
{
"$ref": "#/components/schemas/address_editable_intl"
},
{
"type": "object",
"required": [
"address_line1",
"address_country"
]
},
{
"type": "object",
"oneOf": [
{
"required": [
"address_city",
"address_state"
]
},
{
"required": [
"address_zip"
]
}
]
}
]
}