Versify

The Versify API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

API Reference

The Versify API uses API keys to authenticate requests. You can view and manage your API key in the Versify dashboard.

Authentication

Versify uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Versify's servers.

Errors

are a bulk distribution of collectibles to an audience. For example, you might create an airdrop to send a new collectible to all of your customers who belong to the same email domain.

Airdrops

<h3>Attributes</h3> <pre><code class="language-json">{
 "id": "air_632ca20c824567f5ea38a23c",
 "object": "airdrop",
 "created": 1663869452,
 "metadata": {},
 "updated": 1664554811,
 "account": "acct_6320f8f70aaa3edca008f913",
 "archived": true,
 "email_settings": {
 "content": "Claim your free NFT.",
 "from_email": "airdrops@versifylabs.com",
 "from_image": "https://s3.amazonaws.com/cdn-dev.versifylabs.com/tmp/f18775d1-af98-4764-953a-8e4bfd00807b",
 "from_name": "Versify Labs",
 "preview_text": "Claim your free NFT from Versify Labs",
 "subject_line": "Claim your free NFT from Versify Labs"
 },
 "mint_link": "mlink_632ca216199aa3a35d21ab32",
 "name": "Sep 22 Airdrop",
 "product": "prod_632122daafb2615251ac5685",
 "recipients": {
 "count": 0,
 "segment_options": {
 "conditions": "tags:\"Team\"",
 "match": "all"
 },
 "emails_included": [],
 "emails_excluded": [],
 "tags_included": [],
 "tags_excluded": []
 },
 "status": "complete"
}</code></pre>

The airdrop object

Creates a new airdrop object. <h3>Parameters</h3> <h3>Returns</h3> Returns the airdrop object if the call succeeded.

Create an airdrop

Takes the airdrop draft and sends it to the recipients specified. The airdrop details cannot be modified after the airdrop is sent. <h3>Returns</h3> The updated airdrop object if successful. Otherwise, this call raises an error.

Send an airdrop

Retrieves the details of an existing airdrop. Supply the unique airdrop ID from either a airdrop creation request or the airdrop list, and Versify will return the corresponding airdrop information. <h3>Parameters</h3> No parameters. <h3>Returns</h3> Returns an airdrop object if a valid airdrop ID was provided. Raises an error otherwise.

Retrieve an airdrop

Updates the specific airdrop by setting the values of the parameters of the parameters passed. Any parameters not provided will be left unchanged. <h3>Parameters</h3> <h3>Returns</h3> The updated airdrop object if successful. Otherwise, this call raises an error.

Update an airdrop

Returns a list of your airdrops. The airdrops are returned sorted by creation date, with the most recently created appearing first. <h3>Parameters</h3> <h3>Returns</h3> A dictionary with a <code>data</code> property that contains an array of up to <code>page_size</code> collections. Each entry in the array is a separate collection object. If no more collections are available, the resulting array will be empty. This request should never raise an error.

List all airdrops

describe a specific group of products that can be minted as NFTs. For example, you might create a ‘Looney Tunes' collection that contains several products in It, including a ‘Bugs Bunny’ product. Collections have a one-to-one relationship with ERC1155 smart contracts.&nbsp;

Collections

<h3>Attributes</h3> <pre><code class="language-json">{
 "id": "coll_123",
 "object": "collection",
 "created": 1656595212,
 "active": true,
 "contract_address": "0x57de9894042296e48a90da9ec8e05e806aa12460",
 "description": "Group of tokens from the Looney Tunes squad.",
 "image": "https://cdn.versifylabs.com/123",
 "metadata": {},
 "name": "The Looney Tunes",
 "signature": "123456789",
 "status": "complete",
 "tags": [],
 "transaction": "0xd462d94c0f74ff057e485b85048a5cc557df58a4348bebb190b783a9239516da",
 "uri": "https://cdn.versifylabs.com/coll_123/{id}.json"
}</code></pre>

The collection object

Creates a new collection object. <h3>Parameters</h3> <h3>Returns</h3> Returns the collection object if the call succeeded.

Create a collection

Retrieves the details of an existing collection. Supply the unique collection ID from either a collection creation request or the collection list, and Versify will return the corresponding collection information. <h3>Parameters</h3> No parameters. <h3>Returns</h3> Returns a collection object if a valid collection ID was provided. Raises an error otherwise.

