{ "openapi": "3.1.0", "info": { "title": "Certifier API", "version": "2022-10-26", "description": "The Certifier API uses access tokens to authenticate requests. You can view and manage your access tokens in the Certifier Dashboard.\n\nYour access tokens carry many privileges, so be sure to keep them secure! Do not share your secret access tokens in publicly accessible areas such as GitHub, client-side code, and so forth.\n\n**Authentication** is performed via HTTP Bearer Auth. Provide your access token in the `Authorization` header with Bearer auth-scheme and `Certifier-Version` header:\n\n```\nAuthorization: Bearer \nCertifier-Version: 2022-10-26\n```\n\nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail." }, "servers": [ { "url": "https://api.certifier.io", "description": "Production server" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Credentials", "description": "Endpoints for creating, managing, issuing, and sending credentials" }, { "name": "Credential Interactions", "description": "Endpoints for tracking and managing credential interaction events" }, { "name": "Credential Templates", "description": "Endpoints for managing credential templates (groups)" }, { "name": "Design Templates", "description": "Endpoints for managing certificate and badge design templates" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Provide your access token in the Authorization header with Bearer auth-scheme. You can view and manage your access tokens in the Certifier Dashboard." } }, "schemas": { "Credential": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique credential's identifier", "example": "01hz2f0c9ryvzajg20jqh9taab" }, "publicId": { "type": "string", "format": "uuid", "description": "The external unique credential's identifier (used in the digital wallet to generate a URL, e.g. https://credsverse.com/credentials/{publicId})", "example": "124a8110-1af5-4747-9308-e9d06bd1852a" }, "groupId": { "type": "string", "description": "The unique identifier of the group (credential template).", "example": "01g90279gp5sbmfek7wymcsvec" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "issued", "expired" ], "description": "The status of the credential", "example": "draft" }, "recipient": { "$ref": "#/components/schemas/Recipient" }, "issueDate": { "type": "string", "description": "The date of your credential's issuance. Formatted as an ISO 8601 date string (YYYY-MM-DD)", "example": "2022-01-01" }, "expiryDate": { "type": "string", "nullable": true, "description": "The date of your credential's expiration. Formatted as an ISO 8601 date string (YYYY-MM-DD)", "example": "2023-01-01" }, "attributes": { "type": "object", "additionalProperties": { "nullable": true }, "description": "The key-value object of the credential's attributes. Currently this can only be the recipient.name, configured on a per-credential basis", "example": { "recipient.name": "John Doe" } }, "customAttributes": { "type": "object", "additionalProperties": { "nullable": true }, "description": "The key-value object of your custom attributes, where key is your attribute's tag and value is the text value you want to store", "example": { "custom.mentor": "Jane Doe" } }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when this credential was created. Formatted as an ISO 8601 date and time string", "example": "2022-01-01T00:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when this credential was updated. Formatted as an ISO 8601 date and time string", "example": "2022-01-01T00:00:00.000Z" } }, "required": [ "id", "publicId", "groupId", "status", "recipient", "issueDate", "expiryDate", "attributes", "customAttributes", "createdAt", "updatedAt" ] }, "Recipient": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "The credential recipient's unique identifier", "example": "01jmerb62apgachxwx6db76c7s" }, "name": { "type": "string", "description": "The name of the credential's recipient", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email of the credential's recipient", "example": "john.doe@example.com" } }, "required": [ "id", "name", "email" ], "description": "The recipient object (if an email was provided)" }, "CredentialInteraction": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique credential interaction's identifier", "example": "01hrsvk8xnj8vkt8p1e2tc1jt7" }, "credentialId": { "type": "string", "description": "The unique credential's identifier, to which this credential interaction belongs", "example": "01hrsvjp560yksep2a3bek3z97" }, "eventType": { "type": "string", "enum": [ "credential_viewed", "credential_shared_to_linkedin", "credential_added_to_linkedin_profile", "credential_shared_to_facebook", "credential_shared_to_twitter", "credential_shared_to_messenger", "credential_shared_to_whatsapp", "credential_shared_to_pinterest", "credential_shared_to_telegram", "credential_shared_to_weibo", "credential_downloaded", "credential_link_copied", "credential_verified" ], "description": "Specifies the type of user interaction event related to the credential", "example": "credential_viewed" }, "triggeredBy": { "type": "string", "enum": [ "recipient", "guest" ], "description": "The actor that triggered this credential interaction. Currently one of two values: recipient or guest", "example": "recipient" }, "triggeredAt": { "type": "string", "format": "date-time", "description": "The date and time when this credential interaction happened. Formatted as an ISO 8601 date and time string", "example": "2024-03-12T17:33:05.784Z" } }, "required": [ "id", "credentialId", "eventType", "triggeredBy", "triggeredAt" ] }, "Design": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique design template's identifier", "example": "01g8znjvd9h0qbhxqwc6av0txn" }, "name": { "type": "string", "description": "The name of the design template", "example": "My first design template" }, "type": { "type": "string", "enum": [ "certificate", "badge" ], "description": "The type of the design template, whether it is a certificate design template or a badge design template", "example": "certificate" }, "previewUrl": { "type": "string", "format": "uri", "description": "The direct URL to a PNG image preview of the design template", "example": "https://cdn.certifier.io/911264ad-df05-4aeb-966f-96034b711c10%2Fcertificate-designs%2Fpreviews%2F01k6dfeejfbwn273x2v2jqj4an-1759241517660.png" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when this design template was created. Formatted as an ISO 8601 date and time string", "example": "2022-01-01T00:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when this design template was updated. Formatted as an ISO 8601 date and time string", "example": "2022-01-01T00:00:00.000Z" } }, "required": [ "id", "name", "type", "previewUrl", "createdAt", "updatedAt" ] }, "Group": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the credential template (group).", "example": "01g90279gp5sbmfek7wymcsvec" }, "name": { "type": "string", "description": "The name of the credential template (group) that is used as [group.name] attribute later on", "example": "Financial Markets" }, "learningEventUrl": { "type": "string", "nullable": true, "format": "uri", "description": "The learning event's URL that is shown in the digital wallet", "example": "https://www.coursera.org/learn/financial-markets-global" }, "designIds": { "type": "array", "items": { "type": "string" }, "description": "The ordered list of design template IDs associated with this credential template.", "example": [ "01fpwtztwf7sacca5r0c483mnm", "01hz2ej4yzdcfkq9fa78nhyj0x" ] }, "certificateDesignId": { "type": "string", "nullable": true, "description": "Legacy field, to be removed. Returns the first ordered certificate design ID from designIds, or null when no certificate design is associated. Present only when the legacy request shape was used.", "example": "01fpwtztwf7sacca5r0c483mnm", "deprecated": true }, "badgeDesignId": { "type": "string", "nullable": true, "description": "Legacy field, to be removed. Returns the first ordered badge design ID from designIds, or null when no badge design is associated. Present only when the legacy request shape was used.", "example": "01hz2ej4yzdcfkq9fa78nhyj0x", "deprecated": true }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when this credential template (group) was created. Formatted as an ISO 8601 date and time string", "example": "2022-01-01T00:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when this credential template (group) was updated. Formatted as an ISO 8601 date and time string", "example": "2022-01-01T00:00:00.000Z" } }, "required": [ "id", "name", "learningEventUrl", "designIds", "certificateDesignId", "badgeDesignId", "createdAt", "updatedAt" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "example": "validation_error" }, "message": { "type": "string", "description": "Human-readable error message", "example": "The request body contains invalid or missing fields" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "CreateCredential": { "type": "object", "properties": { "groupId": { "type": "string", "description": "The group's (credential template's) ID you want to issue the credential to. Check the Group (Credential Template) object.", "example": "01g90279gp5sbmfek7wymcsvec" }, "recipient": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the credential's recipient", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email of the credential's recipient", "example": "john.doe@example.com" } }, "required": [ "name" ], "description": "The recipient of the credential" }, "issueDate": { "type": "string", "description": "The date of your credential's issuance (by default is set to today, only YYYY-MM-DD format is allowed)", "example": "2022-01-01" }, "expiryDate": { "type": "string", "description": "The date of your credential's expiration (by default uses the settings configured on the group (credential template), only YYYY-MM-DD format is allowed)", "example": "2023-01-01" }, "customAttributes": { "type": "object", "additionalProperties": { "nullable": true }, "description": "The key-value object of your custom attributes, where key is your attribute's tag and value is the text value you want to store", "example": { "custom.mentor": "Jane Doe" } } }, "required": [ "groupId", "recipient" ] }, "CreateIssueSendCredential": { "type": "object", "properties": { "groupId": { "type": "string", "description": "The group's (credential template's) ID you want to issue the credential to. Read more about groups (credential templates).", "example": "01g90279gp5sbmfek7wymcsvec" }, "recipient": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the credential's recipient", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email of the credential's recipient", "example": "john.doe@example.com" } }, "required": [ "name" ], "description": "The recipient of the credential" }, "issueDate": { "type": "string", "description": "The date of your credential's issuance (by default is set to today, only YYYY-MM-DD format is allowed)", "example": "2022-01-01" }, "expiryDate": { "type": "string", "description": "The date of your credential's expiration (by default uses the settings configured on the group (credential template), only YYYY-MM-DD format is allowed)", "example": "2023-01-01" }, "customAttributes": { "type": "object", "additionalProperties": { "nullable": true }, "description": "The key-value object of your custom attributes where key is your attribute's tag and value is just your value", "example": { "custom.mentor": "Jane Doe" } } }, "required": [ "groupId", "recipient" ] }, "CredentialDesign": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the design template", "example": "01jpqe836f59e62yh4c06h5sd8" }, "name": { "type": "string", "description": "Name of the design template", "example": "Classic Certificate" }, "previews": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialDesignPreview" }, "description": "Available preview formats and URLs for the design template" } }, "required": [ "id", "name", "previews" ] }, "CredentialDesignPreview": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "png", "pdf" ], "description": "The format of the preview", "example": "png" }, "url": { "type": "string", "format": "uri", "description": "The direct URL to the preview", "example": "https://cdn.certifier.io/c2903a31-67f2-4439-8214-5aeab5808536/credentials/01jjcded4kr5t0zz33286qqtxv/designs/01jpqe836f59e62yh4c06h5sd8/YhOo_ijQbQ.png" } }, "required": [ "format", "url" ] }, "SearchCredentials": { "type": "object", "properties": { "filter": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Filter object with AND, OR, NOT operators and field conditions. Supports filtering by id, publicId, groupId, status, recipientId, recipient.name, recipient.email, issueDate, expiryDate, createdAt, updatedAt", "example": {} }, "sort": { "type": "object", "properties": { "property": { "type": "string", "enum": [ "id", "createdAt", "updatedAt", "issueDate", "expiryDate" ], "description": "Property to sort by. Available: id, createdAt, updatedAt, issueDate, expiryDate", "example": "createdAt" }, "order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort order (asc or desc, default: desc)", "example": "desc" } }, "required": [ "property", "order" ], "description": "Sorting options" }, "cursor": { "type": "string", "nullable": true, "description": "Cursor for pagination", "example": null }, "limit": { "type": "integer", "description": "Number of items to return (default: 20)", "example": 25 } } }, "SendCredential": { "type": "object", "properties": { "deliveryMethod": { "type": "string", "enum": [ "email" ], "description": "The way you want to deliver the credential. The only available deliveryMethod for now is email", "example": "email" } }, "required": [ "deliveryMethod" ] }, "UpdateCredential": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "id": { "type": "string", "description": "The credential recipient's unique identifier", "example": "01jmerb62apgachxwx6db76c7s" }, "name": { "type": "string", "description": "The name of the credential's recipient", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email of the credential's recipient", "example": "john.doe@example.com" } }, "required": [ "id", "name" ], "description": "The recipient of the credential" }, "issueDate": { "type": "string", "description": "The date of your credential's issuance (by default is set to today, only YYYY-MM-DD format is allowed)", "example": "2022-01-01" }, "expiryDate": { "type": "string", "nullable": true, "description": "The date of your credential's expiration (by default uses the settings configured on the group (credential template), only YYYY-MM-DD format is allowed). Set to null if you want to reset this field", "example": "2023-01-01" }, "customAttributes": { "type": "object", "additionalProperties": { "nullable": true }, "description": "The key-value object of your custom attributes, where key is your attribute's tag and value is the text value you want to store", "example": { "custom.mentor": "Jane Doe" } } } }, "CreateCredentialInteraction": { "type": "object", "properties": { "credentialId": { "type": "string", "description": "The unique credential's identifier, to which this credential interaction belongs", "example": "01hrsvjp560yksep2a3bek3z97" }, "eventType": { "type": "string", "enum": [ "credential_viewed", "credential_shared_to_linkedin", "credential_added_to_linkedin_profile", "credential_shared_to_facebook", "credential_shared_to_twitter", "credential_shared_to_messenger", "credential_shared_to_whatsapp", "credential_shared_to_pinterest", "credential_shared_to_telegram", "credential_shared_to_weibo", "credential_downloaded", "credential_link_copied", "credential_verified" ], "description": "Specifies the type of user interaction event related to the credential", "example": "credential_viewed" }, "triggeredBy": { "type": "string", "enum": [ "recipient", "guest" ], "description": "The actor that triggered this credential interaction. Currently one of two values: recipient or guest", "example": "recipient" }, "triggeredAt": { "type": "string", "format": "date-time", "description": "The date and time when this credential interaction happened. Formatted as an ISO 8601 date and time string", "example": "2024-03-12T17:33:05.784Z" } }, "required": [ "credentialId", "eventType", "triggeredBy", "triggeredAt" ] }, "CreateGroup": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the credential template (group) that is used as [group.name] attribute later on", "example": "Financial Markets" }, "designIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The ordered list of design template IDs associated with the credential template..", "example": [ "01fpwtztwf7sacca5r0c483mnm", "01hz2ej4yzdcfkq9fa78nhyj0x" ] }, "learningEventUrl": { "type": "string", "format": "uri", "description": "The learning event's URL that is shown in the digital wallet", "example": "https://www.coursera.org/learn/financial-markets-global" } }, "required": [ "name", "designIds" ] }, "UpdateGroup": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the credential template (group) that is used as [group.name] attribute later on", "example": "Updated Financial Markets" }, "designIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Replaces the ordered list of design template IDs associated with the credential template.", "example": [ "01fpwtztwf7sacca5r0c483mnm", "01hz2ej4yzdcfkq9fa78nhyj0x" ] }, "learningEventUrl": { "type": "string", "format": "uri", "description": "The learning event's URL that is shown in the digital wallet", "example": "https://www.coursera.org/learn/financial-markets-global" } } } }, "parameters": {} }, "paths": { "/v1/credentials": { "post": { "tags": [ "Credentials" ], "summary": "Create a credential", "description": "\n Use this endpoint to create a new credential.\n The credential will be created with status `draft`.\n\n As the next step, use the [Issue Credential](/docs/api-reference/credentials/issue-a-credential) endpoint to issue a draft credential, making it active and accessible in the digital wallet.\n\n If you are looking for an all-in-one solution that simultaneously creates, issues, and sends a credential, check the [Create, Issue and Send a Credential](/docs/api-reference/credentials/create-issue-and-send-a-credential) endpoint.\n\n ", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCredential" } } } }, "responses": { "201": { "description": "Credential created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "402": { "description": "Payment Required - Feature requires premium subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "payment_required", "message": "The requested feature is only available to premium organizations" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } }, "get": { "tags": [ "Credentials" ], "summary": "List credentials", "description": "Use this endpoint to list credentials.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cursor for pagination", "example": null }, "required": false, "description": "Cursor for pagination", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "description": "Number of items to return (default: 20)", "example": 20 }, "required": false, "description": "Number of items to return (default: 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "200": { "description": "List of credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Credential" } }, "pagination": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "example": null, "description": "Cursor for previous page" }, "next": { "type": "string", "nullable": true, "example": null, "description": "Cursor for next page" } }, "required": [ "prev", "next" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/credentials/create-issue-send": { "post": { "tags": [ "Credentials" ], "summary": "Create, issue, and send a credential", "description": "Use this endpoint to issue a credential. It is an all-in-one solution that simultaneously creates, issues, and sends a credential. This endpoint covers most of the basic scenarios.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIssueSendCredential" } } } }, "responses": { "200": { "description": "Credential created, issued, and sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "402": { "description": "Payment Required - Feature requires premium subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "payment_required", "message": "The requested feature is only available to premium organizations" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/credentials/{id}": { "delete": { "tags": [ "Credentials" ], "summary": "Delete a credential", "description": "Use this endpoint to permanently delete a credential. This cannot be undone.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the credential", "example": "01hz2f0c9ryvzajg20jqh9taab" }, "required": true, "description": "The unique ID of the credential", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "204": { "description": "Credential deleted successfully" }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } }, "get": { "tags": [ "Credentials" ], "summary": "Get a credential", "description": "Use this endpoint to get a specific credential.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the credential", "example": "01hz2f0c9ryvzajg20jqh9taab" }, "required": true, "description": "The unique ID of the credential", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "200": { "description": "Credential details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } }, "patch": { "tags": [ "Credentials" ], "summary": "Update a credential", "description": "Use this endpoint to update a credential.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the credential", "example": "01hz2f0c9ryvzajg20jqh9taab" }, "required": true, "description": "The unique ID of the credential", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCredential" } } } }, "responses": { "200": { "description": "Credential updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/credentials/{id}/designs": { "get": { "tags": [ "Credentials" ], "summary": "Get credential design templates", "description": "Use this endpoint to list the ordered design templates used by a credential and their available previews. Preview URLs are immutable and versioned by a digest (hash) derived from the design template's last update timestamp and the resolved values of all rendered credential attributes.\n\n \n Preview URLs are immutable and versioned by a digest (hash) derived from:\n\n - the design template’s last update timestamp, and\n - the resolved values of all rendered credential attributes\n\n If you modify the design template (layout, fonts, colors, etc.) or any attribute value that appears in the design template, the digest changes and previous preview URLs will not automatically point to the new design template.\n\n To get the newest preview after any change, fetch **Get credential design templates** again and use the newly returned preview URL.\n\n The digest-versioned URL (…/.png or .pdf) is permanent for that exact version and is cache-friendly, making it safe to store or share.\n \n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the credential", "example": "01hz2f0c9ryvzajg20jqh9taab" }, "required": true, "description": "The unique ID of the credential", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "200": { "description": "List of design templates associated with the credential", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialDesign" } } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/credentials/{id}/issue": { "post": { "tags": [ "Credentials" ], "summary": "Issue a credential", "description": "\n Use this endpoint to issue a draft credential and change the status from `draft` to `issued`.\n You can only issue credentials with `status = \"draft\"`.\n\n As the next step, use the [Send a credential](/docs/api-reference/credentials/send-a-credential) endpoint to send your recipient a published credential.\n\n If you are looking for an all-in-one solution that simultaneously creates, issues, and sends a credential, check the [Create, issue, and send a credential](/docs/api-reference/credentials/create-issue-and-send-a-credential) endpoint.\n ", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the credential", "example": "01hz2f0c9ryvzajg20jqh9taab" }, "required": true, "description": "The unique ID of the credential", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "200": { "description": "Credential issued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "402": { "description": "Payment Required - Feature requires premium subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "payment_required", "message": "The requested feature is only available to premium organizations" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/credentials/search": { "post": { "tags": [ "Credentials" ], "summary": "Search credentials", "description": "\n 1. [Introduction](#introduction)\n * [Example Request](#example-request)\n 2. [Filtering](#filtering)\n * [Logical Operators](#logical-operators)\n * [AND](#and)\n * [OR](#or)\n * [NOT](#not)\n * [Field Types & Comparison Operators](#field-types--comparison-operators)\n * [String Fields](#string-fields)\n * [UUID Fields](#uuid-fields)\n * [Enum Fields](#enum-fields)\n * [Date Fields (YYYY-MM-DD)](#date-fields-yyyy-mm-dd)\n * [DateTime Fields (ISO 8601)](#datetime-fields-iso-8601)\n * [Handling Null Values](#handling-null-values)\n * [In Operator Limitation for Null Values](#in-operator-limitation-for-null-values)\n 3. [Credentials Searchable Fields](#credentials-searchable-fields)\n * [Core Fields](#core-fields)\n * [Recipient Fields](#recipient-fields)\n * [Temporal Fields](#temporal-fields)\n 4. [Sorting](#sorting)\n * [Credentials Sortable Properties](#credentials-sortable-properties)\n 5. [Pagination](#pagination)\n 6. [Complete Example](#complete-example)\n 7. [Tips and Advanced Use](#tips-and-advanced-use)\n * [Implicit AND](#implicit-and)\n * [Top-Level Logical Operators](#top-level-logical-operators)\n * [Filter Condition Objects](#filter-condition-objects)\n * [Comparison Operator Expressions](#comparison-operator-expressions)\n\n ## Introduction\n\n The Credentials Search API allows you to find and filter credentials using structured queries with logical operators, sorting, and pagination.\n\n A search request payload consists of:\n\n * **`filter`** – to define search conditions using `AND`, `OR`, and `NOT` logical operators.\n * **`sort`** – containing `property` and `order`, allowing control over result ordering.\n * [Standard pagination](https://developers.certifier.io/reference/pagination) using `cursor` and `limit`.\n\n ### Example Request\n\n ```\n POST /v1/credentials/search\n Content-Type: application/json\n ```\n\n ```json\n {\n \"filter\": {\n \"AND\": [\n {\n \"status\": {\n \"equals\": \"issued\"\n }\n },\n {\n \"recipient\": {\n \"name\": {\n \"contains\": \"John\"\n }\n }\n }\n ]\n },\n \"sort\": {\n \"property\": \"createdAt\",\n \"order\": \"desc\"\n },\n \"cursor\": \"some_cursor_value\",\n \"limit\": 25\n }\n ```\n\n ***\n\n ## Filtering\n\n Filter allows complex queries by combining multiple conditions using logical operators.\n\n ### Logical Operators\n\n Logical operators define how multiple conditions are combined.\n\n #### `AND`\n\n All conditions must be met.\n\n ```json\n {\n \"filter\": {\n \"AND\": [\n {\n \"status\": {\n \"equals\": \"issued\"\n }\n },\n {\n \"recipient\": {\n \"email\": {\n \"endsWith\": \"@company.com\"\n }\n }\n }\n ]\n }\n }\n ```\n\n #### `OR`\n\n At least one condition must be met.\n\n ```json\n {\n \"filter\": {\n \"OR\": [\n {\n \"status\": {\n \"equals\": \"draft\"\n }\n },\n {\n \"status\": {\n \"equals\": \"expired\"\n }\n }\n ]\n }\n }\n ```\n\n #### `NOT`\n\n Excludes records that match the condition.\n\n ```json\n {\n \"filter\": {\n \"NOT\": [\n {\n \"status\": {\n \"equals\": \"expired\"\n }\n }\n ]\n }\n }\n ```\n\n Operators can be combined:\n\n ```json\n {\n \"filter\": {\n \"AND\": [\n {\n \"NOT\": [\n {\n \"recipient\": {\n \"email\": {\n \"endsWith\": \"@company.com\"\n }\n }\n }\n ]\n },\n {\n \"recipient\": {\n \"name\": {\n \"startsWith\": \"John\"\n }\n }\n }\n ]\n }\n }\n ```\n\n ### Field Types & Comparison Operators\n\n Comparison operators define how field values are filtered.\n\n #### String Fields\n\n ```json\n {\n \"recipient\": {\n \"name\": {\n \"contains\": \"John\"\n }\n }\n }\n ```\n\n * `equals`: Exact match\n * `contains`: Partial match\n * `startsWith`: Prefix match\n * `endsWith`: Suffix match\n * `in`: Matches any value in an array\n\n #### UUID Fields\n\n UUID fields (such as `publicId`) only support exact matching. Each value must be a valid UUID — malformed values are rejected.\n\n ```json\n {\n \"publicId\": {\n \"equals\": \"124a8110-1af5-4747-9308-e9d06bd1852a\"\n }\n }\n ```\n\n * `equals`: Exact match (must be a valid UUID)\n * `in`: Matches any value in an array (each must be a valid UUID)\n\n #### Enum Fields\n\n ```json\n {\n \"status\": {\n \"in\": [\n \"draft\",\n \"expired\"\n ]\n }\n }\n ```\n\n * `equals`: Exact match\n * `in`: Matches any value in an array\n\n #### Date Fields (`YYYY-MM-DD`)\n\n ```json\n {\n \"issueDate\": {\n \"gte\": \"2024-01-01\"\n }\n }\n ```\n\n * `equals`: Exact match\n * `lt`: Less than\n * `lte`: Less than or equal\n * `gt`: Greater than\n * `gte`: Greater than or equal\n\n #### DateTime Fields (ISO 8601)\n\n ```json\n {\n \"createdAt\": {\n \"gte\": \"2025-02-21T14:18:33Z\"\n }\n }\n ```\n\n * `equals`: Exact match\n * `lt`: Less than\n * `lte`: Less than or equal\n * `gt`: Greater than\n * `gte`: Greater than or equal\n\n #### Handling Null Values\n\n ```json\n {\n \"expiryDate\": {\n \"equals\": null\n }\n }\n ```\n\n * `{ \"expiryDate\": { \"equals\": null } }`: Matches records where the field is `null`.\n * `{ NOT: [{ \"expiryDate\": { \"equals\": null } }] }`: Excludes records where the field is `null`.\n\n #### `in` Operator Limitation for Null Values\n\n The `in` operator **does not support** `null` values. If you need to match `null` alongside other values, use an `OR` logical statement instead:\n\n ```json\n {\n \"filter\": {\n \"OR\": [\n {\n \"recipientId\": {\n \"equals\": null\n }\n },\n {\n \"recipientId\": {\n \"in\": [\n \"01jmerb62apgachxwx6db76c7s\",\n \"01jmerbnaa9r183ry7a4mpe4v8\"\n ]\n }\n }\n ]\n }\n }\n ```\n ", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCredentials" } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Credential" } }, "pagination": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "example": null, "description": "Cursor for previous page" }, "next": { "type": "string", "nullable": true, "example": null, "description": "Cursor for next page" } }, "required": [ "prev", "next" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/credentials/{id}/send": { "post": { "tags": [ "Credentials" ], "summary": "Send a credential", "description": "\n Use this endpoint to send a published credential to a recipient.\n You can only send credentials with `status = \"issued\"`.\n\n Currently, the only supported `deliveryMethod` is `email`.\n Certifier will send an email to the recipient using the email template configured for the group (credential template) the credential belongs to.\n\n If you are looking for an all-in-one solution that simultaneously creates, issues, and sends a credential, check the [Create, issue, and send a credential](/docs/api-reference/credentials/create-issue-and-send-a-credential) endpoint.\n ", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the credential", "example": "01hz2f0c9ryvzajg20jqh9taab" }, "required": true, "description": "The unique ID of the credential", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendCredential" } } } }, "responses": { "200": { "description": "Credential sent successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credential" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "412": { "description": "Precondition Failed - Required conditions not met", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "precondition_failed", "message": "The required preconditions were not met" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/credential-interactions": { "post": { "tags": [ "Credential Interactions" ], "summary": "Create a credential interaction", "description": "Creates a new credential interaction event.\n\n \n This feature uses the browser's `LocalStorage` to identify the actions made by the recipient of the credential. When the user accesses the page with `?recipient=true` query parameter, the application saves that information in `LocalStorage` and removes the parameter from the URL. Actions taken afterwards in the same browser are recorded as the recipient's, until the `LocalStorage` data is cleared.\n\n If you are distributing the credential links independently and wish to track events as originating from the recipient, be sure to include the `?recipient=true` parameter. Without this parameter, we won't be able to mark this person as the recipient, and their actions will be marked under the `guest` actor category.\n\n This approach may not capture every scenario. For example, if a recipient opens a link with `?recipient=true` on one device, then shares the link without the parameter (or opens it on a different device without the stored flag), those subsequent views will be categorized as `guest`. Similarly, if the user clears their `LocalStorage` or uses an incognito session, the system can no longer confirm that they are the recipient.\n\n \n ", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialInteraction" } } } }, "responses": { "200": { "description": "Credential interaction created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialInteraction" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } }, "get": { "tags": [ "Credential Interactions" ], "summary": "List credential interactions", "description": "Returns a list of credential interactions, optionally filtered by credential ID.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique credential's identifier", "example": "01hrsvjp560yksep2a3bek3z97" }, "required": false, "description": "The unique credential's identifier", "name": "credentialId", "in": "query" }, { "schema": { "type": "string", "description": "Cursor for pagination", "example": null }, "required": false, "description": "Cursor for pagination", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "description": "Number of items to return (default: 20)", "example": 20 }, "required": false, "description": "Number of items to return (default: 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "200": { "description": "List of credential interactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialInteraction" } }, "pagination": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "example": null, "description": "Cursor for previous page" }, "next": { "type": "string", "nullable": true, "example": null, "description": "Cursor for next page" } }, "required": [ "prev", "next" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/designs/{id}": { "get": { "tags": [ "Design Templates" ], "summary": "Get a design template", "description": "Retrieves the details of an existing design template by its ID.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the design template", "example": "01g8znjvd9h0qbhxqwc6av0txn" }, "required": true, "description": "The unique ID of the design template", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "200": { "description": "Design template details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Design" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/designs": { "get": { "tags": [ "Design Templates" ], "summary": "List design templates", "description": "Returns a list of all design templates (certificates and badges) available in your workspace.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cursor for pagination" }, "required": false, "description": "Cursor for pagination", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "maximum": 100, "description": "Number of items to return (default: 20)", "example": 20 }, "required": false, "description": "Number of items to return (default: 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "200": { "description": "List of design templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Design" } }, "pagination": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "example": null, "description": "Cursor for previous page" }, "next": { "type": "string", "nullable": true, "example": null, "description": "Cursor for next page" } }, "required": [ "prev", "next" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/groups": { "post": { "tags": [ "Credential Templates" ], "summary": "Create a credential template", "description": "Use this endpoint to create a credential template (group).\n\n\nGroups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.\n\nDuring the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.\n\n\n\nFor backward compatibility, this endpoint still accepts the legacy `certificateDesignId` and `badgeDesignId` request fields for the time being. Those fields are deprecated, intentionally omitted from the request schema below, and may be removed without notice. Use `designIds` for all new integrations.\n\nIf you use the legacy request shape, the response will also temporarily include legacy `certificateDesignId` and `badgeDesignId` fields for compatibility.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroup" } } } }, "responses": { "201": { "description": "Credential template (group) created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "402": { "description": "Payment Required - Feature requires premium subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "payment_required", "message": "The requested feature is only available to premium organizations" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } }, "get": { "tags": [ "Credential Templates" ], "summary": "List credential templates", "description": "Use this endpoint to list credential templates (groups).\n\n\nGroups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.\n\nDuring the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Cursor for pagination" }, "required": false, "description": "Cursor for pagination", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "maximum": 100, "description": "Number of items to return (default: 20)", "example": 20 }, "required": false, "description": "Number of items to return (default: 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "200": { "description": "List of credential templates (groups)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "pagination": { "type": "object", "properties": { "prev": { "type": "string", "nullable": true, "example": null, "description": "Cursor for previous page" }, "next": { "type": "string", "nullable": true, "example": null, "description": "Cursor for next page" } }, "required": [ "prev", "next" ] } }, "required": [ "data", "pagination" ] } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } }, "/v1/groups/{id}": { "delete": { "tags": [ "Credential Templates" ], "summary": "Delete a credential template", "description": "Permanently deletes a credential template (group). This cannot be undone.\n\n\nGroups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.\n\nDuring the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the credential template (group).", "example": "01g90279gp5sbmfek7wymcsvec" }, "required": true, "description": "The unique ID of the credential template (group).", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "204": { "description": "Credential template (group) deleted successfully" }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } }, "get": { "tags": [ "Credential Templates" ], "summary": "Get a credential template", "description": "Use this endpoint to get a specific credential template (group).\n\n\nGroups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.\n\nDuring the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the credential template (group).", "example": "01g90279gp5sbmfek7wymcsvec" }, "required": true, "description": "The unique ID of the credential template (group).", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "responses": { "200": { "description": "Credential template (group) details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } }, "patch": { "tags": [ "Credential Templates" ], "summary": "Update a credential template", "description": "Updates the specified credential template (group) by setting the values of the parameters passed. Any parameters not provided will be left unchanged.\n\n\nGroups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.\n\nDuring the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.\n\n\n\nFor backward compatibility, this endpoint still accepts the legacy `certificateDesignId` and `badgeDesignId` request fields for the time being. Those fields are deprecated, intentionally omitted from the request schema below, and may be removed without notice. Do not send both `designIds` and the legacy fields in the same request.\n\nIf you use the legacy request shape, the response will also temporarily include legacy `certificateDesignId` and `badgeDesignId` fields for compatibility.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique ID of the credential template (group).", "example": "01g90279gp5sbmfek7wymcsvec" }, "required": true, "description": "The unique ID of the credential template (group).", "name": "id", "in": "path" }, { "schema": { "type": "string", "default": "2022-10-26", "example": "2022-10-26", "description": "API version header. Required for all requests." }, "required": true, "description": "API version header. Required for all requests.", "name": "Certifier-Version", "in": "header", "example": "2022-10-26" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGroup" } } } }, "responses": { "200": { "description": "Credential template (group) updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Bad Request - Missing version, invalid version, invalid JSON, or validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_version": { "value": { "error": { "code": "missing_version", "message": "The request is missing the required Certifier-Version header" } } }, "invalid_version": { "value": { "error": { "code": "invalid_version", "message": "The Certifier-Version header's value is invalid" } } }, "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "The request body can not be decoded as JSON" } } }, "validation_error": { "value": { "error": { "code": "validation_error", "message": "This usually occurs because of a missing or malformed parameter" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "A valid authentication token was not provided with the request" } } } } }, "402": { "description": "Payment Required - Feature requires premium subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "payment_required", "message": "The requested feature is only available to premium organizations" } } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "The requested resource does not exist" } } } } }, "429": { "description": "Rate Limited - Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "You have exceeded the rate limit" } } } } }, "500": { "description": "Internal Server Error - Problem on Certifier's end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_server_error", "message": "There was a problem on Certifier's end" } } } } } } } } } }