> ## Documentation Index
> Fetch the complete documentation index at: https://compass.docs.sunnyscoach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Match Suggestions

> Admin-only endpoint that returns suggested user pairs that may represent the same person.   Suggestions are generated by comparing emails and personal information (first name, last name, name).


Admin-only endpoint that returns suggested user pairs that may represent the same person. Suggestions are generated by comparing emails and personal information (first name, last name, name).

## Request

### Headers

| Name          | Type   | Required | Description  |
| ------------- | ------ | -------- | ------------ |
| Authorization | string | Yes      | Bearer token |

## Response

### 200 OK - Successfully retrieved match suggestions

```json theme={null}
{
  "message": "Match suggestions retrieved successfully",
  "data": {
    "suggestions": [
      [
        {
          "_id": "64b7f1a2e4b0a5d3f9c12345",
          "emails": "john.doe@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "name": "John Doe",
          "matchScore": 0.95
        },
        {
          "_id": "64b7f2b3e4b0a5d3f9c54321",
          "emails": "j.doe@company.com",
          "firstName": "John",
          "lastName": "Doe",
          "name": "John Doe",
          "matchScore": 0.95
        }
      ],
      [
        {
          "_id": "64b7f3c4e4b0a5d3f9c98765",
          "emails": "jane.smith@example.com",
          "firstName": "Jane",
          "lastName": "Smith",
          "name": "Jane Smith",
          "matchScore": 0.87
        },
        {
          "_id": "64b7f4d5e4b0a5d3f9c11111",
          "emails": "jane.s@company.com",
          "firstName": "Jane",
          "lastName": "Smith",
          "name": "Jane Smith",
          "matchScore": 0.87
        }
      ]
    ]
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid token or insufficient permissions"
  }
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": {
    "code": "SERVER_ERROR",
    "message": "Internal server error"
  }
}
```

## Example

```bash theme={null}
curl -X GET 'http://localhost:2000/user/match-suggestions' \
  -H 'Authorization: Bearer your-jwt-token'
```

## Notes

* This is an admin-only endpoint - requires administrative privileges
* Suggestions are based on similarity of emails and personal information
* Each suggestion is an array of 2 users that may represent the same person
* The match score indicates confidence level (0.0 to 1.0)
* Higher scores indicate stronger matches
* Use these suggestions to identify potential duplicate accounts
* After reviewing, use the link-accounts endpoint to merge duplicates
* The algorithm compares: email domains, names, and other personal data
* Suggestions are generated in real-time and may change as user data updates

## Matching Criteria

The system considers the following when generating suggestions:

* Email address similarity (same domain, similar local parts)
* Exact name matches (first and last name)
* Similar email patterns (e.g., john.doe vs j.doe)
* Phone number matches
* Department and role similarities

## Usage Workflow

1. Call this endpoint to get potential duplicate pairs
2. Review each suggestion manually
3. Use the `/user/link-accounts` endpoint to merge confirmed duplicates
4. Repeat periodically to catch new potential duplicates


## OpenAPI

````yaml GET /user/match-suggestions
openapi: 3.0.3
info:
  title: COMPASS API
  version: 1.0.0
  description: OpenAPI specification for the Compass backend routes.
servers:
  - url: http://localhost:2000
    description: Local development server
security: []
tags:
  - name: Auth
    description: >-
      Authentication and session management endpoints (OAuth and session
      validation)
  - name: Users
    description: Operations for managing user records
  - name: Departments
    description: Operations for managing departments
  - name: Email Meter
    description: APIs to get Email Meter Stats
  - name: HubSpot Tickets
    description: Feedback APIs
  - name: Permissions
    description: Permissions APIs
  - name: Transcription
    description: Transcription APIs
paths:
  /user/match-suggestions:
    get:
      tags:
        - Users
      summary: Get suggested user account matches
      description: >
        Admin-only endpoint that returns suggested user pairs that may represent
        the same person.   Suggestions are generated by comparing emails and
        personal information (first name, last name, name).
      responses:
        '200':
          description: Successfully retrieved match suggestions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      suggestions:
                        type: array
                        description: Array of suggested user pairs
                        items:
                          type: array
                          minItems: 2
                          maxItems: 2
                          items:
                            $ref: '#/components/schemas/MatchSuggestionUser'
        '401':
          description: Unauthorized (missing/invalid token or insufficient permissions)
        '500':
          description: Server error
      security:
        - bearerAuth: []
components:
  schemas:
    MatchSuggestionUser:
      type: object
      properties:
        _id:
          type: string
          example: 64ef3c29f9a1c27e1b2c3a4d
        emails:
          type: array
          items:
            type: string
          example:
            - user@example.com
        personalInformation:
          type: object
          properties:
            firstName:
              type: string
              example: John
            lastName:
              type: string
              example: Doe
            name:
              type: string
              example: John Doe
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````