Postcards 3 endpoints

POST /postcards

Creates a new postcard given information

operationId: postcard_create

Parameters

Name In Required Type Description
Idempotency-Key header optional string

A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide.
idempotency_key query optional string

A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide.

Request Body

required
application/json
schema postcard_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
back object required
front object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional
multipart/form-data
schema postcard_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
back object required
front object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional
application/x-www-form-urlencoded
schema postcard_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
back object required
front object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional

Responses

default

Error
200

Returns a postcard object
POST /postcards
DELETE /postcards/{psc_id}

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 and scheduling. Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition to gain access.

operationId: postcard_delete

Parameters

Name In Required Type Description
psc_id path required

id of the postcard

Responses

default

Error
200

Deleted
DELETE /postcards/{psc_id}
GET /postcards/{psc_id}

Retrieves the details of an existing postcard. You need only supply the unique customer identifier that was returned upon postcard creation.

operationId: postcard_retrieve

Parameters

Name In Required Type Description
psc_id path required

id of the postcard

Responses

default

Error
200

Returns a postcard object
GET /postcards/{psc_id}

Qrcodes 1 endpoints

GET /qr_code_analytics

Returns a list of your QR codes. The QR codes are returned sorted by scan date, with the most recently scanned QR codes appearing first.

operationId: QrCodes_getSortedQrCodes

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
offset query optional integer

An integer that designates the offset at which to begin returning results. Defaults to 0.
include query optional array

Request that the response include the total count by specifying include=["total_count"].
date_created query optional

Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. { "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" } where gt is >, lt is <, gte is ≥, and lte is ≤.
scanned query optional boolean

Filter list of responses to only include QR codes with at least one scan event.
resource_ids query optional array

Filter by the resource ID.

Responses

200

Returns a list of QR Codes and their analytics.
GET /qr_code_analytics

Reversegeocodelookups 1 endpoints

POST /us_reverse_geocode_lookups

Reverse geocode a valid US location with a live API key.

operationId: ReverseGeocodeLookups_usLocationWithLiveApiKey

Parameters

Name In Required Type Description
size query optional integer

Determines the number of locations returned. Possible values are between 1 and 50 and any number higher will be rounded down to 50. Default size is a list of 5 reverse geocoded locations.

Request Body

required
application/json
schema location
Property Type Required
latitude number required
longitude number required
multipart/form-data
schema location
Property Type Required
latitude number required
longitude number required
application/x-www-form-urlencoded
schema location
Property Type Required
latitude number required
longitude number required

Responses

default

Error
200

Returns a zip lookup object if a valid zip was provided.
POST /us_reverse_geocode_lookups

Selfmailers 4 endpoints

GET /self_mailers

Returns a list of your self_mailers. The self_mailers are returned sorted by creation date, with the most recently created self_mailers appearing first.

operationId: SelfMailers_getList

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
before/after query optional

before and after are both optional but only one of them can be in the query at a time.
include query optional array

Request that the response include the total count by specifying include=["total_count"].
date_created query optional

Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. { "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" } where gt is >, lt is <, gte is ≥, and lte is ≤.
metadata query optional

