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

# Step 2: Create Credential Template

> Define the structure and attributes of a verifiable credential.

## Overview

A credential template defines the schema for a verifiable credential — what attributes it contains, which are required, and which are always disclosed to verifiers. Templates are reusable: create one "Web Development Completion" template and use it to credential hundreds of youth.

<Note>
  You provide a human-readable **`code`**. The API uses it to generate a **Verifiable Credential Type (VCT)** URI — the unique identifier that connects issuers to verifiers across the ecosystem. Share this `type` URI with any verifying partner who needs to request credentials of this type.
</Note>

## Endpoint

```
POST https://test.didxtech.com/me-creds/api/templates/credentials
```

## Request

```bash theme={null}
curl -X POST "https://test.didxtech.com/me-creds/api/templates/credentials" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "credentialFormat": "sd-jwt",
    "name": "Web Development Completion",
    "code": "course-completion",
    "description": "Issued to youth who complete the Umuzi web development programme",
    "attributes": {
      "programmeName": {
        "type": "string",
        "name": "Programme Name",
        "description": "Name of the completed programme",
        "required": true,
        "alwaysDisclosed": true
      },
      "completionDate": {
        "type": "string",
        "name": "Completion Date",
        "description": "Date the youth completed the programme",
        "required": true,
        "alwaysDisclosed": true
      },
      "fullName": {
        "type": "string",
        "name": "Full Name",
        "description": "Youth'\''s full name",
        "required": true,
        "alwaysDisclosed": true
      },
      "skillsCovered": {
        "type": "string",
        "name": "Skills Covered",
        "description": "Comma-separated list of skills covered in the programme",
        "required": true,
        "alwaysDisclosed": false
      },
      "assessmentScore": {
        "type": "string",
        "name": "Assessment Score",
        "description": "Final assessment score (percentage)",
        "required": false,
        "alwaysDisclosed": false
      }
    }
  }'
```

### Request Body Fields

| Field              | Type   | Required | Description                                                                                                                                                            |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `credentialFormat` | string | Yes      | Credential format: `sd-jwt`, `mdoc`, or `preset` (to create from an ecosystem preset)                                                                                  |
| `name`             | string | Yes      | Human-readable name for the template                                                                                                                                   |
| `code`             | string | Yes      | Short identifier (e.g. `course-completion`). Alphanumeric, hyphens, and underscores only. The API uses this to generate the full VCT URI returned in the `type` field. |
| `description`      | string | No       | Description of what this credential represents                                                                                                                         |
| `attributes`       | object | Yes      | Key-value map of attribute definitions (see below)                                                                                                                     |

### Attribute Fields

Each attribute in the template defines a data field on the credential:

| Field             | Type    | Description                                                                                                    |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `type`            | string  | Data type (`string`, `date`, etc.)                                                                             |
| `name`            | string  | Human-readable label shown in the youth's wallet                                                               |
| `description`     | string  | Description of the attribute                                                                                   |
| `required`        | boolean | Whether this attribute must be present when issuing                                                            |
| `alwaysDisclosed` | boolean | If `true`, this attribute is **always** shared when the credential is presented — the youth cannot withhold it |

### Selective Disclosure Design

Think carefully about `alwaysDisclosed`. This is a first-class concept, not a footnote:

* **`alwaysDisclosed: true`** — The attribute is always visible to verifiers. Use for essential information like programme name and completion date.
* **`alwaysDisclosed: false`** — The youth chooses whether to share this attribute. Use for sensitive information like assessment scores, personal identifiers, or anything the youth might reasonably want to keep private.

In the example above, Thandi can share her "Web Development Completion" credential with an employer while withholding her assessment score — that's her choice, not the issuer's or the verifier's.

## Response

**HTTP 200 OK**

