Start a card exchange (scan)

POST/card-exchanges

Send the token from the other person's My QR code (`https://4s.link/{slug}?ref=code&token=...`) to start a business card exchange. The response includes a summary of their profile to show on the request screen. The token proves the QR code was scanned in person, so a slug alone cannot start an exchange. Each user has at most one exchange in progress; starting a new one removes the previous one. When you scan a community's card QR code (`https://4s.link/communities/{communityId}?ref=code&token=...`, where the token belongs to the admin showing the card), send the community ID from the path as targetCommunityId. To request as a community you administer, send asCommunityId.

Auth	Login required

Request body

tokenstringrequired

The token query parameter of the My QR code URL (or of a community's card QR code URL).

targetCommunityIdstring | nulloptional

The community ID when you scanned a community's card QR code. The token's owner exchanges as an admin of that community.

asCommunityIdstring | nulloptional

The community ID when you request as a community. You must be an approved admin (ADMIN) of it.

Notes

Returns 404 (errorCode 40201) when the token is invalid or the user has left, and 400 (errorCode 40202) for your own QR code.

Returns 404 (errorCode 40201) when targetCommunityId is given but the token's owner is not an admin of that community (or the community was deleted), and 403 (errorCode 40208) when you are not an admin of the asCommunityId community. Communities cannot exchange with each other, so sending both returns 400 (errorCode 40209).

When the other side is a community, counterpartCommunity holds its summary and counterpart is the admin handling the exchange. On your turn the response also includes defaultSubscribeNewsletter (the initial value for the newsletter switch). When you request as a community, myCommunity is set and defaultShareEmail is omitted.

A scanned exchange expires after 10 minutes.

Response

Returns CardExchange.

Request

curl https://api.4s.link/card-exchanges \
  -X POST \
  -H "Authorization: Bearer 4s_at_..." \
  -H "Content-Type: application/json" \
  -d '{
  "token": "Qm9vZ2xlLWNoZWNraW4tdG9rZW4..."
}'

Example response

{
  "id": "6f1c2d3e-...",
  "status": "SCANNED",
  "role": "REQUESTER",
  "counterpart": {
    "id": "u-taro",
    "slug": "taro",
    "firstName": "Taro",
    "lastName": "Yamada",
    "nativeName": "山田 太郎",
    "avatarUrl": "https://...",
    "title": "代表取締役",
    "bio": "企業の新規事業を支えるサービスを開発しています。",
    "cardDesign": "gradient-01-cobalt-mint",
    "cardPhoto": null,
    "organization": {
      "id": "org-1",
      "name": "株式会社HORIZON",
      "slug": "horizon",
      "logoUrl": null,
      "title": "ビジネス開発チーム"
    }
  },
  "counterpartCommunity": null,
  "myCommunity": null,
  "expiresAt": "2026-07-10T06:33:00.000Z",
  "createdAt": "2026-07-10T06:29:40.000Z",
  "requestedAt": null,
  "respondedAt": null,
  "myShareEmail": null,
  "defaultShareEmail": true,
  "mySubscribeNewsletter": null,
  "previousExchange": null,
  "result": null
}