Filter by metadata key-value pair`.
size query optional array

The self mailer sizes to be returned.
scheduled query optional boolean
  • true - only return orders (past or future) where send_date is
    greater than date_created
  • false - only return orders where send_date is equal to date_created
send_date query optional

Filter by ISO-8601 date or datetime, e.g. { "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" } where gt is >, lt is <, gte is ≥, and lte is ≤.
mail_type query optional

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.
sort_by query optional

Sorts items by ascending or descending dates. Use either date_created or send_date, not both.
campaign_id query optional

Filters resources created by the provided campaign id, prefixed with cmp_.
status query optional

A string describing the render status:

  • processed - the rendering process is currently underway.
  • rendered - the rendering process has completed successfully.
  • failed - the rendering process has failed.

Responses

default

Error
200

A dictionary with a data property that contains an array of up to limit self_mailers. Each entry in the array is a separate self_mailer. The previous and next page of self_mailers can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.
If no more self_mailers are available beyond the current set of returned results, the next_url field will be empty.
GET /self_mailers
POST /self_mailers

Creates a new self_mailer given information

operationId: SelfMailers_createNewSelfMailer

Parameters

Name In Required Type Description
Idempotency-Key header optional string

A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide.
idempotency_key query optional string

A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide.

Request Body

required
application/json
schema self_mailer_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
inside object required
outside object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional
multipart/form-data
schema self_mailer_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
inside object required
outside object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional
application/x-www-form-urlencoded
schema self_mailer_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
inside object required
outside object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional

Responses

default

Error
200

Returns a self_mailer object
POST /self_mailers
DELETE /self_mailers/{sfm_id}

Completely removes a self mailer from production. This can only be done if the self mailer’s send_date has not yet passed. If the self mailer is successfully canceled, you will not be charged for it. This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.

operationId: SelfMailers_removeSelfMailer

Parameters

Name In Required Type Description
sfm_id path required

id of the self_mailer

Responses

default

Error
200

Deleted
DELETE /self_mailers/{sfm_id}
GET /self_mailers/{sfm_id}

Retrieves the details of an existing self_mailer. You need only supply the unique self_mailer identifier that was returned upon self_mailer creation.

operationId: SelfMailers_getDetails

Parameters

Name In Required Type Description
sfm_id path required

id of the self_mailer

Responses

default

Error
200

Returns a self_mailer object
GET /self_mailers/{sfm_id}

Snappacks 1 endpoints

POST /snap_packs

Creates a new snap_pack given information

operationId: SnapPacks_createNewSnapPack

Parameters

Name In Required Type Description
Idempotency-Key header optional string

A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide.
idempotency_key query optional string

A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide.

Request Body

required
application/json
schema snap_pack_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
color boolean optional
inside object required
outside object required
use_type string required
billing_group_id string optional
multipart/form-data
schema snap_pack_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
color boolean optional
inside object required
outside object required
use_type string required
billing_group_id string optional

Responses

default

Error
200

Returns a snap_pack object
POST /snap_packs

Templateversions 5 endpoints

GET /templates/{tmpl_id}/versions

Returns a list of template versions for the given template ID. The template versions are sorted by creation date, with the most recently created appearing first.

operationId: TemplateVersions_getList

Parameters

Name In Required Type Description
tmpl_id path required

The ID of the template associated with the retrieved versions
limit query optional integer

How many results to return.
before/after query optional

before and after are both optional but only one of them can be in the query at a time.
include query optional array

Request that the response include the total count by specifying include=["total_count"].
date_created query optional

Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. { "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" } where gt is >, lt is <, gte is ≥, and lte is ≤.

Responses

default

Error
200

A dictionary with a data property that contains an array of up to limit template versions. Each entry in the array is a separate template version object. The previous and next page of template versions can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.
If no more template versions are available beyond the current set of returned results, the next_url field will be empty.
GET /templates/{tmpl_id}/versions
POST /templates/{tmpl_id}/versions

Creates a new template version attached to the specified template.

operationId: TemplateVersions_createNewVersion

Parameters

Name In Required Type Description
tmpl_id path required

The ID of the template the new version will be attached to

Request Body

required
application/json
schema template_version_writable
Property Type Required
html string required
engine string optional
description string optional
required_vars array optional
multipart/form-data
schema template_version_writable
Property Type Required
html string required
engine string optional
description string optional
required_vars array optional
application/x-www-form-urlencoded
schema template_version_writable
Property Type Required
html string required
engine string optional
description string optional
required_vars array optional

Responses

default

Error
200

Returns the template version with the given template and version ids.
POST /templates/{tmpl_id}/versions
DELETE /templates/{tmpl_id}/versions/{vrsn_id}

Permanently deletes a template version. A template’s published_version can not be deleted.

operationId: TemplateVersions_deleteVersion

Parameters

Name In Required Type Description
tmpl_id path required

The ID of the template to which the version belongs.
vrsn_id path required

id of the template_version

Responses

default

Error
200

Deleted
DELETE /templates/{tmpl_id}/versions/{vrsn_id}
GET /templates/{tmpl_id}/versions/{vrsn_id}

Retrieves the template version with the given template and version ids.

operationId: TemplateVersions_get

Parameters

Name In Required Type Description
tmpl_id path required

The ID of the template to which the version belongs.
vrsn_id path required

id of the template_version

Responses

default

Error
200

Returns the template version with the given template and version ids.
GET /templates/{tmpl_id}/versions/{vrsn_id}
POST /templates/{tmpl_id}/versions/{vrsn_id}

Updates the template version with the given template and version ids.

operationId: TemplateVersions_updateTemplateVersion

Parameters

Name In Required Type Description
tmpl_id path required

The ID of the template to which the version belongs.
vrsn_id path required

id of the template_version

Request Body

required
application/json
schema template_version_updatable
Property Type Required
engine string optional
description string optional
required_vars array optional
multipart/form-data
schema template_version_updatable
Property Type Required
engine string optional
description string optional
required_vars array optional
application/x-www-form-urlencoded
schema template_version_updatable
Property Type Required
engine string optional
description string optional
required_vars array optional

Responses

default

Error
200

Returns the template version with the given template and version ids.
POST /templates/{tmpl_id}/versions/{vrsn_id}

Templates 5 endpoints

GET /templates

Returns a list of your templates. The templates are returned sorted by creation date, with the most recently created templates appearing first.

operationId: templates_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
before/after query optional

before and after are both optional but only one of them can be in the query at a time.
include query optional array

Request that the response include the total count by specifying include=["total_count"].
date_created query optional

Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. { "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" } where gt is >, lt is <, gte is ≥, and lte is ≤.
metadata query optional

Filter by metadata key-value pair`.

