When a Prospect for which is_archived=1 has "update" (by email or ID) or "upsert" (by id) run on it, is_archived will stay 1 for the Prospect.
HOWEVER:
When a Prospect for which is_archived=1 has "upsert" (by email) run on it, is_archived will change to 0 for the Prospect.
This needs to be documented for the time being, and a bug/improvement should be filed for it in JIRA to make the behavior consistent across updates/upserts.
When a Prospect for which is_archived=1 has "update" (by email or ID) or "upsert" (by id) run on it, is_archived will stay 1 for the Prospect.
HOWEVER:
When a Prospect for which is_archived=1 has "upsert" (by email) run on it, is_archived will change to 0 for the Prospect.
This needs to be documented for the time being, and a bug/improvement should be filed for it in JIRA to make the behavior consistent across updates/upserts.