Promotional Properties API Reference

Endpoint: https://accounts.api.cj.com/graphql

The Promotional Properties API is a GraphQL API used to view and manage promotional properties (PIDs).

Publisher vs. Advertiser Access

This API serves both publishers and advertisers, but the level of access differs:

Operation	Publisher	Advertiser
Query promotional properties	✓	✓
Create promotional properties	✓	—
Update promotional properties	✓	—

Publishers have full read and write access. They can query their own promotional properties and use mutations to create or update them. This is useful for publishers with a high number of PIDs that require automation to manage. Publishers with a small number of PIDs are encouraged to manage them manually using the PID management interface.

Advertisers have read-only access. They can query publishers' promotional properties to see where their publishers are posting links or to assess a publisher's promotional method. Mutations are not available to advertisers.

Code Samples

Sample Query

{
  promotionalProperties(publisherId: 99999, status: ACTIVE, limit: 2, offset: 0) {
    totalCount
    resultList {
      id
      publisherId
      name
      description
      status
      isPrimary
      createdAt
      updatedAt
      tags {
        name
      }
      promotionalModels {
        type
        description
        isPrimary
      }
      propertyTypeDetails {
        type
        ... on PromotionalPropertyWebsiteDetails {
          websiteUrl
        }
        ... on PromotionalPropertyBrowserExtensionDetails {
          browserExtensionName
          browserExtensionDescription
          browserExtensionDownloadInformation {
            browserExtensionBrowser
            browserExtensionDownloadLink
          }
        }
        ... on PromotionalPropertyEmailDetails {
          emailAddress
          emailOpenRate
          emailMailingListSize
        }
        ... on PromotionalPropertyMobileAppDetails {
          mobileAppName
          mobileAppDownloadInformation {
            mobileAppPlatform
            mobileAppDownloadLink
          }
        }
        ... on PromotionalPropertyPaidSearchDetails {
          paidSearchEngineDescription
        }
        ... on PromotionalPropertySocialMediaDetails {
          socialMediaHandle
          socialMediaPlatform
        }
        ... on PromotionalPropertyPaidDisplayAdsDetails {
          paidDisplayAdsDescription
        }
        ... on PromotionalPropertyServicesAndToolsDetails {
          servicesAndToolsMarketingSiteUrl
        }
        ... on PromotionalPropertyOtherDetails {
          otherDescription
        }
      }
    }
  }
}

Sample curl Request

curl -H "Authorization: Bearer <your-personal-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{promotionalProperties(publisherId: 99999, status: ACTIVE, limit: 2, offset: 0) {totalCount resultList {id publisherId name description status isPrimary createdAt updatedAt tags {name} promotionalModels {type description isPrimary} propertyTypeDetails {type ... on PromotionalPropertyWebsiteDetails {websiteUrl} ... on PromotionalPropertyBrowserExtensionDetails {browserExtensionName browserExtensionDescription browserExtensionDownloadInformation {browserExtensionBrowser browserExtensionDownloadLink}} ... on PromotionalPropertyEmailDetails {emailAddress emailOpenRate emailMailingListSize} ... on PromotionalPropertyMobileAppDetails {mobileAppName mobileAppDownloadInformation {mobileAppPlatform mobileAppDownloadLink}} ... on PromotionalPropertyPaidSearchDetails {paidSearchEngineDescription} ... on PromotionalPropertySocialMediaDetails {socialMediaHandle socialMediaPlatform} ... on PromotionalPropertyPaidDisplayAdsDetails {paidDisplayAdsDescription} ... on PromotionalPropertyServicesAndToolsDetails {servicesAndToolsMarketingSiteUrl} ... on PromotionalPropertyOtherDetails {otherDescription}}}}}"}' \
  -XPOST https://accounts.api.cj.com/graphql

Sample Response

{
  "data": {
    "promotionalProperties": {
      "totalCount": 97,
      "resultList": [
        {
          "id": "100",
          "publisherId": "99999",
          "name": "sample property name",
          "description": "sample property description",
          "status": "ACTIVE",
          "isPrimary": true,
          "createdAt": "2020-07-09T18:47:50.430Z",
          "updatedAt": "2020-07-21T00:26:59.501Z",
          "tags": [
            { "name": "tag2" },
            { "name": "tag1" }
          ],
          "promotionalModels": [
            { "type": "COUPON_DEAL", "description": null, "isPrimary": false },
            { "type": "CONTENT_BLOG_MEDIA", "description": null, "isPrimary": true }
          ],
          "propertyTypeDetails": {
            "type": "WEBSITE",
            "websiteUrl": "https://cj.com"
          }
        },
        {
          "id": "101",
          "publisherId": "99999",
          "name": "sample instagram property",
          "description": "",
          "status": "ACTIVE",
          "isPrimary": false,
          "createdAt": "2020-07-09T20:59:15.097Z",
          "updatedAt": "2020-07-21T00:28:30.248Z",
          "tags": [],
          "promotionalModels": [
            { "type": "INFLUENCER", "description": null, "isPrimary": true }
          ],
          "propertyTypeDetails": {
            "type": "SOCIAL_MEDIA",
            "socialMediaHandle": "@sample-property",
            "socialMediaPlatform": "INSTAGRAM"
          }
        }
      ]
    }
  }
}

