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.

Was this section helpful?

Why you find this section not helpful?

Base URL

Language Box

Authentication

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


Was this section helpful?

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.


Was this section helpful?

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.


Was this section helpful?

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"
}


Was this section helpful?

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

Content-Typestring

BODY PARAMETERS

Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

QUERY PARAMETERS

expandstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

QUERY PARAMETERS

page_numstring
page_sizestring
statusstring
expandstring
Was this section helpful?

Why you find this section not helpful?

1

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. 


Was this section helpful?

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"
}


Was this section helpful?

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS

descriptionstring
imagestring
namestring

Responses

200
Object

Response attributes

idstring
objectstring
creatednumber
activeboolean
descriptionstring
imagestring
metadataobject
namestring
statusstring
tagsarray
uristring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses

200
Object

Response attributes

idstring
objectstring
creatednumber
activeboolean
descriptionstring
imagestring
metadataobject
namestring
statusstring
tagsarray
uristring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS
Expand all

tagsarray

Responses

200
Object

Response attributes

idstring
objectstring
creatednumber
activeboolean
descriptionstring
imagestring
metadataobject
namestring
statusstring
tagsarray
uristring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses
Expand all

200
Object

Response attributes

objectstring
urlstring
has_moreboolean
dataarray
child attributes
idstring
objectstring
creatednumber
activeboolean
descriptionstring
imagestring
metadataobject
namestring
statusstring
tagsarray
uristring
Was this section helpful?

Why you find this section not helpful?

1

Contacts

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


Was this section helpful?

Why you find this section not helpful?

The contact object

Attributes

Select...
{
"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": []
}

Was this section helpful?

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.

Was this section helpful?

Why you find this section not helpful?

1

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.

Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS
Expand all

tagsarray

Responses

200
Object

Response attributes

idstring
objectstring
creatednumber
activeboolean
addressobject
avatarobject
balancenumber
currencystring
descriptionstring
emailstring
first_namestring
last_namestring
metadataobject
namestring
phoneobject
shippingobject
sourcestring
tagsarray
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses
Expand all

200
Object

Response attributes

objectstring
urlstring
has_moreboolean
dataarray
child attributes
idstring
objectstring
creatednumber
activeboolean
addressobject
avatarobject
balancenumber
currencystring
descriptionstring
emailstring
first_namestring
last_namestring
metadataobject
namestring
phoneobject
shippingobject
sourcestring
tagsarray
Was this section helpful?

Why you find this section not helpful?

1

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.

Was this section helpful?

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"
}


Was this section helpful?

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses
Expand all

200
Object

Response attributes

idstring
objectstring
creatednumber
dataobject
child attributes
objectobject
child attributes
idstring
objectstring
activeboolean
balancenumber
currencystring
pending_webhooksnumber
requestobject
typestring
404
Object

Response attributes

statusCodenumber
messagestring
Was this section helpful?

Why you find this section not helpful?

1

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.

Was this section helpful?

Why you find this section not helpful?

1

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. 

Was this section helpful?

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"
}


Was this section helpful?

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS

productstring

Responses

200
Object

Response attributes

idstring
objectstring
creatednumber
metadataobject
productstring
activeboolean
urlstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses

200
Object

Response attributes

idstring
objectstring
creatednumber
metadataobject
productstring
activeboolean
urlstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS
Expand all

tagsarray

Responses

200
Object

Response attributes

idstring
objectstring
creatednumber
metadataobject
productstring
activeboolean
urlstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses
Expand all

200
Object

Response attributes

objectstring
urlstring
has_moreboolean
dataarray
child attributes
idstring
objectstring
creatednumber
metadataobject
productstring
activeboolean
urlstring
Was this section helpful?

Why you find this section not helpful?

1

Mints

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


Was this section helpful?

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"
}


Was this section helpful?

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS

contactstring
productstring

Responses

200
Object

Response attributes

idstring
objectstring
creatednumber
airdropobject
contactstring
failure_codeobject
failure_messageobject
metadataobject
mint_linkobject
productstring
signatureobject
statusstring
transactionobject
urlstring
wallet_addressobject
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses

200
Object

Response attributes

idstring
objectstring
creatednumber
airdropobject
contactstring
failure_codeobject
failure_messageobject
metadataobject
mint_linkobject
productstring
signatureobject
statusstring
transactionobject
urlstring
wallet_addressobject
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses
Expand all

200
Object

Response attributes

objectstring
urlstring
has_moreboolean
dataarray
child attributes
idstring
objectstring
creatednumber
airdropobject
contactstring
failure_codeobject
failure_messageobject
metadataobject
mint_linkstring
productstring
statusstring
urlstring
wallet_addressstring
Was this section helpful?

Why you find this section not helpful?

1

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.


Was this section helpful?

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"
}


Was this section helpful?

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS

collectionstring
descriptionstring
imagestring
namestring

Responses
Expand all

200
Object

Response attributes

idstring
objectstring
creatednumber
activeboolean
chainstring
collectionstring
contract_addressstring
creator_avatarobject
creator_nameobject
descriptionstring
imagestring
metadataobject
namestring
propertiesarray
child attributes
namestring
valuestring
tagsarray
token_idstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses
Expand all

200
Object

Response attributes

objectstring
urlstring
has_moreboolean
dataarray
child attributes
idstring
objectstring
creatednumber
activeboolean
chainstring
collectionobject
child attributes
idstring
objectstring
creatednumber
activeboolean
contract_addressstring
descriptionstring
imagestring
metadataobject
namestring
statusstring
tagsarray
uristring
contract_addressstring
creator_avatarobject
creator_nameobject
descriptionstring
imagestring
metadataobject
namestring
propertiesarray
child attributes
namestring
valuestring
tagsarray
token_idstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

Responses
Expand all

200
Object

Response attributes

idstring
objectstring
creatednumber
activeboolean
chainstring
collectionstring
contract_addressstring
creator_avatarobject
creator_nameobject
descriptionstring
imagestring
metadataobject
namestring
propertiesarray
child attributes
namestring
valuestring
tagsarray
token_idstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS

activestring

Responses
Expand all

200
Object

Response attributes

idstring
objectstring
creatednumber
activeboolean
chainstring
collectionstring
contract_addressstring
creator_avatarobject
creator_nameobject
descriptionstring
imagestring
metadataobject
namestring
propertiesarray
child attributes
namestring
valuestring
tagsarray
token_idstring
Was this section helpful?

Why you find this section not helpful?

1

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. 


Was this section helpful?

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

Content-Typestring
Authorizationstring
Versify-Accountstring

QUERY PARAMETERS

page_numstring
page_sizestring
statusstring
expandstring
Was this section helpful?

Why you find this section not helpful?

1

Webhooks

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


Was this section helpful?

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"
}


Was this section helpful?

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS
Expand all

enabled_eventsarray
urlstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring
Was this section helpful?

Why you find this section not helpful?

1

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

Content-Typestring
Authorizationstring
Versify-Accountstring

BODY PARAMETERS
Expand all

enabled_eventsarray
urlstring
Was this section helpful?

Why you find this section not helpful?

1

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.


HEADER PARAMETERS

Content-Typestring
Authorizationstring
Versify-Accountstring
Was this section helpful?

Why you find this section not helpful?

1