Quick Start Guide

Allows you to get started easily

Drops are the building blocks of the POAP ecosystem. When an issuer creates a drop to commemorate a memory, they are creating a digital record of that memory that includes an image and other metadata such as a title and description.

The POAP help center includes articles on creating quality drops and the Discourse community also has a thread regarding best practices to create drops.

πŸ“˜

Base URL

https://api.poap.tech

Create a drop

In order to create a drop, use POST /events

{
  "name": name of your Drop,
  "description": Description of your drop, please adhere to the guidelines specified here: https://intercom.help/poap/en/articles/5828287-why-has-my-drop-not-been-approved-yet,
  "city": city where the event will be taking place,
  "country": country where the event will be taking place,
  "start_date": Start date for your Drop,
  "end_date": Can be the same as the End date,
  "expiry_date": From this day onward, no Collectors will be able to mint POAPs from your Drop,
  "year": <number>,
  "event_url": We suggest adding a URL for your drop for Collectors to visit,
  "virtual_event": true or false,
  "image": Image should be 500x500, circle cropped, under 4MB and can either be .png or .gif with .png extension,
  "secret_code": 6 digit secret code that can be used to edit your Drop afterwards,
  "event_template_id": <number: default 0> add a template to customize the page where your Collectors will mint their POAP,
  "email": email address where you will receive <<glossary:mint links>>,
  "requested_codes": <number> amount of <<glossary:mint links>> for your Drop. If you are using other distribution method, this should be zero,
  "private_event": choose whether your drop will be visible on the POAP Drops page or not (app.poap.xyz/admin/events)
}

The Curation Body also has a thread regarding best practices to create drops.

Once you have created your drop, it's time to define how you will distribute it.


Choosing a distribution method

In order to distribute a POAP, you will need to create a petition by choosing one of our distribution methods. A petition is the act of submitting a POAP for review to the POAP Curation Body. There are numerous methods to use for distribution depending on the use case.
Mint Links, Website, Secret Word and Delivery**

Learn more about each method in our help center article

After choosing your distribution method and making a submission, you should await a review from the POAP Curation Body. If you receive a positive review, your distribution method will be activated and you will be able to start distributing POAPs to collectors.

The drop creation endpoint allows you to request mint links in the same request. This will be reviewed by the POAP Curation Body. Your mint links are then sent to the email address provided when the drop was created.
If you intend to choose a different distribution method for your drop, leave this field as "0" and move on to the next section.


Create a petition for mint links

A petition is the act of submitting a POAP for review to the POAP Curation Body.
In order to distribute a POAP, you will need to create a petition by choosing one of our distribution methods. You can create a petition for mint links by using the /redeem-request endpoint.
Once your petition is approved, mint links are sent to the email address provided when the drop was created.
When collectors click the mint link, they are able to mint the POAP by inputting their Ethereum address, or reserve the POAP by inputting their email address.
In case your preferred distribution method is a Delivery, Website, or using a Secret Word, refer to the next sections.

{
  "event_id": the ID of your previously created Drop,
  "requested_codes": amount of <<glossary:mint links>> you'll need for your drop, this is based on the number of attendees you are expecting,
  "secret_code": 6 digit code specified when the Drop was created,
  "redeem_type": qr_code
}

Creating a petition for Secret Word or Website

In order to distribute a POAP, you will need to create a petition by choosing one of our distribution methods. You can create a petition for using a Website or Secret Word by using this /secret-requests endpoint.
Collectors can mint or reserve the POAP for your drop by:

  • Websites: Entering https://poap.website/<claim_name> during the specified time of the petition
  • Secret Word: Entering the Secret Word on the POAP mobile app (iOS, Android) during the specified time of the petition
{
  "event_id": Drop ID previously created,
  "requested_codes": Amount of POAPs you are planning to distribute,
  "secret_code": Secret code for the Drop specified,
  "claim_name": the secret word or path for your website (ie. https://poap.website/claim_name),
  "from": Start date where the POAP will be distributed using hh:mm format,
  "to": End date where the POAP will be distributed using hh:mm format,
  "timezone": Leave at zero,
  "captcha": true,
  "active": true,
  "secret_type": Can be website or secret depending on the distribution method you choose
}

Creating a petition for a Delivery

Delivery is a distribution method that allows the issuer to whitelist a set of Ethereum addresses for minting a certain POAP.
To create a Delivery, you can use this /deliveries endpoint.
For more information about Deliveries, please refer to this article.

πŸ“˜

Add all addresses for a Delivery on the first request, as (at least for the time being) you are not allowed to add addresses retroactively

{
  "slug": path to your delivery page (ie. https://poap.delivery/slug),
  "card_title": title shown on the card of the POAP delivery main page,
  "card_text": description shown on the card of the POAP delivery main page,
  "page_title": title shown on the page of your delivery,
  "page_text": description shown on the page of your delivery,
  "event_ids": ID of the Drops that the Collectors will be able to mint POAPs for,
  "secret_codes": Secret codes corresponding to each Drop ID added,
  "image": URL of the image that will be displayed on the POAP delivery main page,
  "page_title_image": URL of the image that will be displayed on your POAP delivery page,
  "metadata_title": title shown on the snippet when you share your delivery,
  "metadata_description": description shown on the snippet when you share your delivery,
  "addresses": [
    {
      "address": address that will be able to mint the POAP,
      "events": [
        List of Drop IDs that will be minted
      ]
    }
  ]
}

Collectors will be able to mint the POAP for your Delivery by entering https://poap.delivery/{your-slug} and inputting their address or by using this /actions/claim-delivery-v2 endpoint, where id is the ID of the Delivery you created.

Minting POAPs

POAPs can either be minted using an Ethereum address or reserved by inputting an email address. For more information on reserving POAPs via email, refer to this article

Minting POAPs using mint links
Both of these endpoints are protected. This means that you will need an authentication token provided by POAP in order to use these methods.

If you hold a mint link for a POAP (such as https://poap.xyz/claim/abc123), you can use our endpoints to mint that specific POAP to an Ethereum address. Keep in mind that each mint link is valid for a unique POAP and cannot be reused.

In order to mint a POAP using mint links, use this GET /actions/claim-qr endpoint to retrieve the Secret, where qr_hash is the six-character code in the mint link. With the Secret, you can use this POST /actions/claim-qr endpoint to effectively mint the POAP.

πŸ“˜

qr_hash

The six-character code in the mint link

Minting POAPs using a Website or Secret word
Keep in mind that both Website and Secret Word POAPs are only mintable during the active timeframe specified by the issuer.

In order to mint a POAP using a Website, use this POST /website/claim endpoint.
POAPs that use Secret Word can only be minted using the POAP mobile app and thus cannot be minted programmatically.

Minting POAPs using Delivery
In order to mint a POAP using Delivery, you can use this POST /actions/claim-qr endpoint, where id is the ID provided when the Delivery was created by the issuer.