API

Certifyx API documentation

Customer-facing API examples for templates, issuing, verifying, revoking, and webhooks.

Sandbox API

https://sandbox.certifyx.club/v1

Production API

https://api.certifyx.club/v1

Verification

https://verify.certifyx.club

Docs

https://docs.certifyx.club

Authentication

Send API keys as Bearer tokens from your server. Use sk_sandbox_ keys with the sandbox API host and sk_live_ keys with the production API host. Never expose API keys in browser JavaScript, mobile apps, or public repositories.

Authorization: Bearer sk_sandbox_xxx

Endpoints

POST/v1/certificates/issueCreates one certificate, renders the PDF, hashes metadata, and returns the verification URL.POST/v1/certificates/bulkCreates a queued batch for multiple certificate payloads using the same issue schema.GET/v1/certificates/{certificateId}Reads the latest certificate status, PDF signed URL, public metadata, and blockchain transaction records.POST/v1/certificates/{certificateId}/revokeMarks a certificate as revoked and records the revocation reason.GET/v1/verify/{certificateId}Performs server-side verification and writes a verification log for the certificate.GET/v1/templatesLists active organization and Certifyx templates available for issuance.POST/v1/webhooksRegisters an endpoint for certificate lifecycle events and returns the signing secret once.

POST/v1/certificates/issue

Issue certificate

Creates one certificate, renders the PDF, hashes metadata, and returns the verification URL.

Path parameters

No path parameters.

Query parameters

No query parameters.

Request body

Name

Type

Required

Description

certificateIdstring

Customer supplied certificate ID. Use 3 to 64 characters, letters, numbers, or hyphens. Generated if omitted.

templateIduuid | null

Certificate template ID. If omitted, Certifyx uses the first active template available to the organization.

recipientNamestring

Yes

Recipient name printed on the certificate.

recipientEmailemail

Yes

Recipient email address for records and delivery workflows.

titlestring

Yes

Certificate title or program name.

issuedAtISO datetime

Issue timestamp. Defaults to the request time.

expiresAtISO datetime | null

Optional expiry timestamp.

publicMetadataobject

Visible metadata that can be shown in verification and certificate rendering.

privateMetadataobject

Hidden metadata included in the canonical SHA-256 hash but not exposed publicly.

Sample request

{
  "certificateId": "CX-CLIENT-0001",
  "templateId": "8e884cad-6a34-4f15-9d6d-0c2798d4d002",
  "recipientName": "Aina Rahman",
  "recipientEmail": "[email protected]",
  "title": "Safety Training Certificate",
  "issuedAt": "2026-05-10T08:00:00.000Z",
  "expiresAt": "2027-05-10T08:00:00.000Z",
  "publicMetadata": {
    "trainer_name": "Certifyx Academy",
    "venue": "Kuala Lumpur"
  },
  "privateMetadata": {
    "identification_no": "900101-14-1234",
    "device_id": "tablet-042"
  }
}

Success response, 201 Created

{
  "data": {
    "certificateId": "CX-CLIENT-0001",
    "certificateUuid": "6ebeb4b1-8bf6-4df3-a366-cf7a569b0c6e",
    "environment": "sandbox",
    "status": "issued",
    "certificateHash": "b7a5c0...",
    "issuedAt": "2026-05-10T08:00:00.000Z",
    "verificationUrl": "https://verify.certifyx.club/CX-CLIENT-0001",
    "proofMode": "pdf_only",
    "pdf": {
      "url": "https://...",
      "expiresIn": 3600
    },
    "blockchain": null
  }
}

Sample errors

422 Unprocessable EntityVALIDATION_ERROR

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body is invalid."
  }
}

402 Payment RequiredQUOTA_EXCEEDED

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Production certificates require at least one credit. Top up credits from Billing."
  }
}

401 UnauthorizedINVALID_API_KEY

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing Bearer API key."
  }
}

429 Too Many RequestsRATE_LIMITED

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded."
  }
}

POST/v1/certificates/bulk

Bulk issue certificates

Creates a queued batch for multiple certificate payloads using the same issue schema.

Path parameters

No path parameters.