Retrieve a collection

Updates the specific collection. by setting the values of the parameters of the parameters passed. Any parameters not provided will be left unchanged. <h3>Parameters</h3> <h3>Returns</h3> The updated collection object if successful. Otherwise, this call raises an error.

Update a collection

Returns a list of your collections. The collections are returned sorted by creation date, with the most recently created products appearing first. <h3>Parameters</h3> <h3>Returns</h3> A dictionary with a <code>data</code> property that contains an array of up to <code>page_size</code> collections. Each entry in the array is a separate collection object. If no more collections are available, the resulting array will be empty. This request should never raise an error.

List all collections

This object represents a contact of your organization. It lets you send them NFTs and track transactions that belong to the same person.

Contacts

<h3>Attributes</h3> <pre><code class="language-json">{
 "id": "cont_123",
 "object": "contact",
 "created": 1656548724,
 "active": true,
 "address": null,
 "avatar": null,
 "balance": 0,
 "currency": "usd",
 "description": "",
 "email": "jane@example.com",
 "first_name": "Jane",
 "last_name": "Doe",
 "metadata": {},
 "name": "",
 "phone": null,
 "shipping": null,
 "source": "Versify",
 "tags": []
}
</code></pre>

The contact object

A contact must have an email. You can also create contacts in the contacts tab of the dashboard. <h3>Parameters</h3> <h3>Returns</h3> Returns the contact object if the creation succeeded. Raises an error if create parameters are invalid.

Create a contact

Retrieves a Contact object with the given ID. <h3>Parameters</h3> No parameters. <h3>Returns</h3> Returns a Contact object if a valid contact ID was provided. Raises an error otherwise.

Retrieve a contact

Updates the specific contact. by setting the values of the parameters of the parameters passed. Any parameters not provided will be left unchanged. <h3>Parameters</h3> <h3>Returns</h3> The updates contact object if successful. Otherwise, this call raises an error.

Update a contact

Returns a list of your contacts. The contacts are returned sorted by creation date, with the most recent contacts appearing first. <h3>Parameters</h3> <h3>Returns</h3> A dictionary with a <code>data</code> property that contains an array of up to <code>page_size</code> contacts. Each entry in the array is a separate contact object. If no more contacts are available, the resulting array will be empty. This request should never raise an error.

List all contacts

are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new <code>Event</code> object. For example, when an NFT is minted, we create a <code>mint.created</code> event. Note that many API requests may cause multiple events to be created. For example, if you create an airdrop with multiple recipients, you will receive an airdrop.created event and a <code>mint.created</code> event for each recipient. Events occur when the state of another API resource changes. The state of that resource at the time of the change is embedded in the event's data field. For example, a <code>contact.created</code> event will contain a contact, and a <code>product.created</code> event will contain a product. As with other API resources, you can use endpoints to retrieve an individual event or a list of events from the API. We also have a separate webhooks system for sending the <code>Event</code> objects directly to an endpoint on your server. Webhooks are managed in your account settings.

Events

<h3>Attributes</h3> <h3>The Contact Object</h3> <pre><code class="language-json">{
 "id": "evt_123",
 "object": "event",
 "created": 1655927455,
 "data": {
 "object": {
 "id": "cont_123",
 "object": "contact",
 "active": true,
 "balance": 0,
 "currency": "usd"
 }
 },
 "pending_webhooks": 0,
 "request": {},
 "type": "contact.created"
}
</code></pre>

The event object

Retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook. <h3>Parameters</h3> No parameters. <h3>Returns</h3> Returns an event object if a valid identifier was provided. All events share a common structure, detailed to the right. The only property that will differ is the data property.&nbsp; In each case, the data dictionary will have an attribute called object and its value will be the same as retrieving the same object directly from the API. For example, a contact.created event will have the same information as retrieving the relevant contact would.&nbsp; In cases where the attributes of an object have changed, data will also contain a dictionary containing the changes.

Retrieve an event

List events. <h3>Parameters</h3> <h3>Returns</h3> A dictionary with a data property that contains an array of up to page_size events. Each entry in the array is a separate event object. If no more events are available, the resulting array will be empty. This request should never raise an error.

