---
title: "Import Relationships From List"
method: POST
path: "/v2/user/relationships/import-from-list"
tags: ["User"]
---

# Import Relationships From List

`POST /v2/user/relationships/import-from-list`

## Request

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

Queue a backend relationship import from a people SearchList. The list is used as the durable import scope, and job state is exposed on search_lists.import_metadata.relationship_import. Use this for large imports instead of sending client-side batches.

## Request body

- ImportRelationshipsFromListRequest: Request body for queueing a list-backed relationship import
  - `list_id` string, required: SearchList ID containing people to import as relationships
  - `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.
  - `score` number: Relationship score (0-10). Defaults to 5.
  - `selection` union, required: Which graph IDs from the list snapshot to import. Use all for the full list, include for an explicit subset, or exclude for all except the provided IDs.
    - object
      - `mode` 'all', required
    - object
      - `mode` 'include', required
      - `graph_ids` string[], required
    - object
      - `mode` 'exclude', required
      - `graph_ids` string[], required
  - `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`

Relationship import queued

- object
  - `data` ImportRelationshipsFromListResponse, required: Response after queueing a list-backed relationship import
    - `status` 'queued', required: Relationship import job status
    - `list_id` string, required: SearchList ID used as the durable import scope
    - `job_id` string, required: Bull job ID for the queued relationship import
    - `snapshot_at` string, required: ISO timestamp used to snapshot eligible list items
  - `metadata` object, required
    - `request_id` string, required

## Other responses

- `400`: Invalid list, list type, import status, or selection
- `401`: Unauthorized - missing or invalid authentication
- `404`: List not found
- `409`: Relationship import already queued or processing for this list
- `422`: Validation error - invalid relationship type, score, or IDs

---

[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)