postal_code
{
"type": "string",
"maxLength": 12,
"description": "The postal code."
}
postcard
{
"allOf": [
{
"$ref": "#/components/schemas/postcard_base"
},
{
"$ref": "#/components/schemas/generated"
},
{
"$ref": "#/components/schemas/from_us"
},
{
"type": "object",
"required": [
"id",
"front_template_id",
"back_template_id",
"url"
],
"properties": {
"id": {
"$ref": "#/components/schemas/psc_id"
},
"fsc": {
"type": "boolean",
"default": false,
"description": "This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `4x6` or `A5` postcard sizes."
},
"url": {
"$ref": "#/components/schemas/signed_link"
},
"object": {
"enum": [
"postcard"
],
"type": "string",
"default": "postcard",
"description": "Value is resource type."
},
"status": {
"$ref": "#/components/schemas/status"
},
"use_type": {
"$ref": "#/components/schemas/psc_use_type"
},
"campaign_id": {
"$ref": "#/components/schemas/campaign_id"
},
"failure_reason": {
"allOf": [
{
"$ref": "#/components/schemas/failure_reason"
},
{
"nullable": true
}
]
},
"tracking_events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/tracking_event_normal"
},
"nullable": true,
"description": "An array of tracking_event objects ordered by ascending `time`. Will not be populated for postcards created in test mode."
},
"back_template_id": {
"type": "string",
"pattern": "^tmpl_[a-zA-Z0-9]+$",
"nullable": true,
"description": "The unique ID of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID."
},
"front_template_id": {
"type": "string",
"pattern": "^tmpl_[a-zA-Z0-9]+$",
"nullable": true,
"description": "The unique ID of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID."
},
"back_template_version_id": {
"type": "string",
"pattern": "^vrsn_[a-zA-Z0-9]+$",
"nullable": true,
"description": "The unique ID of the specific version of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID."
},
"front_template_version_id": {
"type": "string",
"pattern": "^vrsn_[a-zA-Z0-9]+$",
"nullable": true,
"description": "The unique ID of the specific version of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID."
}
}
}
]
}
postcard_base
{
"allOf": [
{
"$ref": "#/components/schemas/editable"
},
{
"type": "object",
"properties": {
"size": {
"$ref": "#/components/schemas/postcard_size"
}
}
}
]
}
postcard_deletion
{
"properties": {
"id": {
"$ref": "#/components/schemas/psc_id"
},
"deleted": {
"$ref": "#/components/schemas/deleted"
}
},
"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."
}
postcard_editable
{
"allOf": [
{
"$ref": "#/components/schemas/postcard_base"
},
{
"$ref": "#/components/schemas/input_to"
},
{
"$ref": "#/components/schemas/input_from_us"
},
{
"type": "object",
"required": [
"to",
"front",
"back",
"use_type"
],
"properties": {
"fsc": {
"type": "boolean",
"default": false,
"description": "This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `4x6` or `A5` postcard sizes."
},
"back": {
"$ref": "#/components/schemas/psc_back"
},
"front": {
"$ref": "#/components/schemas/psc_front"
},
"qr_code": {
"$ref": "#/components/schemas/qr_code"
},
"use_type": {
"$ref": "#/components/schemas/psc_use_type"
},
"billing_group_id": {
"$ref": "#/components/schemas/billing_group_id"
}
}
}
]
}
postcard_size
{
"enum": [
"4x6",
"6x9",
"6x11"
],
"type": "string",
"default": "4x6",
"description": "Specifies the size of the postcard. Only `4x6` postcards can be sent to international destinations.\n"
}
postcard_types
{
"enum": [
"postcard.created",
"postcard.rendered_pdf",
"postcard.rendered_thumbnails",
"postcard.deleted",
"postcard.delivered",
"postcard.failed",
"postcard.mailed",
"postcard.in_transit",
"postcard.in_local_area",
"postcard.international_exit",
"postcard.processed_for_delivery",
"postcard.re-routed",
"postcard.returned_to_sender",
"postcard.viewed"
],
"type": "string",
"description": "Unique identifier referring to status of postcard"
}
primary_line
{
"type": "string",
"maxLength": 200,
"description": "The primary delivery line (usually the street address) of the address.\n"
}
primary_line_us
{
"type": "string",
"maxLength": 500,
"description": "The primary delivery line (usually the street address) of the address.\nCombination of the following applicable `components`:\n* `primary_number`\n* `street_predirection`\n* `street_name`\n* `street_suffix`\n* `street_postdirection`\n* `secondary_designator`\n* `secondary_number`\n* `pmb_designator`\n* `pmb_number`\n"
}
primary_number
{
"type": "string",
"description": "The numeric or alphanumeric part of an address preceding the street name. Often the house, building, or PO Box number."
}
psc_back
{
"oneOf": [
{
"$ref": "#/components/schemas/html_string"
},
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"$ref": "#/components/schemas/remote_file_url"
},
{
"$ref": "#/components/schemas/local_file_path"
}
],
"description": "The artwork to use as the back 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 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"
}
psc_front
{
"oneOf": [
{
"$ref": "#/components/schemas/html_string"
},
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"$ref": "#/components/schemas/remote_file_url"
},
{
"$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 will be rendered to the specified `size`.\n\nSee [here](#section/HTML-Examples) for HTML examples.\n"
}
psc_id
{
"type": "string",
"pattern": "^psc_[a-zA-Z0-9]+$",
"description": "Unique identifier prefixed with `psc_`."
}
psc_use_type
{
"enum": [
"marketing",
"operational",
null
],
"type": "string",
"nullable": true,
"description": "The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)."
}
qr_code
{
"type": "object",
"required": [
"position",
"redirect_url",
"width"
],
"properties": {
"top": {
"type": "string",
"description": "Vertical distance (in inches) to place QR code from the top. Only allowed if \"bottom\" isn't provided."
},
"left": {
"type": "string",
"description": "Horizontal distance (in inches) to place QR code from the left. Only allowed if \"right\" isn't provided."
},
"pages": {
"type": "string",
"description": "Specify the pages where the QR code should be stamped in a comma separated format. Your QR code can be printed in the same position on multiple pages. For postcards, the values should either be \"front\", \"back\" (for either front or back) or \"front,back\" (for the QR code to be printed on both sides). For self-mailers, the values should either be \"inside\", \"outside\" (for either inside or outside) or \"inside,outside\" (for the QR code to be printed on both sides). For letters, the values can be specific page numbers (\"1\", \"3\"), page number ranges such as \"1-3\", or a comma separated combination of both (\"1,3,5-7\")."
},
"right": {
"type": "string",
"description": "Horizontal distance (in inches) to place QR code from the right. Only allowed if \"left\" isn't provided."
},
"width": {
"type": "string",
"description": "The size (in inches) of the QR code with a minimum of 1 inch. All QR codes are generated as a square."
},
"bottom": {
"type": "string",
"description": "Vertical distance (in inches) to place QR code from the bottom. Only allowed if \"top\" isn't provided."
},
"position": {
"enum": [
"relative"
],
"type": "string",
"description": "Sets how a QR code is being positioned in the document. Together with this, you should provide one of 'top' or 'bottom', and one of 'left' or 'right'."
},
"redirect_url": {
"type": "string",
"description": "The url to redirect the user when a QR code is scanned. The url must start with `https://`"
}
},
"description": "Customize and place a QR code on the creative at the required position. Not available for `us_legal` letter size and snap packs."
}
qr_code_campaigns
{
"type": "object",
"required": [
"position",
"width"
],
"properties": {
"top": {
"type": "string",
"description": "Vertical distance (in inches) to place QR code from the top. Only allowed if \"bottom\" isn't provided."
},
"left": {
"type": "string",
"description": "Horizontal distance (in inches) to place QR code from the left. Only allowed if \"right\" isn't provided."
},
"pages": {
"type": "string",
"description": "Specify the pages where the QR code should be stamped in a comma separated format. Your QR code can be printed in the same position on multiple pages. For postcards, the values should either be \"front\", \"back\" (for either front or back) or \"front,back\" (for the QR code to be printed on both sides). For self-mailers, the values should either be \"inside\", \"outside\" (for either inside or outside) or \"inside,outside\" (for the QR code to be printed on both sides). For letters, the values can be specific page numbers (\"1\", \"3\"), page number ranges such as \"1-3\", or a comma separated combination of both (\"1,3,5-7\")."
},
"right": {
"type": "string",
"description": "Horizontal distance (in inches) to place QR code from the right. Only allowed if \"left\" isn't provided."
},
"width": {
"type": "string",
"description": "The size (in inches) of the QR code with a minimum of 1 inch. All QR codes are generated as a square."
},
"bottom": {
"type": "string",
"description": "Vertical distance (in inches) to place QR code from the bottom. Only allowed if \"top\" isn't provided."
},
"position": {
"enum": [
"relative"
],
"type": "string",
"description": "Sets how a QR code is being positioned in the document. Together with this, you should provide one of 'top' or 'bottom', and one of 'left' or 'right'."
},
"redirect_url": {
"oneOf": [
{
"$ref": "#/components/schemas/single_redirect_url"
},
{
"$ref": "#/components/schemas/customized_redirect_url"
}
],
"description": "Redirect all mail recipients to either a single URL or a custom personalized URL for each recipient. To redirect to a single URL for the whole campaign, add a `redirect_url` in the request body along with the url as string. To redirect to a custom URL for each recipient, do not provide any value for `redirect_url`. Instead, create 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 while creating an upload, map `qr_code_redirect_url` to this column. If the QR code section is used but a redirection url is not provided or mapped while creating an upload, then there might be failures in creating individual mail pieces.\n"
}
},
"description": "Customize and place a QR code on all the postcards, letters or self mailers in a campaign. Redirect URLs can either be unique for each recipient, or a single link can be used for the whole campaign. See `redirect_url` attribute below for more details."
}
qr_code_scans
{
"allOf": [
{
"type": "object",
"properties": {
"scans": {
"type": "array",
"items": {
"$ref": "#/components/schemas/scans"
},
"description": "Detailed scan information associated with each mail piece."
},
"resource_id": {
"type": "string",
"description": "Unique identifier for each mail piece."
},
"date_created": {
"$ref": "#/components/schemas/date_created"
},
"number_of_scans": {
"type": "number",
"description": "Number of times the QR Code associated with this mail piece was scanned."
}
}
}
]
}
recipient
{
"type": "string",
"nullable": true,
"maxLength": 500,
"description": "The intended recipient, typically a person's or firm's name."
}
recipient_input
{
"allOf": [
{
"anyOf": [
{
"title": "Address object with `city` and `state`",
"required": [
"city",
"state"
]
},
{
"title": "Address object with `zip_code`",
"required": [
"zip_code"
]
}
]
},
{
"type": "object",
"required": [
"recipient",
"primary_line"
],
"properties": {
"city": {
"allOf": [
{
"$ref": "#/components/schemas/city_no_description"
},
{
"type": "string",
"description": "The name of the city. `city` and `state` are required if no `zip_code` is passed."
}
]
},
"state": {
"type": "string",
"maxLength": 50,
"description": "The <a href=\"https://en.wikipedia.org/wiki/ISO_3166-2:US\" target=\"_blank\">ISO 3166-2</a> two letter code or subdivision name for the state. `city` and `state` are required if no `zip_code` is passed."
},
"zip_code": {
"allOf": [
{
"description": "Required if `city` and `state` are not passed in. If included, must be formatted as a US ZIP or ZIP+4 (e.g. `94107`, `941072282`, `94107-2282`)."
},
{
"$ref": "#/components/schemas/zip_code"
}
]
},
"recipient": {
"$ref": "#/components/schemas/recipient"
},
"primary_line": {
"$ref": "#/components/schemas/primary_line_us"
},
"urbanization": {
"$ref": "#/components/schemas/urbanization"
},
"secondary_line": {
"$ref": "#/components/schemas/secondary_line"
}
}
}
]
}
recipient_validation
{
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/identity_validation_id"
},
"score": {
"type": "number",
"format": "float",
"default": null,
"maximum": 100,
"minimum": 0,
"nullable": true,
"description": "A numerical score between 0 and 100 that represents the likelihood the provided name is associated with a physical address.\n"
},
"object": {
"enum": [
"id_validation"
],
"type": "string",
"default": "id_validation",
"description": "Value is resource type."
},
"last_line": {
"type": "string",
"description": "Combination of the following applicable `components`:\n* City (`city`)\n* State (`state`)\n* ZIP code (`zip_code`)\n* ZIP+4 (`zip_code_plus_4`)\n"
},
"recipient": {
"$ref": "#/components/schemas/identity_validation_recipient"
},
"confidence": {
"enum": [
"high",
"medium",
"low",
""
],
"type": "string",
"description": "Indicates the likelihood the recipient name and address match based on our custom internal calculation. Possible values are:\n- `high` — Has a Lob confidence score greater than 70.\n- `medium` — Has a Lob confidence score between 40 and 70.\n- `low` — Has a Lob confidence score less than 40.\n- `\"\"` — No tracking data exists for this address.\n"
},
"primary_line": {
"$ref": "#/components/schemas/primary_line_us"
},
"urbanization": {
"$ref": "#/components/schemas/urbanization"
},
"secondary_line": {
"$ref": "#/components/schemas/secondary_line"
}
}
}
redirect_link
{
"type": "string",
"description": "The original target URL."
}
registered
{
"allOf": [
{
"type": "object",
"required": [
"extra_service",
"color"
],
"properties": {
"color": {
"$ref": "#/components/schemas/color"
},
"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"
},
"double_sided": {
"$ref": "#/components/schemas/double_sided"
},
"extra_service": {
"enum": [
"registered"
],
"type": "string",
"description": "Add an extra service to your letter. See <a href=\"https://www.lob.com/pricing/print-mail#compare\" target=\"_blank\">pricing</a> for extra costs incurred.\n * registered - provides tracking and confirmation for international addresses\n"
},
"return_address": {
"$ref": "#/components/schemas/return_address"
},
"custom_envelope": {
"$ref": "#/components/schemas/custom_envelope_returned"
},
"merge_variables": {
"$ref": "#/components/schemas/merge_variables"
},
"perforated_page": {
"type": "integer",
"nullable": true,
"description": "Required if `return_envelope` is `true`. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to `1`. The blank page added by `address_placement=insert_blank_page` will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_perf_template.pdf\" target=\"_blank\">perforation guide</a>."
},
"return_envelope": {
"$ref": "#/components/schemas/return_envelope_returned"
},
"tracking_events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/tracking_event_normal"
},
"maxItems": 0,
"description": "Tracking events are not populated for registered letters."
},
"tracking_number": {
"type": "string",
"nullable": true,
"description": "The tracking number will appear here when it becomes available.\nDummy tracking numbers are not created in test mode."
},
"address_placement": {
"$ref": "#/components/schemas/address_placement"
}
}
},
{
"$ref": "#/components/schemas/letter_generated_base"
}
]
}
remote_file_url
{
"type": "string",
"pattern": "^https://[-a-zA-Z0-9@:%._+~#=/]{1,256}.(html?|pdf|png|jpg)$",
"description": "The location of a remote file. Remote URLs have a 20 MB file size limit and must be downloaded within 40 seconds.\n"
}
required_address_column_mapping
{
"type": "object",
"title": "Required Address Columns",
"example": {
"name": "recipient_name",
"address_zip": "zip_code",
"address_city": "city",
"address_line1": "primary_line",
"address_state": "state"
},
"required": [
"name",
"address_line1",
"address_city",
"address_state",
"address_zip"
],
"properties": {
"name": {
"type": "string",
"default": null,
"nullable": true,
"description": "The column header from the csv file that should be mapped to the required field `name`"
},
"address_zip": {
"type": "string",
"default": null,
"nullable": true,
"description": "The column header from the csv file that should be mapped to the required field `address_zip`"
},
"address_city": {
"type": "string",
"default": null,
"nullable": true,
"description": "The column header from the csv file that should be mapped to the required field `address_city`"
},
"address_line1": {
"type": "string",
"default": null,
"nullable": true,
"description": "The column header from the csv file that should be mapped to the required field `address_line1`"
},
"address_state": {
"type": "string",
"default": null,
"nullable": true,
"description": "The column header from the csv file that should be mapped to the required field `address_state`"
}
},
"description": "The mapping of column headers in your file to Lob-required fields for the resource created. See our <a href=\"https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2\" target=\"_blank\">Campaign Audience Guide</a> for additional details."
}
resource_description
{
"type": "string",
"nullable": true,
"maxLength": 255,
"description": "An internal description that identifies this resource. Must be no longer than 255 characters.\n"
}
return_address
{
"oneOf": [
{
"$ref": "#/components/schemas/adr_id"
},
{
"$ref": "#/components/schemas/inline_address"
}
],
"description": "Specifies the address the return envelope will be sent back to. This is an optional argument that is available if an account is signed up for the return envelope tracking beta, and has `return_envelope`, and `perforated_page` fields populated in the API request."
}
return_envelope_returned
{
"oneOf": [
{
"type": "boolean"
},
{
"type": "object"
}
],
"properties": {
"id": {
"type": "string",
"description": "The unique ID of the Return Envelope."
},
"url": {
"type": "string",
"description": "The url of the return envelope."
},
"alias": {
"type": "string",
"description": "A quick reference name for the Return Envelope."
},
"object": {
"type": "string",
"description": "Value is resource type."
}
}
}
return_envelope_user_provided
{
"oneOf": [
{
"type": "boolean"
},
{
"type": "string"
}
],
"default": false,
"description": "Indicates if a return envelope is requested for the letter. The value corresponding to this field is by default a boolean. But if the account is signed up for custom return envelopes, the value is of type string and is `no_9_single_window` for a standard return envelope and a custom `return_envelope_id` for non-standard return envelopes.\n\nTo include a return envelope with your letter, set to `true` and specify the `perforated_page`. See <a href=\"https://www.lob.com/pricing/print-mail#compare\" target=\"_blank\">pricing</a> for extra costs incurred."
}
returned
{
"properties": {
"size": {
"$ref": "#/components/schemas/postcard_size"
},
"mail_type": {
"$ref": "#/components/schemas/mail_type"
},
"back_original_url": {
"type": "string",
"format": "uri",
"maxLength": 2083,
"minLength": 1,
"description": "The original URL of the `back` template."
},
"front_original_url": {
"type": "string",
"format": "uri",
"maxLength": 2083,
"minLength": 1,
"description": "The original URL of the `front` template."
}
},
"description": "Properties that the postcards in your Creative should have. Check within in order to add a QR code to your creative."
}
returned_resource
{
"oneOf": [
{
"allOf": [
{
"title": "Postcard Creative",
"required": [
"resource_type",
"details"
],
"properties": {
"details": {
"$ref": "#/components/schemas/returned"
},
"resource_type": {
"enum": [
"postcard"
],
"type": "string",
"description": "Mailpiece type for the creative"
}
}
},
{
"$ref": "#/components/schemas/creative_base"
}
]
},
{
"allOf": [
{
"title": "Letter Creative",
"required": [
"from",
"resource_type",
"details"
],
"properties": {
"details": {
"$ref": "#/components/schemas/letter_details_returned"
},
"resource_type": {
"enum": [
"letter"
],
"type": "string",
"description": "Mailpiece type for the creative"
}
}
},
{
"$ref": "#/components/schemas/creative_base"
}
]
},
{
"allOf": [
{
"title": "Self Mailer Creative",
"required": [
"resource_type",
"details"
],
"properties": {
"details": {
"$ref": "#/components/schemas/self_mailer_details_returned"
},
"resource_type": {
"enum": [
"self_mailer"
],
"type": "string",
"description": "Mailpiece type for the creative"
}
}
},
{
"$ref": "#/components/schemas/creative_base"
}
]
}
]
}
reverse_geocode
{
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/reverse_geocode_id"
},
"object": {
"enum": [
"us_reverse_geocode_lookup"
],
"type": "string",
"default": "us_reverse_geocode_lookup",
"description": "Value is resource type."
},
"addresses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/addresses"
},
"description": "list of addresses\n"
}
}
}
reverse_geocode_id
{
"type": "string",
"pattern": "^us_reverse_geocode_[a-zA-Z0-9_]+$",
"description": "Unique identifier prefixed with `us_reverse_geocode_`."
}
scans
{
"type": "object",
"properties": {
"scan_date": {
"type": "string"
},
"ip_location": {
"type": "string"
}
}
}
secondary_line
{
"type": "string",
"maxLength": 500,
"description": "The secondary delivery line of the address. This field is typically empty but may contain information if `primary_line` is too long.\n"
}
self_mailer
{
"allOf": [
{
"$ref": "#/components/schemas/self_mailer_base"
},
{
"$ref": "#/components/schemas/generated"
},
{
"$ref": "#/components/schemas/from_us"
},
{
"type": "object",
"required": [
"id",
"url",
"use_type"
],
"properties": {
"id": {
"$ref": "#/components/schemas/sfm_id"
},
"fsc": {
"type": "boolean",
"default": false,
"description": "This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `11x9_bifold` self-mailer size."
},
"url": {
"$ref": "#/components/schemas/signed_link"
},
"object": {
"enum": [
"self_mailer"
],
"type": "string",
"default": "self_mailer",
"description": "Value is resource type."
},
"status": {
"$ref": "#/components/schemas/status"
},
"use_type": {
"$ref": "#/components/schemas/sfm_use_type"
},
"campaign_id": {
"$ref": "#/components/schemas/campaign_id"
},
"failure_reason": {
"allOf": [
{
"$ref": "#/components/schemas/failure_reason"
},
{
"nullable": true
}
]
},
"tracking_events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/tracking_event_certified"
},
"description": "An array of certified tracking events ordered by ascending `time`. Not populated in test mode."
},
"inside_template_id": {
"allOf": [
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"type": "string",
"nullable": true
}
],
"description": "The unique ID of the HTML template used for the inside of the self mailer."
},
"outside_template_id": {
"allOf": [
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"type": "string",
"nullable": true
}
],
"description": "The unique ID of the HTML template used for the outside of the self mailer."
},
"inside_template_version_id": {
"allOf": [
{
"$ref": "#/components/schemas/vrsn_id"
},
{
"type": "string",
"nullable": true
}
],
"description": "The unique ID of the specific version of the HTML template used for the inside of the self mailer."
},
"outside_template_version_id": {
"allOf": [
{
"$ref": "#/components/schemas/vrsn_id"
},
{
"type": "string",
"nullable": true
}
],
"description": "The unique ID of the specific version of the HTML template used for the outside of the self mailer."
}
}
}
]
}
self_mailer_base
{
"allOf": [
{
"$ref": "#/components/schemas/editable"
},
{
"type": "object",
"properties": {
"size": {
"$ref": "#/components/schemas/self_mailer_size"
}
}
}
]
}
self_mailer_deletion
{
"properties": {
"id": {
"$ref": "#/components/schemas/sfm_id"
},
"deleted": {
"$ref": "#/components/schemas/deleted"
}
},
"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."
}
self_mailer_details_returned
{
"properties": {
"size": {
"$ref": "#/components/schemas/self_mailer_size"
},
"mail_type": {
"$ref": "#/components/schemas/mail_type"
},
"inside_original_url": {
"type": "string",
"format": "uri",
"maxLength": 2083,
"minLength": 1,
"description": "The original URL of the `inside` template."
},
"outside_original_url": {
"type": "string",
"format": "uri",
"maxLength": 2083,
"minLength": 1,
"description": "The original URL of the `outside` template."
}
},
"description": "Properties that the self mailers in your Creative should have. Check within in order to add a QR code to your creative."
}
self_mailer_details_writable
{
"required": [
"color"
],
"properties": {
"size": {
"$ref": "#/components/schemas/self_mailer_size"
},
"qr_code": {
"$ref": "#/components/schemas/qr_code_campaigns"
},
"mail_type": {
"$ref": "#/components/schemas/mail_type"
}
},
"description": "Properties that the self mailers in your Creative should have. Check within in order to add a QR code to your creative."
}
self_mailer_editable
{
"allOf": [
{
"$ref": "#/components/schemas/self_mailer_base"
},
{
"$ref": "#/components/schemas/input_to"
},
{
"$ref": "#/components/schemas/input_from_us"
},
{
"type": "object",
"required": [
"to",
"inside",
"outside",
"use_type"
],
"properties": {
"fsc": {
"type": "boolean",
"default": false,
"description": "This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `11x9_bifold` self-mailer size."
},
"inside": {
"oneOf": [
{
"$ref": "#/components/schemas/html_string"
},
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"$ref": "#/components/schemas/remote_file_url"
},
{
"$ref": "#/components/schemas/local_file_path"
}
],
"description": "The artwork to use as the inside of your self mailer.\n\nNotes:\n- HTML merge variables should not include delimiting whitespace.\n- PDF, PNG, and JPGs must be sized at 6\"x18\" at 300 DPI, while supplied HTML 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/12x9_sfm_bifold_template.pdf\" target=\"_blank\">12x9 bifold template</a>\n - <a href=\"https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/17_75x9_trifold_sfm_template.pdf\" target=\"_blank\">17.75x9 trifold template</a>\n\n\nSee [here](#section/HTML-Examples) for HTML examples.\n"
},
"outside": {
"oneOf": [
{
"$ref": "#/components/schemas/html_string"
},
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"$ref": "#/components/schemas/remote_file_url"
},
{
"$ref": "#/components/schemas/local_file_path"
}
],
"description": "The artwork to use as the outside of your self mailer.\n\nNotes:\n- HTML merge variables should not include delimiting whitespace.\n- PDF, PNG, and JPGs must be sized at 6\"x18\" at 300 DPI, while supplied HTML will be rendered to the specified `size`.\n\nSee [here](#section/HTML-Examples) for HTML examples.\n"
},
"qr_code": {
"$ref": "#/components/schemas/qr_code"
},
"use_type": {
"$ref": "#/components/schemas/sfm_use_type"
},
"billing_group_id": {
"$ref": "#/components/schemas/billing_group_id"
}
}
}
]
}
self_mailer_size
{
"enum": [
"6x18_bifold",
"11x9_bifold",
"12x9_bifold",
"17.75x9_trifold"
],
"type": "string",
"default": "6x18_bifold",
"description": "Specifies the size of the self mailer. The `17.75x9_trifold` size is in beta. Contact support@lob.com or your account contact to learn more."
}
self_mailer_types
{
"enum": [
"self_mailer.created",
"self_mailer.rendered_pdf",
"self_mailer.rendered_thumbnails",
"self_mailer.deleted",
"self_mailer.delivered",
"self_mailer.failed",
"self_mailer.mailed",
"self_mailer.in_transit",
"self_mailer.in_local_area",
"self_mailer.international_exit",
"self_mailer.processed_for_delivery",
"self_mailer.re-routed",
"self_mailer.returned_to_sender",
"self_mailer.viewed"
],
"type": "string",
"description": "Unique identifier referring to status of self mailer"
}
send_date
{
"type": "string",
"anyOf": [
{
"format": "date-time"
},
{
"format": "date"
}
],
"description": "A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](#section/Cancellation-Windows) applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC."
}
sfm_id
{
"type": "string",
"pattern": "^sfm_[a-zA-Z0-9]+$",
"description": "Unique identifier prefixed with `sfm_`."
}
sfm_use_type
{
"enum": [
"marketing",
"operational",
null
],
"type": "string",
"nullable": true,
"description": "The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)."
}
signed_link
{
"type": "string",
"pattern": "^https://lob-assets.com/(letters|postcards|bank-accounts|checks|self-mailers|cards|order-creatives)/([a-z]{3,4}_[a-z0-9]{15,16}|[a-z]{3}_[a-z0-9]{26}_[a-z]{4}_[a-z0-9]{26})('|_signature)(.pdf|_thumb_[a-z]+_[0-9]+.png|.png)?(version=[a-z0-9]*&)expires=[0-9]{10}&signature=[a-zA-Z0-9-_]+",
"description": "A [signed link](#section/Asset-URLs) served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated."
}
single_line_address
{
"type": "object",
"required": [
"address"
],
"properties": {
"address": {
"type": "string",
"maxLength": 500,
"description": "The entire address in one string (e.g., \"210 King Street 94107\"). _Does not support a recipient and will error when other payload parameters are provided._\n"
}
}
}
single_line_address_intl
{
"type": "object",
"required": [
"address",
"country"
],
"properties": {
"address": {
"type": "string",
"maxLength": 500,
"description": "The entire address in one string (e.g., \"370 Water St C1N 1C4\").\n"
},
"country": {
"$ref": "#/components/schemas/country_extended"
}
}
}
single_redirect_url
{
"type": "string",
"description": "Redirect all QRs in the camapign to a common URL. Add a redirect_url in the request body along with the url as string."
}
snap_pack
{
"allOf": [
{
"$ref": "#/components/schemas/snap_pack_base"
},
{
"$ref": "#/components/schemas/generated"
},
{
"$ref": "#/components/schemas/from_us"
},
{
"type": "object",
"required": [
"id",
"url",
"use_type"
],
"properties": {
"id": {
"$ref": "#/components/schemas/snap_pack_id"
},
"fsc": {
"type": "boolean",
"default": false,
"description": "Contact support@lob.com or your account contact to learn more. Not available for snap_pack currently."
},
"url": {
"$ref": "#/components/schemas/signed_link"
},
"color": {
"$ref": "#/components/schemas/color"
},
"object": {
"enum": [
"snap_pack"
],
"type": "string",
"default": "snap_pack",
"description": "Value is resource type."
},
"status": {
"$ref": "#/components/schemas/status"
},
"use_type": {
"$ref": "#/components/schemas/snap_pack_use_type"
},
"campaign_id": {
"$ref": "#/components/schemas/campaign_id"
},
"failure_reason": {
"allOf": [
{
"$ref": "#/components/schemas/failure_reason"
},
{
"nullable": true
}
]
},
"tracking_events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/tracking_event_normal"
},
"description": "An array of tracking events ordered by ascending `time`. Not populated in test mode."
},
"inside_template_id": {
"allOf": [
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"type": "string",
"nullable": true
}
],
"description": "The unique ID of the HTML template used for the inside of the snap pack."
},
"outside_template_id": {
"allOf": [
{
"$ref": "#/components/schemas/tmpl_id"
},
{
"type": "string",
"nullable": true
}
],
"description": "The unique ID of the HTML template used for the outside of the snap pack."
},
"inside_template_version_id": {
"allOf": [
{
"$ref": "#/components/schemas/vrsn_id"
},
{
"type": "string",
"nullable": true
}
],
"description": "The unique ID of the specific version of the HTML template used for the inside of the snap pack."
},
"outside_template_version_id": {
"allOf": [
{
"$ref": "#/components/schemas/vrsn_id"
},
{
"type": "string",
"nullable": true
}
],
"description": "The unique ID of the specific version of the HTML template used for the outside of the snap pack."
}
}
}
]
}