Address Cleanse API

• The Address Cleanse API is a web service that can be used to perform address validation, deduplication and suppression checks using a variety of data types.
• It follows RESTful principles – accepting HTTP requests and returning JSON response documents. Unless otherwise stated all methods will return HTTP status 200 on success and a 4xx or 5xx status when an error occurs.
• A Hopewiser online Address Cleanse Account is needed.
• Click here for more detailed Address Cleanse API reference documentation

Authentication

Authorization: Bearer $TOKEN_VALUE

Job Configuration

A list of uploaded files and their metadata can be retrieved using the following method. This method takes no parameters and returns a JSON array containing a description of each uploaded file.

/api/v1/files

Response:

[
  {
    "id": 147,
    "cols": 6,
    "rowCount": 597,
    "delimiter": ",",
    "hasHeader": true,
    "useQuotes": true,
    "creationDate": 1510939445,
    "inputFileDeleteDate": 1510939445,
    "lastUpdate": 1510939445
  }
]

The dates in the response are given using Unix time, which is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00:00:00Z).

Start a cleanse job

To start a cleanse process on an uploaded file call the following method, giving it the inputFileId which was returned as the fileId response in the /upload methods, and a name to identify this job. The request body should contain the JSON settings data previously generated from the web interface and exported using “Export settings for API”.

/api/v1/run?inputFileId=CustomerAddresses1234&name=CleanseRun1

Parameters:

Body:

{
  "inputFileDesc": {
    "cols": 7,
    "delimiter": "|",
    "hasHeader": true,
    "useQuotes": true
  },
  "inputFields": [
  {
    "name": "Add Line 1",
    "mappingId": 6,
    "mappingOrder": 9
  },
  {
    "name": "Add Line 2",
    "mappingId": 6,
    "mappingOrder": 10
  },
  {
    "name": "Add Line 3",
    "mappingId": 6,
    "mappingOrder": 11
  },
  {
    "name": "Add Line 4",
    "mappingId": 6,
    "mappingOrder": 12
  },
  {
    "name": "Add Line 5",
    "mappingId": 6,
    "mappingOrder": 13
  },
  {
    "name": "City",
    "mappingId": 6,
    "mappingOrder": 14
  },
  {
    "name": "Country",
    "mappingId": 0,
    "mappingOrder": 15
  }
  }],
  "outputFields": [{
    "groupId": 1
  },
  {
    "groupId": 8
  },
  {
    "groupId": 2
  },
  {
    "groupId": 3
  },
  {
    "groupId": 4
  }],
  "dedupe": {
    "duplicationLevel": 2,
    "dedupeSeparateFile": false
  },
  "suppress": {
    "suppressDeceased": true,
    "suppressGoneaways": true,
    "suppressPreferenceServices": true
  }
}

Response:

{
  "runId": 49
}

Get the status of a job

Depending on the size of the file and the options selected the run could take only a few seconds or several minutes. To determine the current status of the job you can poll using the following method, giving it the runId returned from /run. This will return a block of JSON text containing the current status of the job. The returned HTTP status code will also change. While the job is running the returned HTTP status will be 404, once the job is complete it will become 200.

/api/v1/run/status?runId=49

Parameter:

{
    "name": "CleanseRun1",
    "statusCode": 6,
    "statusDesc": "Processing",
    "stage": {
        "stageCount": 7,
        "currentStage": 5,
        "stageName": "Post processing",
        "stageStatus": "Postprocess",
        "stageProgress": 0.14285714285714286
    }
}

The stage part of the response is optional, it will only be there while the job is being processed. Once the cleanse part of the job is complete the response will only contain the name, statusCode and statusDesc fields.

Possible status codes

The number and values of the stages in the stage object are subject to change. The field names are fixed, but their values may be updated at any time as the software is upgraded.

For example, there are currently 7 stages, but that number may increase or decrease in future. If it does change the stageCount will update to reflect this.

Statistics

Once a job is complete various statistics and metadata is available to download. These can be viewed without payment. To download the results file however, it must first be payed for. All the results methods take as a parameter the runId returned by the /run method to identify which job you are interested in.

To get the number of matches for the various categories of checks made by Address Cleanse (address matches, de-duplications and suppressions):

/api/v1/results/statistics?runId=49

Parameter:

Response:

{
    "recordCount": 76,
    "codingStats": [
        {
            "name": "Matched",
            "description": "A correct address",
            "count": 11
        },
        {
            "name": "UnmatchedPremise",
            "description": "The premise, e.g. house number, was not found",
            "count": 1
        },
        {
            "name": "UnmatchedStreet",
            "description": "The thoroughfare, e.g. street, was not found",
            "count": 1
        },
        {
            "name": "UnmatchedTown",
            "description": "The town was not found",
            "count": 62
        },
        {
            "name": "Unmatched",
            "description": "No parts of the address could be verified",
            "count": 1
        }
    ],
    "dedupeStats": [
        {
            "name": "Unique",
            "description": "The record is unique",
            "count": 98
        },
        {
            "name": "Parent",
            "description": "The first record that is a duplicate based on the level selected",
            "count": 1
        },
        {
            "name": "Child",
            "description": "The record is a duplicate of a parent record",
            "count": 1
        }
    ],
    "suppressionRemovedStats": [
        {
            "name": "Goneaway",
            "description": "People who have moved",
            "typeName": "DBS",
            "typeDescription": "Purifi",
            "count": 11
        },
        {
            "name": "Goneaway",
            "description": "People who have moved",
            "typeName": "DCR",
            "typeDescription": "DisConnect",
            "count": 3
        },
        {
            "name": "Goneaway",
            "description": "People who have moved",
            "typeName": "GAS",
            "typeDescription": "Goneaway Suppression",
            "count": 1
        },
        {
            "name": "Goneaway",
            "description": "People who have moved",
            "typeName": "RMG",
            "typeDescription": "Re-Movers",
            "count": 7
        },
        {
            "name": "Preference",
            "description": "People listed on Mailing Preference Service",
            "typeName": "MPS",
            "typeDescription": "Mailing Preference Service",
            "count": 1
        }
    ],
    "suppressionFlaggedStats": []
}

Costs

To see a breakdown of the various charges incurred for the run:

/api/v1/results/costs?runId=49

Parameter:

Response:

[
    {
        "name": "Address Validation",
        "netcost": 3072,
        "cost": 3610
    },
    {
        "name": "De-duplication",
        "netcost": 43,
        "cost": 50
    },
    {
        "name": "Telephone Preference Service",
        "netcost": 7,
        "cost": 8
    },
    {
        "name": "Goneaways",
        "netcost": 299,
        "cost": 351
    },
    {
        "name": "Preference Services",
        "netcost": 1,
        "cost": 1
    }
]

Download results file

Finally, to retrieve the results, call the following method, which will return a url from which a zip file containing results and statistics can be downloaded.

/api/v1/results/file?runId=49

Parameter:

Response:

{
  "downloadUrl": "https://filesvr.hopewiser.com/filesvr/download?downloadName=AddressCleanseResults.zip&fileId=CleanseRun1234.dat"
}