API Reference
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.
Why you find this section not helpful?
Base URL
Authentication
The Versify API uses API keys to authenticate requests. You can view and manage your API key in the Versify dashboard.
Why you find this section not helpful?
Errors
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.
Why you find this section not helpful?
Status Codes
200
OK
Everything worked as expected.
400
Bad request
The request was unacceptable, often due to missing a required parameter.
401
Unauthorized
The request was unacceptable, often due to missing a required parameter.
402
Request Failed
The parameters were valid but the request failed.
403
Forbidden
The API key doesnt have permissions to perform the request.
404
Not Found
The requested resource does not exist.
500, 502, 503, 504
Server Errors
Something went wrong on Versify's end.
Airdrops
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.
Why you find this section not helpful?
The airdrop object
Attributes
{ "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"}Why you find this section not helpful?
Create an airdrop
Creates a new airdrop object.
Parameters
Returns
Returns the airdrop object if the call succeeded.
HEADER PARAMETERS
BODY PARAMETERS
Why you find this section not helpful?
Send an airdrop
Takes the airdrop draft and sends it to the recipients specified. The airdrop details cannot be modified after the airdrop is sent.
Returns
The updated airdrop object if successful. Otherwise, this call raises an error.
HEADER PARAMETERS
Why you find this section not helpful?
Retrieve 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.
Parameters
No parameters.
Returns
Returns an airdrop object if a valid airdrop ID was provided. Raises an error otherwise.
HEADER PARAMETERS
QUERY PARAMETERS
Why you find this section not helpful?
Update 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.
Parameters
Returns
The updated airdrop object if successful. Otherwise, this call raises an error.
HEADER PARAMETERS
Why you find this section not helpful?
List all airdrops
Returns a list of your airdrops. The airdrops are returned sorted by creation date, with the most recently created appearing first.
Parameters
Returns
A dictionary with a data property that contains an array of up to page_size 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.
HEADER PARAMETERS
QUERY PARAMETERS
Why you find this section not helpful?
Collections
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.
Why you find this section not helpful?
The collection object
Attributes
{ "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"}Why you find this section not helpful?
Create a collection
Creates a new collection object.
Parameters
Returns
Returns the collection object if the call succeeded.
HEADER PARAMETERS
BODY PARAMETERS
Responses
Response attributes
Why you find this section not helpful?
Retrieve 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.
Parameters
No parameters.
Returns
Returns a collection object if a valid collection ID was provided. Raises an error otherwise.
HEADER PARAMETERS
Responses
Response attributes
Why you find this section not helpful?
Update 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.
Parameters
Returns
The updated collection object if successful. Otherwise, this call raises an error.
HEADER PARAMETERS
BODY PARAMETERS
Responses
Response attributes
Why you find this section not helpful?
List all collections
Returns a list of your collections. The collections are returned sorted by creation date, with the most recently created products appearing first.
Parameters
Returns
A dictionary with a data property that contains an array of up to page_size 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.
HEADER PARAMETERS
Responses
Response attributes
child attributes
Why you find this section not helpful?
Contacts
This object represents a contact of your organization. It lets you send them NFTs and track transactions that belong to the same person.
Why you find this section not helpful?
The contact object
Attributes
Select...
Why you find this section not helpful?
Create a contact
A contact must have an email. You can also create contacts in the contacts tab of the dashboard.
Parameters
Returns
Returns the contact object if the creation succeeded. Raises an error if create parameters are invalid.
Why you find this section not helpful?
Retrieve a contact
Retrieves a Contact object with the given ID.
Parameters
No parameters.
Returns
Returns a Contact object if a valid contact ID was provided. Raises an error otherwise.
Why you find this section not helpful?
Update 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.
Parameters
Returns
The updates contact object if successful. Otherwise, this call raises an error.
HEADER PARAMETERS
BODY PARAMETERS
Responses
Response attributes
Why you find this section not helpful?
List all contacts
Returns a list of your contacts. The contacts are returned sorted by creation date, with the most recent contacts appearing first.
Parameters
Returns
A dictionary with a data property that contains an array of up to page_size 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.
HEADER PARAMETERS
Responses
Response attributes
child attributes
Why you find this section not helpful?
Events
are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new Event object. For example, when an NFT is minted, we create a mint.created 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 mint.created 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 contact.created event will contain a contact, and a product.created 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 Event objects directly to an endpoint on your server. Webhooks are managed in your account settings.
Why you find this section not helpful?
The event object
Attributes
The Contact Object
{ "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"}Why you find this section not helpful?
Retrieve an event
Retrieves the details of an event. Supply the unique identifier of the event, which you might have received in a webhook.
Parameters
No parameters.
Returns
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.
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.
In cases where the attributes of an object have changed, data will also contain a dictionary containing the changes.
HEADER PARAMETERS
Responses
Response attributes
child attributes
child attributes
Response attributes
Why you find this section not helpful?
List all events
List events.
Parameters
Returns
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.
Why you find this section not helpful?
Mint Links
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.
Why you find this section not helpful?
The mint link object
Attributes
{ "id": "mlink_123", "object": "mint_link", "created": 1657058294, "metadata": {}, "product": "prod_123", "active": true, "url": "https://mint.versifylabs.com/link/mlink_123"}Why you find this section not helpful?
Create a mint link
Creates a mint link for a specific product.
Parameters
Returns
Returns the mint link object.
HEADER PARAMETERS
BODY PARAMETERS
Responses
Response attributes
Why you find this section not helpful?
Retrieve a mint link
Retrieves the mint link with the given ID.
Parameters
No parameters.
Returns
Returns a mint link if a valid ID was provided. Raises an error otherwise.
HEADER PARAMETERS
Responses
Response attributes
Why you find this section not helpful?
Update a mint link
Updates the mint link. You may update whether or not your webhook is active.
Parameters
Returns
The updated mint links object if successful. Otherwise, this call raises an error.
HEADER PARAMETERS
BODY PARAMETERS
Responses
Response attributes
Why you find this section not helpful?
List all mint links
Returns a list of your mint links.
Parameters
Returns
A dictionary with a data property that contains an array of up to page_size 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.
HEADER PARAMETERS
Responses
Response attributes
child attributes
Why you find this section not helpful?
Mints
To mint an NFT, you create a Mint object for a contact and product.
Why you find this section not helpful?
The mint object
Attributes
{ "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"}Why you find this section not helpful?
Create a mint
A mint an NFT, you create a Mint object.
Parameters
Returns
Returns the mint object.
HEADER PARAMETERS
BODY PARAMETERS
Responses
Response attributes
Why you find this section not helpful?
Retrieve 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.
Parameters
No parameters.
Returns
Returns a mint if a valid mint ID was provided. Raises an error otherwise.
HEADER PARAMETERS
Responses
Response attributes
Why you find this section not helpful?
List all mints
Returns a list of mints you've previously created. The mints are returned in sorted order, with the most recent mints appearing first.
Parameters
Returns
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.
HEADER PARAMETERS
Responses
Response attributes
child attributes
Why you find this section not helpful?
Products
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.
Why you find this section not helpful?
The product object
Attributes
{ "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"}Why you find this section not helpful?
Create a product
Creates a new product object.
Parameters
Returns
Returns a product object if the call succeeded.
HEADER PARAMETERS
BODY PARAMETERS
Responses
Response attributes
child attributes
Why you find this section not helpful?
List all products
Returns a list of your products. The products are returned sorted by creation date, with the most recently created products appearing first.
Parameters
Returns
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.
HEADER PARAMETERS
Responses
Response attributes
child attributes
child attributes
child attributes
Why you find this section not helpful?
Retrieve a product
Retrieves the details of an existing product with the given ID.
Parameters
No parameters.
Returns
Returns a product object if a valid ID was provided. Raises an error otherwise.
HEADER PARAMETERS
Responses
Response attributes
child attributes
Why you find this section not helpful?
Update a product
Updates the specific product by setting the values of the values of the parameters passed.
Parameters
Returns
The updated product object if successful. Otherwise, this call raises an error.
HEADER PARAMETERS
BODY PARAMETERS
Responses
Response attributes
child attributes
Why you find this section not helpful?
Search
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.
Why you find this section not helpful?
Search data
Returns a list of your data matching the search parameters.
Parameters
Returns
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.
HEADER PARAMETERS
QUERY PARAMETERS
Why you find this section not helpful?
Webhooks
You can configure webhooks via the API to be notified about events that happen in your Versify account.
Why you find this section not helpful?
The webhook object
Attributes
The Contact Object
{ "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"}Why you find this section not helpful?
Create a webhook
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.
Parameters
Returns
Returns the webhook object with the secret field populated
HEADER PARAMETERS
BODY PARAMETERS
Why you find this section not helpful?
List all webhooks
Returns a list of your webhooks.
Parameters
Returns
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.
HEADER PARAMETERS
Why you find this section not helpful?
Retrieve a webhook
Retrieves the webhook with the given ID.
Parameters
No parameters.
Returns
Returns a webhook if a valid webhook ID was provided. Raises an error otherwise.
HEADER PARAMETERS
Why you find this section not helpful?
Update a webhook
Updates the webhook. You may edit the url, the list of enabled_events, or whether or not your webhook is active.
Parameters
Returns
The updates webhook object if successful. Otherwise, this call raises an error.
HEADER PARAMETERS
BODY PARAMETERS
Why you find this section not helpful?
Delete a webhook
Deletes the webhook.
Parameters
No parameters.
Returns
An object with the deleted webhook's ID. Otherwise, this call raises an error, such as if the webhook has already been deleted.