Back to top

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

Campaigns
GET/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

GET https://api-v1.izea.com/unity/campaigns
Response  200
HideShow
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

Metrics
GET/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

GET https://api-v1.izea.com/unity/metrics?campaignid=6&page=1
URI Parameters
HideShow
campaignid
string (required) Example: 6

The ID of the campaign to retrieve metrics for.

page
number (optional) Example: 1

The page of offers to retrieve. 1 if not specified.

Response  200
HideShow
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 Groups
GET/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

GET https://api-v1.izea.com/content/groups?filterType=campaign&page=1
URI Parameters
HideShow
filterType
string (optional) Example: campaign

Which type of groups to return. If not provided all content groups will be returned.

Choices: campaign platform custom

page
number (optional) Default: 1 Example: 1

The page of content groups to return. If not specified, defaults to the first page

Response  200
HideShow
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 Assets
GET/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

GET https://api-v1.izea.com/content/groups/assets?groupid=6001&page=1
URI Parameters
HideShow
groupid
string (required) Example: 6001

ID of Content Group

page
number (optional) Default: 1 Example: 1

The page of the Content Group’s Assets to return. If not specified, defaults to the first page

Response  200
HideShow
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 Group Asset

Content Group Asset
GET/content/groups/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

GET https://api-v1.izea.com/content/groups/asset?assetid=6001
URI Parameters
HideShow
assetid
string (required) Example: 6001
Response  200
HideShow
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

Campaigns
GET/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

GET https://api-v1.izea.com/campaigns
Response  200
HideShow
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

Metrics
GET/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

Facebook

  • comments
    • likes
    • shares
    • views

Instagram

  • comments
    • likes
    • views

Twitter

  • likes
    • replies
    • retweets

YouTube

  • comments
    • likes
    • views

Example URI

GET https://api-v1.izea.com/metrics?campaignid=6&page=1
URI Parameters
HideShow
campaignid
string (required) Example: 6

The ID of the campaign to retrieve metrics for.

page
number (optional) Example: 1

The page of offers to retrieve. 1 if not specified.

Response  200
HideShow
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

Creator
GET/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

GET https://api-v1.izea.com/creator?creatorid=102030
URI Parameters
HideShow
creatorid
string (required) Example: 102030

ID of the Creator

Response  200
HideShow
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

Creators
GET/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

GET https://api-v1.izea.com/creators
Response  200
HideShow
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"
    }
  }
}

Generated by aglio on 04 Dec 2019