Query parameters

No query parameters.

Request body

Name

Type

Required

Description

batchNamestring

Yes

Human-readable batch name for dashboard tracking.

certificatesIssueCertificateInput[]

Yes

Array of 1 to 1000 certificate payloads. Each item uses the Issue certificate request shape.

Sample request

{
  "batchName": "May 2026 Safety Training",
  "certificates": [
    {
      "certificateId": "CX-BATCH-0001",
      "recipientName": "Aina Rahman",
      "recipientEmail": "[email protected]",
      "title": "Safety Training Certificate",
      "publicMetadata": {
        "trainer_name": "Certifyx Academy"
      },
      "privateMetadata": {
        "identification_no": "900101-14-1234"
      }
    }
  ]
}

Success response, 202 Accepted

{
  "data": {
    "batch": {
      "id": "7c4c0d2d-49d6-48a7-b107-bc6f62bc8170",
      "name": "May 2026 Safety Training",
      "environment": "sandbox",
      "status": "queued",
      "total_count": 1,
      "created_at": "2026-05-10T08:15:27.578Z"
    }
  }
}

Sample errors

422 Unprocessable EntityVALIDATION_ERROR

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "certificates must contain at least 1 item."
  }
}

401 UnauthorizedINVALID_API_KEY

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing Bearer API key."
  }
}

429 Too Many RequestsRATE_LIMITED

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded."
  }
}

GET/v1/certificates/{certificateId}

Get certificate

Reads the latest certificate status, PDF signed URL, public metadata, and blockchain transaction records.

Path parameters

Name

Type

Required

Description

certificateIdstring

Yes

Certificate number such as CX-CLIENT-0001.

Query parameters

No query parameters.

Request body

No request body.

Success response, 200 OK

{
  "data": {
    "certificateId": "CX-CLIENT-0001",
    "certificateUuid": "6ebeb4b1-8bf6-4df3-a366-cf7a569b0c6e",
    "environment": "sandbox",
    "status": "issued",
    "recipientName": "Aina Rahman",
    "recipientEmail": "[email protected]",
    "title": "Safety Training Certificate",
    "issueDate": "2026-05-10",
    "expiresAt": "2027-05-10T08:00:00.000Z",
    "certificateHash": "b7a5c0...",
    "publicMetadata": {
      "trainer_name": "Certifyx Academy"
    },
    "verificationUrl": "https://verify.certifyx.club/CX-CLIENT-0001",
    "proofMode": "pdf_only",
    "pdf": {
      "url": "https://...",
      "expiresIn": 3600
    },
    "blockchainTransactions": []
  }
}

Sample errors

404 Not FoundCERTIFICATE_NOT_FOUND

{
  "error": {
    "code": "CERTIFICATE_NOT_FOUND",
    "message": "Certificate was not found."
  }
}

401 UnauthorizedINVALID_API_KEY

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing Bearer API key."
  }
}

429 Too Many RequestsRATE_LIMITED

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded."
  }
}

POST/v1/certificates/{certificateId}/revoke

Revoke certificate

Marks a certificate as revoked and records the revocation reason.

Path parameters

Name

Type

Required

Description

certificateIdstring

Yes

Certificate number such as CX-CLIENT-0001.

Query parameters

No query parameters.

Request body

Name

Type

Required

Description

reasonstring

Yes

Reason for revocation. Must be 3 to 500 characters.

Sample request

{
  "reason": "Issued with incorrect recipient details"
}

Success response, 200 OK

{
  "data": {
    "certificateId": "CX-CLIENT-0001",
    "environment": "sandbox",
    "status": "revoked",
    "revokedAt": "2026-05-10T09:00:00.000Z",
    "reason": "Issued with incorrect recipient details",
    "proofMode": "pdf_only",
    "blockchain": null
  }
}

Sample errors

404 Not FoundCERTIFICATE_NOT_FOUND

{
  "error": {
    "code": "CERTIFICATE_NOT_FOUND",
    "message": "Certificate was not found."
  }
}

409 ConflictCERTIFICATE_REVOKED

{
  "error": {
    "code": "CERTIFICATE_REVOKED",
    "message": "Certificate is already revoked."
  }
}

