Querying the Mail Record Database

This article describes the process required to query your direct mail database from a third-party system and convert the mail record into a contact.

Requirements

• Active Forth CRM Account
• Direct Mail Database enabled (contact Support@Setforth.com to enable)
• API-Key (contact Support@Setforth.com to generate your key)
• ForthCRM Data Source URL for conversion
• Knowledge and ability to parse JSON responses

Getting Started

1. Request an API Key from Forth (Send an email request to Support@setforth.com)

2. Create a Data Source for lead conversion

3. Upload Mail Data into the database and map internal fields.

Querying Direct Mail Data

Required Query Parameters

• &api_key= (replace {APIKEY} with your provided API key)
• &q= (the mailer ID code)

Optional Query Parameters

• mapped=true (returns standardized field mappings instead of raw column names from mail data)

We suggest you use the mapped parameter for consistency if you are a third-party integrator, implementing this with multiple Forth Clients.

Send a GET Request to the following URL:

https://login.forthcrm.com/post/mailsearch.php?api_key={APIKEY}&q={SEARCHQUERY}

This request should be done programmatically using CURL or similar to create HTTP Requests. You can test this directly via your browser as well.

JSON Response

If multiple results are found, they will be contained in the results array.

Unmapped Response ​(not using &mapped=true) parameter. Field names will vary based on your data structure.

{
  "results": [
   {
    "id": "1754",
    "sdate": "0000-00-00",
    "tmp_campaignid": "55031",
    "tmp_ref": "0609B-11231",
    "tmp_first": "John",
    "tmp_middle": "",
    "tmp_last": "Doe",
    "tmp_sfx": "",
    "tmp_address": "123 Main Street",
    "tmp_city": "Anytown",
    "tmp_st": "VA",
    "tmp_zip": "20166-6686",
    "tmp_dem10": "5551231133",
    "tmp_tmparv06": null,
    "tmp_tmparv24": null,
    "tmp_tmpsettlement": null,
    "tmp_tmpehvs": null,
    "tmp_tmptollfree": null,
    "tmp_tmpehvd": null,
    "tmp_tmpcrrt": null,
    "tmp_tmpcountynm": null,
    "tmp_tmpsavings": null,
    "tmp_tmpversion": null,
    "tmp_tmpcurrpay": null,
    "tmp_tmpnewpay": null,
    "tmp_tmpmonthsav": null,
    "tmp_tmpannualsav": null,
    "tmp_tmpspellamt": null,
   }
  ]
}

Mapped Response ​(using &mapped=true) parameter. Standard fields like firstname, lastname, address, and phone numbers will be consistent between multiple Forth Accounts.

{
 "results": [
  {
   "standard": {
    "__mailer_id": "0609B-11231",
    "firstname": "John",
    "middlename": "",
    "lastname": "Doe",
    "address": "123 Main Street",
    "city": "Anytown",
    "state": "VA",
    "zip": "20166-6686",
    "phone": "",
    "phone3": ""
  },
   "customfields": [
    {
     "id": "205685",
     "name": "Benefit ID Number",
     "value": "55031"
   },
   {
     "id": "226403",
     "name": "Number of Times Client Has Been Delinquent",
     "value": null
   },
   {
     "id": "205664",
     "name": "Credit Score",
     "value": "611"
   },
   {
     "id": "205667",
     "name": "Credit Utilization %",
     "value": "93"
   },
   {
     "id": "189410",
     "name": "Debt Amount",
     "value": "23000"
   },
   {
     "id": "226409",
     "name": "Number of Revolving Accounts",
     "value": null
   },
   {
     "id": "189410",
     "name": "Debt Amount",
     "value": null
   },
   {
     "id": "262484",
     "name": "Debt Mailer Current Payment",
     "value": null
   },
   {
     "id": "262487",
     "name": "Debt Mailer New Payment",
     "value": null
   },
   {
     "id": "262490",
     "name": "Debt Mailer Monthly Savings",
     "value": null
   },
   {
     "id": "262496",
     "name": "Debt Mailer Annual Savings",
     "value": null
    }
   ]
  }
 ]
}

Conversion to Lead

To convert this record to a lead, create an HTTP POST Request using CURL or similar to your designated Data Source URL.

Example Data Source URL:

https://login.forthcrm.com/post/cd0c8b249befb2a72ddd162610c9be934bf53329/

Pass the parameter __mailer_id​ in your POST request with any other fields you wish to include.

Example POST Body

[“__mailer_id”] => ‘0609B-11231’
[“firstname”] => ‘John’
[“lastname”] => ‘Doe’
[“phone”] => “555-123-2344”
[“debt_amount”] = ‘50000’

Text Response

On successful posting, you will receive a raw text response of:

Success:5023943

The value 5023943 will be unique to the record ID of the newly inserted lead.

Article Version History: