Regular (static) badges

Regular badges can be issued using via the Holopin website or via the Holopin API. They are claimed by the recipient using a URL that is either emailed to them on behalf of you or that you share with them.

Via the Holopin website

On the badge page, you will see three options for issuing the badge:

Issue to a single recipient via email

This option allows you to issue the badge to a single recipient by entering their email address. The recipient will receive an email with a link to claim the badge.

Issue to one recipient by generating a unique claim URL

This option allows you to issue the badge to a single recipient by generating a unique claim URL. You can then share this URL with the recipient, who can claim the badge by visiting the URL.

Issue to multiple recipients by generating a claim URL

This option allows you to issue the badge to multiple recipients by generating a multiple-use claim URL. You can then share this URL with the recipients, who can claim the badge by visiting the URL.

Multiple-use claim URLs are non-unique and can be used by anyone. You can revoke it and generate a new one at any time.

Via the Holopin API

The API offers more flexibility in how you can issue badges. You can issue badges to multiple recipients at once, and you can also issue badges to a single recipient without sending them an email.

POST https://www.holopin.io/api/sticker/share?id=[stickerId]&apiKey=[apiKey]

The stickerId is the ID of the badge you want to issue. This can be found in the URL of the evolving badge's page. The apiKey is the API key of your organization.

Options for the body of the request:

Success response:

{
"message": "Coupon created",
"data": {
    "id": [couponId],
    "stickerId": [stickerId],
    "metadata": [metadata] // only if the metadata parameter was used
    }
}

The couponId is the ID for the unique claim URL that you can share with the recipient (if no email was sent), in this case, the recipient can claim the badge by visiting the URL.

Claim URL is in this format:

https://holopin.io/claim/[couponId]

Experimental API Endpoints

Custom image per recipient

We are currently working on a new API that will allow you to issue badges with a custom image per recipient. This is currently in beta.

POST https://www.holopin.io/api/beta/coupon/?id=[stickerId]&apiKey=[apiKey]

The stickerId is the ID of the badge you want to issue. This can be found in the URL of the badge's page.

Options for the body of the request:

Success response:

{
  "message": "Coupon created.",
  "data": {
    "coupon": "cl9hhbeke000909mjizuasfq2", // coupon ID
    "sticker": "cl9g3zg8t052271bgkfgik563", // sticker ID
    "claimUrl": "https://holopin.io/claim/cl9hhbeke000909mjizuasfq2",
    "emailed": true, // whether we've sent an email to the user
    "metadata": "example metadata" // only if the metadata parameter was used
  }
}

Retrieve coupon status

You can check whether a badge has been claimed by a recipient by using the following endpoint:

GET https://www.holopin.io/api/beta/coupon/?id=[couponId]&apiKey=[apiKey]

The couponId is the ID of the coupon you want to check.

• If a coupon has been claimed, the response will be:

{
  "createdAt": "2022-08-24T14:36:20.174Z", // when the coupon was created
  "claimedAt": "2023-06-05T21:25:21.581Z", // when the coupon was claimed by the user
  "claimed": true,
  "username": <holopin username>,
  "email": <email address>, // if the badge was sent via email
  "url": <user's claimed badge URL>
}

• If a coupon has not been claimed, the response will be:

{
  "createdAt": "2022-08-24T14:36:20.174Z",
  "claimed": false,
  "email": <email address> // if the badge was sent via email. This will be null if the badge was not sent via email
}