Skip to main content

DirectMailReplies

Direct Mail Replies

This object represents a reply to a direct mail piece. Each reply is uniquely identified and can include additional optional information about the respondent.

Insert or update (upsert) a Direct Mail Reply

Uniqueness is determined based on a combination of the location unique identifier and the external ID. If a record with the same location unique identifier and external unique identifier already exists, the existing record will be updated. Otherwise, a new record will be created.

New data is merged with existing data. See clarification below for details.

Parameters

location_unique_identifier
Requiredstring

The unique identifier of the location.

external_identifier
Requiredstring

The external identifier of this reply, to enforce uniqueness. This is the identifier of the reply in your system.

image_urls
Requiredarray of strings

A list of image URLs associated with the direct mail reply. Each file must be a JPG at this time. At least one URL is required.

The maxium number of allowed image_urls is 10 images at this time.

This can include a scanned photo of the back of the reply card and any other images associated with the reply.

respondent_person
(optional)object

Details about the respondent.

full_name
(optional)string

The full name of the respondent (e.g. "Jane Doe").

phone_number1
(optional)E164_string

The respondent's primary phone number, formatted as a valid US number (e.g. +14155552671, (415) 555-2671, 415-555-2671, 4155552671, etc).

phone_number2
(optional)E164_string

The respondent's secondary phone number, formatted as a valid US number (e.g. +14155552671, (415) 555-2671, 415-555-2671, 4155552671, etc).

email_address
(optional)string

The email address address of the respondent.

birth_date
(optional)string

The birth date of the respondent (any date format is supported at this time).

respondent_address
(optional)object

Address details about the respondent.

street_address_line_1
(optional)string

The first line of the street address of the respondent.

street_address_line_2
(optional)string

The second line of the street address of the respondent.

city
(optional)string

The city of the respondent.

county
(optional)string

The county of the respondent.

state
(optional)string

The state of the respondent.

country
(optional)string

The country of the respondent.

postal_code
(optional)string

The postal code of the respondent.

additional_metadata
(optional)object

Additional metadata about the reply, which can include any object with string keys and string values.

This allows any additional data to be stored with the reply. Examples are order numbers, mailer codes, etc.

Returns

A dictionary representing the created or updated direct mail reply object.

POST
/v1/direct_mail_replies/upsert
curl -X POST https://api.mogulbridge.com/v1/direct_mail_replies/upsert \
-u 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: \
-H "Content-Type: application/json" \
-d '{
  "location_unique_identifier": "loc_XFRitug2hXD3ESq6NXRfo",
  "external_identifier": "your-external-identifier",
  "image_urls": ["https://uploads.mogulbridge.com/images/MailerExampleBack.jpg", "https://uploads.mogulbridge.com/images/MailerExampleFront.jpg"],
  "respondent_person": {
    "full_name": "Jane Doe",
    "phone_number1": "+13175551234",
    "phone_number2": "+13175551235",
    "email_address": "jane.doe@example.com",
    "birth_date": "1990-01-01"
  },
  "respondent_address": {
    "street_address_line_1": "123 Main St",
    "street_address_line_2": "Apt 4B",
    "city": "Anytown",
    "county": "Marion",
    "state": "IN",
    "country": "USA",
    "postal_code": "46220"
  },
  "additional_metadata": {
    "order_number": "12345",
    "mailer_code": "ABC123"
  }
}'
RESPONSE
{
  "object": "direct_mail_reply",
  "inserted_at": "2024-06-07T18:51:10Z",
  "updated_at": "2024-06-07T18:51:10Z",
  "unique_identifier": "dmr_FTgfrqazBRAfBscSDVwFA",
  "external_identifier": "your-external-identifier",
  "location_unique_identifier": "loc_XFRitug2hXD3ESq6NXRfo",
  "public_data": {
    "image_urls": [
      "https://uploads.mogulbridge.com/images/MailerExampleBack.jpg",
      "https://uploads.mogulbridge.com/images/MailerExampleFront.jpg"
    ],
    "respondent_person": {
      "full_name": "Jane Doe",
      "email_address": "jane.doe@example.com",
      "phone_number1": "+13175551234",
      "phone_number2": "+13175551235",
      "birth_date": "1990-01-01"
    },
    "respondent_address": {
      "street_address_line_1": "123 Main St",
      "street_address_line_2": "Apt 4B",
      "city": "Anytown",
      "county": "Marion",
      "state": "IN",
      "country": "USA",
      "postal_code": "46220"
    },
    "additional_metadata": {
      "mailer_code": "ABC123",
      "order_number": "12345"
    }
  }
}