---
title: "Import Relationships"
method: POST
path: "/v2/user/relationships"
tags: ["User"]
---

# Import Relationships

`POST /v2/user/relationships`

## Request

- Base URL: `https://api.village.ai`
- URL: `https://api.village.ai/v2/user/relationships`
- Auth: HTTP bearer

Import manual relationships to expand your network graph. Use this to add people you know but aren't connected to digitally. Provide email addresses or LinkedIn URLs with optional relationship scores (0-10, defaulting to 5). Higher scores indicate stronger relationships. Maximum 1000 people per request. Returns: summary counts and individual results showing created, updated, or failed imports.

## Request body

- ImportRelationshipsRequest: Request body for importing user relationships
  - `people` union[], required: Array of people to import as relationships. Can be email addresses, LinkedIn URLs, or objects with identifier and optional score.
    - union
      - string, email
      - string
      - object
        - `identifier` union, required
          - string, email
          - string
        - `score` number
        - `user_relationship_type` 'met_in_person' | 'worked_together' | 'studied_together' | 'attended_event' | 'introduced_by_someone' | 'other': Optional user-set category for this relationship. Distinct from pipeline-derived signals — captured when the user explicitly tags how they know the contact.
  - `min_score` number: Default score for relationships without explicit score (0-10). Defaults to 5.
  - `unhide` boolean: Also bring back contacts the user hid. The Village app sets it when the user writes a contact again; automated imports leave it off so hidden contacts stay hidden.

## Response `200`

Relationships imported successfully

- object
  - `data` ImportRelationshipsResponse, required: Response for importing user relationships
    - `summary` object, required: Summary of the import operation
      - `processed` number, required: Total number of relationships processed
      - `created` number, required: Number of new relationships created
      - `updated` number, required: Number of existing relationships updated
      - `failed` number, required: Number of relationships that failed to process
    - `results` object[], required: Detailed results for each relationship
      - `identifier` string, required: The original identifier provided
      - `status` 'created' | 'updated' | 'failed', required: Result status for this relationship
      - `person` object: Person details (present on success)
        - `id` string, required: Village person ID
        - `name` string, required: Person full name
        - `linkedin` string: LinkedIn profile URL
      - `error` object: Error details (present on failure)
        - `code` string, required: Error code
        - `message` string, required: Error message
  - `metadata` object, required
    - `request_id` string, required

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - missing or invalid authentication
- `422`: Validation error - invalid identifiers or scores

---

[API](https://skmtc.dev/village/apis/village-v2-api.md) - [All operations](https://skmtc.dev/village/apis/village-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/village/apis/village-v2-api/revisions/aebe21a1a544?raw)