```json theme={null}
{
  "data": {
    "id": "tpl_6421a8905c17830c188e2e2f",
    "name": "Web Development Completion",
    "description": "Issued to youth who complete the Umuzi web development programme",
    "type": "https://didx.co.za/vct/didx/course-completion",
    "format": "sd-jwt-vc",
    "attributes": {
      "programmeName": {
        "type": "string",
        "name": "Programme Name",
        "description": "Name of the completed programme",
        "required": true,
        "alwaysDisclosed": true
      },
      "completionDate": {
        "type": "string",
        "name": "Completion Date",
        "description": "Date the youth completed the programme",
        "required": true,
        "alwaysDisclosed": true
      },
      "fullName": {
        "type": "string",
        "name": "Full Name",
        "description": "Youth's full name",
        "required": true,
        "alwaysDisclosed": true
      },
      "skillsCovered": {
        "type": "string",
        "name": "Skills Covered",
        "description": "Comma-separated list of skills covered in the programme",
        "required": true,
        "alwaysDisclosed": false
      },
      "assessmentScore": {
        "type": "string",
        "name": "Assessment Score",
        "description": "Final assessment score (percentage)",
        "required": false,
        "alwaysDisclosed": false
      }
    },
    "createdAt": "2025-01-20T11:27:37.051Z",
    "updatedAt": "2025-01-20T11:27:37.051Z",
    "archivedAt": null,
    "status": "active"
  },
  "links": {
    "self": "https://test.didxtech.com/me-creds/api/templates/credentials/tpl_6421a8905c17830c188e2e2f"
  }
}
```

### Key Response Fields

| Field    | Description                                                                                                                  |
| -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `id`     | Unique template identifier — save this for issuing credentials in Step 3                                                     |
| `type`   | The VCT URI generated from your `code`. Share this with verifying partners — it's how they request credentials of this type. |
| `format` | `sd-jwt-vc` — Selective Disclosure JSON Web Token, enabling per-attribute disclosure control                                 |
| `status` | `active` once the template is ready for use                                                                                  |

<Tip>
  Save the `id` (needed for [Step 3: Issue a Credential](/api/issuers/issue-credential)) and the `type` URI (share with verifying partners).
</Tip>

## Listing Credential Templates

Retrieve all credential templates for your organisation:

```bash theme={null}
curl -X GET "https://test.didxtech.com/me-creds/api/templates/credentials" \
  -H "Authorization: Bearer <access_token>"
```

Returns an array of all templates with their `id`, `name`, `type`, `status`, and `attributes`.

## Ecosystem Presets

YoID provides **ecosystem presets** — standardised credential structures for common use cases. Partners can create a template directly from a preset, or customise one based on a preset.

<AccordionGroup>
  <Accordion title="Impact Verification (from preset)">
    ```json theme={null}
    {
      "name": "Community Impact Verification",
      "description": "Issued to youth who complete a verified impact activity",
      "code": "impact-verified",
      "attributes": {
        "activityName": {
          "type": "string", "name": "Activity Name",
          "required": true, "alwaysDisclosed": true
        },
        "fullName": {
          "type": "string", "name": "Full Name",
          "required": true, "alwaysDisclosed": true
        },
        "completionDate": {
          "type": "string", "name": "Completion Date",
          "required": true, "alwaysDisclosed": true
        },
        "impactMetric": {
          "type": "string", "name": "Impact Metric",
          "required": true, "alwaysDisclosed": false
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Programme Completion (customised from preset)">
    ```json theme={null}
    {
      "name": "Digital Skills Programme Completion",
      "description": "Issued to youth who complete a digital skills training programme",
      "code": "digital-skills",
      "attributes": {
        "programmeName": {
          "type": "string", "name": "Programme Name",
          "required": true, "alwaysDisclosed": true
        },
        "fullName": {
          "type": "string", "name": "Full Name",
          "required": true, "alwaysDisclosed": true
        },
        "completionDate": {
          "type": "string", "name": "Completion Date",
          "required": true, "alwaysDisclosed": true
        },
        "modulesCompleted": {
          "type": "string", "name": "Modules Completed",
          "required": true, "alwaysDisclosed": false
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>