openapi: 3.0.3 info: title: Lob Ltr_id API version: 1.20.2 description: "Experience direct mail like never before, with unmatched personalization and scalability \x14 all in one intuitive platform." license: name: MIT url: https://mit-license.org/ contact: name: Lob Developer Experience url: https://support.lob.com/ email: lob-openapi@lob.com termsOfService: https://www.lob.com/legal servers: - url: https://api.lob.com/v1 description: production security: - basicAuth: [] tags: - name: Ltr_id paths: /letters/{ltr_id}: parameters: - in: path name: ltr_id description: id of the letter required: true schema: $ref: '#/components/schemas/ltr_id' get: operationId: letter_retrieve summary: Retrieve description: Retrieves the details of an existing letter. You need only supply the unique letter identifier that was returned upon letter creation. tags: - Ltr_id responses: '200': description: Returns a letter object content: application/json: schema: $ref: '#/components/schemas/letter' example: id: ltr_4868c3b754655f90 description: Demo Letter metadata: {} to: id: adr_d3489cd64c791ab5 description: null name: HARRY ZHANG company: null phone: null email: null address_line1: 210 KING ST STE 6100 address_line2: null address_city: SAN FRANCISCO address_state: CA address_zip: 94107-1741 address_country: UNITED STATES metadata: {} date_created: '2017-09-05T15:54:53.264Z' date_modified: '2017-09-05T15:54:53.264Z' deleted: true object: address from: id: adr_b8fb5acf3a2b55db description: null name: LEORE AVIDAR company: null phone: null email: null address_line1: 210 KING ST STE 6100 address_line2: null address_city: SAN FRANCISCO address_state: CA address_zip: 94107-1741 address_country: UNITED STATES metadata: {} date_created: '2017-09-05T15:54:53.264Z' date_modified: '2017-09-05T15:54:53.264Z' deleted: true object: address color: true double_sided: true address_placement: top_first_page return_envelope: false perforated_page: null custom_envelope: null extra_service: null mail_type: usps_first_class url: https://lob-assets.com/letters/ltr_4868c3b754655f90.pdf?expires=1540372221&signature=8r94fse8uam7wGWmW5baxXulU88X2CA carrier: USPS tracking_number: null tracking_events: [] thumbnails: - small: https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=a5fRBJ22ZA78Vgpg34M9UfmHWTS3eha medium: https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=bAzL8sv935PY09FWSkpDpWKkyvGSWYF large: https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=gsKvxXgrm4v4iZD3bOibK7jApNkEMdW merge_variables: name: Harry expected_delivery_date: '2017-09-12' date_created: '2017-09-05T15:54:53.346Z' date_modified: '2017-09-05T15:54:53.346Z' send_date: '2017-09-05T15:54:53.346Z' cards: - id: card_c51ae96f5cebf3e account_id: fa9ea650fc7b31a89f92 description: null url: https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA size: 2.125x3.375 auto_reorder: false reorder_quantity: null raw_url: https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw front_original_url: https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw back_original_url: https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw thumbnails: - small: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg medium: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA large: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw - small: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg medium: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag large: https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw available_quantity: 10000 pending_quantity: 0 countries: null status: rendered mode: test orientation: horizontal threshold_amount: 0 date_created: '2017-08-05T15:54:53.346Z' date_modified: '2017-08-05T15:54:53.346Z' object: card use_type: marketing fsc: false object: letter default: $ref: '#/components/responses/mailpiece_error' x-codeSamples: - lang: Shell source: "curl https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \\\n -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\n" label: CURL - lang: Typescript source: "try {\n const letter= await new LettersApi(config).get('ltr_xxxx');\n} catch (err: any) {\n console.error(err);\n}\n" label: TYPESCRIPT - lang: Javascript source: "Lob.letters.retrieve('ltr_4868c3b754655f90', function (err, res) {\n console.log(err, res);\n});\n" label: NODE - lang: Ruby source: "letterApi = LettersApi.new(config)\n\nbegin\n retrievedLetter = letterApi.get(\"ltr_4868c3b754655f90\")\nrescue => err\n p err.message\nend\n" label: RUBY - lang: Python source: "with ApiClient(configuration) as api_client:\n api = LettersApi(api_client)\n\ntry:\n letter = api.get(\"ltr_4868c3b754655f90\")\nexcept ApiException as e:\n print(e)\n" label: PYTHON - lang: PHP source: "$apiInstance = new OpenAPI\\Client\\Api\\LettersApi($config, new GuzzleHttp\\Client());\n\ntry {\n $result = $apiInstance->get(\"ltr_4868c3b754655f90\");\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n" - lang: Java source: "LettersApi apiInstance = new LettersApi(config);\n\ntry {\n Letter response = apiInstance.get(\"ltr_4868c3b754655f90\");\n} catch (ApiException e) {\n e.printStackTrace();\n}\n" label: JAVA - lang: Elixir source: 'Lob.Letter.find("ltr_4868c3b754655f90") ' label: ELIXIR - lang: CSharp source: "LettersApi api = new LettersApi(config);\n\ntry {\n Letter response = api.get(\"ltr_4868c3b754655f90\");\n} catch (ApiException e) {\n Console.WriteLine(e.ToString());\n}\n" label: CSHARP - lang: Go source: "var context = context.Background()\ncontext = context.WithValue(suite.ctx, lob.ContextBasicAuth, lob.BasicAuth{UserName: os.Getenv(\"\")})\n\nvar apiClient = *lob.NewAPIClient(configuration)\n\nfetchedLetter, _, err := apiClient.LettersApi.Get(context,\"ltr_4868c3b754655f90\").Execute()\n\nif err != nil {\n return err\n}\n" label: GO delete: operationId: letter_cancel summary: Cancel description: Completely removes a letter from production. This can only be done if the letter has a `send_date` and the `send_date` has not yet passed. If the letter is successfully canceled, you will not be charged for it. Read more on [cancellation windows](#section/Cancellation-Windows) and [scheduling](#section/Scheduled-Mailings). Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition to gain access. tags: - Ltr_id responses: '200': $ref: '#/components/responses/letter_deleted' default: $ref: '#/components/responses/mailpiece_error' x-codeSamples: - lang: Shell source: "curl -X DELETE https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \\\n -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\n" label: CURL - lang: Typescript source: "try {\n const deleteLetter = await new LettersApi(config).cancel('ltr_xxxx')\n} catch (err: any) {\n console.error(err);\n}\n" label: TYPESCRIPT - lang: Javascript source: "Lob.letters.cancel('ltr_4868c3b754655f90', function (err, res) {\n console.log(err, res);\n});\n" label: NODE - lang: Ruby source: "letterApi = LettersApi.new(config)\n\nbegin\n deletedLetter = letterApi.cancel(\"ltr_4868c3b754655f90\")\nrescue => err\n p err.message\nend\n" label: RUBY - lang: Python source: "with ApiClient(configuration) as api_client:\n api = LettersApi(api_client)\n\ntry:\n deleted_resource = api.cancel(\"ltr_4868c3b754655f90\")\nexcept ApiException as e:\n print(e)\n" label: PYTHON - lang: PHP source: "$apiInstance = new OpenAPI\\Client\\Api\\LettersApi($config, new GuzzleHttp\\Client());\n\ntry {\n $result = $apiInstance->cancel(\"ltr_4868c3b754655f90\");\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n" - lang: Java source: "LettersApi apiInstance = new LettersApi(config);\n\ntry {\n LetterDeletion response = apiInstance.cancel(\"ltr_4868c3b754655f90\");\n} catch (ApiException e) {\n e.printStackTrace();\n}\n" label: JAVA - lang: Elixir source: 'Lob.Letter.destroy("ltr_4868c3b754655f90") ' label: ELIXIR - lang: CSharp source: "LettersApi api = new LettersApi(config);\n\ntry {\n LetterDeletion response = api.cancel(\"ltr_4868c3b754655f90\");\n} catch (ApiException e) {\n Console.WriteLine(e.ToString());\n}\n" label: CSHARP - lang: Go source: "var context = context.Background()\ncontext = context.WithValue(suite.ctx, lob.ContextBasicAuth, lob.BasicAuth{UserName: os.Getenv(\"\")})\n\nvar apiClient = *lob.NewAPIClient(configuration)\n\ndeletedLetter, _, err := apiClient.LettersApi.Cancel(context, \"ltr_4868c3b754655f90\").Execute()\n\nif err != nil {\n return err\n}\n" label: GO components: schemas: date_created: type: string format: date-time description: A timestamp in ISO 8601 format of the date the resource was created. custom_envelope_returned: type: object description: A nested custom envelope object containing more information about the custom envelope used or `null` if a custom envelope was not used. required: - id - url - object properties: id: type: string description: The unique identifier of the custom envelope used. maxLength: 40 url: type: string description: The url of the envelope asset used. object: type: string enum: - envelope default: envelope nullable: true tracking_event_details: type: object required: - event - description - action_required properties: event: type: string enum: - package_accepted - package_arrived - package_departed - package_processing - package_processed - package_in_local_area - delivery_scheduled - out_for_delivery - pickup_available - delivered - package_forwarded - returned_to_sender - address_issue - contact_carrier - delayed - delivery_attempted - delivery_rescheduled - location_inaccessible - notice_left - package_damaged - package_disposed - package_held - package_lost - package_unclaimed - package_undeliverable - reschedule_delivery - other description: 'Find the full table [here](#tag/Tracking-Events). A detailed substatus about the event: * `package_accepted` - Package has been accepted into the carrier network for delivery. * `package_arrived` - Package has arrived at an intermediate location in the carrier network. * `package_departed` - Package has departed from an intermediate location in the carrier network. * `package_processing` - Package is processing at an intermediate location in the carrier network. * `package_processed` - Package has been processed at an intermediate location. * `package_in_local_area` - Package is at a location near the end destination. * `delivery_scheduled` - Package is scheduled for delivery. * `out_for_delivery` - Package is out for delivery. * `pickup_available` - Package is available for pickup at carrier location. * `delivered` - Package has been delivered. * `package_forwarded` - Package has been forwarded. * `returned_to_sender` - Package is to be returned to sender. * `address_issue` - Address information is incorrect. Contact carrier to ensure delivery. * `contact_carrier` - Contact the carrier for more information. * `delayed` - Delivery of package is delayed. * `delivery_attempted` - Delivery of package has been attempted. Contact carrier to ensure delivery. * `delivery_rescheduled` - Delivery of package has been rescheduled. * `location_inaccessible` - Delivery location inaccessible to carrier. Contact carrier to ensure delivery. * `notice_left` - Carrier left notice during attempted delivery. Follow carrier instructions on notice. * `package_damaged` - Package has been damaged. Contact carrier for more details. * `package_disposed` - Package has been disposed. * `package_held` - Package held at carrier location. Contact carrier for more details. * `package_lost` - Package has been lost. Contact carrier for more details. * `package_unclaimed` - Package is unclaimed. * `package_undeliverable` - Package is not able to be delivered. * `reschedule_delivery` - Contact carrier to reschedule delivery. * `other` - Unrecognized carrier status. ' description: type: string description: The description as listed in the description for event. notes: type: string description: Event-specific notes from USPS about the tracking event. action_required: type: boolean description: '`true` if action is required by the end recipient, `false` otherwise. ' adr_id: type: string description: Unique identifier prefixed with `adr_`. pattern: ^adr_[a-zA-Z0-9]+$ error: type: object 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. required: - error properties: error: type: object required: - message - status_code - code properties: message: type: string description: A human-readable message with more details about the error example: Rate limit exceeded. Please wait 5 seconds and try your request again. status_code: $ref: '#/components/schemas/failure_status_code' code: type: string 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 description: 'A pre-defined string identifying an error. Error codes fall into three categories: **GENERIC** * `bad_request` - 422: an invalid request was made. See error message for details. * `conflict` - 409/422: this operation would leave data in a conflicted state. * `feature_limit_reached` - 403: the account has reached its resource limit and requires upgrading to add more. * `internal_server_error` - 500: an error has occured on Lob''s servers. Please try request again. * `invalid` - 422: an invalid request was made. See error message for details. * `not_deletable` - 422: an attempt was made to delete a resource, but the resource cannot be deleted. * `not_found` - 404: the requested resource was not found. * `request_timeout` - 408: the request took too long. Please try again. * `service_unavailable` - 503: the Lob servers are temporarily unavailable. Please try agian. * `unrecognized_endpoint` - 404: the requested endpoint doesn''t exist. * `unsupported_lob_version` - 422: an unsupported Lob API version was requested. **ADVANCED** * `address_length_exceeds_limit` - 422: the sum of to.address_line1 and to.address_line2 cannot surpass 50 characters. * `bank_account_already_verified` - 422: the bank account has already been verified. * `bank_error` - 422: there''s an issue with the bank account. * `billing_address_required` - 403: in order to create a live mail piece, your account needs to set up a billing address. * `custom_envelope_inventory_depleted` - 422: custom envelope inventory is depleted, and more will need to be ordered. * `deleted_bank_account` - 404: checks cannot be created with a deleted bank account. * `failed_deliverability_strictness` - 422: the `to` address doesn''t meet strictness requirements. See Account Settings to configure strictness. * `file_pages_below_min` - 422: not enough pages. * `file_pages_exceed_max` - 422: too many pages. * `file_size_exceeds_limit` - 422: the file size is too large. See description for details. * `foreign_return_address` - 422: the `from` address must be a US address. * `inconsistent_page_dimensions` - 422: all pages of the input file must have the same dimensions. * `invalid_bank_account` - 422: the provided bank routing number is invalid. * `invalid_bank_account_verification` - 422: verification amounts do not match. * `invalid_check_international` - 422: checks cannot be sent internationally. * `invalid_country_covid` - 422: the postal service in the specified country is currently unable to process the request due to COVID-19 restrictions. * `invalid_file` - 422: the file is invalid. * `invalid_file_dimensions` - 422: file dimensions are incorrect for the selected mail type. * `invalid_file_download_time` - 422: file download from remote server took too long. * `invalid_file_url` - 422: the file URL when creating a resource is invalid. * `invalid_image_dpi` - 422: DPI must be at least 300. * `invalid_international_feature` - 422: the specified product cannot be sent to the destination. * `invalid_perforation_return_envelope` - 422: both `return_envelope` and `perforation` must be used together. * `invalid_template_html` - 422: the provided HTML is invalid. * `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. * `merge_variable_required` - 422: a required merge variable is missing. * `merge_variable_whitespace` - 422: merge variable names cannot contain whitespace. * `payment_method_unverified` - 401: you must have a verified bank account or credit card to submit live requests. * `pdf_encrypted` - 422: an encrypted PDF was provided. * `special_characters_restricted` - 422: cannot use special characters for merge variable names. * `unembedded_fonts` - 422: the provided PDF contains non-standard unembedded fonts. See description for details. **AUTHENTICATION** * `email_required` - 401: account must have a verified email address before creating live resources. * `invalid_api_key` - 401/403: the API key is invalid. * `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. * `rate_limit_exceeded` - 429: requests were sent too quickly and must be slowed down. * `unauthorized` - 401: the request isn''t authorized. * `unauthorized_token` - 401: token isn''t authorized. ' return_envelope_returned: oneOf: - type: boolean - type: object properties: id: type: string description: The unique ID of the Return Envelope. alias: type: string description: A quick reference name for the Return Envelope. url: type: string description: The url of the return envelope. object: type: string description: Value is resource type. letter: oneOf: - allOf: - title: regular - $ref: '#/components/schemas/no_extra_service' - allOf: - title: registered - $ref: '#/components/schemas/registered' - allOf: - title: certified - $ref: '#/components/schemas/certified' signed_link: type: string 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. 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-_]+ tmpl_id: type: string description: Unique identifier prefixed with `tmpl_`. ID of a saved [HTML template](#section/HTML-Templates). pattern: ^tmpl_[a-zA-Z0-9]+$ send_date: type: string 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. anyOf: - format: date-time - format: date buckslip_order: allOf: - $ref: '#/components/schemas/lob_base' - type: object properties: id: $ref: '#/components/schemas/bo_id' buckslip_id: $ref: '#/components/schemas/buckslip_id' status: description: The status of the buckslip order. enum: - pending - printing - available - cancelled - depleted type: string quantity_ordered: description: The quantity of buckslips ordered. type: number default: 0 unit_price: description: The unit price for the buckslip order. type: number default: 0 inventory: description: The inventory of the buckslip order. type: number default: 0 cancelled_reason: description: The reason for cancellation. type: string availability_date: type: string format: date-time description: A timestamp in ISO 8601 format of the date the resource was created. expected_availability_date: type: string format: date-time description: The fixed deadline for the buckslips to be printed. campaign_id: title: campaign_id description: Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. type: string pattern: ^(cmp|camp)_[a-zA-Z0-9]+$ nullable: true company: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc). ' maxLength: 40 nullable: true ltr_id: type: string description: Unique identifier prefixed with `ltr_`. pattern: ^ltr_[a-zA-Z0-9]+$ failure_reason: type: object description: An object describing the reason for failure if the resource failed to render. properties: remediation: type: string description: Instructions on how to resolve the error failure_reason: type: string description: Reason failure occurred errors: type: array nullable: true items: $ref: '#/components/schemas/failure_reason_error' letter_generated_base: allOf: - $ref: '#/components/schemas/generated' - $ref: '#/components/schemas/from' - type: object required: - id - from - use_type properties: url: $ref: '#/components/schemas/signed_link' id: $ref: '#/components/schemas/ltr_id' template_id: allOf: - description: The unique ID of the HTML template used for the letter. - $ref: '#/components/schemas/tmpl_id' template_version_id: allOf: - description: The unique ID of the specific version of the HTML template used for the letter. type: string - $ref: '#/components/schemas/vrsn_id' campaign_id: $ref: '#/components/schemas/campaign_id' use_type: $ref: '#/components/schemas/ltr_use_type' fsc: type: boolean description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `A4` letter size. default: false status: $ref: '#/components/schemas/status' failure_reason: allOf: - $ref: '#/components/schemas/failure_reason' - nullable: true object: type: string description: Value is resource type. enum: - letter default: letter address_editable_intl: allOf: - $ref: '#/components/schemas/address_fields_intl' - type: object anyOf: - title: address obj with `name` defined required: - name - title: address obj with `company` defined required: - company properties: description: $ref: '#/components/schemas/resource_description' name: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. ' maxLength: 40 nullable: true company: $ref: '#/components/schemas/company' phone: type: string description: Must be no longer than 40 characters. maxLength: 40 nullable: true email: type: string description: Must be no longer than 100 characters. maxLength: 100 nullable: true address_country: $ref: '#/components/schemas/country_extended' metadata: $ref: '#/components/schemas/metadata' from: type: object properties: from: $ref: '#/components/schemas/address' address_us: allOf: - $ref: '#/components/schemas/lob_base' - type: object required: - id - address_line1 - address_city - address_state - address_zip anyOf: - title: address obj with `name` defined required: - name - title: address obj with `company` defined required: - company properties: id: $ref: '#/components/schemas/adr_id' object: type: string description: Value is resource type. enum: - address default: address description: $ref: '#/components/schemas/resource_description' name: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. ' maxLength: 40 nullable: true company: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc). ' maxLength: 40 nullable: true phone: type: string description: Must be no longer than 40 characters. maxLength: 40 nullable: true email: type: string description: Must be no longer than 100 characters. maxLength: 100 nullable: true address_line1: type: string description: The primary number, street name, and directional information. maxLength: 64 address_line2: type: string description: An optional field containing any information which can't fit into line 1. maxLength: 64 nullable: true address_city: type: string maxLength: 200 address_state: type: string description: 2 letter state short-name code pattern: ^[a-zA-Z]{2}$ address_zip: type: string description: 'Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`. ' pattern: ^\d{5}(-\d{4})?$ address_country: type: string enum: - UNITED STATES description: Full name of country minLength: 13 maxLength: 13 metadata: $ref: '#/components/schemas/metadata' recipient_moved: type: boolean description: 'Only returned for accounts on certain Print & Mail Editions. Value is `true` if the address was altered because the recipient filed for a National Change of Address Linkage (NCOALink), `false` if the NCOALink check was run but no altered address was found, and `null` if the NCOALink check was not run. The NCOALink check does not happen for non-US addresses, for non-deliverable US addresses, or for addresses created before the NCOALink feature was added to your account. ' nullable: true example: id: adr_e68217bd744d65c8 description: Harry - Office name: HARRY ZHANG company: LOB phone: '5555555555' email: harry@lob.com address_line1: 210 KING ST STE 6100 address_line2: null address_city: SAN FRANCISCO address_state: CA address_zip: 94107-1741 address_country: UNITED STATES metadata: {} recipient_moved: false date_created: '2019-08-12T00:16:00.361Z' date_modified: '2019-08-12T00:16:00.361Z' object: address country_extended: type: string description: Must be a 2 letter country short-name code (ISO 3166). Does not accept `US`, `AS`, `PR`, `FM`, `GU`, `MH`, `MP`, `PW`, or `VI`. For these addresses, please use the US verification API. Also does not accept `PS`, which is not currently supported. enum: - AD - AE - AF - AG - AI - AL - AN - AO - AQ - AR - AT - AU - AW - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BM - BN - BO - BQ - BR - BS - BT - BW - BY - BZ - CA - CD - CG - CH - CI - CK - CL - CM - CN - CO - CR - CS - CU - CV - CW - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FO - FR - GA - GB - GD - GE - GH - GI - GL - GM - GN - GQ - GR - GS - GT - GW - GY - HK - HN - HR - HT - HU - ID - IE - IL - IN - IO - IQ - IR - IS - IT - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MG - MK - ML - MM - MN - MO - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PG - PH - PK - PL - PN - PT - PY - QA - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UY - UZ - VA - VC - VE - VG - VN - VU - WS - YE - ZA - ZM - ZW registered: allOf: - type: object required: - extra_service - color properties: extra_service: type: string enum: - registered description: "Add an extra service to your letter. See pricing for extra costs incurred.\n * registered - provides tracking and confirmation for international addresses\n" tracking_number: type: string description: 'The tracking number will appear here when it becomes available. Dummy tracking numbers are not created in test mode.' nullable: true tracking_events: description: Tracking events are not populated for registered letters. type: array items: $ref: '#/components/schemas/tracking_event_normal' maxItems: 0 return_address: $ref: '#/components/schemas/return_address' description: $ref: '#/components/schemas/resource_description' metadata: $ref: '#/components/schemas/metadata' merge_variables: $ref: '#/components/schemas/merge_variables' send_date: $ref: '#/components/schemas/send_date' mail_type: $ref: '#/components/schemas/mail_type' color: $ref: '#/components/schemas/color' double_sided: $ref: '#/components/schemas/double_sided' address_placement: $ref: '#/components/schemas/address_placement' return_envelope: $ref: '#/components/schemas/return_envelope_returned' perforated_page: type: integer 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 perforation guide. nullable: true custom_envelope: $ref: '#/components/schemas/custom_envelope_returned' - $ref: '#/components/schemas/letter_generated_base' bo_id: type: string description: Unique identifier prefixed with `bo_`. pattern: ^bo_[a-zA-Z0-9]+$ card_description: type: string description: Description of the card. maxLength: 255 nullable: true color: type: boolean description: Set this key to `true` if you would like to print in color. Set to `false` if you would like to print in black and white. inline_address_us: allOf: - $ref: '#/components/schemas/address_editable_us' - type: object required: - address_line1 - address_city - address_state - address_zip tracking_event_normal: allOf: - $ref: '#/components/schemas/tracking_event_base' - type: object required: - type - name properties: type: description: non-Certified postcards, self mailers, letters, checks and snap packs type: string enum: - normal name: type: string enum: - Mailed - In Transit - In Local Area - Processed for Delivery - Delivered - Re-Routed - Returned to Sender - International Exit description: "Name of tracking event (for normal postcards, self mailers, letters, checks and snap packs):\n\n * `Mailed` - The mailpiece has been handed off to and accepted by USPS\n and is en route. More about\n Mailed.\n Note this data is only available in Enterprise editions of\n Lob. Contact Sales if\n you want access to this feature.\n\n * `In Transit` - The mailpiece is being processed at the entry/origin facility.\n\n * `In Local Area` - The mailpiece is being processed at the destination facility.\n\n * `Processed for Delivery` - The mailpiece has been greenlit for\n delivery at the recipient's nearest postal facility. The mailpiece\n should reach the mailbox within 1 business day of this tracking\n event.\n\n * `Delivered` - The mail piece has been delivered to \n the recipients address. The final scan is generated when the mail \n carrier's GPS unit leaves the delivery area.\n\n * `Re-Routed` - The mailpiece is re-routed due to recipient change of\n address, address errors, or USPS relabeling of barcode/ID tag\n area.\n\n * `Returned to Sender` - The mailpiece is being returned to sender due\n to barcode, ID tag area, or address errors.\n \n * `International Exit` - The mail piece has been processed to \n ship to a destination abroad. This is typically the last \n scan a US-originated international mail piece will receive \n from the USPS.\n\nMore about tracking\n" details: description: Will be `null` for `type=normal` events type: object enum: - null nullable: true location: type: string description: 'The zip code in which the scan event occurred. Null for `Mailed` events. ' nullable: true buckslip_base: type: object properties: description: $ref: '#/components/schemas/buckslip_description' size: description: The size of the buckslip enum: - 8.75x3.75 type: string default: 8.75x3.75 vrsn_id: type: string description: Unique identifier prefixed with `vrsn_`. pattern: ^vrsn_[a-zA-Z0-9]+$ card_id: type: string description: Unique identifier prefixed with `card_`. pattern: ^card_[a-zA-Z0-9]+$ resource_description: type: string description: 'An internal description that identifies this resource. Must be no longer than 255 characters. ' maxLength: 255 nullable: true thumbnail: type: object properties: small: $ref: '#/components/schemas/signed_link' medium: $ref: '#/components/schemas/signed_link' large: $ref: '#/components/schemas/signed_link' no_extra_service: allOf: - type: object required: - color properties: tracking_events: description: An array of tracking events ordered by ascending `time`. type: array items: $ref: '#/components/schemas/tracking_event_normal' cards: description: An array of cards associated with a specific letter type: array items: $ref: '#/components/schemas/card' nullable: true buckslips: description: An array of buckslip(s) associated with a specific letter type: array items: $ref: '#/components/schemas/buckslip' nullable: true return_address: $ref: '#/components/schemas/return_address' description: $ref: '#/components/schemas/resource_description' metadata: $ref: '#/components/schemas/metadata' merge_variables: $ref: '#/components/schemas/merge_variables' send_date: $ref: '#/components/schemas/send_date' mail_type: $ref: '#/components/schemas/mail_type' color: $ref: '#/components/schemas/color' double_sided: $ref: '#/components/schemas/double_sided' address_placement: $ref: '#/components/schemas/address_placement' return_envelope: $ref: '#/components/schemas/return_envelope_returned' perforated_page: type: integer 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 perforation guide. nullable: true custom_envelope: $ref: '#/components/schemas/custom_envelope_returned' - $ref: '#/components/schemas/letter_generated_base' address_placement: type: string enum: - top_first_page - insert_blank_page - bottom_first_page_center - bottom_first_page description: "Specifies the location of the address information that will show through the double-window envelope. To see how this will impact your letter design, view our letter template.\nSome values are exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.\n * `top_first_page` - (default) print address information at the top of your provided first page\n * `insert_blank_page` - insert a blank address page at the beginning of your file (you will be charged for the extra page)\n * `bottom_first_page_center` - **(exclusive, deprecation planned within a few months)** print address information at the bottom center of your provided first page\n * `bottom_first_page` - **(exclusive)** print address information at the bottom of your provided first page\n" default: top_first_page address_intl: allOf: - $ref: '#/components/schemas/lob_base' - type: object required: - id - address_line1 - address_country anyOf: - title: address obj with `name` defined required: - name - title: address obj with `company` defined required: - company properties: id: $ref: '#/components/schemas/adr_id' description: $ref: '#/components/schemas/resource_description' name: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. ' maxLength: 40 nullable: true company: $ref: '#/components/schemas/company' phone: type: string description: Must be no longer than 40 characters. maxLength: 40 nullable: true email: type: string description: Must be no longer than 100 characters. maxLength: 100 nullable: true metadata: $ref: '#/components/schemas/metadata' address_line1: type: string maxLength: 200 address_line2: type: string maxLength: 200 nullable: true address_city: type: string maxLength: 200 nullable: true address_state: description: Will be returned as a full string type: string maxLength: 200 nullable: true address_zip: type: string description: Optional postal code. maxLength: 40 nullable: true address_country: description: Full name of country type: string maxLength: 200 enum: - AFGHANISTAN - ALBANIA - ALGERIA - AMERICAN SAMOA - ANDORRA - ANGOLA - ANGUILLA - ANTARCTICA - ANTIGUA AND BARBUDA - ARGENTINA - ARUBA - AUSTRALIA - AUSTRIA - AZERBAIJAN - BAHRAIN - BANGLADESH - BARBADOS - BELARUS - BELGIUM - BELIZE - BENIN - BERMUDA - BHUTAN - BOLIVIA (PLURINATIONAL STATE OF) - BONAIRE, SAINT EUSTATIUS AND SABA - BOSNIA AND HERZEGOVINA - BOTSWANA - BRAZIL - BRITISH INDIAN OCEAN TERRITORY - BRITISH VIRGIN ISLANDS - BRUNEI DARUSSALAM - BULGARIA - BURKINA FASO - BURUNDI - CABO VERDE - CAMBODIA - CAMEROON - CANADA - CAYMAN ISLANDS - CENTRAL AFRICAN REPUBLIC - CHAD - CHILE - CHINA - COLOMBIA - COMOROS - CONGO - CONGO, DEMOCRATIC REPUBLIC OF THE - COOK ISLANDS - COSTA RICA - C�TE D'IVOIRE - CROATIA - CUBA - CURA�AO - CYPRUS - CZECH REPUBLIC - DENMARK - DJIBOUTI - DOMINICA - DOMINICAN REPUBLIC - ECUADOR - EGYPT - EL SALVADOR - EQUATORIAL GUINEA - ERITREA - ESTONIA - ESWATINI - ETHIOPIA - FALKLAND ISLANDS (MALVINAS) - FAROE ISLANDS - FIJI - FINLAND - FRANCE - GABON - GAMBIA - GEORGIA - GERMANY - GHANA - GIBRALTAR - GREECE - GREENLAND - GRENADA - GUATEMALA - GUINEA - GUINEA-BISSAU - GUYANA - HAITI - HOLY SEE - HONDURAS - HONG KONG - HUNGARY - ICELAND - INDIA - INDONESIA - IRAN (ISLAMIC REPUBLIC OF) - IRAQ - IRELAND - ISRAEL - ITALY - JAMAICA - JAPAN - JORDAN - KAZAKHSTAN - KENYA - KIRIBATI - KOREA (DEMOCRATIC PEOPLES REPUBLIC OF) - KOREA, REPUBLIC OF - KUWAIT - KYRGYZSTAN - LAO PEOPLES DEMOCRATIC REPUBLIC - LATVIA - LEBANON - LESOTHO - LIBERIA - LIBYA - LIECHTENSTEIN - LITHUANIA - LUXEMBOURG - MACAO - MACEDONIA - MADAGASCAR - MALAWI - MALAYSIA - MALDIVES - MALI - MALTA - MAURITANIA - MAURITIUS - MEXICO - MOLDOVA, REPUBLIC OF - MONACO - MONGOLIA - MONTENEGRO - MONTSERRAT - MOROCCO - MOZAMBIQUE - MYANMAR - NAMIBIA - NAURU - NEPAL - NETHERLAND ANTILLES - NETHERLANDS - NEW ZEALAND - NICARAGUA - NIGER - NIGERIA - NIUE - NORFOLK ISLAND - NORWAY - OMAN - PAKISTAN - PANAMA - PAPUA NEW GUINEA - PARAGUAY - PERU - PHILIPPINES - PITCAIRN - POLAND - PORTUGAL - QATAR - ROMANIA - RUSSIAN FEDERATION - RWANDA - SAINT HELENA - SAINT KITTS AND NEVIS - SAINT LUCIA - SAINT VINCENT AND THE GRENADINES - SAMOA - SAN MARINO - SAO TOME AND PRINCIPE - SAUDI ARABIA - SENEGAL - SERBIA - SEYCHELLES - SIERRA LEONE - SINGAPORE - SINT MAARTEN - SLOVAKIA - SLOVENIA - SOLOMON ISLANDS - SOMALIA - SOUTH AFRICA - SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS - SOUTH SUDAN - SPAIN - SRI LANKA - SUDAN - SURINAME - SWEDEN - SWITZERLAND - SYRIAN ARAB REPUBLIC - TAIWAN - TAJIKISTAN - TANZANIA - THAILAND - THE BAHAMAS - TIMOR-LESTE - TOGO - TOKELAU - TONGA - TRINIDAD AND TOBAGO - TUNISIA - TURKEY - TURKMENISTAN - TURKS AND CAICOS ISLANDS - TUVALU - UGANDA - UKRAINE - UNITED ARAB EMIRATES - UNITED KINGDOM - URUGUAY - UZBEKISTAN - VANUATU - VENEZUELA - VIET NAM - WESTERN SAHARA - YEMEN - ZAMBIA - ZIMBABWE object: type: string description: Value is resource type. enum: - address default: address example: id: adr_e68217bd744d65c8 description: Harry - Office name: Harry Zhang company: Lob phone: '5555555555' email: harry@lob.com metadata: {} address_line1: 370 WATER ST address_line2: '' address_city: SUMMERSIDE address_state: PRINCE EDWARD ISLAND address_zip: C1N 1C4 address_country: CANADA tracking_event_base: type: object description: As mail pieces travel through the mail stream, USPS scans their unique barcodes, and Lob processes these mail scans to generate tracking events. required: - id - date_created - date_modified - object properties: id: $ref: '#/components/schemas/evnt_id' time: type: string format: date-time description: A timestamp in ISO 8601 format of the date USPS registered the event. date_created: $ref: '#/components/schemas/date_created' date_modified: $ref: '#/components/schemas/date_modified' object: allOf: - $ref: '#/components/schemas/object' - type: string enum: - tracking_event default: tracking_event double_sided: type: boolean description: Set this attribute to `true` for double sided printing, or `false` for for single sided printing. Defaults to `true`. default: true evnt_id: type: string description: Unique identifier prefixed with `evnt_`. pattern: ^evnt_[a-zA-Z0-9]+$ mail_type: type: string enum: - usps_first_class - usps_standard description: 'A string designating the mail postage type: * `usps_first_class` - (default) * `usps_standard` - a cheaper option which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. ' default: usps_first_class deleted: type: boolean description: Only returned if the resource has been successfully deleted. ltr_use_type: 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). type: string enum: - marketing - operational - null nullable: true letter_deletion: 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. properties: id: $ref: '#/components/schemas/ltr_id' deleted: $ref: '#/components/schemas/deleted' generated: type: object required: - to - carrier properties: to: $ref: '#/components/schemas/address' carrier: type: string enum: - USPS default: USPS thumbnails: type: array items: $ref: '#/components/schemas/thumbnail' expected_delivery_date: $ref: '#/components/schemas/expected_delivery_date' date_created: $ref: '#/components/schemas/date_created' date_modified: $ref: '#/components/schemas/date_modified' deleted: $ref: '#/components/schemas/deleted' 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 address_fields_intl: type: object required: - address_line1 - address_country properties: address_line1: type: string description: The primary number, street name, and directional information. maxLength: 200 address_line2: type: string description: An optional field containing any information which can't fit into line 1. maxLength: 200 nullable: true address_city: type: string maxLength: 200 nullable: true address_state: type: string maxLength: 200 nullable: true address_zip: type: string description: Optional postal code. maxLength: 40 nullable: true lob_base: type: object required: - date_created - date_modified - object properties: date_created: $ref: '#/components/schemas/date_created' date_modified: $ref: '#/components/schemas/date_modified' deleted: $ref: '#/components/schemas/deleted' object: $ref: '#/components/schemas/object' merge_variables: type: object description: 'You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `''`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `|`, `}`, `~`. More instructions can be found in our guide to using html and merge variables. Depending on your Merge Variable strictness setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs.' maxLength: 25000 nullable: true address_editable_us: allOf: - $ref: '#/components/schemas/address_fields_us' - type: object anyOf: - title: address obj with `name` defined required: - name - title: address obj with `company` defined required: - company properties: description: $ref: '#/components/schemas/resource_description' name: type: string description: 'Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. ' maxLength: 40 nullable: true company: $ref: '#/components/schemas/company' phone: type: string description: Must be no longer than 40 characters. maxLength: 40 nullable: true email: type: string description: Must be no longer than 100 characters. maxLength: 100 nullable: true address_country: type: string enum: - US default: US metadata: $ref: '#/components/schemas/metadata' metadata: type: object additionalProperties: type: string description: 'Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. ''{"customer_id" : "NEWYORK2015"}'' Nested objects are not supported. See [Metadata](#section/Metadata) for more information.' maxLength: 500 pattern: '[^"\\]{0,500}' address: oneOf: - $ref: '#/components/schemas/address_us' - $ref: '#/components/schemas/address_intl' buckslip_description: type: string description: Description of the buckslip. maxLength: 255 nullable: true failure_status_code: type: integer enum: - 401 - 403 - 404 - 413 - 422 - 429 - 500 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" tracking_event_certified: allOf: - $ref: '#/components/schemas/tracking_event_base' - type: object required: - type - name properties: type: description: a Certified letter tracking event type: string enum: - certified name: type: string enum: - Mailed - In Transit - In Local Area - Processed for Delivery - Pickup Available - Delivered - Re-Routed - Returned to Sender - Issue description: "Name of tracking event for Certified letters. Letters sent with USPS Certified Mail are fully tracked by USPS, therefore their tracking events have an additional details object with more detailed information about the tracking event. Some certified tracking event names have multiple meanings, noted in the list here. See the description of the details object for the full set of combined certified tracking event name meanings.\n\n * `Mailed` - Package has been accepted into the carrier network for delivery.\n\n * `In Transit` - Maps to four distinct stages of transit.\n\n * `In Local Area` - Package is at a location near the end destination.\n\n * `Processed for Delivery` - Maps to two distinct stages of delivery.\n\n * `Pickup Available` - Package is available for pickup at carrier location.\n\n * `Delivered` - Package has been delivered.\n\n * `Re-Routed` - Package has been forwarded.\n\n * `Returned to Sender` - Package is to be returned to sender.\n\n * `Issue` - Maps to (at least) 15 possible issues, some of which are actionable.\n" details: $ref: '#/components/schemas/tracking_event_details' location: type: string description: 'The zip code in which the event occurred if it exists, otherwise will be the name of a Regional Distribution Center if it exists, otherwise will be null. ' nullable: true object: type: string description: Value is resource type. address_fields_us: type: object required: - address_line1 - address_city - address_state - address_zip properties: address_line1: type: string description: The primary number, street name, and directional information. maxLength: 64 address_line2: type: string description: An optional field containing any information which can't fit into line 1. maxLength: 64 nullable: true address_city: type: string maxLength: 200 address_state: type: string description: 2 letter state short-name code pattern: ^[a-zA-Z]{2}$ address_zip: type: string description: 'Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`. ' pattern: ^\d{5}(-\d{4})?$ buckslip_id: type: string description: Unique identifier prefixed with `bck_`. pattern: ^bck_[a-zA-Z0-9]+$ card: allOf: - $ref: '#/components/schemas/lob_base' - $ref: '#/components/schemas/card_base' - required: - description - type: object required: - id - url - auto_reorder - reorder_quantity - raw_url - front_original_url - back_original_url - thumbnails - available_quantity - pending_quantity - status - orientation - threshold_amount - object properties: id: $ref: '#/components/schemas/card_id' url: description: The signed link for the card. maxLength: 2083 minLength: 1 type: string format: uri auto_reorder: description: True if the cards should be auto-reordered. type: boolean default: false reorder_quantity: description: The number of cards to be reordered. type: integer nullable: true raw_url: description: The raw URL of the card. maxLength: 2083 minLength: 1 type: string format: uri front_original_url: description: The original URL of the front template. maxLength: 2083 minLength: 1 type: string format: uri back_original_url: description: The original URL of the back template. maxLength: 2083 minLength: 1 type: string format: uri thumbnails: type: array items: $ref: '#/components/schemas/thumbnail' available_quantity: description: The available quantity of cards. type: integer default: 0 pending_quantity: description: The pending quantity of cards. type: integer default: 0 status: title: The status of the card. enum: - processed - rendered type: string orientation: description: The orientation of the card. enum: - horizontal - vertical type: string default: horizontal threshold_amount: description: The threshold amount of the card type: integer default: 0 object: description: object enum: - card type: string default: card failure_reason_error: type: object description: Failure error details properties: url: type: string description: Failed URL of asset nullable: true host: type: string description: URL host nullable: true path: type: string description: URL path nullable: true protocol: type: string description: Network protocol nullable: true remediation: type: string description: Instructions on how to resolve the error nullable: true error_type: type: string description: HTTP response status code message or service defined error nullable: true status_code: type: number description: HTTP response status codes if the error is asset related nullable: true status: type: string enum: - processed - rendered - failed description: 'A string describing the PDF render status: * `processed` - the rendering process is currently in progress. * `rendered` - a PDF has been successfully rendered of the mailpiece. * `failed` - one or more issues has caused the rendering process to fail. ' card_base: type: object properties: description: $ref: '#/components/schemas/card_description' size: description: The size of the card enum: - 3.375x2.125 - 2.125x3.375 type: string default: 2.125x3.375 date_modified: type: string format: date-time description: A timestamp in ISO 8601 format of the date the resource was last modified. expected_delivery_date: type: string description: A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. format: date return_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. oneOf: - $ref: '#/components/schemas/adr_id' - $ref: '#/components/schemas/inline_address' buckslip: allOf: - $ref: '#/components/schemas/lob_base' - $ref: '#/components/schemas/buckslip_base' - required: - description - type: object required: - id - auto_reorder - reorder_quantity - threshold_amount - url - raw_url - front_original_url - back_original_url - thumbnails - available_quantity - allocated_quantity - onhand_quantity - pending_quantity - projected_quantity - buckslip_orders - stock - weight - finish - status - object properties: id: $ref: '#/components/schemas/buckslip_id' auto_reorder: description: True if the buckslips should be auto-reordered. type: boolean default: false reorder_quantity: description: The number of buckslips to be reordered. type: integer nullable: true threshold_amount: description: The threshold amount of the buckslip type: integer default: 0 url: description: The signed link for the buckslip. maxLength: 2083 minLength: 1 type: string format: uri raw_url: description: The raw URL of the buckslip. maxLength: 2083 minLength: 1 type: string format: uri front_original_url: description: The original URL of the front template. maxLength: 2083 minLength: 1 type: string format: uri back_original_url: description: The original URL of the back template. maxLength: 2083 minLength: 1 type: string format: uri thumbnails: type: array items: $ref: '#/components/schemas/thumbnail' available_quantity: description: The available quantity of buckslips. type: number default: 0 allocated_quantity: description: The allocated quantity of buckslips. type: number default: 0 onhand_quantity: description: The onhand quantity of buckslips. type: number default: 0 pending_quantity: description: The pending quantity of buckslips. type: number default: 0 projected_quantity: description: The sum of pending and onhand quantities of buckslips. type: number default: 0 buckslip_orders: description: An array of buckslip orders that are associated with the buckslip. type: array items: $ref: '#/components/schemas/buckslip_order' minItems: 0 stock: title: The stock of the buckslip. enum: - text - cover type: string weight: title: The weight of the buckslip. enum: - 80# type: string finish: title: The finish of the buckslip. enum: - gloss - matte type: string status: title: The status of the buckslip. enum: - processed - rendered - failed type: string object: description: object enum: - buckslip type: string default: buckslip inline_address: oneOf: - $ref: '#/components/schemas/inline_address_us' - $ref: '#/components/schemas/inline_address_intl' certified: allOf: - type: object required: - extra_service - tracking_events - color properties: extra_service: type: string enum: - certified - certified_return_receipt description: "Add an extra service to your letter. See pricing 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: #10 envelope and flat envelope (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" tracking_number: type: string description: 'The tracking number will be here immediately upon creation. Dummy tracking numbers are created in test mode.' nullable: true tracking_events: description: An array of certified tracking events ordered by ascending `time`. Not populated in test mode. type: array items: $ref: '#/components/schemas/tracking_event_certified' return_address: $ref: '#/components/schemas/return_address' description: $ref: '#/components/schemas/resource_description' metadata: $ref: '#/components/schemas/metadata' merge_variables: $ref: '#/components/schemas/merge_variables' send_date: $ref: '#/components/schemas/send_date' mail_type: $ref: '#/components/schemas/mail_type' color: $ref: '#/components/schemas/color' double_sided: $ref: '#/components/schemas/double_sided' address_placement: $ref: '#/components/schemas/address_placement' return_envelope: $ref: '#/components/schemas/return_envelope_returned' perforated_page: type: integer 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 perforation guide. nullable: true custom_envelope: $ref: '#/components/schemas/custom_envelope_returned' - $ref: '#/components/schemas/letter_generated_base' responses: mailpiece_error: description: Error content: application/json: schema: $ref: '#/components/schemas/error' example: error: code: not_found message: to address not found status_code: 404 letter_deleted: description: Deleted content: application/json: schema: $ref: '#/components/schemas/letter_deletion' example: id: ltr_123456789 deleted: true securitySchemes: basicAuth: type: http scheme: basic x-webhooks: events: post: summary: Events description: Information about an event operationId: event tags: - Events responses: '200': $ref: '#/components/responses/events' tracking_events: post: summary: Tracking Events description: Information about tracking events operationId: tracking_event tags: - Tracking Events responses: '200': $ref: '#/components/responses/tracking_events' x-tagGroups: - name: Overview tags: - Introduction - Authentication - Getting Started - SDKs and Tools - name: Address Book tags: - Addresses - National Change of Address - name: Print and Mail API tags: - Postcards - Self Mailers - Letters - Checks - Snap Packs - Booklets - Bank Accounts - Templates - Template Versions - Template Design - Manage Mail - name: Campaigns API (BETA) tags: - Campaigns - Creatives - Uploads - name: Informed Delivery Campaign API tags: - Informed Delivery Campaign - name: Address Verification API tags: - US Verifications - US Verification Types - US Autocompletions - Reverse Geocode Lookups - Zip Lookups - Identity Validation - Intl Verifications - name: Webhooks tags: - Webhooks - Events - Tracking Events - name: Special Features tags: - Billing Groups - Buckslips - Buckslip Orders - Cards - Card Orders - QR Codes - URL Shortener - name: Appendix tags: - Beta Program - Errors - Rate Limiting - Requests and Responses - Test and Live Environments - Versioning and Changelog