Proposed api function Contact.getmatches

In conjunction with CRM-18442 it makes sense to add an api function to retrieve dedupe matches. While my primary motivation at this stage is to write a test for that function I also feel in future I WILL want to use it - mostly with some enhancements over the existing merge batch ie. instead of calling

job.batchmerge rgid=45 gid=10

I would want to do something like

$prospects = dedupe.getmatches rule_group_id=45 contact_id={5,7,8,9}

```
foreach ($prospects as $prospectPair)

{ contact.merge($prospectPair); }

```
Fleshing this out a bit more I would probably want to be able to pass contact.api criteria in ie

OR

$prospects = dedupe.getmatches rule_group_id=45 first_name=Bob

It probably makes sense for it to look more like

{{{$prospects = dedupe.getmatches rule_group_id=45 contract_criteria=

{first_name:Bob}

}}

OR

$prospects = dedupe.getmatches rule_group_id=45 contract_criteria={id:{5,6,7}}

Group is supposed by contact api so

$prospects = dedupe.getmatches rule_group_id=45 contract_criteria={first_name:Bob, group:{6,7}}

would work in this approach