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

# Custom credential template (advanced)

> Define your own credential shape when no preset fits.

<Note>
  **Most integrations don't need this page.** If you can issue against a published preset, do that. See [Issue a
  credential](/products/didx-me/guides/issuers/issue-credential). Custom templates are for cases where you need a
  credential shape that no preset covers (private credentials, internal-only schemes, experiments).
</Note>

## Overview

A credential template defines the schema for a verifiable credential: what attributes it carries, their types, and which are always disclosed. Create it once and reuse it to issue many credentials with different data.

Use a custom template when:

* No published preset matches the credential you want to issue.
* You're building a private or internal credential that shouldn't live in a shared catalogue.
* You need fine-grained control over `alwaysDisclosed`, attribute types, or the `type` URI.

<Note>
  The `type` field you set in a credential template is what verifiers later match against in the credential presentation
  flow.
</Note>

## Pick the right endpoint for your format

The API exposes a separate POST endpoint per credential format. Use the one that matches the credential you want to define:

* **SD-JWT:** `POST /templates/credentials/sd-jwt`
* **mDoc:** `POST /templates/credentials/mdoc`

A generic `POST /templates/credentials` exists too (it dispatches by `credentialFormat` in the body), but the format-specific endpoints have a single, format-shaped request body and are simpler to work with.

## Request (SD-JWT)

```bash theme={null}
curl -X POST "https://test.didxtech.com/me-creds/api/v1/templates/credentials/sd-jwt" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Basic Identity",
    "description": "First name and last name",
    "type": "BasicIdentity",
    "attributes": {
      "firstName": {
        "type": "string",
        "name": "First Name",
        "description": "Given name",
        "required": true,
        "alwaysDisclosed": false
      },
      "lastName": {
        "type": "string",
        "name": "Last Name",
        "description": "Family name",
        "required": true,
        "alwaysDisclosed": false
      }
    }
  }'
```

### Attribute fields

Each attribute is a field on the credential. The following properties configure each one:

| Field             | Type    | Description                                                                 |
| ----------------- | ------- | --------------------------------------------------------------------------- |
| `type`            | string  | Data type (`string`, `date`, etc.)                                          |
| `name`            | string  | Human-readable label for the attribute                                      |
| `description`     | string  | Description of the attribute                                                |
| `required`        | boolean | Whether this attribute must be present                                      |
| `alwaysDisclosed` | boolean | If `true`, this attribute is always shared when the credential is presented |

## Response

**HTTP 201 Created**

```json theme={null}
{
  "data": {
    "id": "tpl_6421a8905c17830c188e2e2f",
    "name": "Basic Identity",
    "description": "First name and last name",
    "type": "https://didx.co.za/vct/didx/basic-identity",
    "format": "sd-jwt-vc",
    "attributes": {
      "firstName": {
        "type": "string",
        "name": "First Name",
        "description": "Given name",
        "required": true,
        "alwaysDisclosed": false
      },
      "lastName": {
        "type": "string",
        "name": "Last Name",
        "description": "Family name",
        "required": true,
        "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/v1/templates/credentials/sd-jwt/tpl_6421a8905c17830c188e2e2f",
    "issuances": "https://test.didxtech.com/me-creds/api/v1/templates/credentials/sd-jwt/tpl_6421a8905c17830c188e2e2f/issuances"
  },
  "meta": {
    "version": "1.0",
    "totalAttributes": 2
  }
}
```

### Key response fields

| Field    | Description                                                                    |
| -------- | ------------------------------------------------------------------------------ |
| `id`     | Unique template identifier. Pass it as `credentialTemplateId` when issuing     |
| `type`   | URI identifying the credential category. Used by verifiers during presentation |
| `format` | The credential format the template uses (e.g. `sd-jwt-vc`)                     |
| `status` | `active` once the template is ready for use                                    |

<Tip>
  Save the `id` from the response. You'll need it as the `credentialTemplateId` in [Issue a
  credential](/products/didx-me/guides/issuers/issue-credential).
</Tip>