Responses

default

Error
200

A dictionary with a data property that contains an array of up to limit templates. Each entry in the array is a separate template. The previous and next page of templates can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.
If no more templates are available beyond the current set of returned results, the next_url field will be empty.
GET /templates
POST /templates

Creates a new template for use with the Print & Mail API. In Live mode, you can only have as many non-deleted templates as allotted in your current Print & Mail Edition. If you attempt to create a template past your limit, you will receive a 403 error. There is no limit in Test mode.

operationId: create_template

Request Body

required
application/json
schema template_writable
Property Type Required
html string required
engine string optional
metadata object optional
description string optional
required_vars array optional
multipart/form-data
schema template_writable
Property Type Required
html string required
engine string optional
metadata object optional
description string optional
required_vars array optional
application/x-www-form-urlencoded
schema template_writable
Property Type Required
html string required
engine string optional
metadata object optional
description string optional
required_vars array optional

Responses

default

Error
200

Returns a template object
POST /templates
DELETE /templates/{tmpl_id}

Permanently deletes a template. Deleting a template also deletes its associated versions. Deleted templates can not be used to create postcard, letter, or check resources.

operationId: template_delete

Parameters

Name In Required Type Description
tmpl_id path required

id of the template

Responses

default

Error
200

Deleted
DELETE /templates/{tmpl_id}
GET /templates/{tmpl_id}

Retrieves the details of an existing template. You need only supply the unique template identifier that was returned upon template creation.

operationId: template_retrieve

Parameters

Name In Required Type Description
tmpl_id path required

id of the template

Responses

default

Error
200

Returns a template object
GET /templates/{tmpl_id}
POST /templates/{tmpl_id}

Updates the description and/or published version of the template with the given id. To update the template’s html, create a new version of the template.

operationId: template_update

Parameters

Name In Required Type Description
tmpl_id path required

id of the template

Request Body

required
application/json
schema template_update
Property Type Required
description string optional
published_version string optional
multipart/form-data
schema template_update
Property Type Required
description string optional
published_version string optional
application/x-www-form-urlencoded
schema template_update
Property Type Required
description string optional
published_version string optional

Responses

default

Error
200

Returns the updated template object
POST /templates/{tmpl_id}

Urlshortener 11 endpoints

GET /domains

Retrieve a list of all created domains.

operationId: domain_list

Responses

default

Error
200

