Syniti Match API Reference

Success Response

Error Response

Response

Description

Returns a list of active engine numbers.

E.g.

Usage Examples

Using a browser:

Using cURL:

curl -X GET http://localhost:8080/matchITHub/engines
{"status":"OK","ids":""}

Request

Response

Description

Initialises an instance of the engine and applies the activation_code.

The activation_code can be omitted, in which case a valid activation code must be PUT to the Initialization resource before the engine instance can be used.

If you supply a name for an instance, you can use this as <engine> in the url instead of the instance number.

Usage Example

Using cURL:

curl -X POST --data "activation_code=<activation_code>" http://localhost:8080/matchITHub/engines
{"status":"OK","engine":1}

Or:

curl -X POST --data-urlencode "activation_code@activation.txt" http://localhost:8080/matchITHub/engines
{"status":"OK","engine":1}

Request

Description

Deletes the specified engine instance.

Usage Example

Using cURL:

curl -X DELETE http://localhost:8080/matchITHub/engines/1
{"status":"OK"}

Request

Description

Configures logging which is disabled by default.

Severity is one of :

• None
• Error
• Warning
• Information
• Debug

Setting severity to "Error" will log only error messages, setting severity to "Warning" will log error and warning messages, and so on. I.e. each setting is more verbose than the previous with "Debug" being the most verbose.

If filename is not specified (or is not accessible) messages are logged to the console (not visible when run as a Windows service).

Note: logging settings are per engine instance, but you can set all instances to log messages to the same file.

Log messages are of the form:

<engine id>,<HH:mm:ss>,<severity>,<source>,<message>

Usage Example

Using cURL:

curl -X POST --data "severity=Debug" --data "filename=debuglog.txt" http://localhost:8080/matchITHub/engines/1/log
{"status":"OK"}

Initialization

Resources relative to http://host:8080/matchITHub/engines/<engine>

PUT /matchITHub/engines/<engine>/initialization?activation_code=<activation_code>

Usage Example

Using cURL:

curl -X PUT http://localhost:8080/matchITHub/engines/1/initialization?activation_code=<activation_code>
{"status":"OK"}

Request

Response

Description

Gets the state of the engine.

Usage Examples

Using a browser

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/state
{"status":"OK","state":"Initialized:\nthe engine has been initialized but no settings applied"}

Request

Description

Changes the state of the engine. Equivalent to the hub methods: pause, resume, abort, reset.

Usage Example

Using cURL:

curl -X PUT http://localhost:8080/matchITHub/engines/1?state=pause

Request

Description

Applies the given settings.

Request

Description

Uploads a file of settings to apply.

Usage Example

Using cURL:

curl -X POST --data-urlencode "file=settings.xml" http://localhost:8080/matchITHub/engines/1/settings
{"status":"OK"}

Request

Response

Description

Retrieves and returns the engine's current settings as an XML-formatted string.

Usage Examples

Using a browser:

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/settings
{"status":"OK","configXML":"<?xml version=\"1.0\" encoding=\"utf-8\" ?>\n<settings>\n...</settings>"}

GET /matchITHub/engines/<engine>/settings/advanced

Usage Example

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/settings/advanced
{"status":"OK","configXML":"<?xml version=\"1.0\" encoding=\"utf-8\" ?>\n<settings>\n...</settings>"}

Request

Description

Adds data to the engine's input buffer.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

Usage Example

Using cURL:

curl -X POST --data-urlencode "data=,57,MR,MATTHEW,KASPAR,AVIATION SERVICES INC,14824 BOWE ROAD,BARNWELD,NEW YORK,13304" --data-urlencode "timeout=1000" http://localhost:8080/matchITHub/engines/1/tables/1
{"status":"OK"}

Request

Description

Uploads a block of data records to add to the engine's input buffer.

The content of this POST is a plain text block of records. Records should be separated by a new line characters and each record must start with the delimiter character used for that record.

Request

Description

Specify a filename for the service to load input data from.. Filenames are added to a list and processed in the order added. If no delimiter is specified, each record must start with the delimiter character used for that record. If no encoding is specified, UTF-8 is used. The file must be accessible from the service. If adding data from a different machine, post the data in blocks or use the Proxy Engine.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

Usage Example

Using cURL:

curl -X POST --data-urlencode "filename=D:\testdata\inputfile.txt" --data-urlencode "delimiter=\t" --data-urlencode "encoding=UTF-8" --data "nomore=true" http://localhost:8080/matchITHub/engines/1/tables/1/files
{"status":"OK"}

Request

Description

Update a record with the new data. The unique ID of the record to update is extracted from the data.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

