Customize a record per issuance with overwriteRecord

When you issue a credential with POST /credential/issue, the record (the PDF) uses by default the design, texts, and images defined in the template (credentialTemplateId). The overwriteRecord object lets you override those three aspects for that single issuance only, without touching the template or affecting any other issuance.

1. What each sub-key overrides

overwriteRecord is optional and accepts three independent sub-keys — you can send one, two, or all three; you don’t have to include all of them:

Sub-key What it overrides
recordDesign The record design defined in the template.
texts Any text defined in the record design.
images Any of the images (logos, signatures, backgrounds, etc.) in the record design.

🔎 Note: overwriteRecord is a one-off exception mechanism. The template remains the source of truth for all other issuances; this object only affects the record generated for that specific earner.

The exact detail of the inner fields of recordDesign, texts, and images (types and allowed values) is in the Swagger OpenAPI contract: https://public-api.acreditta.com/swagger/#/. This guide explains how to use the object; it doesn’t replace that reference.

2. Example payload

{
  "credentialTemplateId": "string",
  "firstName": "Ana",
  "lastName": "Gómez",
  "email": "ana.gomez@example.com",
  "awardedAt": "2026-09-07",
  "sendNotification": true,
  "overwriteRecord": {
    "recordDesign": "",
    "texts": [
      { "name": "my_textbox_1", "str": "new string to replace" },
      { "name": "my_textbox_2", "str": "some generic text" }
    ],
    "images": [
      { "name": "logo", "url": "https://example.com/logo.png" }
    ]
  }
}

Each sub-key is independent: if you only need to change one text for this particular earner, send only texts.

3. Errors and validations to consider

  • If the body doesn’t pass schema validation (for example, an invalid structure inside overwriteRecord), the API responds 406. Check the body against the exact schema in Swagger before integrating in production.
  • overwriteRecord has no effect if the same request sends updateCredential: true together with credentialUUID — that is the update path for an already-issued credential, not a new issuance (see API Endpoints).
  • The name field must match a text or image element in the design; if it matches none, it is ignored. If several elements share the same name, the replacement is applied to the first one found. Make sure the name is unique: right-click the text or image element you want to replace, click Properties, and there set the name you want for the container.
  • For images, the replacement is done by URL, and that URL must point directly to a public image file (JPG or PNG, not an HTML page). This means links from storage providers such as Google Drive or Microsoft that don’t give a direct path to the image won’t work.

4. Using it in a bulk issuance

If you issue in batches from the platform (not via API) and need the record of a specific row in the file to look different from the rest, you can add a column named overwrite_record to the upload file and paste the same object there — see Bulk sending.

References


CONTENIDO

Powered By EazyDocs