Skip to main content

​
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.
The code field you set here determines the type URI — the bridge between issuers and verifiers across the ecosystem. When an opportunity provider creates a credential template, the type URI in the response is what employment providers reference in their presentation template to request matching credentials. Share this URI with any verifying partner who needs to check credentials of this type.

​
Endpoint

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

​
Request

curl -X POST "https://test.didxtech.com/me-creds/api/templates/credentials" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Web Development Completion",
    "code": "web-dev-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

FieldTypeRequiredDescription
namestringYesHuman-readable name for the template
codestringYesShort identifier (e.g. web-dev-completion). The API uses this to generate the full type URI in the response.
descriptionstringNoDescription of what this credential represents
attributesobjectYesKey-value map of attribute definitions (see below)
Deprecation notice: The type field is deprecated for SD-JWT templates. Use code instead. If you pass type, the API will return a deprecation warning. Existing templates using type continue to work, but all new templates should use code.

​
Attribute Fields

Each attribute in the template defines a data field on the credential:
FieldTypeDescription
typestringData type (string, date, etc.)
namestringHuman-readable label shown in the youth’s wallet
descriptionstringDescription of the attribute
requiredbooleanWhether this attribute must be present when issuing
alwaysDisclosedbooleanIf 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 201 Created 
{
  "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/web-dev-completion-v1",
    "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",
    "issuances": "https://test.didxtech.com/me-creds/api/templates/credentials/tpl_6421a8905c17830c188e2e2f/issuances"
  },
  "meta": {
    "version": "1.0",
    "totalAttributes": 5
  }
}

​
Key Response Fields

FieldDescription
idUnique template identifier — save this for issuing credentials in Step 3
typeA URI identifying this credential type. This is the bridge — share it with verifying partners so they can request credentials of this type.
formatsd-jwt-vc — Selective Disclosure JSON Web Token, enabling per-attribute disclosure control
statusactive once the template is ready for use
Save the id and the type URI. You need id for Step 3: Issue a Credential. Share type with any verifying partner who will request this credential type.

​
Listing Credential Templates

Retrieve all credential templates for your organisation: 
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. 
{
  "name": "Community Impact Verification",
  "description": "Issued to youth who complete a verified impact activity",
  "code": "impact-verification",
  "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
    }
  }
}

{
  "name": "Digital Skills Programme Completion",
  "description": "Issued to youth who complete a digital skills training programme",
  "code": "digital-skills-completion",
  "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
    }
  }
}