# Credentials - issued certificates

> With the credentials:read scope, GET /credentials lists every course and programme certificate the team has issued, and GET /credentials/{certificate_number} returns one, including the signed credential. Filter by learner, course, programme, award date or state.

Both endpoints need the `credentials:read` scope.

| Method | Path | What it does |
|---|---|---|
| GET | `/credentials` | List issued certificates |
| GET | `/credentials/{certificate_number}` | One certificate, with its signed credential |

A credential is a certificate Continuum has issued to a learner, for a course or for a [programme](https://continuumlearn.com/help/programmes). Each has its own certificate number. Issued certificates don't change when a template is edited later, so what the API returns is what the learner received.

## The credential object

```json
{
  "certificate_number": "CL-58-01M70BNQMBD7GRTW9QZ33R63W4",
  "state": "valid",
  "title": "Food Safety Level 2",
  "learner_name": "Sam Patel",
  "awarded_at": "2026-11-09T14:33:54+00:00",
  "expires_at": "2029-11-09T14:33:54+00:00",
  "revoked_at": null,
  "verify_url": "https://acme.continuumlearn.com/verify/...",
  "credential_url": "https://continuumlearn.com/credentials/...",
  "badge_url": "https://continuumlearn.com/credentials/....png",
  "certifiable": { "type": "course", "id": 412 },
  "user": {
    "id": 2,
    "email": "sam@example.org",
    "name": "Sam Patel",
    "external": { "id": "M-1042", "source": "acme" }
  }
}
```

| Field | Description |
|---|---|
| `certificate_number` | The number printed on the certificate. |
| `state` | `valid`, `expired` (past `expires_at`), `revoked`, or `unsigned` (issued, but its digital signature hasn't been added yet). |
| `title` | The course or programme title as printed on the certificate. |
| `learner_name` | The name as printed on the certificate, which can differ from the account's current name. |
| `awarded_at`, `expires_at`, `revoked_at` | When it was awarded, when it expires (`null` if it doesn't) and when it was revoked (`null` if it wasn't). |
| `verify_url` | The public verification page, or `null` unless verification is turned on in the certificate template. |
| `credential_url` | The signed digital credential, once it has been signed; otherwise `null`. |
| `badge_url` | The badge image. |
| `certifiable` | What it was awarded for: `type` is `course` or `programme`, with its `id`. |
| `user` | The learner, in the compact user shape. |

`GET /credentials/{certificate_number}` adds `credential_jwt`: the signed credential as a JWT, or `null` while it is unsigned.

## List credentials

| Query parameter | Description |
|---|---|
| `user_id` | One learner's certificates. |
| `course_id` | Certificates for one course. |
| `programme_id` | Certificates for one programme. |
| `issued_since` | ISO 8601. Certificates awarded since then. |
| `state` | `valid`, `revoked`, `expired` or `unsigned`. |
| `limit`, `cursor` | See [Pagination](https://continuumlearn.com/developers/pagination). Ordered by when the certificate was recorded, oldest first. |

An invalid filter returns `422` with `error.code` `invalid_filter`.

```bash
# Every certificate awarded for course 412 since 1 November
curl "https://your-team.continuumlearn.com/api/v2/credentials?course_id=412&issued_since=2026-11-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $CONTINUUM_API_KEY"
```

```php
<?php
$page = json_decode($client->get('credentials', [
    'query' => ['user_id' => $continuumUserId, 'state' => 'valid'],
])->getBody(), true);

foreach ($page['data'] as $credential) {
    echo $credential['certificate_number'], ' ', $credential['title'], PHP_EOL;
}
```

```js
const res = await fetch('https://your-team.continuumlearn.com/api/v2/credentials/CL-58-01M70BNQMBD7GRTW9QZ33R63W4', {
  headers: { Authorization: `Bearer ${process.env.CONTINUUM_API_KEY}` },
});
const { data } = await res.json();
console.log(data.state, data.verify_url);
```

A certificate number from another team returns `404`.

## Staying up to date

To hear about new certificates as they are issued, including renewals, subscribe to the `certificate.issued` [webhook](https://continuumlearn.com/developers/webhooks) and fetch the full record here when you need it. Each learner's certificate for a course is also on their [progress](https://continuumlearn.com/developers/progress) row.

## Frequently asked questions

### What is the difference between the progress certificate and this?

The progress row shows the certificate for one learner on one course. The credentials endpoints list every certificate the team has issued, course and programme, with the badge image and signed credential.

### Is there an older credentials endpoint?

Yes. API v1 has `GET /api/v1/credentials`, used by existing integrations with the team key. It keeps working, but new integrations should use v2.