Returns a list of all domains.
GET /domains
POST /domains

Add a new custom domain that can be used to create custom links.

operationId: domain_create

Request Body

required
application/json
schema domains
Property Type Required
domain string required
multipart/form-data
schema domains
Property Type Required
domain string required
application/x-www-form-urlencoded
schema domains
Property Type Required
domain string required

Responses

default

Error
200

Returns a domain object with details.
POST /domains
DELETE /domains/{domain_id}

Delete a registered domain. This operation can only be performed if all associated links with the domain are deleted.

operationId: domain_delete

Parameters

Name In Required Type Description
domain_id path required string

Unique identifier for a domain.

Responses

default

Error
200

Returns the deleted link object.
DELETE /domains/{domain_id}
GET /domains/{domain_id}

Retrieve details for a single domain.

operationId: domain_get

Parameters

Name In Required Type Description
domain_id path required string

Unique identifier for a domain.

Responses

default

Error
200

Returns domain related details.
GET /domains/{domain_id}
DELETE /domains/{domain_id}/links

Delete all associated links for a domain

operationId: UrlShortener_deleteAllLinksForDomain

Parameters

Name In Required Type Description
domain_id path required string

Unique identifier for a domain.

Responses

default

Error
200

Returns the deleted objects.
DELETE /domains/{domain_id}/links
GET /links

Retrieves a list of shortened links. The list is sorted by creation date, with the most recently created appearing first.

operationId: links_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
offset query optional integer

An integer that designates the offset at which to begin returning results. Defaults to 0.
include query optional array

Request that the response include the total count by specifying include=["total_count"].
date_created query optional

Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. { "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" } where gt is >, lt is <, gte is ≥, and lte is ≤.
metadata query optional

