Skip to content

previewImport

POST
/imports/preview
curl --request POST \
  --url http://localhost:8080/api/v1/imports/preview \
  --header 'Content-Type: application/json' \
  --cookie hs_session=<hs_session> \
  --data '{ "url": "https://example.com", "pack": { "format": "homestead.circle-pack", "version": 1, "circle": { "name": "example", "icon": "example", "color": "terracotta" }, "sharedBy": { "householdName": "example", "memberName": "example" }, "people": [ { "ref": "example", "displayName": "example", "relationLabel": "example", "kind": "family", "notes": "example", "avatarUrl": "https://example.com", "accounts": [ { "platform": "instagram", "handle": "example", "platformUserId": "example", "profileUrl": "https://example.com" } ] } ], "createdAt": "2026-04-15T12:00:00Z", "expiresAt": "2026-04-15T12:00:00Z" } }'

Fetches a share URL (any Homestead instance; allow-listed path shape only) or takes an inline pack, and matches people and accounts against this household.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
object
url
required
string format: uri
pack

Portable circle format. Also saved as .homestead.json files.

object
format
required
string
Allowed value: homestead.circle-pack
version
required
integer
Allowed value: 1
circle
required
object
name
required
string
icon
required
string
color
required
string
Allowed values: terracotta honey sage dusk plum clay
sharedBy
object
householdName
string
memberName
string
people
required
Array<object>
<= 1000 items
object
ref
required

Opaque per-pack reference.

string
displayName
required
string
relationLabel
string
kind
required
string
Allowed values: family friend creator other
notes
string
avatarUrl
string format: uri
accounts
required
Array<object>
object
platform
required
string
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
handle
required
string
platformUserId
string
profileUrl
required
string format: uri
createdAt
required
string format: date-time
expiresAt
One of:
string format: date-time

Responses

Section titled “Responses”

200

Section titled “200”

Preview with suggested actions.

Media typeapplication/json
object
pack
required

Portable circle format. Also saved as .homestead.json files.

object
format
required
string
Allowed value: homestead.circle-pack
version
required
integer
Allowed value: 1
circle
required
object
name
required
string
icon
required
string
color
required
string
Allowed values: terracotta honey sage dusk plum clay
sharedBy
object
householdName
string
memberName
string
people
required
Array<object>
<= 1000 items
object
ref
required

Opaque per-pack reference.

string
displayName
required
string
relationLabel
string
kind
required
string
Allowed values: family friend creator other
notes
string
avatarUrl
string format: uri
accounts
required
Array<object>
object
platform
required
string
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
handle
required
string
platformUserId
string
profileUrl
required
string format: uri
createdAt
required
string format: date-time
expiresAt
One of:
string format: date-time
matches
required
Array<object>
object
ref
required
string
existingPersonId
One of:
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
existingAccountIds
Array<string>
suggestedAction
required
string
Allowed values: create merge skip
warnings

Reasons this person or their accounts cannot be imported as-is.

Array<string>
Allowed values: platform_unsupported invalid_handle invalid_profile_url no_accounts

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "matches": [
    {
      "existingAccountIds": [
        "acc_01j93283xpmc4y04hy7rmmt7y7"
      ],
      "existingPersonId": "per_01j9wst6a8vjc69r66y6fj70t5",
      "ref": "p1",
      "suggestedAction": "merge"
    },
    {
      "existingAccountIds": [
        "acc_01j9te0skfktnnmw6zvew46azb"
      ],
      "existingPersonId": "per_01j9f8r1agkh6g3jp30xcwnytc",
      "ref": "p2",
      "suggestedAction": "merge"
    },
    {
      "existingAccountIds": [],
      "existingPersonId": null,
      "ref": "p3",
      "suggestedAction": "create"
    },
    {
      "existingAccountIds": [
        "acc_01j9e8wtqqwvx5c5qxjqyd78he",
        "acc_01j936xmqyft8qfbq7srt9h04r"
      ],
      "existingPersonId": "per_01j9yjkch7a0ayzz8784jtf08t",
      "ref": "p4",
      "suggestedAction": "skip"
    }
  ],
  "pack": {
    "circle": {
      "color": "terracotta",
      "icon": "home",
      "name": "Family"
    },
    "createdAt": "2026-10-15T09:00:00.000Z",
    "expiresAt": "2026-11-16T09:00:00.000Z",
    "format": "homestead.circle-pack",
    "people": [
      {
        "accounts": [
          {
            "handle": "mom.wong.bkk",
            "platform": "instagram",
            "profileUrl": "https://www.instagram.com/mom.wong.bkk/"
          },
          {
            "handle": "pranee.wong",
            "platform": "facebook",
            "profileUrl": "https://www.facebook.com/pranee.wong"
          }
        ],
        "displayName": "Mom",
        "kind": "family",
        "ref": "p1",
        "relationLabel": "แม่"
      },
      {
        "accounts": [
          {
            "handle": "lin.cooks",
            "platform": "instagram",
            "profileUrl": "https://www.instagram.com/lin.cooks/"
          }
        ],
        "displayName": "Lin",
        "kind": "family",
        "ref": "p2",
        "relationLabel": "Cousin"
      },
      {
        "accounts": [
          {
            "handle": "~grandma_noi",
            "platform": "line",
            "profileUrl": "https://line.me/R/ti/p/~grandma_noi"
          }
        ],
        "displayName": "Grandma Noi",
        "kind": "family",
        "ref": "p3",
        "relationLabel": "ยาย"
      },
      {
        "accounts": [
          {
            "handle": "wei_chengdu88",
            "platform": "wechat",
            "profileUrl": "https://weixin.qq.com/"
          },
          {
            "handle": "MS4wLjABAAAAweichengdu0000000000000000000000",
            "platform": "douyin",
            "platformUserId": "98765432101",
            "profileUrl": "https://www.douyin.com/user/MS4wLjABAAAAweichengdu0000000000000000000000"
          }
        ],
        "displayName": "Uncle Wei",
        "kind": "family",
        "ref": "p4",
        "relationLabel": "舅舅"
      }
    ],
    "sharedBy": {
      "householdName": "The Wongs' Homestead",
      "memberName": "Mali"
    },
    "version": 1
  }
}

400

Section titled “400”

Invalid request.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
i18nKey
string
detail
string
fields
Array<object>
object
path
required
string
code
required
string
i18nKey
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}

410

Section titled “410”

Expired or revoked.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
i18nKey
string
detail
string
fields
Array<object>
object
path
required
string
code
required
string
i18nKey
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}

502

Section titled “502”

A remote server did not answer.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
i18nKey
string
detail
string
fields
Array<object>
object
path
required
string
code
required
string
i18nKey
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}