List all events

A mint link is a shareable URL that will take your contacts to a hosted mint page. A mint link can be shared and used multiple times.&nbsp;

Mint Links

<h3>Attributes</h3> <pre><code class="language-json">{
 "id": "mlink_123",
 "object": "mint_link",
 "created": 1657058294,
 "metadata": {},
 "product": "prod_123",
 "active": true,
 "url": "https://mint.versifylabs.com/link/mlink_123"
}</code></pre>

The mint link object

Creates a mint link for a specific product. <h3>Parameters</h3> <h3>Returns</h3> Returns the mint link object.

Create a mint link

Retrieves the mint link with the given ID. <h3>Parameters</h3> No parameters. <h3>Returns</h3> Returns a mint link if a valid ID was provided. Raises an error otherwise.

Retrieve a mint link

Updates the mint link. You may update whether or not your webhook is <code>active</code>. <h3>Parameters</h3> <h3>Returns</h3> The updated mint links object if successful. Otherwise, this call raises an error.

Update a mint link

Returns a list of your mint links. <h3>Parameters</h3> <h3>Returns</h3> A dictionary with a <code>data</code> property that contains an array of up to <code>page_size</code> mint links. Each entry in the array is a separate mint link object. If no more mint links are available, the resulting array will be empty. This request should never raise an error.

List all mint links

To mint an NFT, you create a Mint object for a contact and product.

Mints

<h3>Attributes</h3> <pre><code class="language-json">{
 "id": "evt_123",
 "object": "event",
 "created": 1655927455,
 "data": {
 "object": {
 "id": "cont_123",
 "object": "contact",
 "active": true,
 "balance": 0,
 "currency": "usd"
 }
 },
 "pending_webhooks": 0,
 "request": {},
 "type": "contact.created"
}</code></pre>

The mint object

A mint an NFT, you create a Mint object. <h3>Parameters</h3> <h3>Returns</h3> Returns the mint object.

Create a mint

Retrieves the details of a mint that has previously been created. Supply the unique mint ID that was returned from your previous request or associated with an airdrop or mint link. <h3>Parameters</h3> No parameters. <h3>Returns</h3> Returns a mint if a valid mint ID was provided. Raises an error otherwise.

Retrieve a mint

Returns a list of mints you've previously created. The mints are returned in sorted order, with the most recent mints appearing first. <h3>Parameters</h3> <h3>Returns</h3> A dictionary with a <code>data</code> property that contains an array of up to <code>page_size</code> objects. Each entry in the array is a separate object. If no more objects are available, the resulting array will be empty. This request should never raise an error.

List all mints

describe the specific good that your customers can mint. For example, you might offer a ‘Bugs Bunny’ t-shirt product that can be minted on to the blockchain and used in the metaverse.

Products

<h3>Attributes</h3> <pre><code class="language-json">{
 "id": "prod_123",
 "object": "product",
 "created": 1656555024,
 "active": true,
 "chain": "polygon",
 "collection": "coll_123",
 "contract_address": "0x123",
 "creator_avatar": null,
 "creator_name": null,
 "description": "Member of the Looney Tunes",
 "image": "https://cdn.versifylabs.com/123",
 "metadata": {},
 "name": "Bugs Bunny",
 "properties": [
 {
 "name": "Squad",
 "value": "Looney Tunes"
 }
 ],
 "tags": [],
 "token_id": "1"
}
</code></pre>

The product object

Creates a new product object. <h3>Parameters</h3> <h3>Returns</h3> Returns a product object if the call succeeded.

Create a product

Returns a list of your products. The products are returned sorted by creation date, with the most recently created products appearing first. <h3>Parameters</h3> <h3>Returns</h3> A dictionary with a <code>data</code> property that contains an array of up to <code>page_size</code> objects. Each entry in the array is a separate object. If no more objects are available, the resulting array will be empty. This request should never raise an error.

List all products

Retrieves the details of an existing product with the given ID. <h3>Parameters</h3> No parameters. <h3>Returns</h3> Returns a product object if a valid ID was provided. Raises an error otherwise.

Retrieve a product

