Skip to content

LettrLabs Public API Documentation (1.0.0)

LettrLabs Public API Documentation.

Download OpenAPI description
LettrLabs_API_Reference.json
LettrLabs_API_Reference.yaml
Languages
Servers
Mock server

https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/

https://app.lettrlabs.com/api/

Conversions

Operations

Orders

Operations

Create from Template

Request

Create an order using a specified template Id.

Security
apikey
Bodyapplication/jsonrequired

Template to use

templateIdinteger(int32)

The Id of the template to use from within the portal

curl -i -X POST \
  https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "templateId": 0
  }'

Responses

Successful operation

Bodyapplication/json
profileobject(profile)
payloadobject(externalOrdersCreateOrderResponseVm)
errorsArray of strings
hasErrorsboolean
warningsArray of strings
hasWarningsboolean
metadataobject
Response
application/json
{
  "profile": {
    "id": 0,
    "aadId": "1cbad290-069a-4527-be23-a0c144b5302d",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "created": "2019-08-24T14:15:22Z",
    "shouldProcessQrCodes": true
  },
  "payload": {
    "orderId": 0,
    "status": "string"
  },
  "errors": [
    "string"
  ],
  "hasErrors": true,
  "warnings": [
    "string"
  ],
  "hasWarnings": true,
  "metadata": {
    "property1": {},
    "property2": {}
  }
}

Retrieve

Request

Retrieve all orders created by OpenAPI calls. This endpoint does not return orders created on-platform.

Security
apikey
Query
OrderIdsArray of integers(int32)

Filter orders by a list of order IDs separated by comma.

OrderStatusstring

Filter orders by status (e.g., 'Draft', 'Mailed').

Paidboolean

Filter orders by whether they are paid or not.

ProductTypestring

Filter orders by product type.

PostageTypestring

Filter orders by postage type.

ShowRecipientsboolean

Filter whether to return recipient information.

Skipinteger(int32)

Used for pagination, the number of records to skip. Defaults to 0.

Takeinteger(int32)

Used for pagination, the number of records to retrieve. Defaults to 100.

curl -i -X GET \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order?OrderIds=0&OrderStatus=string&Paid=true&ProductType=string&PostageType=string&ShowRecipients=true&Skip=0&Take=0' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

Successful operation

Bodyapplication/json
string(binary)
Response
application/json
"string"

Delete

Request

Deletes an order that is in draft or edits needs status.

Security
apikey
Query
Idinteger(int32)required

The Id of the order to delete.

curl -i -X DELETE \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order/{id}?Id=0' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

Successful operation

Bodyapplication/json
profileobject(profile)
payloadobject(externalOrdersDeleteOrderResponseVm)
errorsArray of strings
hasErrorsboolean
warningsArray of strings
hasWarningsboolean
metadataobject
Response
application/json
{
  "profile": {
    "id": 0,
    "aadId": "1cbad290-069a-4527-be23-a0c144b5302d",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "created": "2019-08-24T14:15:22Z",
    "shouldProcessQrCodes": true
  },
  "payload": {
    "orderId": 0,
    "status": "string"
  },
  "errors": [
    "string"
  ],
  "hasErrors": true,
  "warnings": [
    "string"
  ],
  "hasWarnings": true,
  "metadata": {
    "property1": {},
    "property2": {}
  }
}

Proof

Request

Retrieve the auto-generated proof for a specified order in PDF format. The proof contains front, page and envelope (if applicable) pages.

Security
apikey
Query
Idinteger(int32)required

The Id of the order to generate proof.

Recipientinteger(int32)

Recipient Id to substitute mail merge fields.

curl -i -X GET \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order/{id}/proof/{recipient?}=&Id=0&Recipient=0' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

Successful operation

Bodyapplication/pdf
string(binary)
Response
No content

Analytics

Request

Retrieve order analytics such as delivery, number of recipients and order status from a given order id.

Security
apikey
Query
Idinteger(int32)required

The Id of the order to retrieve analytics information from.

curl -i -X GET \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order/{id}/analytics?Id=0' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

Successful operation

Bodyapplication/json
profileobject(profile)
payloadobject(externalOrdersGetOrderStatistics)
errorsArray of strings
hasErrorsboolean
warningsArray of strings
hasWarningsboolean
metadataobject
Response
application/json
{
  "profile": {
    "id": 0,
    "aadId": "1cbad290-069a-4527-be23-a0c144b5302d",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "created": "2019-08-24T14:15:22Z",
    "shouldProcessQrCodes": true
  },
  "payload": {
    "qrCode": { … },
    "orderId": 0,
    "status": "string"
  },
  "errors": [
    "string"
  ],
  "hasErrors": true,
  "warnings": [
    "string"
  ],
  "hasWarnings": true,
  "metadata": {
    "property1": {},
    "property2": {}
  }
}

Transactions

Request

