File a flag
Files a safety flag about a person or an animal. It is shared ACROSS organizations: once it is vetted, every other organization using RescueConsole can read it, including the narrative, the evidence references, the identifiers as they are kept, and your organization’s name, contact email and contact phone.
A new flag is always pending_review, whatever you send. When its visibility is network, the people at every other organization who may review flags (write on Registry) are asked to: a notice on their bell and an email, saying the kind of flag, its severity and its subject type, never who it is about or what it says. They can open it to review it; no search returns it until two of them corroborate it and it becomes active. If you set visibility to private, no other organization is asked, or ever sees it.
The identifiers are what a search matches on, and they are kept masked. A microchip number, email address and phone number are kept only as a hash, so a search that already has one can match it, and the value itself is not stored. A date of birth is kept as its year plus a hash of the full date. An address is cut to its city, state or region, and country; the street lines and postal code are dropped. A name, an alias and an animal’s description are kept as written and shown in full. An identifier that is not allowed for the subject type is refused, not ignored.
The API has no route to edit or withdraw a flag once it is filed. Needs write on Registry.
Authorizations
Body
What the flag can be found by. At least one key. A person may carry name, name_alias, email, phone, phone_country, address, date_of_birth and microchip_number. An animal may carry microchip_number, animal_name, species, breed, color, sex and name_alias. Any other key is refused. After masking at least one searchable value must be left: a street address alone is refused.
Response
The flag, as it was filed, with its identifiers masked.
The identifiers as a reader sees them. Only the keys the flag was filed with are present.
Nothing hashed comes back (Phase 422). A microchip number, an email address, a phone number, a date of birth and a street address are stored ONLY as hashes, and those hashes are not returned: a date of birth has about 36,500 plausible values, a phone number with its area code has ten million, and a hash handed to a reader is one offline pass away from being the value itself. What you get instead is the part that was always meant to be read - the birth YEAR, the town and state, the name, the animal’s description.
To match what you already hold, SEND IT: GET /api/registry/search takes microchip_number, email, phone, date_of_birth, address and name_alias as plain values, hashes them the same way the flag was hashed, and answers with the flags that match. That is the whole bargain this registry works to - confirm what you hold, and do not harvest what you do not.
Null while the review is open, and when the votes made the flag active. not_corroborated: the review closed with as many or more votes to dispute it or say there is not enough evidence as to corroborate it (a tie included). expired: it closed with no votes; the organization that filed it can ask again. Either way the flag stays pending_review, is not a finding, and is open to nobody's review.
not_corroborated, expired, null 
