Get Credential

Retrieve a credential by its identifier, including the full W3C Verifiable Credential, and the latest status of all grantor decisions. The credentialId must be a credential URN (urn:via:credential:<uuid>); a malformed URN returns 400.

GET /credential/{credentialId}

Get Credential

cURL

curl --request GET \
  --url https://api.example.com/credential/{credentialId}

import requests

url = "https://api.example.com/credential/{credentialId}"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.example.com/credential/{credentialId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/credential/{credentialId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/credential/{credentialId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/credential/{credentialId}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/credential/{credentialId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

200

{
  "id": "urn:via:credential:550e8400-e29b-41d4-a716-446655440000",
  "resourceType": "DOCUMENT",
  "status": "DRAFT",
  "w3cCredential": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://via.humanos.dev/ns/v1"
    ],
    "id": "urn:via:credential:550e8400-e29b-41d4-a716-446655440000",
    "type": [
      "VerifiableCredential",
      "VIAMandate"
    ],
    "issuer": "did:web:humanos.tech",
    "validFrom": "2025-01-01T00:00:00Z",
    "validUntil": null,
    "credentialSubject": {
      "id": "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
      "mandate": {
        "grantor": "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "scope": "humanos.credential.request",
        "context": {
          "authorizedDIDs": [
            "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
            "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7"
          ]
        }
      }
    },
    "evidences": [
      {
        "id": "urn:via:evidence:9b2e4f1a-3c7d-4e8a-bf12-2a6c5d8e0f34",
        "digestSRI": "sha256-abc123",
        "location": "https://api.humanos.dev/credential/evidence/urn:via:evidence:9b2e4f1a-3c7d-4e8a-bf12-2a6c5d8e0f34"
      }
    ],
    "proofs": [
      {
        "type": "DataIntegrityProof",
        "cryptosuite": "eddsa-jcs-2022",
        "verificationMethod": "did:web:example.com#key-1",
        "created": "2026-05-02T10:15:30.000Z",
        "proofPurpose": "assertionMethod",
        "proofValue": "z2pcVdSdoMTrkYP9rVdz...",
        "action": "ISSUE",
        "actionProof": "sha256-9b2e4f1a3c7d4e8abf122a6c5d8e0f34abc123def456..."
      },
      {
        "type": "DataIntegrityProof",
        "cryptosuite": "eddsa-jcs-2022",
        "verificationMethod": "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7#key-1",
        "created": "2026-05-02T10:15:30.000Z",
        "proofPurpose": "assertionMethod",
        "proofValue": "z2pcVdSdoMTrkTCXzp...",
        "action": "ACCEPT",
        "actionProof": "sha256-9b2e4f1a3c7d4e8abf122a6c5d8e0f34abc123def457..."
      },
      {
        "type": "DataIntegrityProof",
        "cryptosuite": "eddsa-jcs-2022",
        "verificationMethod": "did:web:humanos.tech#key-1",
        "created": "2026-05-02T10:15:30.000Z",
        "proofPurpose": "assertionMethod",
        "proofValue": "z2pcVdSdoMTrkTRrXdz...",
        "action": "STAMP",
        "actionProof": "sha256-9b2e4f1a3c7d4e8abf122a6c5d8e0f34abc123def458..."
      }
    ]
  },
  "decisions": [
    {
      "id": "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "contact": "[e-mail]",
      "accepted": true,
      "decidedAt": "2025-06-01T12:00:00.000Z"
    }
  ],
  "name": "Credential Name",
  "description": "Document to be requested on onboarding",
  "internalId": "internal-12345",
  "tags": [
    "onboarding",
    "kyc"
  ]
}

{
  "statusCode": 400,
  "message": "Invalid urn",
  "error": "Bad Request"
}

{
  "statusCode": 404,
  "message": "Credential not found",
  "error": "Not Found"
}

Headers

API-Version · string

Pin request, response, and webhook shapes to a specific dated API version (YYYY-MM-DD). Omit to use the version pinned to your API key (set when the key is created; new keys default to the latest version). New integrations should target the latest version.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-07-06"

Path Parameters

credentialId · string · required

URN of the credential to retrieve

Example:

"urn:via:credential:550e8400-e29b-41d4-a716-446655440000"

Response

200

application/json

The credential, including its W3C Verifiable Credential and the latest grantor decisions.

id · string · required

URN of the credential.

Example:

"urn:via:credential:550e8400-e29b-41d4-a716-446655440000"

resourceType · string · required

The type of resource for this credential (e.g., DOCUMENT, CONSENT, FORM)

Example:

"DOCUMENT"

status · enum<string> · required

The status of the credential

Available options: DRAFT, ACTIVE, REJECTED, CANCELED, REVOKED, EXPIRED

Example:

"DRAFT"

w3cCredential · object · required

The W3C Verifiable Credential following the VIA protocol specification.

While the credential is in DRAFT status, this object is in building mode: evidences, proofs, and other fields may still be attached or modified as grantors review and decide. The proofs array will be empty at this stage.

Once all grantors have accepted (or the request window expires), the status transitions out of DRAFT and cryptographic signature proofs are attached. At that point the credential is fully sealed and can be passed for verification as defined by the VIA protocol.

Example:

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://via.humanos.dev/ns/v1"
  ],
  "id": "urn:via:credential:550e8400-e29b-41d4-a716-446655440000",
  "type": ["VerifiableCredential", "VIAMandate"],
  "issuer": "did:web:humanos.tech",
  "validFrom": "2025-01-01T00:00:00Z",
  "validUntil": null,
  "credentialSubject": {
    "id": "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
    "mandate": {
      "grantor": "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "scope": "humanos.credential.request",
      "context": {
        "authorizedDIDs": [
          "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
          "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7"
        ]
      }
    }
  },
  "evidences": [
    {
      "id": "urn:via:evidence:9b2e4f1a-3c7d-4e8a-bf12-2a6c5d8e0f34",
      "digestSRI": "sha256-abc123",
      "location": "https://api.humanos.dev/credential/evidence/urn:via:evidence:9b2e4f1a-3c7d-4e8a-bf12-2a6c5d8e0f34"
    }
  ],
  "proofs": [
    {
      "type": "DataIntegrityProof",
      "cryptosuite": "eddsa-jcs-2022",
      "verificationMethod": "did:web:example.com#key-1",
      "created": "2026-05-02T10:15:30.000Z",
      "proofPurpose": "assertionMethod",
      "proofValue": "z2pcVdSdoMTrkYP9rVdz...",
      "action": "ISSUE",
      "actionProof": "sha256-9b2e4f1a3c7d4e8abf122a6c5d8e0f34abc123def456..."
    },
    {
      "type": "DataIntegrityProof",
      "cryptosuite": "eddsa-jcs-2022",
      "verificationMethod": "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7#key-1",
      "created": "2026-05-02T10:15:30.000Z",
      "proofPurpose": "assertionMethod",
      "proofValue": "z2pcVdSdoMTrkTCXzp...",
      "action": "ACCEPT",
      "actionProof": "sha256-9b2e4f1a3c7d4e8abf122a6c5d8e0f34abc123def457..."
    },
    {
      "type": "DataIntegrityProof",
      "cryptosuite": "eddsa-jcs-2022",
      "verificationMethod": "did:web:humanos.tech#key-1",
      "created": "2026-05-02T10:15:30.000Z",
      "proofPurpose": "assertionMethod",
      "proofValue": "z2pcVdSdoMTrkTRrXdz...",
      "action": "STAMP",
      "actionProof": "sha256-9b2e4f1a3c7d4e8abf122a6c5d8e0f34abc123def458..."
    }
  ]
}

decisions · array[] · required

Whether each grantor accepted or rejected the credential and information about the grantor contact. The id field carries the grantor's DID. Always an array (empty when there are no decisions yet).

Example:

[
  {
    "id": "did:web:humanos.tech:user:7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "contact": "[e-mail]",
    "accepted": true,
    "decidedAt": "2025-06-01T12:00:00.000Z"
  }
]

name · string

Human-readable name of the credential; null when unset.

Example:

"Credential Name"

description · string

Free-text description of the credential; null when unset.

Example:

"Document to be requested on onboarding"

internalId · string

Identifier to help you identify the credential in your own system. We recommend using a unique value.

Example:

"internal-12345"

tags · string[]

Free-form labels attached to the credential.

Example:

["onboarding", "kyc"]