401 UnauthorizedINVALID_API_KEY

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing Bearer API key."
  }
}

429 Too Many RequestsRATE_LIMITED

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded."
  }
}

GET/v1/verify/{certificateId}

Verify certificate

Performs server-side verification and writes a verification log for the certificate.

Path parameters

Name

Type

Required

Description

certificateIdstring

Yes

Certificate number such as CX-CLIENT-0001.

Query parameters

No query parameters.

Request body

No request body.

Success response, 200 OK

{
  "data": {
    "certificateId": "CX-CLIENT-0001",
    "certificateUuid": "6ebeb4b1-8bf6-4df3-a366-cf7a569b0c6e",
    "environment": "sandbox",
    "status": "verified",
    "certificateStatus": "issued",
    "recipientName": "Aina Rahman",
    "title": "Safety Training Certificate",
    "issueDate": "2026-05-10",
    "expiresAt": "2027-05-10T08:00:00.000Z",
    "certificateHash": "b7a5c0...",
    "verificationUrl": "https://verify.certifyx.club/CX-CLIENT-0001",
    "proofMode": "pdf_only",
    "blockchain": null
  }
}

Not found response, 200 OK

{
  "data": {
    "certificateId": "CX-MISSING",
    "environment": "sandbox",
    "status": "not_found",
    "message": "Certificate was not found.",
    "blockchain": null
  }
}

Sample errors

401 UnauthorizedINVALID_API_KEY

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing Bearer API key."
  }
}

429 Too Many RequestsRATE_LIMITED

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded."
  }
}

GET/v1/templates

List templates

Lists active organization and Certifyx templates available for issuance.

Path parameters

No path parameters.

Query parameters

No query parameters.

Request body

No request body.

Success response, 200 OK

{
  "data": {
    "environment": "sandbox",
    "templates": [
      {
        "id": "8e884cad-6a34-4f15-9d6d-0c2798d4d002",
        "name": "Classic Academic",
        "description": "Formal certificate with a strong border.",
        "is_premium": false,
        "is_active": true,
        "metadata_schema": {
          "fields": [
            {
              "key": "identification_no",
              "label": "Identification No.",
              "type": "text",
              "visibility": "private"
            }
          ]
        },
        "updated_at": "2026-05-10T08:15:27.578Z"
      }
    ]
  }
}

Sample errors

500 Internal Server ErrorINTERNAL_ERROR

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unable to load templates."
  }
}

401 UnauthorizedINVALID_API_KEY

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing Bearer API key."
  }
}

429 Too Many RequestsRATE_LIMITED

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded."
  }
}

POST/v1/webhooks

Create webhook endpoint

Registers an endpoint for certificate lifecycle events and returns the signing secret once.

Path parameters

No path parameters.

Query parameters

No query parameters.

Request body

Name

Type

Required

Description

urlurl

Yes

HTTPS endpoint that receives webhook deliveries.

descriptionstring

Optional label up to 200 characters.

eventsstring[]

Yes

Allowed values: certificate.issued, certificate.revoked, certificate.verified, certificate.failed, certificate.tampered.

Sample request

{
  "url": "https://client.example.com/certifyx/webhook",
  "description": "Production certificate events",
  "events": ["certificate.issued", "certificate.revoked"]
}

Success response, 201 Created

{
  "data": {
    "environment": "sandbox",
    "webhook": {
      "id": "ff99b705-1db0-4b5d-894e-91347ce53648",
      "url": "https://client.example.com/certifyx/webhook",
      "events": ["certificate.issued", "certificate.revoked"],
      "active": true,
      "created_at": "2026-05-10T08:15:27.578Z"
    },
    "signingSecret": "whsec_..."
  }
}

Sample errors

422 Unprocessable EntityVALIDATION_ERROR

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "url must be a valid URL."
  }
}

401 UnauthorizedINVALID_API_KEY

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing Bearer API key."
  }
}

429 Too Many RequestsRATE_LIMITED

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded."
  }
}