Retrieve transaction data from order id.

Security
apikey
Query
Idinteger(int32)required

The Id of the order to retrieve transaction information from.

curl -i -X GET \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order/{id}/transaction?Id=0' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

Successful operation

Bodyapplication/json
profileobject(profile)
payloadobject(externalOrdersGetOrderFinancialData)
errorsArray of strings
hasErrorsboolean
warningsArray of strings
hasWarningsboolean
metadataobject
Response
application/json
{
  "profile": {
    "id": 0,
    "aadId": "1cbad290-069a-4527-be23-a0c144b5302d",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "created": "2019-08-24T14:15:22Z",
    "shouldProcessQrCodes": true
  },
  "payload": {
    "volume": 0,
    "totalPrice": 0.1,
    "costPerPiece": 0.1,
    "detail": { … },
    "discount": { … },
    "orderId": 0,
    "status": "string"
  },
  "errors": [
    "string"
  ],
  "hasErrors": true,
  "warnings": [
    "string"
  ],
  "hasWarnings": true,
  "metadata": {
    "property1": {},
    "property2": {}
  }
}

Checkout Summary

Request

Calculate and retrieves the line item cost, production and estimated delivery details for a specific order for review prior to executing the checkout. This is not required to be called before executing a checkout.

Security
apikey
Query
Idinteger(int32)required

The Id of the order to calculate checkout details.

PostageTypestring

The type of postage for the order. Available values: Standard, FirstClass.

ProductionSpeedstring

The speed of production for the order. Available values: Normal, ExpeditedFaster, ExpeditedFastest.

HoldUntilDatestring(date-time)

The date to hold order production until. This date must be further in the future than the normal estimated production completion date.

curl -i -X GET \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order/{id}/checkout?Id=0&PostageType=string&ProductionSpeed=string&HoldUntilDate=2019-08-24T14%3A15%3A22Z' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

Successful operation

Bodyapplication/json
profileobject(profile)
payloadobject(externalOrdersGetCheckoutResponseVm)
errorsArray of strings
hasErrorsboolean
warningsArray of strings
hasWarningsboolean
metadataobject
Response
application/json
{
  "profile": {
    "id": 0,
    "aadId": "1cbad290-069a-4527-be23-a0c144b5302d",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "created": "2019-08-24T14:15:22Z",
    "shouldProcessQrCodes": true
  },
  "payload": {
    "lineItems": [ … ],
    "credits": [ … ],
    "totalCharges": 0.1,
    "totalTax": 0.1,
    "totalCredits": 0.1,
    "balance": 0.1,
    "productionSpeeds": { … },
    "productionSpeedPrices": { … },
    "postageTypePrices": { … },
    "estimatedDeliveryDateMin": "2019-08-24T14:15:22Z",
    "estimatedDeliveryDateMax": "2019-08-24T14:15:22Z",
    "orderId": 0,
    "status": "string"
  },
  "errors": [
    "string"
  ],
  "hasErrors": true,
  "warnings": [
    "string"
  ],
  "hasWarnings": true,
  "metadata": {
    "property1": {},
    "property2": {}
  }
}

Checkout

Request

Executes the checkout process for a specified order using its unique Order Id. Upon success, credits or payment methods will be charged for the order. To review the cost prior to execution, call Checkout Review.

Security
apikey
Query
Idinteger(int32)required

The Id of the order to execute checkout and finalize the transaction.

Bodyapplication/jsonrequired

The body of the checkout request including postage type, production speed, and hold until date.

postageTypestring

The type of postage for the order. Available values: Standard, FirstClass.

productionSpeedstring

The speed of production for the order. Available values: Normal, ExpeditedFaster, ExpeditedFastest.

holdUntilDatestring(date-time)

The date to hold order production until. This date must be further in the future than the normal estimated production completion date.

autoBillboolean

If set to true, allow auto-charging of your default payment method if insufficient credits are available in your account to complete the transaction.

curl -i -X POST \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order/{id}/checkout?Id=0' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "postageType": "string",
    "productionSpeed": "string",
    "holdUntilDate": "2019-08-24T14:15:22Z",
    "autoBill": true
  }'

Responses

Successful operation

Bodyapplication/json
profileobject(profile)
payloadobject(externalOrdersPostCheckoutResponseVm)
errorsArray of strings
hasErrorsboolean
warningsArray of strings
hasWarningsboolean
metadataobject
Response
application/json
{
  "profile": {
    "id": 0,
    "aadId": "1cbad290-069a-4527-be23-a0c144b5302d",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "created": "2019-08-24T14:15:22Z",
    "shouldProcessQrCodes": true
  },
  "payload": {
    "orderId": 0,
    "status": "string"
  },
  "errors": [
    "string"
  ],
  "hasErrors": true,
  "warnings": [
    "string"
  ],
  "hasWarnings": true,
  "metadata": {
    "property1": {},
    "property2": {}
  }
}