Filter by metadata key-value pair`.
campaign_id query optional

Filter the links generated for a particular campaign using its campaign id.
clicked query optional boolean

Retrieve the list of links that have been opened.
billing_group_id query optional

Filter the links generated for a particular billing group id.

Responses

default

Error
200

Returns the deleted link object.
GET /links
POST /links/shorten

Given a long URL, shorten your URL either by using a custom domain or Lob’s own short domain.

operationId: link_create

Request Body

required
application/json
schema link_single
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
multipart/form-data
schema link_single
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
application/x-www-form-urlencoded
schema link_single
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional

Responses

default

Error
200

Returns a successfully created link.
POST /links/shorten
POST /links/shorten/bulk

Shortens a list of links in a single request.

operationId: UrlShortener_bulkShortenLinks

Request Body

required
application/json
schema link_list
array of object
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
multipart/form-data
schema link_list
array of object
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
application/x-www-form-urlencoded
schema link_list
array of object
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional

Responses

default

Error
200

Returns all successfully created links
POST /links/shorten/bulk
DELETE /links/{link_id}

Delete the shortened link.

operationId: links_delete

Parameters

Name In Required Type Description
link_id path required string

Unique identifier for a link.

Responses

default

Error
200

Returns the deleted short link object
DELETE /links/{link_id}
GET /links/{link_id}

Retrievs a single shortened link.

operationId: links_get

Parameters

Name In Required Type Description
link_id path required string

Unique identifier for a link.

Responses

default

Error
200

Returns a single link.
GET /links/{link_id}
PATCH /links/{link_id}

Update any of the properties of a shortened link.

operationId: link_update

Parameters

Name In Required Type Description
link_id path required string

Unique identifier for a link.

Request Body

required
application/json
schema link_single
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
multipart/form-data
schema link_single
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
application/x-www-form-urlencoded
schema link_single
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional

Responses

default

Error
200

Returns the updated link.
PATCH /links/{link_id}

Usautocompletions 1 endpoints

POST /us_autocompletions

Given an address prefix consisting of a partial primary line, as well as optional input of city, state, and zip code, this functionality returns up to 10 full US address suggestions. Not all of them will turn out to be valid addresses; they’ll need to be verified.

operationId: UsAutocompletions_getSuggestions

Parameters

Name In Required Type Description
case query optional string

Casing of the verified address. Possible values are upper and proper for uppercased (e.g. “PO BOX”) and proper-cased (e.g. “PO Box”), respectively. Only affects primary_line, city, and state. Default casing is upper.
valid_addresses query optional boolean

Possible values are true and false. If false, not all of the suggestions in the response will be valid addresses; they’ll need to be verified in order to determine the deliverability. The valid_addresses flag will greatly reduce the number of keystrokes needed before reaching an intended address.

Request Body

required
application/json
schema us_autocompletions_writable
Property Type Required
city string optional
state string optional
zip_code string optional
geo_ip_sort boolean optional
address_prefix string required
multipart/form-data
schema us_autocompletions_writable
Property Type Required
city string optional
state string optional
zip_code string optional
geo_ip_sort boolean optional
address_prefix string required
application/x-www-form-urlencoded
schema us_autocompletions_writable
Property Type Required
city string optional
state string optional
zip_code string optional
geo_ip_sort boolean optional
address_prefix string required

Responses

default

Error
200

Returns a US autocompletion object.
POST /us_autocompletions

Usverifications 2 endpoints

POST /bulk/us_verifications

Verify a list of US or US territory addresses with a live API key. Requests to this endpoint with a test API key will return a dummy response based on the primary line you input.

operationId: UsVerifications_bulkVerifyAddresses

Parameters

Name In Required Type Description
case query optional string

Casing of the verified address. Possible values are upper and proper for uppercased (e.g. “PO BOX”) and proper-cased (e.g. “PO Box”), respectively. Only affects recipient, primary_line, secondary_line, urbanization, and last_line. Default casing is upper.

Request Body

required
application/json
schema multiple_components_list
Property Type Required
addresses array required
└ city string optional
└ state string optional
└ zip_code string optional
└ recipient string optional
└ primary_line string required
└ urbanization string optional
└ secondary_line string optional
multipart/form-data
schema multiple_components_list
Property Type Required
addresses array required
└ city string optional
└ state string optional
└ zip_code string optional
└ recipient string optional
└ primary_line string required
└ urbanization string optional
└ secondary_line string optional
application/x-www-form-urlencoded
schema multiple_components_list
Property Type Required
addresses array required
└ city string optional
└ state string optional
└ zip_code string optional
└ recipient string optional
└ primary_line string required
└ urbanization string optional
└ secondary_line string optional

Responses

default

Error
200

Returns a list of US verification objects.
POST /bulk/us_verifications
POST /us_verifications

Verify a US or US territory address with a live API key. The address can be in components (e.g. primary_line is “210 King Street”, zip_code is “94107”) or as a single string (e.g. “210 King Street 94107”), but not as both. Requests using a test API key validate required fields but return empty values unless specific primary_line values are provided. See the US Verifications Test Environment for details.

operationId: us_verification

Parameters

Name In Required Type Description
case query optional string

Casing of the verified address. Possible values are upper and proper for uppercased (e.g. “PO BOX”) and proper-cased (e.g. “PO Box”), respectively. Only affects recipient, primary_line, secondary_line, urbanization, and last_line. Default casing is upper.

Request Body

required
application/json
schema us_verifications_writable
multipart/form-data
schema us_verifications_writable
application/x-www-form-urlencoded
schema us_verifications_writable

Responses

default

Error
200

Returns a US verification object.
POST /us_verifications

Uploads 9 endpoints

GET /uploads

Returns a list of your uploads. Optionally, filter uploads by campaign.

operationId: uploads_list

Parameters

Name In Required Type Description
campaignId query optional

id of the campaign

Responses

200

An array of matching uploads. Each entry in the array is a separate upload.
GET /uploads
POST /uploads

Creates a new upload with the provided properties.

operationId: upload_create

Request Body

required
application/json
schema upload_writable
Property Type Required
metadata object optional
└ columns array required
campaignId string required
mergeVariableColumnMapping object optional
optionalAddressColumnMapping object optional
└ company string required
└ address_line2 string required
└ address_country string required
requiredAddressColumnMapping object optional
└ name string required
└ address_zip string required
└ address_city string required
└ address_line1 string required
└ address_state string required

Responses

201

Upload created successfully
422

Validation Error
POST /uploads
DELETE /uploads/{upl_id}

Delete an existing upload. You need only supply the unique identifier that was returned upon upload creation.

operationId: upload_delete

Parameters

Name In Required Type Description
upl_id path required

id of the upload

Responses

204

Successful Response
DELETE /uploads/{upl_id}
GET /uploads/{upl_id}

Retrieves the details of an existing upload. You need only supply the unique upload identifier that was returned upon upload creation.

operationId: upload_retrieve

Parameters

Name In Required Type Description
upl_id path required

id of the upload

Responses

200

Returns an upload object
404

Not Found Error
422

Validation Error
GET /uploads/{upl_id}
PATCH /uploads/{upl_id}

Update the details of an existing upload. You need only supply the unique identifier that was returned upon upload creation.

operationId: upload_update

Parameters

Name In Required Type Description
upl_id path required

id of the upload

Request Body

required
application/json
schema upload_updatable
Property Type Required
metadata object optional
└ columns array required
originalFilename string optional
mergeVariableColumnMapping object optional
optionalAddressColumnMapping object optional
└ company string required
└ address_line2 string required
└ address_country string required
requiredAddressColumnMapping object optional
└ name string required
└ address_zip string required
└ address_city string required
└ address_line1 string required
└ address_state string required

Responses

200

Returns an upload object
404

Not Found Error
422

Validation Error
PATCH /uploads/{upl_id}
POST /uploads/{upl_id}/exports

Campaign Exports can help you understand exactly which records in a campaign could not be created. By initiating and retrieving an export, you will get row-by-row errors for your campaign. For a step-by-step walkthrough of creating a campaign and exporting failures, see our Campaigns Guide.

Create an export file associated with an upload.

operationId: Uploads_createExportFile

Parameters

Name In Required Type Description
upl_id path required

ID of the upload

Request Body

required
application/json
schema UploadsCreateExportFileRequest
Property Type Required
type string optional

Responses

4XX

Create Export Error
200

Successful Response
POST /uploads/{upl_id}/exports
GET /uploads/{upl_id}/exports/{ex_id}

Retrieves the details of an existing export. You need only supply the unique export identifier that was returned upon export creation. If you try retrieving an export immediately after creating one (i.e., before we’re done processing the export), you will get back an export object with state = in_progress.

operationId: export_retrieve

Parameters

Name In Required Type Description
upl_id path required

ID of the upload
ex_id path required

ID of the export

Responses

200

Returns an export object
GET /uploads/{upl_id}/exports/{ex_id}
POST /uploads/{upl_id}/file

Upload an audience file and associate it with an upload.

operationId: upload_file

Parameters

Name In Required Type Description
upl_id path required

ID of the upload

Request Body

required
multipart/form-data
schema UploadFileRequest
Property Type Required
file string optional

Responses

202

Successful Response
422

Validation Error
POST /uploads/{upl_id}/file
GET /uploads/{upl_id}/report

Retrieves the line item data for each row from the csv file associated with the upload id record. NOTE: This endpoint is currently feature flagged. Please reach out to Lob’s support team if you would like access to this API endpoint.

operationId: report_retrieve

Parameters

Name In Required Type Description
upl_id path required

ID of the upload
status query optional string

The status of line items to filter and retrieve. By default all line items are returned.
limit query optional integer

How many results to return.
offset query optional integer

An integer that designates the offset at which to begin returning results. Defaults to 0.

Responses

200

Returns an report object
403

Forbidden Error
404

Not Found Error
GET /uploads/{upl_id}/report

Ziplookups 1 endpoints

POST /us_zip_lookups

Returns information about a ZIP code

operationId: zip_lookup

Request Body

required
application/json
schema zip5
Property Type Required
zip_code string required
multipart/form-data
schema zip5
Property Type Required
zip_code string required
application/x-www-form-urlencoded
schema zip5
Property Type Required
zip_code string required

Responses

default

Error
200

Returns a zip lookup object if a valid zip was provided.
POST /us_zip_lookups