Skip to main content
Cloud

Address Cleanse API

Overview

  • The Address Cleanse API is a web service that can be used to perform address validation, deduplication and suppression checks. Flag or make changes to imported data files.
  • It follows RESTful principles – accepting HTTPS requests and returning JSON response documents.
  • Click here for more detailed reference documentation.

Quick Start

  • Register or Login to your Address Cleanse account to get started.
  • Create an Address Cleanse API Token as described in the Authentication section below.
  • To upload a file, a job configuration file must also be supplied. The creation of this is described in theĀ  Job Configuration section below.

 

Authentication / Configuration

Authentication

All Address Cleanse API methods require a security token for authorisation. This token can be generated using the web interface here once logged in.

Simply click on your username in the top right hand corner of the screen to open up a menu. Select Export API Token; a window will appear containing the token text. Store that text for use by your application in all Address Cleanse API service calls.

The token should be sent in a HTTPS header of the format…

Authorization: Bearer $TOKEN_VALUE

 

Job Configuration

Address Cleanse API job configuration is done via the web interface here. This only needs to be done once as the same settings can be used for any number of input files, providing the file format and structure remains constant.

Once a job configuration has been created through the UI, it can be exported for use with your client application.

Click on the menu icon in the top right corner and select Export settings for API. A window will appear containing the JSON text describing your settings. Save that text for use by your application, it will be needed by the /api/v1/run method.

 

Upload a File

There are 3 different methods to be used in uploading a file. This is to allow for the uploading of large files and in avoiding import latency.

Begin

First call the begin method, giving it a size and filePrefix (name).

/api/v1/files/upload/begin?size=XXX&filePrefix=NAME

Parameters:

Name Description Example Value
size The file size in bytes 16384
filePrefix A string that will become part of the filename on the server CustomerAddresses

Response:

{
  "fileId":"CustomerAddresses1234.dat",
  "chunkUrl":"https://filesvr.hopewiser.com/filesvr/upload/chunk"
}

Chunk

Then call the chunk method using the chunkUrl (in place of the service endpoint used in all other methods here), the fileId returned by /begin and an idx indicating which chunk this is, starting from zero. The file data should be sent in the body of the HTTPS POST request as raw binary data bytes.

https://filesvr.hopewiser.com/filesvr/upload/chunk?fileId=XXX&idx=0
https://filesvr.hopewiser.com/filesvr/upload/chunk?fileId=XXX&idx=1

etc.

Parameters:

Name Description Example Value
fileId ID returned by /begin CustomerAddresses1234
idx Index number for the chunk 0

It is recommended the chunks be no larger than 10 MB; especially if your application is browser based. Call this method repeatedly for each part of the file you upload, incrementing the idx parameter by 1 each time.

End

Once the file data is completely uploaded, call the end method with the fileId returned by /begin, and optionally a hash field containing the sha256 hash of the file. If a hash is provided it will be compared with the file data stored on the server to guarantee the uploaded file’s integrity.

/api/v1/files/upload/end?fileId=XXX&hash=YYY

Parameters:

Name Description Example Value
fileId ID returned by /begin CustomerAddresses1234
hash SHA256 hash of the file (optional) d785d959746f4180c8c6ef885d9abaccb5a43f004c718a906271c3de014eb69b

 

Retrieve a list of uploaded files

A list of uploaded files and their metadata can be retrieved using the files method which 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
  }
  { 
    "id": 149,
    "cols": 6, 
    "rowCount": 1452,
    "delimiter": ",",
    "hasHeader": true,
    "useQuotes": true, 
    "creationDate": 1510949999, 
    "inputFileDeleteDate": 1510949999,
    "lastUpdate": 1510949999
  }
]

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).

 

Run an Address Cleanse API job

Start a cleanse job

To start a processing run on an uploaded file, call the run method, providing the inputFileId which was returned 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 in an earlier step.

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

Parameters:

Name Description Example Value
inputFileId ID returned by /begin CustomerAddresses1234
name A name to identify this run CleanseRun1

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 processing run could take only a few seconds or several minutes. To determine the current status of the job you can poll using the status 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 Description Example Value
runId ID returned by /run 49
{
    "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 will only appear whilst the processing run is in progress. Once the cleanse part of the job is complete the response will only contain the name, statusCode and statusDesc sections.

Possible status codes

Value Description
0 Uploading
1 Uploaded
2 QueuedForTest
3 ProcessingTest
4 FinishedTest
5 QueuedForResults
6 ProcessingResults
7 AwaitingPayment
8 Paid
9 Error
10 Deleted

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.

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

 

Get results

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 paid for.

All the results methods take as a parameter the runId returned by the run method to identify which job is the one of interest.

Statistics

To obtain details of matches for the various categories of checks made by Address Cleanse (address matches, de-duplications and suppressions), use the statistics method…

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

Parameter:

Name Description Example Value
runId ID returned by /run 49

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, use the costs method…

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

Parameter:

Name Description Example Value
runId ID returned by /run 49

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
    }
]

Pay

To allow the file to be downloaded use the pay method…

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

Parameter:

Name Description Example Value
runId ID returned by /run 49

If you have not set up an agreement with Hopewiser to allow automatic payments, this will return a URL you must manually visit in a browser to complete your payment information.

If you have set up such an agreement then you must still call the pay method, but no further action is needed.

Response:

{
  "invoiceUrl": "http://www.hopewiser.com/payment/xxxx"
}
{
  "invoiceId": "196"
}

Download results file

To retrieve the results (upon completion of payment step), call the file method. This will return a URL from which a zip file containing results and statistics can be downloaded.

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

Parameter:

Name Description Example Value
runId ID returned by /run 49

Response:

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

Version

Retrieve the version of Address Cleanse software using the version method…

/api/v1/version

Response:

{
    "major": 1,
    "minor": 1,
    "patch": 0,
    "description": "1.1.0"
}