Read one verification back

Authenticates a document **as the calling organisation**, signing its hash with the organisation's own post-quantum key and anchoring the result to Hedera. This is the only operation on this API that creates anything. Send a hash. Audrie never receives the document. > **A `test`-prefixed credential cannot reach this operation.** There is > no sandbox ledger: this endpoint signs with your organisation's > production key and anchors a permanent, public Hedera message that > **cannot be withdrawn**, so a key labelled `test` is never granted > `records:write` at all and is refused here with `403`. Mint a `live` > credential when you are ready to create records that are real. ## What this is, and what it is not The signature attributes to an **organisation**, not to a person. No individual is accountable for it: there is no identity-verified signer and no WebAuthn ceremony behind an API call. A verifier sees that difference — these records answer `verified_org` rather than `verified`, carry `signerType: org` on the match, and at the `organisation` tier carry your organisation's registered name in `signerOrg`. Use it where an organisation is the right signer: bulk authentication of documents your organisation issues. Where a named person must be accountable, have that person authenticate in the portal instead. ## Idempotency Retrying is safe, and you do not need an idempotency key: the document hash is the key. Your organisation can hold **one active record per document hash**. A repeat call for a hash you already hold returns that record with `200` and creates nothing; a first call returns `201`. The body is identical either way, because after a timeout you cannot know which call you made — branch on the status only if you care. A record whose anchor ultimately **failed** stops counting, so a later call for that hash creates a new record rather than returning the failed one forever. ## Anchoring is asynchronous, and it can fail On a `201`, `anchorState` is `pending` or `accepted`, and reaches `anchored` at Hedera finality — typically 3–5 seconds. On a `200` retry it is whatever the existing record has already reached, which may be `anchored`. Branch over all three values, not two. Poll `POST /v1/verifications` with the same hash rather than this operation. **Read the verdict, not the clock, and expect three outcomes.** Until the record reaches the ledger, verification answers `no_record` — it reports only records that have been accepted for anchoring, so a record you have just created is briefly invisible there. Then: | The verdict becomes | Meaning | What to do | |---|---|---| | `pending_anchor` | On the ledger, awaiting consensus. | Wait `retryAfterSeconds` and poll again. | | `verified_org` | Anchored. Done. | Nothing. | | still `no_record` after ~3 minutes | **The anchor failed** before the message was submitted. The record is abandoned and stops being active. | Call `POST /v1/records` again for this hash. It will create a new record rather than returning the abandoned one. | | stuck at `pending_anchor` for many minutes | The message reached the ledger but consensus has not been reconciled. **This one does not self-resolve by retrying**, and re-authenticating will not help — the record is still active, so a repeat call returns it unchanged. | Report it with the `recordId`. | **An anchored record cannot be withdrawn.** A Hedera message is permanent. Revocation marks a record as no longer in good standing rather than removing it — see `POST /v1/records/{recordId}/revoke`. ## Errors A `400` means `originalDocHash` is not `sha256:` followed by 64 **lowercase** hex characters, `filename` is longer than 500 characters or contains a control or invisible formatting character, or the body is not a JSON object. `error.details` names the field. Uppercase hex is refused rather than normalised: the hash is used verbatim inside the signature and the ledger message, so two spellings would be two separate permanent records for one document. The `402` and `403` each have more than one cause. **Branch on `error.code`**, and read the response descriptions below — they say which causes exist and which of them mean "wait" rather than "fix something".