Request

Description

Uploads a block of transaction records to add to the engine's input buffer.

The content of this POST is a plain text block of records. Records should be separated by a new line characters and each record must start with the delimiter character used for that record.

Request

Description

Specify a filename for the service to load update transaction data from. Filenames are added to the same list used for input data and processed in the order added. If no delimiter is specified, each record must start with the delimiter character used for that record. If no encoding is specified, UTF-8 is used.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

Request

Description

Informs the engine that no more data will be added for the indicated table.

Usage Example

Using cURL:

curl -X PUT http://localhost:8080/matchITHub/engines/1/tables/1/eof
{"status":"OK"}

Request

Description

Informs the engine to allow more data to be added for the indicated table.

Request

Response

Description

Returns the number of records that have not yet been processed.

Usage Examples

Using a browser:

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/unprocessed
{"status":"OK","unprocessedCount":0}

Request

Response

Description

Get a record with the specified unique ID.

Usage Examples

Using a browser:

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/tables/1/17
{"status":"OK","result":"\t17\tROBERT HANSEN\tSTATEWEST AIRLINES INC\t4909 EAST MCDOWELL ROAD\tFT COLLINS\tCOLORADO\t80524"}

Request

Description

Delete a record with the specified unique ID.

Using cURL:

curl -X DELETE http://localhost:8080/matchITHub/engines/1/tables/1/17
{"status":"OK"}

Request

Description

Removes and discards all data relating to the indicated table. This includes: buffered input data, cached records, clusters, matching pairs, matching groups.

Usage Example

Using cURL:

curl -X DELETE -H "async: true" http://localhost:8080/matchITHub/engines/1/tables/2
{"status":"OK"}

Request

Response

Description

Returns the number of buffered results in the output buffer.

Usage Example

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/results/count
{"status":"OK","resultCount":0}

Request

Response

Description

Gets and returns the next buffered result and removes it from the output buffer.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

Usage Example

Using cURL:

curl -X POST --data "timeout=1000" http://localhost:8080/matchITHub/engines/1/results/next
{"status":"OK","result":"\tMG\tlevel\tgroup\tbase_score\ttable\trecord"}

Request

Response

Unlike other methods, this method does not return a application/json format response. Instead the response is a text/plain stream of records delimited by newline

Description

Gets and returns all the results as a plain text stream.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

curl -X POST --data "timeout=1000" http://localhost:8080/matchITHub/engines/1/results
        MG      I       56      105     0       57
        MG      I       26      118     0       26
        MG      I       26      118     0       35
        MG      I       4       119     0       4
        MG      I       4       119     0       71
        MG      I       10      98      0       10
        MG      I       10      98      0       65
        MG      I       10      98      0       64
        MG      I       80      130     0       80
        MG      I       80      130     0       81
        MG      I       38      103     0       38
        MG      I       38      103     0       63
        MG      I       113     139     0       113
        MG      I       113     139     0       74
        MG      I       15      113     0       15
        MG      I       15      113     0       123

Request

Description

Sets the output filename for the Syniti Match API Service to write results to. If no encoding is specified, UTF-8 is used.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

Usage Example

Using cURL:

curl -X POST --data "filename=D:\testing\outputfile.txt" http://localhost:8080/matchITHub/engines/1/results/outputfile
{"status":"OK"}

Request

Description

The output buffer is cleared; any buffered results are lost.

Usage Example

Using cURL:

curl -X DELETE http://localhost:8080/matchITHub/engines/1/results
{"status":"OK"}

Request

Response

Description

Equivalent to adding data to table 2 and repeatedly calling RESULTS/NEXT.

The timeLimit parameter specifies how long the service should wait for Hub to finish processing the query before fetching the results.

If it fails to lock the engine for timeout milliseconds you may get some empty strings in the results.

The count in the response is the number of matches that Syniti Match API found. If I record limit was specified the result array may contain fewer records.

Usage Example

Using cURL:

curl -X POST --data-urlencode "data=,,JOHN,TATTLE,,,BIRMINGHAM,,B3 3ER" http://localhost:8080/matchITHub/engines/1/lookup
{"status":"OK","results":["\t4\tJOHN TATTLE\tINFORMATION SYSTEMS MANAGER\tFRINTON WILKES PLC\t12 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS\tB3 3ER\t\t5\t117\t0\t57\t57\t0\t0","\t13\tMR V MACNICHOLS\t\tWETHERALL CONSULTING\t31 DALE END\tBIRMINGHAM\tWEST MIDLANDS\t\tB4 7LH\t4\t27\t0\t27\t27\t0\t4","\t28\tMR G HOOD\t\tFRINTON WILKES PLC\t12 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS\tB3 3ER\t\t4\t57\t0\t57\t57\t0\t4","\t71\tMR J RATTLE\tIT MANAGER\tFRINTON WILKES LTD\tEDMUND HOUSE\t12 NEWHALL STREET\tBIRMINGHAM\tB3 3ER\t\t1\t97\t0\t57\t57\t0\t4"],"count":4}

