Authors and claims

Many people who wrote on the old platform have not joined Zen Social when you move their posts in. Their posts can still come in under their name, and be handed to them later, when they have joined. Handing them over is a claim. A claim can be undone.

Names from the old platform

A post created with author instead of author_id (see Posts) shows the name you sent, with no profile and no link:

{"author": {"external_id": "fb-user-1002", "name": "Ole Berg"}}

The external_id in author is your own id for that person on the old platform. It is what a claim works with: the claim hands over every post of this community that you created with that author external_id. So:

Use the same author external_id for all posts by the same person, and a different one for every person, even when two people share a name.
Send the post's own external_id too. Zen Social remembers authors only for posts created with an external_id. A post created with an author name but without its own external_id can never be claimed, and stays under the old name for good.

Claim: `POST /authors/:author_external_id/claim`

When the person has joined and you have found them in GET /members, the claim makes them the author of all their imported posts.

Confirm with the admin first. Show them the name match you intend to make (for example "Ole Berg on Facebook, 2 posts → Ole Berg, member Qm3TzK8pWn2D") and wait for their yes. When a name fits more than one member, or fits only roughly, ask; do not guess.

curl "$API/authors/fb-user-1002/claim" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"member_id": "Qm3TzK8pWn2D"}'

member_id is the member's id from Members. Answers 201 Created:

{"claimed": 2, "claimed_ids": [9002, 9003], "skipped": 0, "skipped_ids": []}

claimed_ids are the posts that now belong to the member; skipped_ids are posts that were not handed over (below).

What a claim skips

A post is skipped, and listed in skipped_ids, when:

the member is not in every one of its circles. Posts are never handed to someone who cannot see them. Tell the admin which circle it is; once the member has joined it in the app, send the same claim again and the skipped posts are claimed then.
the admin can no longer post in one of its circles. Ask the admin to rejoin that circle, or have an admin who can post there make a key.

Undo: `DELETE /authors/:author_external_id/claim`

A claim made by mistake is undone with DELETE on the same address. Confirm with the admin first, as for a claim.

curl -X DELETE "$API/authors/fb-user-1002/claim" -H "Authorization: Bearer $KEY"

Answers 200 OK:

{"released": 2, "released_ids": [9002, 9003], "skipped": 0, "skipped_ids": []}

The posts go back to the name from the old platform, exactly as they were imported, again without telling anyone. Posts that were never claimed are left as they are and not listed. A post in a circle the admin can no longer post in is skipped and listed in skipped_ids. 404 not_found when this community never imported a post with that author external_id.

The author id in the address

The author external_id is part of the address, so percent-encode it: a space is %20, and a slash must be sent as %2F. Letters, digits, -, _, . and : can stay as they are.

For the author external_id old-site/users/17:

curl "$API/authors/old-site%2Fusers%2F17/claim" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"member_id": "Qm3TzK8pWn2D"}'

Example: three posts from two Facebook authors

The admin is moving the Facebook group's "Garden Swap" posts into the circle with id 412. Three posts, by two people:

Karen Holm wrote one post. She is already a member: GET /members lists her as EveABqLyto9L, and she is in the Garden Swap circle.
Ole Berg wrote two. He has not joined yet. His Facebook user id is 1002.

You have agreed the plan with the admin. The first post is Karen's, under her member id:

curl "$API/posts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"external_id": "fb-post-5001", "circle_ids": [412], "author_id": "EveABqLyto9L", "created_at": "2023-04-15T10:00:00Z", "content": "Who has spare tomato seedlings?\n\nI can swap basil."}'

The other two are Ole's, under his name, each with its own external_id and both with the same author external_id:

curl "$API/posts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"external_id": "fb-post-5002", "circle_ids": [412], "author": {"external_id": "fb-user-1002", "name": "Ole Berg"}, "created_at": "2023-04-16T08:15:00Z", "content": "I have six seedlings for you, Karen."}'

curl "$API/posts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"external_id": "fb-post-5003", "circle_ids": [412], "author": {"external_id": "fb-user-1002", "name": "Ole Berg"}, "created_at": "2023-05-02T18:30:00Z", "content": "The swap table is up!", "image_urls": ["https://example.org/swap-table.jpg"]}'

Each answers 201 Created, with ids 9001, 9002 and 9003. Nobody is told. Ask the admin to look at the circle in the app: the posts sit in April and May 2023, and Ole's show his name without a profile.

Weeks later, Ole accepts the admin's invitation and joins Garden Swap. GET /members now lists him:

{"id": "Qm3TzK8pWn2D", "name": "Ole Berg", "avatar_url": null, "circles": [{"id": 412, "name": "Garden Swap"}]}

Tell the admin: "Ole Berg on Facebook (2 posts) looks like the member Ole Berg (Qm3TzK8pWn2D). Shall I hand his posts to him?" When they say yes:

curl "$API/authors/fb-user-1002/claim" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"member_id": "Qm3TzK8pWn2D"}'

It answers 201 Created with {"claimed": 2, "claimed_ids": [9002, 9003], "skipped": 0, "skipped_ids": []}. Both posts are now Ole's. Karen's post was never part of it.

If the admin later says it was a different Ole, undo it with DELETE "$API/authors/fb-user-1002/claim", and the posts show "Ole Berg" from Facebook again.