> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dokstamp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Certificates

> Issue, manage, and verify digital certificates — the core output of the DokStamp platform.

# Certificates

A certificate is the digital credential that binds a student to a course, issued by an institution. It includes a signed PDF file, a public verification URL, and an immutable snapshot of the student's identity at issuance time.

***

## The certificate object

```json theme={null}
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "issued",
  "issued_at": "2024-12-01T00:00:00.000000Z",
  "revoked_at": null,
  "revocation_reason": null,
  "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4",
  "blockchain_tx_hash": null,
  "blockchain_tx_url": null,
  "institution": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Federal University of Technology"
  },
  "course": {
    "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Bachelor of Computer Science"
  },
  "student": {
    "uuid": "f6a7b8c9-d0e1-2345-fghi-456789012345",
    "name": "Maria Fernanda Silva"
  },
  "cohort": null,
  "enrollment": null,
  "template": null,
  "files": [
    {
      "type": "certificate",
      "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567"
    }
  ]
}
```

| Field                     | Type           | Description                                |
| ------------------------- | -------------- | ------------------------------------------ |
| `uuid`                    | string         | Unique identifier                          |
| `status`                  | enum           | `draft`, `issued`, `revoked`, `expired`    |
| `issued_at`               | datetime       | Official issuance date                     |
| `revoked_at`              | datetime\|null | Revocation timestamp                       |
| `revocation_reason`       | string\|null   | Reason for revocation                      |
| `public_verification_url` | string\|null   | Shareable URL for third-party verification |
| `blockchain_tx_hash`      | string\|null   | Blockchain transaction hash (if anchored)  |
| `files`                   | array          | Attached PDF files                         |

***

## List certificates

```http theme={null}
GET /certificates
```

<CodeGroup>
  ```bash cURL theme={null}
  # List all issued certificates for a course
  curl "https://api.dokstamp.com/certificates?where[status]=issued&where[course_uuid]=c3d4e5f6-a7b8-9012-cdef-123456789012&sort[column]=issued_at&sort[order]=desc" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}"
  ```
</CodeGroup>

***

## Issue a certificate

```http theme={null}
POST /certificates
```

| Parameter                 | Type    | Required | Description                                                                                       |
| ------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------- |
| `institution_uuid`        | string  | Yes      | Issuing institution UUID                                                                          |
| `course_uuid`             | string  | Yes      | Course UUID                                                                                       |
| `student_uuid`            | string  | Yes      | Recipient student UUID                                                                            |
| `file_uuid`               | string  | Yes      | UUID of the uploaded PDF file (must be unused)                                                    |
| `finish`                  | boolean | No       | `true` to immediately issue the certificate (see below). Defaults to `false` (creates as `draft`) |
| `cohort_uuid`             | string  | No       | Cohort UUID                                                                                       |
| `enrollment_uuid`         | string  | No       | Enrollment UUID                                                                                   |
| `template_uuid`           | string  | No       | Certificate template UUID                                                                         |
| `public_verification_url` | string  | No       | Custom verification URL (auto-generated if omitted)                                               |

<Info>
  **`finish: true`** triggers the full issuance pipeline in a single call: sets `status` to `issued`, cryptographically signs all files, generates the academic transcript PDF, and sends the certificate notification to the student. Without it, the certificate is saved as `draft`.
</Info>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dokstamp.com/certificates \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Tenant: {TENANT}" \
    -d '{
      "institution_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "course_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "student_uuid": "f6a7b8c9-d0e1-2345-fghi-456789012345",
      "file_uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
      "cohort_uuid": "e5f6a7b8-c9d0-1234-efgh-345678901234",
      "enrollment_uuid": "g7h8i9j0-k1l2-3456-mnop-567890123456",
      "finish": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://api.dokstamp.com/certificates', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'X-Tenant': TENANT,
    },
    body: JSON.stringify({
      institution_uuid: INSTITUTION_UUID,
      course_uuid: COURSE_UUID,
      student_uuid: STUDENT_UUID,
      file_uuid: FILE_UUID,
      finish: true,
    }),
  });
  const { data: certificate } = await res.json();
  console.log('Verification URL:', certificate.public_verification_url);
  ```

  ```php PHP theme={null}
  $response = Http::withToken($token)
      ->withHeaders(['X-Tenant' => $tenant, 'Accept' => 'application/json'])
      ->post('https://api.dokstamp.com/certificates', [
          'institution_uuid' => $institutionUuid,
          'course_uuid'      => $courseUuid,
          'student_uuid'     => $studentUuid,
          'file_uuid'        => $fileUuid,
          'finish'           => true,
      ]);

  $certificate = $response->json('data');
  ```
</CodeGroup>

**Response `201`:**

```json theme={null}
{
  "data": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "issued",
    "issued_at": "2024-12-01T00:00:00.000000Z",
    "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4",
    "institution": { "name": "Federal University of Technology" },
    "course": { "name": "Bachelor of Computer Science" },
    "student": { "name": "Maria Fernanda Silva" }
  }
}
```

<Warning>
  A file UUID can only be used once. If you attempt to create a second certificate with the same `file_uuid`, you will receive a `422` error. Upload a new file for each certificate.
</Warning>

***

## Get a certificate

```http theme={null}
GET /certificates/{uuid}
```

```bash theme={null}
GET /certificates/{uuid}?includes[student]=1&includes[course]=1&includes[institution]=1&includes[files]=1
```

***

## Update a certificate

```http theme={null}
PATCH /certificates/{uuid}
PUT   /certificates/{uuid}
```

You can update certificates in `draft` status. Updating an `issued` certificate is restricted.

***

## Delete a certificate

```http theme={null}
DELETE /certificates/{uuid}
DELETE /certificates/batch/destroy
```

***

## Badge assertion (Open Badges)

```http theme={null}
GET /certificates/{uuid}/badges/assertions
```

Returns the W3C Open Badges 2.0 assertion for the certificate. This endpoint is used by badge verification services and badge backpacks (e.g., Badgr, Credly).

***

## Related

* [Revoke a Certificate](/en/api-reference/certificates/revocation)
* [Certificate Lifecycle](/en/core-concepts/certificate-lifecycle)
* [Files](/en/api-reference/files) — upload PDFs before creating certificates