openapi: 3.0.3 info: title: Lob Psc_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: Psc_id paths: /postcards/{psc_id}: parameters: - in: path name: psc_id description: id of the postcard required: true schema: $ref: '#/components/schemas/psc_id' get: operationId: postcard_retrieve summary: Retrieve description: Retrieves the details of an existing postcard. You need only supply the unique customer identifier that was returned upon postcard creation. tags: - Psc_id responses: '200': description: Returns a postcard object content: application/json: schema: $ref: '#/components/schemas/postcard' examples: basic: value: id: psc_208e45e48d271294 description: null metadata: {} to: id: adr_210a8d4b0b76d77b description: null name: null company: LOB 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: '2018-12-08T03:01:07.651Z' date_modified: '2018-12-08T03:01:07.651Z' object: address url: https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA carrier: USPS front_template_id: null back_template_id: null date_created: '2021-03-24T22:51:42.838Z' date_modified: '2021-03-24T22:51:42.838Z' send_date: '2021-03-24T22:51:42.838Z' use_type: marketing fsc: false object: postcard full: value: id: psc_0e03d1ad7d31f151 description: null metadata: {} to: id: adr_c7cb63d68f8d6 description: null name: JANE DOE company: LOB phone: '5555555555' email: jane.doe@lob.com address_line1: 370 WATER ST address_line2: '' address_city: SUMMERSIDE address_state: PE address_zip: C1N 1C4 address_country: CANADA metadata: {} date_created: '2018-12-08T03:01:07.651Z' date_modified: '2018-12-08T03:01:07.651Z' object: address recipient_moved: false from: id: adr_210a8d4b0b76d77b 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: '2018-12-08T03:01:07.651Z' date_modified: '2018-12-08T03:01:07.651Z' object: address url: https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA carrier: USPS front_template_id: tmpl_93c369f06171958 back_template_id: tmpl_93c369f06171958 front_template_version_id: vrsn_a83e044941c393b back_template_version_id: vrsn_a83e044941c393b tracking_events: [] size: 6x11 mail_type: usps_first_class merge_variables: {} 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 expected_delivery_date: '2021-03-30' date_created: '2021-03-24T22:51:42.838Z' date_modified: '2021-03-24T22:51:42.838Z' send_date: '2021-03-24T22:51:42.838Z' use_type: marketing fsc: false object: postcard default: $ref: '#/components/responses/mailpiece_error' x-codeSamples: - lang: Shell source: "curl https://api.lob.com/v1/postcards/psc_5c002b86ce47537a \\\n -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\n" label: CURL - lang: Typescript source: "try {\n const postcard = await new PostCardsApi(config).get('psc_xxxx');\n} catch (err: any) {\n console.error(err);\n}\n" label: TYPESCRIPT - lang: Javascript source: "Lob.postcards.retrieve('psc_5c002b86ce47537a', 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 = PostcardsApi(api_client)\n\ntry:\n postcard = api.get(\"psc_5c002b86ce47537a\")\nexcept ApiException as e:\n print(e)\n" label: PYTHON - lang: PHP source: "$apiInstance = new OpenAPI\\Client\\Api\\PostcardsApi($config, new GuzzleHttp\\Client());\n\ntry {\n $result = $apiInstance->get(\"psc_5c002b86ce47537a\");\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n" - lang: Java source: "PostcardsApi apiInstance = new PostcardsApi(config);\n\ntry {\n Postcard response = apiInstance.get(\"psc_5c002b86ce47537a\");\n} catch (ApiException e) {\n e.printStackTrace();\n}\n" label: JAVA - lang: Elixir source: 'Lob.Postcard.find("psc_5c002b86ce47537a") ' label: ELIXIR - lang: CSharp source: "PostcardsApi api = new PostcardsApi(config);\n\ntry {\n Postcard response = api.get(\"psc_5c002b86ce47537a\");\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\nfetchedPostcard, _, err := apiClient.PostcardsApi.Get(context,\"psc_5c002b86ce47537a\").Execute()\n\nif err != nil {\n return err\n}\n" label: GO delete: operationId: postcard_delete summary: Cancel description: Completely removes a postcard from production. This can only be done if the postcard has a `send_date` and the `send_date` has not yet passed. If the postcard 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: - Psc_id responses: '200': $ref: '#/components/responses/postcard_deleted' default: $ref: '#/components/responses/mailpiece_error' x-codeSamples: - lang: Shell source: "curl -X DELETE https://api.lob.com/v1/postcards/psc_5c002b86ce47537a \\\n -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:\n" label: CURL - lang: Typescript source: "try {\n const deletePostcard = await new PostcardsApi(config).cancel('psc_xxxx');\n} catch (err: any) {\n console.error(err);\n}\n" label: TYPESCRIPT - lang: Javascript source: "Lob.postcards.cancel('psc_5c002b86ce47537a', function (err, res) {\n console.log(err, res);\n});\n" label: NODE - lang: Ruby source: "postcardApi = PostcardsApi.new(config)\n\nbegin\n deletedPostcard = postcardApi.cancel(\"psc_4868c3b754655f90\")\nrescue => err\n p err.message\nend\n" label: RUBY - lang: Python source: "with ApiClient(configuration) as api_client:\n api = PostcardsApi(api_client)\n\ntry:\n deleted_resource = api.cancel(\"psc_5c002b86ce47537a\")\nexcept ApiException as e:\n print(e)\n" label: PYTHON - lang: PHP source: "$apiInstance = new OpenAPI\\Client\\Api\\PostcardsApi($config, new GuzzleHttp\\Client());\n\ntry {\n $result = $apiInstance->cancel(\"psc_5c002b86ce47537a\");\n} catch (Exception $e) {\n echo $e->getMessage(), PHP_EOL;\n}\n" - lang: Java source: "PostcardsApi apiInstance = new PostcardsApi(config);\n\ntry {\n PostcardDeletion response = apiInstance.cancel(\"psc_5c002b86ce47537a\");\n} catch (ApiException e) {\n e.printStackTrace();\n}\n" label: JAVA - lang: Elixir source: 'Lob.Postcard.destroy("psc_5c002b86ce47537a") ' label: ELIXIR - lang: CSharp source: "PostcardsApi api = new PostcardsApi(config);\n\ntry {\n PostcardDeletion response = api.cancel(\"psc_5c002b86ce47537a\");\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\ndeletedPostcard, _, err := apiClient.PostcardsApi.Cancel(context, \"psc_5c002b86ce47537a\").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. postcard_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/psc_id' deleted: $ref: '#/components/schemas/deleted' postcard_base: allOf: - $ref: '#/components/schemas/editable' - type: object properties: size: $ref: '#/components/schemas/postcard_size' 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. ' 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-_]+ 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 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 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' 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 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 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' 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 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' front_template_id: type: string 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. pattern: ^tmpl_[a-zA-Z0-9]+$ nullable: true back_template_id: type: string 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. pattern: ^tmpl_[a-zA-Z0-9]+$ nullable: true front_template_version_id: type: string 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. pattern: ^vrsn_[a-zA-Z0-9]+$ nullable: true back_template_version_id: type: string 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. pattern: ^vrsn_[a-zA-Z0-9]+$ nullable: true tracking_events: description: An array of tracking_event objects ordered by ascending `time`. Will not be populated for postcards created in test mode. type: array items: $ref: '#/components/schemas/tracking_event_normal' nullable: true url: $ref: '#/components/schemas/signed_link' campaign_id: $ref: '#/components/schemas/campaign_id' use_type: $ref: '#/components/schemas/psc_use_type' fsc: type: boolean description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `4x6` or `A5` postcard sizes. 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: - postcard default: postcard 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 postcard_size: type: string enum: - 4x6 - 6x9 - 6x11 description: 'Specifies the size of the postcard. Only `4x6` postcards can be sent to international destinations. ' default: 4x6 editable: type: object properties: description: $ref: '#/components/schemas/resource_description' metadata: $ref: '#/components/schemas/metadata' mail_type: $ref: '#/components/schemas/mail_type' merge_variables: $ref: '#/components/schemas/merge_variables' send_date: $ref: '#/components/schemas/send_date' 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. 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' psc_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 from_us: type: object properties: from: $ref: '#/components/schemas/address_us' 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 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' 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" object: type: string description: Value is resource type. 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. ' 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 psc_id: type: string description: Unique identifier prefixed with `psc_`. pattern: ^psc_[a-zA-Z0-9]+$ 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 postcard_deleted: description: Deleted content: application/json: schema: $ref: '#/components/schemas/postcard_deletion' example: id: psc_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