Back to top

IZEAx V1 API

The IZEAx API allows you to connect to your IZEAx Campaign data and content programmatically. Using this API you can enumerate your Campaigns and then retrieve information and metrics about the Offers in each one. 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.

NOTE: 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 a given 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.

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

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.

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

Generated by aglio on 18 Sep 2019