Request

Response

Description

Same as POST lookup. Equivalent to adding data to table 2 and repeatedly calling RESULTS/NEXT.

E.g.

POST /matchITHub/engines/<engine>/lookup data=<json query>

From version 2.0.4.

 Prior to version 2.0.4.15 the "Array of result records" output was an array of delimited strings. Since verison 2.0.4.15 the "Array of result records" output is an array of json objects, see example below.

curl -X POST -H "Content-Type: application/json" --data "{\"forenames\":\"JOHN\",\"surname\":\"TATTLE\",\"city\":\"BIRMINGHAM\",\"postcode\":\"B3 3ER\"}" http://localhost:8080/matchITHub/engines/lookup/lookup
{"status":"OK","results":["\t4\tJOHN TATTLE\tINFORMATION SYSTEMS MANAGER\tFRINTON WILKES PLC\t12 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS\tB3 3ER\t\t5\t95\t0\t35\t35\t0\t0","\t73\tJ R MAGSON\tPROD MGR\tFRINTON WILKES LTD\tEDMUND HOUSE\t12/22 NEWHALL STREET\tBIRMINGHAM\tW MIDLANDS\tB3 3ER\t4\t35\t0\t35\t35\t0\t5","\t72\tMR F W BOWER\tMANAGING DIRECTOR\tFRINTON WILKES GROUP\tEDMUND HOUSE\t12/22 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS    B3 3ER\t\t4\t35\t0\t35\t35\t0\t5","\t28\tMR G HOOD\t\tFRINTON WILKES PLC\t12 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS\tB3 3ER\t\t4\t35\t0\t35\t35\t0\t5","\t71\tMR J RATTLE\tIT MANAGER\tFRINTON WILKES LTD\tEDMUND HOUSE\t12 NEWHALL STREET\tBIRMINGHAM\tB3 3ER\t\t5\t75\t0\t35\t35\t0\t5"],"count":5}

curl -X POST -H "Content-Type: application/json" --data "{\"surname\": \"CHILVERS\"}" http://localhost:8080/matchITHub/engines/lookup/lookup
{
   "status":"OK",
   "results":[
      {
         "uniqueref":"1",
         "fullname":"MR G K CHILVERS",
         "jobtitle":"LASER MANAGER",
         "organization":"STANTON COPSHAW DIRECT",
         "address1":"10 EAGLES WOOD BUSINESS PARK",
         "address2":"ALMONDSBURY",
         "address3":"",
         "address4":"BRISTOL",
         "postcode":"BS12 4EU",
         "levels":"13",
         "individualScores":{
            "totalScore":"55",
            "nameScore":"40",
            "organizationScore":"0",
            "addressScore":"5",
            "postcodeScore":"10"
         },
         "familyScores":{
            "totalScore":"0",
            "nameScore":"",
            "organizationScore":"",
            "addressScore":"",
            "postcodeScore":""
         },
         "addressScores":{
            "totalScore":"15",
            "nameScore":"0",
            "organizationScore":"0",
            "addressScore":"5",
            "postcodeScore":"10"
         },
         "businessScores":{
            "totalScore":"30",
            "nameScore":"0",
            "organizationScore":"15",
            "addressScore":"5",
            "postcodeScore":"10"
         },
         "customScores":{
            "totalScore":"0",
            "nameScore":"",
            "organizationScore":"",
            "addressScore":"",
            "postcodeScore":""
         },
         "key":"1"
      }
   ],
   "count":1
}

Request

Response

Description

Produces and returns an XML-formatted string that lists useful statistical details for the current processing mode.

E.g.

Information

Resources relative to http://host:8080/matchITHub/engines/<engine>

GET /matchITHub/engines/<engine>/version

GET /matchITHub/engines/<engine>/expiry

Request

Response

Description

Retrieve all error messages as an array. Most methods return the errors immediately, but if you post an input filename or an updates filename an error may occur while the data is being loaded. If that happens the engine state will change to aborted and you can use this method to find out what went wrong.

curl -X POST http://localhost:8080/matchITHub/engines/1/errors
{"status":"OK","errorMsgs":[]}