API ReferenceOrders
List an order's recipients
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.
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.
Authorization
ApiKey X-API-KEY<token>
In: header
Path Parameters
id*integer
The Id of the order to retrieve the recipient list from.
Query Parameters
query?string
Search filter for recipient data. Filter by recipient name, address or organization.
pageNumber?integer
For pagination: Page number.
pageSize?integer
For pagination: Number of records to retrieve.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/order/0/recipients"{ "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", "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": "", "custom2": "", "custom3": "", "custom4": "", "custom5": "", "custom6": "", "image1": "", "image2": "", "image3": "", "image4": "", "image5": "", "image6": "", "salutation": "", "returnTitle": "", "returnFirstName": "", "returnLastName": "", "returnOrganization": "", "returnAddress1": "", "returnAddress2": "", "returnCity": "", "returnZip": "", "returnState": "", "email": "", "qrUrl": "", "text": "", "text2": "", "radiusPinStreet": "", "radiusPinAddress": "", "fullAddress": "", "deliveryStatus": "Waiting on USPS Info" } } ] }, "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", "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": "", "custom2": "", "custom3": "", "custom4": "", "custom5": "", "custom6": "", "image1": "", "image2": "", "image3": "", "image4": "", "image5": "", "image6": "", "salutation": "", "returnTitle": "", "returnFirstName": "", "returnLastName": "", "returnOrganization": "", "returnAddress1": "", "returnAddress2": "", "returnCity": "", "returnZip": "", "returnState": "", "email": "", "qrUrl": "", "text": "", "text2": "", "radiusPinStreet": "", "radiusPinAddress": "", "fullAddress": "", "deliveryStatus": "Waiting on USPS Info" } } ] }, "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", "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": "", "custom2": "", "custom3": "", "custom4": "", "custom5": "", "custom6": "", "image1": "", "image2": "", "image3": "", "image4": "", "image5": "", "image6": "", "salutation": "", "returnTitle": "", "returnFirstName": "", "returnLastName": "", "returnOrganization": "", "returnAddress1": "", "returnAddress2": "", "returnCity": "", "returnZip": "", "returnState": "", "email": "", "qrUrl": "", "text": "", "text2": "", "radiusPinStreet": "", "radiusPinAddress": "", "fullAddress": "", "deliveryStatus": "Waiting on USPS Info" } } ] }, "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", "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": "", "custom2": "", "custom3": "", "custom4": "", "custom5": "", "custom6": "", "image1": "", "image2": "", "image3": "", "image4": "", "image5": "", "image6": "", "salutation": "", "returnTitle": "", "returnFirstName": "", "returnLastName": "", "returnOrganization": "", "returnAddress1": "", "returnAddress2": "", "returnCity": "", "returnZip": "", "returnState": "", "email": "", "qrUrl": "", "text": "", "text2": "", "radiusPinStreet": "", "radiusPinAddress": "", "fullAddress": "", "deliveryStatus": "Waiting on USPS Info" } } ] }, "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", "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": "", "custom2": "", "custom3": "", "custom4": "", "custom5": "", "custom6": "", "image1": "", "image2": "", "image3": "", "image4": "", "image5": "", "image6": "", "salutation": "", "returnTitle": "", "returnFirstName": "", "returnLastName": "", "returnOrganization": "", "returnAddress1": "", "returnAddress2": "", "returnCity": "", "returnZip": "", "returnState": "", "email": "", "qrUrl": "", "text": "", "text2": "", "radiusPinStreet": "", "radiusPinAddress": "", "fullAddress": "", "deliveryStatus": "Waiting on USPS Info" } } ] }, "errorCode": "UNAUTHENTICATED", "errors": [ "string" ], "hasErrors": true, "warnings": [ "string" ], "hasWarnings": true, "errorDetails": [ null ], "metadata": { "property1": null, "property2": null }}Delete an order's recipients DELETE
Removes the specified recipients from an order. Pass the IDs of the recipients to remove in the request body. The 200 response reports `requestedRecipients` (distinct ids submitted), `deletedRecipients` (rows actually removed), and `notFoundRecipientIds` (submitted ids that matched no recipient on the order) so a caller holding a stale id can detect a no-op instead of receiving a bare success.
Append recipients to an order PUT
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.