Request a card exchange

PUT/card-exchanges/:exchangeId/request

Ask the scanned person to exchange cards (SCANNED → PENDING). A push notification is sent to their official app, and the request waits 3 minutes for approval. Any other exchange the person had in progress is removed.

Auth	Login required

Path parameters

exchangeIdstringrequired

Exchange ID.

Request body

shareEmailbooleanrequired

Whether to share your email address with the other side. Saved as your sharing setting for them; change it later with PATCH /meet-logs/contacts/:userId (or PATCH /meet-logs/communities/:communityId when the other side is a community). When you exchange as a community (myCommunity is not null), it is always treated as false.

subscribeNewsletterbooleanoptional

Whether to receive the newsletter of the other side's community. Required when the other side exchanges as a community, and ignored otherwise. While true, your email address is disclosed to that community even if shareEmail is false.

locationCardExchangeLocation | nulloptional

Current location from the device. Omit it when unavailable. It is kept only in your own record and is never shown to the other side (when you exchange as a community, it is kept in the community's record and visible to all admins).

Notes

You can request the same person up to 5 times per hour (429, errorCode 40206, beyond that).

Returns 409 (errorCode 40204) when expired, and 409 (errorCode 40205, with the current status) when the state does not allow it.

subscribeNewsletter is required when the other side is exchanging as a community (counterpartCommunity is not null); otherwise the call returns 400 (errorCode 40217). This keeps a client that assumes the other side is a person from completing the exchange and handing the email address to a community.

An exchange cannot proceed once the admin lost the role or the community was deleted partway through (after the scan or the request). The exchange is removed and the call returns 403 (errorCode 40208) when you are the community side, or 409 (errorCode 40207) when the other side is.

Response

Returns CardExchange.

Request

curl https://api.4s.link/card-exchanges/EXCHANGE_ID/request \
  -X PUT \
  -H "Authorization: Bearer 4s_at_..." \
  -H "Content-Type: application/json" \
  -d '{
  "shareEmail": true,
  "location": { "latitude": 35.6581, "longitude": 139.7017, "accuracy": 12 }
}'

Example response

{
  "id": "6f1c2d3e-...",
  "status": "PENDING",
  "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": "2026-07-10T06:30:00.000Z",
  "respondedAt": null,
  "myShareEmail": true,
  "mySubscribeNewsletter": null,
  "result": null
}