{ "certificateId": "CX-CLIENT-0001", "templateId": "8e884cad-6a34-4f15-9d6d-0c2798d4d002", "recipientName": "Aina Rahman", "recipientEmail": "[email protected]", "title": "Safety Training Certificate", "issuedAt": "2026-05-10T08:00:00.000Z", "expiresAt": "2027-05-10T08:00:00.000Z", "publicMetadata": { "trainer_name": "Certifyx Academy", "venue": "Kuala Lumpur" }, "privateMetadata": { "identification_no": "900101-14-1234", "device_id": "tablet-042" } }

{ "data": { "certificateId": "CX-CLIENT-0001", "certificateUuid": "6ebeb4b1-8bf6-4df3-a366-cf7a569b0c6e", "environment": "sandbox", "status": "issued", "certificateHash": "b7a5c0...", "issuedAt": "2026-05-10T08:00:00.000Z", "verificationUrl": "https://verify.certifyx.club/CX-CLIENT-0001", "proofMode": "pdf_only", "pdf": { "url": "https://...", "expiresIn": 3600 }, "blockchain": null } }

{ "batchName": "May 2026 Safety Training", "certificates": [ { "certificateId": "CX-BATCH-0001", "recipientName": "Aina Rahman", "recipientEmail": "[email protected]", "title": "Safety Training Certificate", "publicMetadata": { "trainer_name": "Certifyx Academy" }, "privateMetadata": { "identification_no": "900101-14-1234" } } ] }

{ "data": { "batch": { "id": "7c4c0d2d-49d6-48a7-b107-bc6f62bc8170", "name": "May 2026 Safety Training", "environment": "sandbox", "status": "queued", "total_count": 1, "created_at": "2026-05-10T08:15:27.578Z" } } }

{ "data": { "certificateId": "CX-CLIENT-0001", "certificateUuid": "6ebeb4b1-8bf6-4df3-a366-cf7a569b0c6e", "environment": "sandbox", "status": "issued", "recipientName": "Aina Rahman", "recipientEmail": "[email protected]", "title": "Safety Training Certificate", "issueDate": "2026-05-10", "expiresAt": "2027-05-10T08:00:00.000Z", "certificateHash": "b7a5c0...", "publicMetadata": { "trainer_name": "Certifyx Academy" }, "verificationUrl": "https://verify.certifyx.club/CX-CLIENT-0001", "proofMode": "pdf_only", "pdf": { "url": "https://...", "expiresIn": 3600 }, "blockchainTransactions": [] } }

{ "data": { "certificateId": "CX-CLIENT-0001", "environment": "sandbox", "status": "revoked", "revokedAt": "2026-05-10T09:00:00.000Z", "reason": "Issued with incorrect recipient details", "proofMode": "pdf_only", "blockchain": null } }

{ "data": { "certificateId": "CX-CLIENT-0001", "certificateUuid": "6ebeb4b1-8bf6-4df3-a366-cf7a569b0c6e", "environment": "sandbox", "status": "verified", "certificateStatus": "issued", "recipientName": "Aina Rahman", "title": "Safety Training Certificate", "issueDate": "2026-05-10", "expiresAt": "2027-05-10T08:00:00.000Z", "certificateHash": "b7a5c0...", "verificationUrl": "https://verify.certifyx.club/CX-CLIENT-0001", "proofMode": "pdf_only", "blockchain": null } }

{ "data": { "environment": "sandbox", "templates": [ { "id": "8e884cad-6a34-4f15-9d6d-0c2798d4d002", "name": "Classic Academic", "description": "Formal certificate with a strong border.", "is_premium": false, "is_active": true, "metadata_schema": { "fields": [ { "key": "identification_no", "label": "Identification No.", "type": "text", "visibility": "private" } ] }, "updated_at": "2026-05-10T08:15:27.578Z" } ] } }

{ "data": { "environment": "sandbox", "webhook": { "id": "ff99b705-1db0-4b5d-894e-91347ce53648", "url": "https://client.example.com/certifyx/webhook", "events": ["certificate.issued", "certificate.revoked"], "active": true, "created_at": "2026-05-10T08:15:27.578Z" }, "signingSecret": "whsec_..." } }