Submit and track a verification

This guide checks a candidate's stated job title and start date against the employment record in their Arrota Vault.

Before you begin

• Your organisation is an active verifier organisation, on a plan with API access.
• You have an API key with the verifications:write scope.
• The candidate has shared the Record ID of the record to check, from their Vault.
• You have the candidate's consent. You can link your consent form with authorisation_proof_url.

1. Submit the claims

Send the facts exactly as the candidate stated them. Only fields that belong to the record's type are accepted.

const submit = await fetch("https://app.arrota.com/api/v1/verifications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARROTA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    record_id: "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    submitted_claims: { job_title: "Operations Manager", start_date: "2021-01-15" },
    authorisation_proof_url: "https://hr.example.com/consent/7781.pdf",
  }),
});
const { request_id } = await submit.json();

Store request_id. Each accepted call creates a new request and emails the candidate, so submit once per check.

2. Wait for the holder

Arrota emails the candidate, who approves or denies the request in their Vault. Until then the status is authorisation_required. Tell the candidate to expect the email.

3. Poll for the result

There is no webhook for your own requests. Poll with a generous interval: results depend on a person and sometimes on the issuing organisation's review, so they can take hours or days.

async function getVerification(requestId) {
  const response = await fetch(`https://app.arrota.com/api/v1/verifications/${requestId}`, {
    headers: { Authorization: `Bearer ${process.env.ARROTA_API_KEY}` },
  });
  if (!response.ok) throw new Error(`Arrota API ${response.status}`);
  return response.json();
}

const request = await getVerification(request_id);
if (request.status === "resolved") {
  console.log(request.outcome, request.fields);
}

Poll a few times an hour at most, and stop once status is resolved. If the status is Payment Required, complete payment in the verifier workspace to release the result.

4. Read the result

• outcome summarises the check: Matched, Partially Matched, Not Matched or Refused.
• fields gives a verdict for each claim: match, mismatch or not_applicable.

A mismatch tells you the claim differs from the record, never what the record says. Refused means the candidate declined or the issuing organisation does not disclose this record; it says nothing about whether the claims are true.