Updates the specific product by setting the values of the values of the parameters passed. <h3>Parameters</h3> <h3>Returns</h3> The updated product object if successful. Otherwise, this call raises an error.

Update a product

for data you've previously created using Versify's query language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages.&nbsp;

Search

Returns a list of your data matching the search parameters. <h3>Parameters</h3> <h3>Returns</h3> A dictionary with a data property that contains an array of up to page_size objects. Each entry in the array is a separate object. If no more objects are available, the resulting array will be empty. This request should never raise an error unless an invalid parameter is provided.

Search data

You can configure webhooks via the API to be notified about events that happen in your Versify account.

Webhooks

<h3>Attributes</h3> <h3>The Contact Object</h3> <pre><code class="language-json">{
 "id": "wh_dgj2392rFSDF23dsFs3",
 "object": "webhook",
 "active": true,
 "created": 1777888999,
 "description": "Sample webhook for API docs",
 "enabled_events": [
 "airdrop.created",
 "airdrop.deleted",
 "airdrop.updated",
 "collection.created",
 "collection.deleted",
 "collection.updated",
 "contact.created",
 "contact.deleted",
 "contact.updated",
 "mint.created",
 "mint.fulfilled",
 "mint.updated",
 "mint_link.created",
 "mint_link.deleted",
 "mint_link.updated",
 "product.created",
 "product.deleted",
 "product.updated",
 ],
 "metadata": {},
 "url": "https://api.example.com/webhook"
}
</code></pre>

The webhook object

A webhook must have a url and a list of enabled events. You can also create webhooks in the webhooks settings section of the dashboard. <h3>Parameters</h3> <h3>Returns</h3> Returns the webhook object with the secret field populated

Create a webhook

Returns a list of your webhooks. <h3>Parameters</h3> <h3>Returns</h3> A dictionary with a data property that contains an array of up to page_size webhooks. Each entry in the array is a separate webhook object. If no more webhooks are available, the resulting array will be empty. This request should never raise an error.

List all webhooks

Retrieves the webhook with the given ID. <h3>Parameters</h3> No parameters. <h3>Returns</h3> Returns a webhook if a valid webhook ID was provided. Raises an error otherwise.

Retrieve a webhook

Updates the webhook. You may edit the <code>url</code>, the list of <code>enabled_events</code>, or whether or not your webhook is <code>active</code>. <h3>Parameters</h3> <h3>Returns</h3> The updates webhook object if successful. Otherwise, this call raises an error.

Update a webhook

Deletes the webhook. <h3>Parameters</h3> No parameters. <h3>Returns</h3> An object with the deleted webhook's ID. Otherwise, this call raises an error, such as if the webhook has already been deleted.

Delete a webhook

The Versify API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The Versify API uses API keys to authenticate requests. You can view and manage your API key in the Versify dashboard.

Versify uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Versify&apos;s servers.

200 - OK

The request was unacceptable, often due to missing a required parameter.

400 - Bad request

401 - Unauthorized

The parameters were valid but the request failed.

402 - Request Failed

The API key doesnt have permissions to perform the request.

403 - Forbidden

404 - Not Found

500, 502, 503, 504 - Server Errors

are a bulk distribution of collectibles to an audience. For example, you might create an airdrop to send a new collectible to all of your customers who belong to the same email domain.

describe a specific group of products that can be minted as NFTs. For example, you might create a ‘Looney Tunes' collection that contains several products in It, including a ‘Bugs Bunny’ product. Collections have a one-to-one relationship with ERC1155 smart contracts.

This object represents a contact of your organization. It lets you send them NFTs and track transactions that belong to the same person.

are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new <code>Event</code> object. For example, when an NFT is minted, we create a <code>mint.created</code> event. Note that many API requests may cause multiple events to be created. For example, if you create an airdrop with mul

A mint link is a shareable URL that will take your contacts to a hosted mint page. A mint link can be shared and used multiple times.

To mint an NFT, you create a Mint object for a contact and product.

describe the specific good that your customers can mint. For example, you might offer a ‘Bugs Bunny’ t-shirt product that can be minted on to the blockchain and used in the metaverse.

for data you've previously created using Versify's query language. Don't use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages.

You can configure webhooks via the API to be notified about events that happen in your Versify account.