API ReferenceOrders
Append recipients to an order
Adds recipients to an existing order without replacing the ones already on it. Accepts up to 5,000 recipients per request. The order must be editable — status Draft or Edits Needed; once a checkout has been accepted (Paid, Ready For Production, and later statuses) appends are rejected with a 400 invalid-status error, matching the recipient-delete and checkout operations.
Adds recipients to an existing order without replacing the ones already on it. Accepts up to 5,000 recipients per request. The order must be editable — status Draft or Edits Needed; once a checkout has been accepted (Paid, Ready For Production, and later statuses) appends are rejected with a 400 invalid-status error, matching the recipient-delete and checkout operations.
Authorization
ApiKey X-API-KEY<token>
In: header
Path Parameters
id*integer
The Id of the order to add recipients to.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
recipients*array<>
List of recipients to be added to order
Response Body
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/v1/order/0/recipients" \ -H "Content-Type: application/json" \ -d '{ "recipients": [ { "id": 0, "address": { "address1": "1600 Pennsylvania Ave NW", "address2": "Suite 300", "city": "Washington", "state": "DC", "zipCode": 20500, "zip4": "0003", "zip2": "01", "country": "United States" }, "personal": { "firstName": "Dana", "lastName": "Whitfield", "toOrganization": "Whitfield Roofing", "salutation": "Dana" }, "metadata": { "dpvConfirmationCode": "Y", "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", "deliveryStatus": "Waiting on USPS Info" } } ] }'{ "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": "Success", "totalRecipients": 0, "submittedRecipients": 0, "acceptedRecipients": 0, "droppedRecipients": 0, "deliverable": { "addressValidated": 0, "addressInvalidated": 0 }, "undeliverable": { "duplicated": 0, "doNotMail": 0, "invalidAddress": 0, "undeliverableRecipients": [ { "id": 0, "address": { "address1": "1600 Pennsylvania Ave NW", "address2": "Suite 300", "city": "Washington", "state": "DC", "zipCode": 20500, "zip4": "0003", "zip2": "01", "country": "United States" }, "personal": { "firstName": "Dana", "lastName": "Whitfield", "toOrganization": "Whitfield Roofing", "salutation": "Dana" }, "metadata": { "dpvConfirmationCode": "Y", "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", "deliveryStatus": "Waiting on USPS Info" }, "reason": "string" } ] }, "variableImages": { "summary": { "accepted": 0, "aspectRatioMismatch": 0, "lowDpi": 0, "unsupportedOrBroken": 0, "missing": 0, "doesNotExist": 0 }, "recipientsWithIssues": [ { "recipientIndex": 0, "issues": [ { "field": "string", "code": "IMAGE_BROKEN_LINK", "message": "string", "httpStatus": 0 } ] } ] } }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}{ "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": "Success", "totalRecipients": 0, "submittedRecipients": 0, "acceptedRecipients": 0, "droppedRecipients": 0, "deliverable": { "addressValidated": 0, "addressInvalidated": 0 }, "undeliverable": { "duplicated": 0, "doNotMail": 0, "invalidAddress": 0, "undeliverableRecipients": [ { "id": 0, "address": { "address1": "1600 Pennsylvania Ave NW", "address2": "Suite 300", "city": "Washington", "state": "DC", "zipCode": 20500, "zip4": "0003", "zip2": "01", "country": "United States" }, "personal": { "firstName": "Dana", "lastName": "Whitfield", "toOrganization": "Whitfield Roofing", "salutation": "Dana" }, "metadata": { "dpvConfirmationCode": "Y", "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", "deliveryStatus": "Waiting on USPS Info" }, "reason": "string" } ] }, "variableImages": { "summary": { "accepted": 0, "aspectRatioMismatch": 0, "lowDpi": 0, "unsupportedOrBroken": 0, "missing": 0, "doesNotExist": 0 }, "recipientsWithIssues": [ { "recipientIndex": 0, "issues": [ { "field": "string", "code": "IMAGE_BROKEN_LINK", "message": "string", "httpStatus": 0 } ] } ] } }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}{ "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": "Success", "totalRecipients": 0, "submittedRecipients": 0, "acceptedRecipients": 0, "droppedRecipients": 0, "deliverable": { "addressValidated": 0, "addressInvalidated": 0 }, "undeliverable": { "duplicated": 0, "doNotMail": 0, "invalidAddress": 0, "undeliverableRecipients": [ { "id": 0, "address": { "address1": "1600 Pennsylvania Ave NW", "address2": "Suite 300", "city": "Washington", "state": "DC", "zipCode": 20500, "zip4": "0003", "zip2": "01", "country": "United States" }, "personal": { "firstName": "Dana", "lastName": "Whitfield", "toOrganization": "Whitfield Roofing", "salutation": "Dana" }, "metadata": { "dpvConfirmationCode": "Y", "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", "deliveryStatus": "Waiting on USPS Info" }, "reason": "string" } ] }, "variableImages": { "summary": { "accepted": 0, "aspectRatioMismatch": 0, "lowDpi": 0, "unsupportedOrBroken": 0, "missing": 0, "doesNotExist": 0 }, "recipientsWithIssues": [ { "recipientIndex": 0, "issues": [ { "field": "string", "code": "IMAGE_BROKEN_LINK", "message": "string", "httpStatus": 0 } ] } ] } }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}Empty
{ "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": "Success", "totalRecipients": 0, "submittedRecipients": 0, "acceptedRecipients": 0, "droppedRecipients": 0, "deliverable": { "addressValidated": 0, "addressInvalidated": 0 }, "undeliverable": { "duplicated": 0, "doNotMail": 0, "invalidAddress": 0, "undeliverableRecipients": [ { "id": 0, "address": { "address1": "1600 Pennsylvania Ave NW", "address2": "Suite 300", "city": "Washington", "state": "DC", "zipCode": 20500, "zip4": "0003", "zip2": "01", "country": "United States" }, "personal": { "firstName": "Dana", "lastName": "Whitfield", "toOrganization": "Whitfield Roofing", "salutation": "Dana" }, "metadata": { "dpvConfirmationCode": "Y", "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", "deliveryStatus": "Waiting on USPS Info" }, "reason": "string" } ] }, "variableImages": { "summary": { "accepted": 0, "aspectRatioMismatch": 0, "lowDpi": 0, "unsupportedOrBroken": 0, "missing": 0, "doesNotExist": 0 }, "recipientsWithIssues": [ { "recipientIndex": 0, "issues": [ { "field": "string", "code": "IMAGE_BROKEN_LINK", "message": "string", "httpStatus": 0 } ] } ] } }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}List an order's recipients GET
Returns the recipients on an order with their address and mail-merge data. Supports a query filter on recipient name, address, or organization, plus pageNumber/pageSize pagination.
Create an order POST
Creates a new order from an existing template, copying its design and product settings, and returns the new order's ID. Add recipients and execute checkout separately to send the order.