---
title: "Issue a new Assertion to a recipient"
method: POST
path: "/v2/{scope}/{idOrEntityId}/assertions"
tags: ["Issuers", "Assertions", "BadgeClasses"]
---

# Issue a new Assertion to a recipient

`POST /v2/{scope}/{idOrEntityId}/assertions`

## Path parameters

- `scope` 'badgeclasses' | 'issuers', required
- `idOrEntityId` string, required

## Request body

- V2AssertionForAwarding — Request to award an assertion. When request scope is issuers, one of badgeclass or badgeclassOpenBadgeId must be provided.
  - `allowDuplicateAwards` boolean — If set to false and the recipient already has this assertion, then the request will fail
  - `badgeclass` string, nullable — ID or Entity ID of the badge class to be awarded
  - `badgeclassOpenBadgeId` string, uri, nullable — OB URL of the badge class to be awarded
  - `evidence` V2AssertionEvidence[] — List of evidence associated with the achievement
    - `audience` string, nullable
    - `description` string, nullable
    - `genre` string, nullable
    - `name` string, nullable
    - `narrative` string, nullable — Markdown narrative that describes the achievement
    - `url` string, uri, nullable — URL of a webpage presenting evidence of the achievement
  - `expires` string, date-time, nullable
  - `extensions` AssertionExtension
    - `value` object, required
  - `issuedOn` string, date-time, nullable — Timestamp when the assertion was issued
  - `narrative` string, nullable — Markdown narrative of the achievement
  - `ob3AwardProperties` ApiOb3AwardProperties
    - `activityEnd` string, date-time, nullable
    - `activityStart` string, date-time, nullable
    - `licenseNumber` string, nullable
    - `role` string, nullable
  - `recipient` RecipientForAssertionAwarding, required
    - `hashed` boolean, nullable — If true, the provided identity value will be hashed
    - `identity` string, nullable, required — The plaintext value of the identity
    - `type` 'email' | 'telephone' | 'url' — Type of identifier used to identify recipient

## Response `201`

Created

- LegacyResponseWrapperV2Assertion
  - `errorCode` string, nullable
  - `fieldErrors` object, required
  - `latestTermsVersion` integer, nullable
  - `nonFieldErrors` string[], required
  - `result` V2Assertion[], required
    - `acceptance` 'Unaccepted' | 'Accepted' | 'Rejected', nullable — Recipient interaction with Assertion
    - `assertionRef` GlobalAssertionRef, required
      - `assertionUrl` string, uri, required — URL of the OpenBadge compliant json
    - `badgeRef` GlobalBadgeRef, required
      - `badgeUrl` string, uri, required — URL of the OpenBadge compliant json
    - `badgeclass` string — Entity ID of the BadgeClass of this award, or the OB badgeclass and issuer objects if expand is requested
    - `badgeclassOpenBadgeId` string, uri, required — OB URL of the BadgeClass of this award
    - `createdAt` string, date-time, nullable — Timestamp when the Assertion was created
    - `createdBy` string, nullable — Entity ID of the user who created this Assertion
    - `entityId` string, required — Unique identifier for this Assertion
    - `entityType` string, required
    - `evidence` V2AssertionEvidence[], required — List of evidence associated with the achievement
      - `audience` string, nullable
      - `description` string, nullable
      - `genre` string, nullable
      - `name` string, nullable
      - `narrative` string, nullable — Markdown narrative that describes the achievement
      - `url` string, uri, nullable — URL of a webpage presenting evidence of the achievement
    - `expires` string, date-time, nullable
    - `extensions` object, required
    - `id` string, required
    - `image` string, uri, nullable — URL to the baked assertion image
    - `imagePath` string, nullable — Internal image path
    - `issuedOn` string, date-time, nullable — Timestamp when the Assertion was issued
    - `issuer` string — Entity ID of the awarding issuer
    - `issuerOpenBadgeId` string, uri, required — OB URL of the awarding issuer
    - `issuerRef` GlobalIssuerRef, required
      - `issuerUrl` string, uri, required — URL of the OpenBadge compliant json
    - `narrative` string, nullable — Markdown narrative of the achievement
    - `ob3AwardProperties` ApiOb3AwardProperties
      - `activityEnd` string, date-time, nullable
      - `activityStart` string, date-time, nullable
      - `licenseNumber` string, nullable
      - `role` string, nullable
    - `openBadgeId` string, uri, required — URL of the OpenBadge compliant json
    - `originalJson` string, nullable — The original OB JSON if the assertion was exported
    - `pending` boolean, nullable
    - `recipient` V2AssertionRecipient, required — Recipient that was issued the Assertion
      - `hashed` boolean, required
      - `identity` string, required — Either the hash of the identity or the plaintext value
      - `plaintextIdentity` string, nullable
      - `salt` string, nullable — An optional salt used in producing the hashed identity if hashed
      - `type` 'email' | 'telephone' | 'url', required — Type of identifier used to identify recipient
    - `revocationReason` string, nullable — Short description of why the Assertion was revoked
    - `revoked` boolean, required
    - `source` string, nullable — The original source of the assertion
    - `sourceUrl` string, uri, nullable — The original URL of the assertion if it was imported
  - `status` BadgrStatus, required
    - `description` string, required
    - `success` boolean, required
  - `timestamp` string, date-time, nullable
  - `validationErrors` string[], required
  - `warnings` object, required

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/instructure/apis/public-api-docs.md) · [All operations](https://skmtc.net/instructure/apis/public-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/instructure/public-api-docs/revisions/44eb39b4bd65/schema)