# Match and connect records

Finds rows on another accessible board where one selected column exactly matches the supplied value after trimming whitespace and ignoring case, then writes this row's native record-link column only when exactly one match exists. Zero or multiple matches return a branchable status and candidates without changing data. An existing different link returns conflict and is never overwritten; retrying the same link is idempotent. Use for email, client code, SSN, EIN, or any stored non-blank value. Name source_column to match this record's own cell in that column (e.g. its Email) instead of passing match_value. The source board must be writable and the target board readable.

Access class: `def:read`.

## Endpoint

`POST /v1/definitions/{key}/rows/{rowId}/match-link`

## Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| key | path | string | Yes |
| rowId | path | string | Yes |

## Request body

Content type: `application/json`.

```json
{
  "body": {
    "audit_cells": {},
    "match_column": "string",
    "match_value": "string",
    "relation_column": "string",
    "source_column": "string",
    "target_definition_key": "string"
  },
  "params": {
    ":key": "string",
    ":rowId": ""
  },
  "query": {}
}
```

## Responses

### 201

the action's answer

Content type: `application/json`.

```json
{
  "data": {
    "idempotent": true,
    "linked": true,
    "match_count": 1,
    "matches": [
      {
        "cells": "string",
        "label": "string",
        "row_id": ""
      }
    ],
    "previous_target_id": "",
    "status": "string",
    "target_row_id": ""
  }
}
```

### default

a refusal: `{"error": "<what a person needs to read>"}`. 401 no credential, 402 the plan does not include this, 403 the seat does not, 404 the thing does not exist or is not yours to see.

Content type: `application/json`.

```json
{
  "error": "string"
}
```