Retrieve Recipients

Request

Retrieve a list of recipients associated to a specific order.

Security
apikey
Query
Idinteger(int32)required

The Id of the order to retrieve the recipient list from.

Querystring

Search filter for recipient data. Filter by recipient name, address or organization.

Skipinteger(int32)

For pagination: Number of records to skip.

Takeinteger(int32)

For pagination: Number of records to retrieve.

curl -i -X GET \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order/{id}/recipients?Id=0&Query=string&Skip=0&Take=0' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

Successful operation

Bodyapplication/json
string(binary)
Response
application/json
"string"

Delete Recipients

Request

Delete recipients associated with a specific order in draft or edits needed status.

Security
apikey
Bodyapplication/jsonrequired

Recipients to delete.

recipientsIdsArray of integers(int32)

Enum of Recipient Ids to delete from draft of edits needed order.

curl -i -X DELETE \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order/{id}/recipients' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "recipientsIds": [
      0
    ]
  }'

Responses

Successful operation

Bodyapplication/json
payloadobject(externalOrdersDeleteRecipientsResponseVm)
errorsArray of strings
warningsArray of strings
hasErrorsboolean
hasWarningsboolean
Response
application/json
{
  "payload": {
    "orderId": 0,
    "status": "string"
  },
  "errors": [
    "string"
  ],
  "warnings": [
    "string"
  ],
  "hasErrors": true,
  "hasWarnings": true
}

Add Recipients

Request

Add recipients to a specified order in draft or edits needed status. Recipients will run through address validation, and the response will return how many are valid. Any recipients that have incomplete addresses will not be added to the order. Define mail-merge, image-merge, return address override, and other metadata at the recipient level.

Security
apikey
Query
Idinteger(int32)required

The Id of the order to add recipients to.

Bodyapplication/jsonrequired

List of Recipients to add to order.

recipientsArray of objects(externalOrdersRecipientVm)required

Array of recipient Ids to add to order.

recipients[].​idinteger(int32)
recipients[].​addressobject or null(externalOrdersRecipientAddressVm)

Recipient Mailing Address. Where the piece will be mailed to.

recipients[].​personalobject or null(externalOrdersRecipientPersonalDataVm)

Recipient Personal Information

recipients[].​metadataobject or null(externalOrdersRecipientMetadataVm)

Recipient Metadata. This is used for Mail-Merge and Image-merge fields to personalize the mailing to the individual.

curl -i -X PUT \
  'https://docs.lettrlabs.com/_mock/lettrlabs_api_reference/v1/order/{id}/recipients:append?Id=0' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "recipients": [
      {
        "id": 0,
        "address": {
          "address1": "string",
          "address2": "string",
          "city": "string",
          "state": "string",
          "zipCode": "string",
          "zip4": "string",
          "zip2": "string",
          "country": "string"
        },
        "personal": {
          "firstName": "string",
          "lastName": "string",
          "toOrganization": "string",
          "salutation": "string"
        },
        "metadata": {
          "dpvConfirmationCode": "string",
          "custom1": "string",
          "custom2": "string",
          "custom3": "string",
          "custom4": "string",
          "custom5": "string",
          "custom6": "string",
          "image1": "string",
          "image2": "string",
          "image3": "string",
          "image4": "string",
          "image5": "string",
          "image6": "string",
          "salutation": "string",
          "returnTitle": "string",
          "returnFirstName": "string",
          "returnLastName": "string",
          "returnOrganization": "string",
          "returnAddress1": "string",
          "returnAddress2": "string",
          "returnCity": "string",
          "returnZip": "string",
          "returnState": "string",
          "email": "string",
          "qrUrl": "string",
          "text": "string",
          "text2": "string",
          "radiusPinStreet": "string",
          "radiusPinAddress": "string",
          "fullAddress": "string"
        }
      }
    ]
  }'

Responses

Successful operation

Bodyapplication/json
profileobject(profile)
payloadobject(externalOrdersAddRecipientsToOrderResponseVm)
errorsArray of strings
hasErrorsboolean
warningsArray of strings
hasWarningsboolean
metadataobject
Response
application/json
{
  "profile": {
    "id": 0,
    "aadId": "1cbad290-069a-4527-be23-a0c144b5302d",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "created": "2019-08-24T14:15:22Z",
    "shouldProcessQrCodes": true
  },
  "payload": {
    "totalRecipients": 0,
    "deliverable": { … },
    "undeliverable": { … },
    "orderId": 0,
    "status": "string"
  },
  "errors": [
    "string"
  ],
  "hasErrors": true,
  "warnings": [
    "string"
  ],
  "hasWarnings": true,
  "metadata": {
    "property1": {},
    "property2": {}
  }
}

Automations

Operations

Order Recipient Analytics

Operations

Address Book

Operations