IZEAx V1 API
The IZEAx API allows you to connect to your IZEAx Campaign data and content, as well as Creator data programmatically. Using this API you can enumerate your Campaigns and then retrieve information and metrics about the Offers in each one. You can use this API to understand cummulatice Creator performance across all your campaigns, and display Creator profiles in your own applications. Additionally, you can use the API to access your Content Groups and Assets managed by IZEAx’s ContentMine feature.
Authentication
In order to successfully call the IZEAx API you will need an Authentication Token. You can retrieve your Authentication
Token in the API Keys tab of your IZEAx Account Settings.
This token must be passed in an Authentication
header of your request as shown below:
Authorization: Bearer: <token>
NOTE: We may need to enable the API Token tab for your account. Please reach out to your account representatives for access.
IMPORTANT: Your API Token is tied to your User and can access information for any Account that you can. Treat it like a password!
Authorization
Requests to the API are scoped to an Account so you must pass the ID of the Account that you want to access with your
API requests. Your Account ID can be found on the API Keys tab of your IZEAx Account Settings.
The Account ID should be sent with the X-IZEA-Account-ID
header as shown below:
X-IZEA-Account-ID: <accountid>
Unity Campaigns ¶
These endpoints allow you to access campaign data for your Unity Campaigns. Using these endpoints, you can build applications that sync campaign performance data to your own systems and tools.
Campaigns ¶
CampaignsGET/unity/campaigns
Use this request to enumerate and retrieve information about all of your Unity Campaigns in IZEAx. In order to call the
/unity/metrics
endpoint, you must have a campaign ID, so use this endpoint to start.
Each campaign object in the response will also contain a content_group_id
which can be used with the /content/groups
endpoint to find all content associated with the campaign.
Example URI
200
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "6",
"campaign_type": "'sponsorship' or 'unity'",
"name": "My Campaign",
"content_group_id": "virtual-campaign-6"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"data": {
"type": "array"
}
}
}
Metrics ¶
MetricsGET/unity/metrics{?campaignid,page}
Once you have an ID for your Unity Campaign, you can use this endpoint to retrieve a paginated set of Units for the Campaign. Each Unit will come with the last 30 days of metrics.
This endpoint is paginated with a page size of 10. If your campaign has more Units than that, a link to the next page will be provided in the response.
The creator_id
field in the returned data can be used against the /creator
endpoint
to get information about who produced the asset.
Example URI
- campaignid
string
(required) Example: 6The ID of the campaign to retrieve metrics for.
- page
number
(optional) Example: 1The page of offers to retrieve. 1 if not specified.
200
Body
{
"data": {
"units": [
{
"id": "10000",
"creator_id": "102030",
"published_at": "2018-01-01T02:45:90.000-05:00",
"unit_type": "Instagram Story Frame",
"all_time_metrics": [
{
"engagements": 100,
"followers": 100,
"comments": 2,
"likes": 312,
"clicks": 8376,
"shares": 12,
"views": 234
}
],
"metrics": [
{
"metric_on": "2018-01-01T02:45:90.000-05:00",
"comments": 2,
"likes": 312,
"clicks": 8376,
"reach": 10000,
"shares": 12,
"views": 234
}
]
}
]
},
"links": {
"_next": "url of next page",
"_prev": "url of previous page"
}
}
Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"units": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"creator_id": {
"type": "string"
},
"published_at": {
"type": "string"
},
"unit_type": {
"type": "string"
},
"all_time_metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"engagements": {
"type": "number"
},
"followers": {
"type": "number"
},
"comments": {
"type": "number"
},
"likes": {
"type": "number"
},
"clicks": {
"type": "number"
},
"shares": {
"type": "number"
},
"views": {
"type": "number"
}
}
}
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"metric_on": {
"type": "string"
},
"comments": {
"type": "number"
},
"likes": {
"type": "number"
},
"clicks": {
"type": "number"
},
"reach": {
"type": "number"
},
"shares": {
"type": "number"
},
"views": {
"type": "number"
}
}
}
}
}
}
}
}
},
"links": {
"type": "object",
"properties": {
"_next": {
"type": "string"
},
"_prev": {
"type": "string"
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
ContentMine ¶
These endpoints allow you to programmatically access the content was produced through the execution of your Campaigns (Unity and Legacy) as well as content that may have been manually uploaded into ContentMine.
Content Groups ¶
Content GroupsGET/content/groups{?filterType,page}
All content in ContentMine is organized into a set of Content Groups. This endpoint returns a paginated set of all Content Groups available to you based on the provided query parameters and Authorization and Authentication headers.
There are three different types of Content Groups in ContentMine. Campaign Groups get created automatically as part of the process of executing a Unity Campaign. Platform Groups aggregate content across campaign’s by their publishing location (e.g. Instagram), and Custom Groups are created by users in the ContentMine interface.
You access the id of a Content Group associated with a particular campaign, by querying the /unity/campaigns
or /campaigns
endpoint.
Example URI
- filterType
string
(optional) Example: campaignWhich type of groups to return. If not provided all content groups will be returned.
Choices:
campaign
platform
custom
- page
number
(optional) Default: 1 Example: 1The page of content groups to return. If not specified, defaults to the first page
200
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "60",
"name": "My upload",
"asset_count": 2,
"cover_image_url": "https://d2w079/exam.jpg",
"cover_asset_id": "227954"
}
],
"links": {
"_next": "url of next page",
"_prev": "url of previous page"
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"data": {
"type": "array"
},
"links": {
"type": "object",
"properties": {
"_next": {
"type": "string"
},
"_prev": {
"type": "string"
}
}
}
}
}
Content Group Assets ¶
Content Group AssetsGET/content/groups/assets{?groupid,page}
Once you have a Content Group ID, you can use this endpoint to returns a paginated set of abbreviated information about the assets in the specified group.
The creator_id
field returned for each object can be used against the /creator
endpoint
to get information about the Creator that produced the asset.
Example URI
- groupid
string
(required) Example: 6001ID of Content Group
- page
number
(optional) Default: 1 Example: 1The page of the Content Group’s Assets to return. If not specified, defaults to the first page
200
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "60",
"creator_id": "CreatorId",
"creator_name": "CreatorName",
"thumbnail_url": "https://d2w079/exam.jpg",
"published_platform": "Platform",
"cover_asset_id": "227954"
}
],
"links": {
"_next": "url of next page",
"_prev": "url of previous page"
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"data": {
"type": "array"
},
"links": {
"type": "object",
"properties": {
"_next": {
"type": "string"
},
"_prev": {
"type": "string"
}
}
}
}
}
Content Asset ¶
Content AssetGET/content/asset{?assetid}
This endpoint returns detailed information about a specific Asset including, if it exists, a URL to the asset that can be used to download the asset.
The creator_id
field in the returned data can be used against the /creator
endpoint
to get information about who produced the asset.
NOTE: When downloading the Asset, please respect license
field of the Asset. Your usage of this content is subject to
same terms and conditions as the IZEA platform, and your agreements in place with the creator of the Asset.
NOTE: Download links will expire! If you are attempting to download this content programmatically, you should do so as soon as possible after receiving that link.
Example URI
- assetid
string
(required) Example: 6001
200
Headers
Content-Type: application/json
Body
{
"data": {
"id": "60",
"creator_id": "CreatorId",
"creator_name": "CreatorName",
"file_name": "FileName",
"license": "Licence",
"download_url": "https://app.izea.com/asset/download/imageuploaded.jpg",
"thumbnail_url": "https://d2w079/exam.jpg",
"tag_list": [
"[\"figurine\"",
"\"art\"",
"\"porcelain\"]"
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"creator_id": {
"type": "string"
},
"creator_name": {
"type": "string"
},
"file_name": {
"type": "string"
},
"license": {
"type": "string"
},
"download_url": {
"type": "string"
},
"thumbnail_url": {
"type": "string"
},
"tag_list": {
"type": "array"
}
}
}
}
}
Legacy Campaigns ¶
These endpoints allow you to access campaign data for your Legacy Campaigns. Using these endpoints, you can build applications that sync campaign performance data to your own systems and tools.
Campaigns ¶
CampaignsGET/campaigns
Use this request to enumerate and retrieve information about all of your Legacy Campaigns in IZEAx. In order to call the
/metrics
endpoint, you must have a campaign ID, so use this endpoint to start.
Each campaign object in the response will also contain a content_group_id
which can be used with the /content/groups
endpoint to find all content associated with the campaign.
Example URI
200
Headers
Content-Type: application/json
Body
{
"data": [
{
"id": "6",
"campaign_type": "'sponsorship' or 'unity'",
"name": "My Campaign",
"content_group_id": "virtual-campaign-6"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"data": {
"type": "array"
}
}
}
Metrics ¶
MetricsGET/metrics{?campaignid,page}
Once you have an ID for your Legacy Campaign, you can use this endpoint to retrieve a paginated set of Offers for the Campaign. Each Offer will come with the last 30 days of metrics.
This endpoint is paginated with a page size of 10. If your campaign has more Offers than that, a link to the next page will be provided in the response.
The platform_data
field in the response will vary depending on what platform the Offer was published on. Supported values are as follows:
Blogs
- comments
- comments
- likes
- shares
- views
- comments
- likes
- views
- likes
- replies
- retweets
YouTube
- comments
- likes
- views
Example URI
- campaignid
string
(required) Example: 6The ID of the campaign to retrieve metrics for.
- page
number
(optional) Example: 1The page of offers to retrieve. 1 if not specified.
200
Body
{
"data": {
"offers": [
{
"id": "10000",
"published_at": "2018-01-01T02:45:90.000-05:00",
"published_url": "http://twitter.com/izea/",
"reach_when_published": 3000,
"connection_name": "@izea",
"platform": "twitter",
"connection_url": "http://twitter.com/izea",
"metrics": [
{
"metric_on": "2018-01-01",
"platform_data": {
"comments": 2,
"likes": 312,
"loops": 77,
"reblogs": 436,
"shares": 12,
"replies": 8,
"retweets": 1,
"views": 234
},
"total_clicks_to_date": 76,
"total_views_to_date": 400
}
]
}
]
},
"links": {
"_next": "url of next page",
"_prev": "url of previous page"
}
}
Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"offers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"published_at": {
"type": "string"
},
"published_url": {
"type": "string"
},
"reach_when_published": {
"type": "number"
},
"connection_name": {
"type": "string"
},
"platform": {
"type": "string"
},
"connection_url": {
"type": "string"
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"metric_on": {
"type": "string"
},
"platform_data": {
"type": "object",
"properties": {
"comments": {
"type": "number"
},
"likes": {
"type": "number"
},
"loops": {
"type": "number"
},
"reblogs": {
"type": "number"
},
"shares": {
"type": "number"
},
"replies": {
"type": "number"
},
"retweets": {
"type": "number"
},
"views": {
"type": "number"
}
}
},
"total_clicks_to_date": {
"type": "number"
},
"total_views_to_date": {
"type": "number"
}
}
}
}
}
}
}
}
},
"links": {
"type": "object",
"properties": {
"_next": {
"type": "string"
},
"_prev": {
"type": "string"
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
Creators ¶
These endpoints allow you to access performance metrics for Creators across all of your Account’s Campaigns. Using these endpoints you can develop insight into your best performing Creators for inclusion on your next Campaign. You can also access basic profile information for a single Creator to build your own profiles views.
Creator ¶
CreatorGET/creator{?creatorid}
Once you have a Creator ID from using one of the other endpoints in the API, use this request to retrieve profile information and context about that Creator.
Example URI
- creatorid
string
(required) Example: 102030ID of the Creator
200
Headers
Content-Type: application/json
Body
{
"data": {
"avatar": "https://some.url.com",
"name": "Ms. Creator",
"bio": "This is all about me!",
"connections": [
{
"type": "FacebookProperty",
"avatar": "https://some.url.com",
"followers": 1000
}
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"avatar": {
"type": "string"
},
"name": {
"type": "string"
},
"bio": {
"type": "string"
},
"connections": {
"type": "array"
}
}
}
}
}
Creators ¶
CreatorsGET/creators
Use this request to retrieve performance information, aggregated across all Campaigns, for Creators that you have activated
through your Account. You can use the /creator
endpoint to get additional context about a
Creator.
Example URI
200
Headers
Content-Type: application/json
Body
{
"data": [
{
"creator_id": "102030",
"clicks": 345,
"comments": 2,
"engagement_rate": 3.5,
"engagements": 234,
"likes": 641,
"reach": 20012,
"shares": 454,
"views": 21341
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"data": {
"type": "array"
}
}
}