Credentials

List credentials

GET/api/v1/credentials

Returns the digital credentials your organisation has issued, newest first. Requires the credentials:read scope.

Query parameters

Example request

curl "https://app.arrota.com/api/v1/credentials?limit=10&status=active" \
  -H "Authorization: Bearer $ARROTA_API_KEY"

const url = new URL("https://app.arrota.com/api/v1/credentials");
url.searchParams.set("limit", "10");
url.searchParams.set("status", "active");
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ARROTA_API_KEY}` },
});
const { data, next_cursor } = await response.json();

Response

{
  "data": [
    {
      "id": "5b6f0c2a-1d3e-4f5a-9b7c-8d9e0f1a2b3c",
      "type": "Certification",
      "status": "active",
      "recipient_name": "Alex Rivera",
      "issued_on": "2026-09-18",
      "created_at": "2026-09-18T10:42:11.402Z",
      "expires_on": "2029-09-18"
    }
  ],
  "next_cursor": null
}

The issued_after and issued_before filters use issued_on; created_after and created_before use created_at. Results are always ordered by created_at, newest first, so pagination is stable.

Changed in September 2026: issued_on and the issued_* filters previously used the Arrota creation time. They now use the credential's own issue date, and created_at carries the creation time.

Errors

400 for an invalid limit, status, record_type, date or cursor; 401; 403 for a missing scope or a plan without API access; 429. See Errors.

Issue a credential

POST/api/v1/credentials

Issues one digital credential from a certificate template and delivers it to the recipient. Requires the credentials:write scope. This creates a real credential; there is no test mode.

Headers

Body

Employment documents (offer, appointment, promotion, experience and relieving letters, and employment verification) and background checks cannot be issued from a template. They must be evidenced by the original document, which you issue in the dashboard; the API refuses them with TEMPLATE_NOT_ALLOWED.

Example request

curl -X POST "https://app.arrota.com/api/v1/credentials" \
  -H "Authorization: Bearer $ARROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: course-4471-alex-rivera" \
  -d '{
    "recipient_name": "Alex Rivera",
    "work_email": "alex.rivera@example.com",
    "document_type": "Certification",
    "issue_date": "2026-09-18"
  }'

const response = await fetch("https://app.arrota.com/api/v1/credentials", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ARROTA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "course-4471-alex-rivera",
  },
  body: JSON.stringify({
    recipient_name: "Alex Rivera",
    work_email: "alex.rivera@example.com",
    document_type: "Certification",
    issue_date: "2026-09-18",
  }),
});

Responses

202 Accepted: the credential was issued.

{
  "ok": true,
  "document_id": "5b6f0c2a-1d3e-4f5a-9b7c-8d9e0f1a2b3c",
  "record_id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
  "verification_status": "Issuer Issued",
  "email_queued": true,
  "check": "/api/v1/credentials?limit=1"
}

email_queued is false when no email was sent, for example for a historical import.

200 OK: an identical issuance already exists, so nothing new was created.

{ "ok": true, "document_id": "5b6f0c2a-1d3e-4f5a-9b7c-8d9e0f1a2b3c", "status": "already_issued" }

Errors

See Errors for 401, 429 and server errors.

Related webhook events

credential.issued fires for every issued credential, credential.claimed when the holder claims it and credential.revoked if it is revoked. See Webhook events.