Sample Mutation — Create a New Promotional Property

Publishers only. Advertisers do not have access to mutations.

mutation {
  createPromotionalProperty(
    input: {
      name: "test website"
      description: "test description."
      publisherId: 99999
      propertyTypeDetails: {
        type: WEBSITE
        websiteUrl: "https://cj.com"
      }
      isPrimary: false
      status: ACTIVE
      promotionalModels: [
        { type: CONTENT_BLOG_MEDIA, isPrimary: false }
        { type: COUPON_DEAL, isPrimary: true }
      ]
      tags: [{ name: "myTag" }, { name: "mySecondTag" }]
    }
  ) {
    id
  }
}

Sample curl Request

curl -H "Authorization: Bearer <your-personal-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"operationName":null,"variables":{},"query":"mutation {createPromotionalProperty(input: {name: \"test website\", description: \"test description\", publisherId: 99999, propertyTypeDetails: {type: WEBSITE, websiteUrl: \"https://cj.com\"}, isPrimary: false, status: ACTIVE, promotionalModels: [{type: CONTENT_BLOG_MEDIA, isPrimary: false}, {type: COUPON_DEAL, isPrimary: true}], tags: [{name: \"myTag\"}, {name: \"mySecondTag\"}]}) {id}}"}' \
  -XPOST https://accounts.api.cj.com/graphql

Sample Response

{
  "data": {
    "createPromotionalProperty": {
      "id": "103"
    }
  }
}

Sample Mutation — Update an Existing Promotional Property

Publishers only. Advertisers do not have access to mutations.

mutation {
  updatePromotionalProperty(
    input: {
      id: 103
      name: "updated name"
      description: "updated description"
      publisherId: 99999
      status: ACTIVE
      isPrimary: false
      tags: [{ name: "tag 1" }]
      promotionalModels: [
        { type: INFLUENCER, isPrimary: true }
        { type: CONTENT_BLOG_MEDIA, isPrimary: false }
      ]
      propertyTypeDetails: {
        type: SOCIAL_MEDIA
        socialMediaHandle: "@sampleSocialHandle"
        socialMediaPlatform: INSTAGRAM
      }
    }
  ) {
    id
    name
  }
}

Sample Response

{
  "data": {
    "updatePromotionalProperty": {
      "id": "103",
      "name": "updated name"
    }
  }
}

Errors

Error	Example	Cause	Fix
Invalid authorization token	`"message": "Invalid authorization token"`	The provided auth token is not valid.	Provide a valid Personal Access Token.
Missing subfields	`"Field \"propertyType\" of type \"PropertyType!\" must have a selection of subfields."`	Required subfields for a field were not included in the query.	Query all required subfields.
Parse error	`"Cannot query field \"propertyTyipe\" on type \"PromotionalProperty\"."`	An invalid or misspelled field was included in the query.	Check spelling and validity of all queried fields.

Objects

PromotionalProperty

A single promotional property (PID) belonging to a publisher.

Field	Type	Description
`createdAt`	`ISODateTime`	Timestamp of when the promotional property was created.
`description`	`String`	A text description of the promotional property.
`id`	`ID!`	The promotional property ID.
`isPrimary`	`Boolean!`	Indicates whether this is the primary promotional property for this CID.
`name`	`String!`	Name of the promotional property.
`promotionalModels`	`[PromotionalModel!]!`	Promotional models associated with this property.
`propertyTypeDetails`	`PromotionalPropertyTypeDetails!`	Type-specific details for this property. Uses inline fragments — see Property Type Details.
`publisherId`	`ID!`	The publisher's CID.
`status`	`PromotionalPropertyStatus!`	Current status of the property.
`tags`	`[PromotionalPropertyTag!]!`	Tags added to this property.
`updatedAt`	`ISODateTime`	Timestamp of when the property was last edited.

PromotionalProperties

Wrapper object returned by the promotionalProperties query.

Field	Type	Description
`resultList`	`[PromotionalProperty!]!`	List of promotional properties matching the query.
`totalCount`	`Int!`	Total count of promotional properties matching the query, regardless of `limit`.

PromotionalModel

Describes the promotional model associated with a promotional property.

Field	Type	Description
`description`	`String`	Text description of the promotional model. Only applicable for `OTHER` type properties.
`isPrimary`	`Boolean!`	Indicates whether this is the primary promotional model for the property. Used primarily for reporting.
`type`	`PromotionalModelType!`	The kind of promotional model. See `PromotionalModelType` enum.

PromotionalPropertyTag

An optional tag added to a promotional property. Tags can be keywords, categories, or other descriptors — they are searchable and visible to advertisers.

Field	Type	Description
`name`	`String!`	The tag value.

DistinctPropertyValues

Returns the unique promotional models and property types in use across a publisher's properties.

Field	Type	Description
`promotionalModels`	`[String!]!`	List of all promotional models the publisher is using.
`propertyTypes`	`[String!]!`	List of all property types the publisher is using.

BrowserExtensionDownloadInformation

Browser extension type properties may have multiple supported browsers. Each entry represents one browser and its download link.

Field	Type	Description
`browserExtensionBrowser`	`BrowserType!`	The browser the extension runs on. See `BrowserType` enum.
`browserExtensionDownloadLink`	`String!`	The URL where end users can download the extension for that browser.

MobileAppDownloadInformation

Mobile app type properties may support multiple platforms. Each entry represents one platform and its download link.

Field	Type	Description
`mobileAppDownloadLink`	`String!`	The URL where end users can download the app for that platform.
`mobileAppPlatform`	`MobileAppPlatform!`	The platform the app is built for. See `MobileAppPlatform` enum.

Interface: `PromotionalPropertyTypeDetails`

All propertyTypeDetails objects implement this interface. Use inline fragments (... on TypeName) in your query to access type-specific fields. The type field is always present and identifies which concrete type was returned.

Implementations:

Type	`type` Value	Type-Specific Fields
`PromotionalPropertyWebsiteDetails`	`WEBSITE`	`websiteUrl`
`PromotionalPropertyBrowserExtensionDetails`	`BROWSER_EXTENSION`	`browserExtensionName`, `browserExtensionDescription`, `browserExtensionDownloadInformation`, `browserExtensionTrackingConsentType`
`PromotionalPropertyEmailDetails`	`EMAIL`	`emailAddress`, `emailOpenRate`, `emailMailingListSize`
`PromotionalPropertyMobileAppDetails`	`MOBILE_APP`	`mobileAppName`, `mobileAppDownloadInformation`
`PromotionalPropertyPaidSearchDetails`	`PAID_SEARCH_ENGINE`	`paidSearchEngineDescription`
`PromotionalPropertySocialMediaDetails`	`SOCIAL_MEDIA`	`socialMediaHandle`, `socialMediaPlatform`
`PromotionalPropertyPaidDisplayAdsDetails`	`PAID_DISPLAY_ADS`	`paidDisplayAdsDescription`
`PromotionalPropertyServicesAndToolsDetails`	`SERVICES_AND_TOOLS`	`servicesAndToolsMarketingSiteUrl`
`PromotionalPropertyOtherDetails`	`OTHER`	`otherDescription`

PromotionalPropertyWebsiteDetails

Field	Type	Description
`type`	`PromotionalPropertyType!`	Always `WEBSITE`.
`websiteUrl`	`String!`	The website URL.

PromotionalPropertyBrowserExtensionDetails

Field	Type	Description
`browserExtensionDescription`	`String`	Description of how the browser extension functions and how customers engage with it.
`browserExtensionDownloadInformation`	`[BrowserExtensionDownloadInformation!]!`	Download links and supported browsers.
`browserExtensionName`	`String!`	The name of the extension as it appears in the download store.
`browserExtensionTrackingConsentType`	`TrackingConsentType`	Indicates whether the extension operates on affirmative click only or automatic redirect with affirmative click on request.
`type`	`PromotionalPropertyType!`	Always `BROWSER_EXTENSION`.

PromotionalPropertyEmailDetails

Field	Type	Description
`emailAddress`	`String!`	The send-from address for the email newsletter campaign.
`emailMailingListSize`	`String!`	Approximate number of unique subscribers.
`emailOpenRate`	`String!`	Approximate open rate for email newsletters.
`type`	`PromotionalPropertyType!`	Always `EMAIL`.

PromotionalPropertyMobileAppDetails

Field	Type	Description
`mobileAppDownloadInformation`	`[MobileAppDownloadInformation!]!`	Download links and supported platforms.
`mobileAppName`	`String!`	The name of the app as it appears in the app store.
`type`	`PromotionalPropertyType!`	Always `MOBILE_APP`.

PromotionalPropertyPaidSearchDetails

Field	Type	Description
`paidSearchEngineDescription`	`String!`	The platforms where search ads are purchased and the click-through rates achieved.
`type`	`PromotionalPropertyType!`	Always `PAID_SEARCH_ENGINE`.

PromotionalPropertySocialMediaDetails

Field	Type	Description
`socialMediaHandle`	`String!`	The link or handle for the social media account.
`socialMediaPlatform`	`SocialPlatform!`	The social platform. See `SocialPlatform` enum.
`type`	`PromotionalPropertyType!`	Always `SOCIAL_MEDIA`.

PromotionalPropertyPaidDisplayAdsDetails

Field	Type	Description
`paidDisplayAdsDescription`	`String!`	The platforms where display ads are purchased and the click-through rates achieved.
`type`	`PromotionalPropertyType!`	Always `PAID_DISPLAY_ADS`.

PromotionalPropertyServicesAndToolsDetails

Field	Type	Description
`servicesAndToolsMarketingSiteUrl`	`String!`	Marketing site URL for the services and tools property.
`type`	`PromotionalPropertyType!`	Always `SERVICES_AND_TOOLS`.

PromotionalPropertyOtherDetails

Field	Type	Description
`otherDescription`	`String!`	A text description of the promotional property type.
`type`	`PromotionalPropertyType!`	Always `OTHER`.

Enums

BrowserType

Value
`CHROME`
`FIREFOX`
`SAFARI`
`OPERA`

MobileAppPlatform

Value
`IOS`
`ANDROID`

PromotionalModelType

Describes the kind of promotional model for a property. Each property may have more than one model, but one must be designated as primary.

Value	Description
`CONTENT_BLOG_MEDIA`	Customers read original content or articles about topics that interest them.
`COUPON_DEAL`	Customers come to discover coupons, vouchers, or discounts.
`LOYALTY_CASH_BACK`	Customers receive cash back as a percentage of their purchase.
`LOYALTY_NON_CASH_REWARDS`	Customers receive non-cash rewards such as points, airline miles, or charity donations.
`LOYALTY_CLOSED_USER_GROUP`	A membership service where customers must have an exclusive login to access benefits (e.g. employee benefits, credit card rewards, airline rewards malls).
`TRADEMARK_BIDDING`	Search engine ads are purchased by bidding on advertiser brand names; customers are directed to the publisher's own website.
`INFLUENCER`	Customers follow a personality or figure they are interested in.
`PAY_PER_CALL`	Call tracking is used to drive customer transactions over the telephone.
`PRODUCT_COMPARISON_REVIEWS_DISCOVERY`	Links to specific products that customers can browse, compare, or search for.
`OTHER`	None of the above — a brief description of the promotional method should be provided.

PromotionalPropertyStatus

Value
`ACTIVE`
`ARCHIVED`
`TERMINATED`

PromotionalPropertyType

Value
`WEBSITE`
`SOCIAL_MEDIA`
`EMAIL`
`MOBILE_APP`
`BROWSER_EXTENSION`
`SERVICES_AND_TOOLS`
`PAID_SEARCH_ENGINE`
`PAID_DISPLAY_ADS`
`OTHER`

SocialPlatform

Value
`INSTAGRAM`
`FACEBOOK`
`YOUTUBE`
`TWITTER`
`PINTEREST`
`TWITCH`
`WHATSAPP`
`SNAPCHAT`
`OTHER`

TrackingConsentType

Value
`AFFIRMATIVE`
`AUTOMATIC`

Scalars

Name	Description
`Boolean`	Represents `true` or `false`.
`Float`	Signed double-precision fractional values (IEEE 754).
`ID`	Unique identifier. Appears as a String in JSON; accepts string or integer input.
`ISODateTime`	ISO 8601 datetime. e.g. `1999-12-31T23:59:59Z`
`Int`	Non-fractional signed whole numeric values. Range: -(2^31) to 2^31 - 1.
`String`	Textual data represented as UTF-8 character sequences.
`Upload`	Represents a file upload.

Promotional Properties API Reference

Publisher vs. Advertiser Access

Code Samples

Sample Query

Sample curl Request

Sample Response

Sample Mutation — Create a New Promotional Property

Sample curl Request

Sample Response

Sample Mutation — Update an Existing Promotional Property

Sample Response

Errors

Objects

PromotionalProperty

PromotionalProperties

PromotionalModel

PromotionalPropertyTag

DistinctPropertyValues

BrowserExtensionDownloadInformation

MobileAppDownloadInformation

Interface: PromotionalPropertyTypeDetails

PromotionalPropertyWebsiteDetails

PromotionalPropertyBrowserExtensionDetails

PromotionalPropertyEmailDetails

PromotionalPropertyMobileAppDetails

PromotionalPropertyPaidSearchDetails

PromotionalPropertySocialMediaDetails

PromotionalPropertyPaidDisplayAdsDetails

PromotionalPropertyServicesAndToolsDetails

PromotionalPropertyOtherDetails

Enums

BrowserType

MobileAppPlatform

PromotionalModelType

PromotionalPropertyStatus

PromotionalPropertyType

SocialPlatform

TrackingConsentType

Scalars

Interface: `PromotionalPropertyTypeDetails`