Create

post

https://api.certify.one/api/v2/issuer-api/issued-credentials/create

Issue a credential to a recipient identified by name + email, against a
credential identified by its identifier or uuid.

If the recipient already has this credential, already_existed and
updated in the response tell you what happened:

by default the existing credential is returned unchanged (custom field
values you send are still saved);
with update_if_exists: true it is updated with the fields you send;
with allow_duplication: true a second credential is issued.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

recipient_name

string

required

length ≥ 2

recipient_email

string

required

credential_identifier

string

required

you can use credential identifier or credential uuid

is_organization

boolean

Defaults to false

optional
default is false
accepted input are true, false, 1, 0, "1", "0"

expiration_date

date | null

optional
only yyyy-mm-dd format is allowed
when omitted on a new credential, the credential's default validity
applies (as configured on the credential: a number of days after issue,
counted from today in UTC, or a fixed date); no expiration when the
credential has none
send null to issue without expiration, whatever the credential's default
with update_if_exists, omit it to keep the current expiration date and
send null to remove it (changing or removing it consumes a credit)

completion_date

date | null

optional
default is null
only yyyy-mm-dd format is allowed
must be today or earlier in UTC (a future date is rejected)
with update_if_exists, omit it to keep the current date and send null
to remove it

notify_recipient

boolean

Defaults to true

optional
default is true
accepted input are true, false, 1, 0, "1", "0"

allow_duplication

boolean

Defaults to false

optional
default is false
when true, a new credential is issued even if the recipient already
has this credential (a duplicate). Duplication wins when both
allow_duplication and update_if_exists are set
accepted input are true, false, 1, 0, "1", "0"

update_if_exists

boolean

Defaults to false

optional
default is false
when true, if the recipient already has this credential it is updated
with the fields you send instead of being left unchanged
a field you omit (expiration_date, completion_date, is_organization,
certificate_pdf_url) keeps its current value; a field sent as null is
cleared. The recipient name is always applied, and the credential's
visibility is never changed
when everything you send matches what is stored, nothing happens: no
certificate rebuild, no e-mail, and updated is false
accepted input are true, false, 1, 0, "1", "0"

custom_fields

object

optional
custom field values to attach to the recipient and/or the issued
credential. Each key must match a custom field configured for your
account (list them with GET /custom-fields); unknown keys are rejected
values may be strings or numbers; numbers are stored as text (95 is
stored as "95")
send values of date fields as yyyy-mm-dd (for example 2026-03-15);
certificates show them as dd/mm/yyyy. The value is not validated: any
other text is stored and printed as sent
null or "" deletes the stored value
if the recipient already has this credential, the values you send are
saved even without update_if_exists

certificate_pdf_url

uri

length ≤ 2048

optional
external https url to a certificate PDF. When set, it is used as the
certificate for this issuance instead of the badge's design template
(the external PDF takes precedence)
must be https and reachable; the file is downloaded and stored intact,
and a preview image + thumbnail are derived from its first page
with update_if_exists, omit it to keep the current certificate and send
null or "" to remove the external certificate (the credential's design
template is used again)

cpf

string

optional
the recipient's CPF, with or without punctuation (123.456.789-09 or
12345678909); it must have 11 digits, leading zeros included, and valid
check digits
stored on the recipient, whether the credential is new or already exists,
even without update_if_exists; omit it to keep the stored CPF
an empty CPF is always filled. A different stored CPF is replaced only when
the recipient has received credentials from your account alone; otherwise
the stored CPF is kept and the request still succeeds
saving it never rebuilds the certificate, e-mails the recipient or sets
updated

cnpj

string

optional
the recipient's CNPJ, with or without punctuation (11.222.333/0001-81 or
11222333000181); it must have 14 digits, leading zeros included, and
valid check digits
stored like cpf: on the recipient, whether the credential is new or not,
filling an empty CNPJ and replacing a different one only for a recipient
of your account alone

Responses

`error` is `Unauthenticated` when no token
is sent and `Invalid Issuer Key` when it matches no account.

Create

`error` is `Unauthenticated` when no token
is sent and `Invalid Issuer Key` when it matches no account.

`error` is
`Account suspended` when a payment is outstanding and `No active contract`
when your plan has ended. Reading, revoking and deleting are never refused
this way.

`message` says what was not found, for example
`issued credential not found`, `credential not found` or `recipient not found`.

`message` plus `errors`, with one list of messages
per invalid field;
plan limit reached (issuing only): `error` is `Customer limit exceeded`
and `details` carries your usage.

`Retry-After` header before trying again.

200OK

401Missing or invalid access token. error is Unauthenticated when no token is sent and Invalid Issuer Key when it matches no account.

402The request would consume a credit and your account cannot: error is Account suspended when a payment is outstanding and No active contract when your plan has ended. Reading, revoking and deleting are never refused this way.

404Not found in your account. message says what was not found, for example issued credential not found, credential not found or recipient not found.

422Two cases, told apart by the body: validation error: message plus errors, with one list of messages per invalid field; plan limit reached (issuing only): error is Customer limit exceeded and details carries your usage.

429Too many requests (60 per minute per token by default). Wait the number of seconds in the Retry-After header before trying again.

`error` is `Unauthenticated` when no token
is sent and `Invalid Issuer Key` when it matches no account.

`error` is
`Account suspended` when a payment is outstanding and `No active contract`
when your plan has ended. Reading, revoking and deleting are never refused
this way.

`message` says what was not found, for example
`issued credential not found`, `credential not found` or `recipient not found`.

`message` plus `errors`, with one list of messages
per invalid field;
plan limit reached (issuing only): `error` is `Customer limit exceeded`
and `details` carries your usage.

`Retry-After` header before trying again.