User

Import Relationships From List

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.

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

Request body

list_idstring 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.

scorenumber

Relationship score (0-10). Defaults to 5.

unhideboolean

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.

Example request

{
  "list_id": "123",
  "relationship_type": "worked_together",
  "score": 5
}

Response

Relationship import queued

Example response

{
  "data": {
    "status": "queued",
    "list_id": "123",
    "job_id": "relationship-import-list-123-1717351820000",
    "snapshot_at": "2026-06-05T12:00:00.000Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.