> For the complete documentation index, see [llms.txt](https://docs.parameter1.com/native-x-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parameter1.com/native-x-api/querying-data/an-outline-of-types.md).

# An Outline of Types

Outlining types of data returned from the NativeX API

### Introduction

In order to best outline the returned results of a given query this will outline the shape of various data types returned via the API as well as cover the `Connection` approach to returning data via GraphQL.

### What is a connection?

Return types ending in `Connection` will return data in a format akin to the following:

```
{
  "data": {
    "totalCount": A_NUMBER,
    "edges": [
      {
        "node": {
        Various Returned Data For Type "Connected To" Goes Here...
        }
      }...
    ],  
    "pageInfo": {
      "hasNextPage": true/false,
      "endCursor": CURSOR_STRING_VALUE    
  },
}
```

This means for a given Connection, provided the same query with "next" cursors for their respective connection this will allow for pagination of a given "fragment" of data for the query. This is important to be able to query for say all Campaigns from the same Advertiser or all Creatives for a given Campaign as necessary.

{% hint style="info" %}
Note: Most of these connections default to return the first 25 most recently created items for their given connection, for how this can be adjusted take a look at the [Queries](/native-x-api/querying-data/queries.md) section.
{% endhint %}

### Type Overview

Next we'll take a look at various data types and their respective shapes to outline what is being returned and where.

#### Advertiser

Advertisers can have Campaigns (and by extension Creatives) and Stories. Here is the information that can be returned for an Advertiser:

* `id` - The ID for the Advertiser (used for queries that require an Advertiser ID)
* `hash` - The hash for the Advertiser (used for queries that require an Advertiser Hash)
* `name` - The name of the Advertiser
* `logo` - Includes `id`, `src`, `filename`, `size`, `width` and `height` subfields
* `website` - The advertiser's website
* `externalId` - An external ID for the advertiser should one be available
* `deleted` - Whether or not the Advertiser has been marked as deleted
* `createdAt` - A UNIX timestamp when the Advertiser was added to NativeX
* `updatedAt` - A UNIX timestamp when the Advertiser was last updated in NativeX
* `campaigns` - A list of campaigns for the given Advertiser using the `CampaignConnection` type, see [Campaign](#campaign) for more detail as to what is returned regarding campaigns
* `stories` - A list of stories for the given Advertiser using the `StoryConnection` type, see [Story](#story) for more detail as to what is returned regarding stories.

#### Campaign

Campaigns contain information regarding where and how advertising items are suppose to appear on site and within e-mail as well as various metrics regarding performance. Here is the information that can be returned for a Campaign:

* `id` - The ID for the Campaign (used for queries that require a Campaign ID)
* `hash` - The hash for the Campaign (used for queries that require a Campaign Hash)
* `name` - The name of the Campaign
* `description` - A description for the Campaign
* `createdAt` - A UNIX timestamp for when the Campaign was created within NativeX
* `updatedAt` - A UNIX timestamp for when the Campaign was updated within NativeX
* `advertiser` - The Advertiser for the associated Campaign. See [Advertiser](#advertiser) for more detail as to what is returned regarding advertisers.
* `story` - The Story for the associated Campaign. See [Story](#story) for more detail as to what is returned regarding stories.
* `status` - Returns one of the following `Deleted, Incomplete, Finished, Paused, Running, Scheduled`
* `requires` - Returns a string noting what the Campaign still needs before it is able to run
* `deleted` - Whether or not the campaign has been deleted
* `paused` - Whether or not the campaign has been paused
* `requiredCreatives` - Returns the number of creatives required by the Campaign
* `publishers` - A list of publishers for the given campaign using the `PublisherConnection` type, see [Publisher](#publisher) for more detail as to what is returned regarding publishers.
* `emailLineItems` - A list of email line items for the given campaign using the `EmailLineItemConnection` type, see [Email Line Item](#undefined) for more detail as to what is returned regarding email line items.
* `url` - The URL that is linked to for items in the campaign.
* `primaryImage` - Includes `id`, `src`, `filename`, `size`, `width` and `height` subfields (this typically returns the image associated with the first creative for a campaign) (Needs clarification)
* `creatives` - A list of creatives for the given campaign see[ Campaign Creative ](#campaign-creative)for more detail as to what is returned regarding creatives.
* `criteria` - Includes subfields of `start` and `end` (UNIX timestamps for start and end of Campaign) as well as a list of placements (as the placements subfield), see [Placement](#placement) for more detail as to what is returned regarding placements.
* `externalLinks` - A list of external links including the label as well as url on each link.
* `metrics` - Includes subfields of `views`, `clicks` and `ctr` (all numbers) regarding Campaign performance.
* `reports` - Includes a `byDay` subfield which requires input of `startDate` and `endDate` (both of which are UNIX timestamps) which then includes an additional subfields of `day` which requires input of `format` ("MMMM Do YYYY" should work and will provide a date in the format August 5th 1999) and `metrics` which returns the same information as the Campaign `metrics` field albeit for the individual day of the Campaign instead of the entire Campaign.

#### Campaign Creative

* `id` - The id for the Campaign Creative (used for queries that require a Campaign Creative ID)
* `title` - The title for the Campaign Creative
* `teaser` - The teaser for the Campaign Creative
* `linkText` - The text that appears for the link associated with the Campaign Creative (ex: Click here to download!)
* `active` - Whether or not the Campaign Creative is active
* `image` - Includes `id`, `src`, `filename`, `size`, `width` and `height` subfields
* `metrics` - See `Campaign.metrics` for fields and data provided, this applies to the returned creative(s) as appropriate
* `reports` - See `Campaign.reports` for fields and data provided, this applies to the returned creative(s) as appropriate

#### Placement

* `id` - The id for the Placement (used for queries that require a Placement ID)
* `name` - The name of the placement
* `publisher` - The publisher associated with the placement see [Publisher](#publisher) for more detail as to what is returned regarding publishers.
* `topic` - The topic associated with the placement includes subfields for `id`, `name`, `publisher`, `placements` and `externalId`
* `reservePct` - The percentage of impressions that are reserved for content, rather than ads.
* `createdAt` - A UNIX timestamp for when the Placement was created within NativeX
* `updatedAt` - A UNIX timestamp for when the Placement was updated within NativeX
* `metrics` - Contains the same fields as `Campaign.metrics` but additionally requires input of `start` and `end` as UNIX timestamps in order to determine the window to examine metrics for

#### Publisher

Publishers end up being the root of NativeX as publishers contain the placement information for NativeX advertisements for both email and website products. Here is the information that can be returned for a Publisher:

* `id` - The id for the Publisher (used for queries that require a Publisher ID)
* `name` - The name of the Publisher
* `domainName` - If configured the custom domain to serve NativeX Story content on
* `storyPath` - If configured the custom path on the publisher website to serve NativeX story content on
* `website` - The publisher website
* `logo` See `Advertiser.logo`
* `topics` See `Placement.topic` the difference here is this is done via the `TopicConnection` type
* `placements` A list of placements for the publisher on their respective website using the `PlacementConnection` type, see [Placement](#placement) for more detail regarding what is returned regarding placements
* `campaigns` - A list of campaigns for the publisher on their respective website using the  `CampaignConnection` type, see [Campaign](#campaign) for more detail regarding what is returned regarding campaigns
* `emailDeployments` - A list of email deployments for the publisher on their respective products using the `EmailDeploymentConnection` type, see [Email Deployment](#email-deployment) for more detail regarding what is returned regarding email deployments
* `emailPlacements` - A list of email placements for the publisher on their respective products using the `EmailPlacementsConnection` type, see [Email Placement](#undefined) for more detail regarding what is returned regarding email placements
* `createdAt` - A UNIX timestamp for when the Publisher was created within NativeX
* `updatedAt` - A UNIX timestamp for when the Publisher was updated within NativeX
* `metrics` - See `Placement.metrics` except this applies for the publisher as a whole over individual placements

#### Story

NativeX Stories operate as a full page extension of the NativeX advertising platform allowing for additional engagement opportunities. Here is the information that be returned for a Story:

* `id` - The id for the Story (used for queries that require a Story ID)
* `hash` - The hash for the Story (used for queries that require a Story Hash)
* `title` - The title of the Story
* `slug` - A human readable identifier for the story that is a part of the stories website path
* `advertiser` - The advertiser associated with the Story, see [Advertiser](#advertiser) for more detail regarding what is returned regarding advertisers.
* `publisher` - The publisher associated with the Story, see [Publisher](#publisher) for more detail regarding what is returned regarding publishers.
* `teaser` - The teaser for the Story
* `body` - The body copy of the Story
* `path` - The path to the Story on the website it displays on
* `status` - Options are `Deleted`, `Placeholder`, `Published`, `Scheduled` or `Draft`
* `placeholder` - Whether or not the Story is a placeholder
* `deleted` - Whether or not the story is deleted
* `publishedAt` - A UNIX timestamp for when the Story was published
* `primaryImage` - Includes id, src, filename, size, width and height subfields
* `images` - A list of images including the same information as `primaryImage`
* `previewUrl` - The URL the story can be previewed on, helpful for when a Story is not yet published
* `url` - The URL the story can be viewed on when published
* `campaigns` - A list of campaigns for the given Story using the `CampaignConnection` type, see [Campaign](#campaign) for more detail as to what is returned regarding campaigns
* `createdAt` - A UNIX timestamp for when the Story was created within NativeX
* `updatedAt` - A UNIX timestamp for when the Story was updated within NativeX
* `metrics` - Includes `pageviews`, `uniquePageviews`, `sessions`, `users`, `avgSessionDuration`, `bounceRate`, `timeOnPage`, `avgTimeOnPage` and `shares` subfields all of which are numbers of some kind (integer or decimal) 
* `reports` - Includes:\
  \
  A`byDay` subfield which requires input of `startDate` and `endDate` (both of which are UNIX timestamps) which then includes an additional subfields of `day` which requires input of `format` ("MM-DD-YYYY" should work (CONFIRM THIS)) and `metrics` which returns the same information as the Story `metrics` field albeit for the individual day of the Story's run instead of the entire Story's run. \
  \
  An `acquisition` subfield containing a list of publication channels (`channelGrouping`) and their respective metrics (`metrics)` using the same format as the Story `metrics` field albeit for the individual channel the Story ran in. \
  \
  Lastly this includes a `devices` subfield containing a list of the `deviceCategory` and `metrics` much like the other metrics but for a given device category.

### Email Specific Type Overview

As NativeX allows for advertising on both email and website products there are some additional return types that are exclusive to email.

#### Email Deployment

* `id` - The Email Deployment ID (used for queries that require an Email Deployment ID)
* `name` - The name of the Email Deployment
* `fullName` - The full name of the Email Deployment (typically includes some sort of prefix or suffix relative to the name field)
* `publisher` - The publisher of the Email Deployment, see [Publisher](#publisher) for more detail regarding what is returned regarding publishers.
* `placements` - See `Publisher.emailPlacements` albeit this is limited to placements for the returned deployment
* `createdAt` - A UNIX timestamp for when the Email Deployment was created within NativeX
* `updatedAt` - A UNIX timestamp for when the Email Deployment was updated within NativeX

#### Email Line Item

* `id` - The Email Line Item ID (used for queries that require an Email Line Item ID)
* `name` - The name of the Email Line Item
* `campaign` - The campaign the Email Line Item is a part of, see [Campaign](#campaign) for more detail regarding what is returned regarding campaigns
* `placement` - The placement the Email Line Item is placed at, see Email Placement for more detail regarding what is returned regarding email placements
* `dates` - Includes `start`, `end` and `days` subfields, the first two of which are UNIX timestamps and the last of which is a list of UNIX timestamps that indicate the days by which the line item ran
* `status` - See `Campaign.status` for values
* `requires` - See `Campaign.requires` this operates similarly but for Email Line Items
* `paused` - Whether or not the Email Line Item is paused
* `ready` - Whether or not the Email Line Item is ready to be served
* `deleted` - Whether or not the Email Line Item is deleted
* `createdAt` - A UNIX timestamp for when the Email Line Item was created within NativeX
* `updatedAt` - A UNIX timestamp for when the Email Line Item was updated within NativeX

#### Email Placement

* `id` - The Email Placement ID (used for queries that require an Email Placement ID)
* `name` - The name of the Email Placement
* `fullName` - The full name of the Email Placement (usually including some sort of prefix or suffix relative to name)
* `emailDeployment` - The email deployment the Email Placement is associated with, see [Email Deployment](#email-deployment) for more detail regarding what is returned regarding email deployments
* `createdAt` - A UNIX timestamp for when the Email Placement was created within NativeX
* `updatedAt` - A UNIX timestamp for when the Email Placement was updated within NativeX