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).

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.

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

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

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

curl -H "Authorization: Bearer <your-personal-access-token>" -H "Content-Type: application/json" -d '{"operationName":null,"variables":{},"query":"mutation {\n  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}}"}' -XPOST https://accounts.api.cj.com/graphql

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.

Enums

`BrowserType`

CHROME
FIREFOX
SAFARI
OPERA

`CacheControlScope`

PUBLIC
PRIVATE

`MobileAppPlatform`

IOS
ANDROID

`PromotionalModelType`

Indicates your property’s primary promotional model. Each property may have more than one model, but one model must be indicated as your primary model.

Value	Description
CONTENT_BLOG_MEDIA	My customers read original content or articles that I write about topics that interest them.
COUPON_DEAL	My customers come to discover coupons, vouchers, or discounts.
LOYALTY_CASH_BACK	My customers receive rewards in the form of cash back as a percentage of their purchase.
LOYALTY_NON_CASH_REWARDS	My customers receive non-cash rewards for their purchase in the form of points, airline miles, charity donations, etc.
LOYALTY_CLOSED_USER_GROUP	I provide a membership service where my customers must have an exclusive login to access benefits, such as employee benefits, credit card rewards, or airline rewards malls.
TRADEMARK_BIDDING	I purchase search engine ads by bidding on the brand names of my advertisers, but I display my own brand in the ad and when they click, my customers are directed to my own website.
INFLUENCER	My customers follow me because I am a personality or figure they are interested in following.
PAY_PER_CALL	I use call tracking to drive customer transactions over the telephone.
PRODUCT_COMPARISON_REVIEWS_DISCOVERY	I provide links to specific products that customers can browse, compare, or search for.
OTHER	If your property does not fit into any of the above options, please briefly describe your promotional method/property type here so that advertisers can understand what you do.

`PromotionalPropertyStatus`

ACTIVE
ARCHIVED
TERMINATED

`PromotionalPropertyType`

WEBSITE
SOCIAL_MEDIA
EMAIL
MOBILE_APP
BROWSER_EXTENSION
SERVICES_AND_TOOLS
PAID_SEARCH_ENGINE
PAID_DISPLAY_ADS
OTHER

`SocialPlatform`

INSTAGRAM
FACEBOOK
YOUTUBE
TWITTER
PINTEREST
TWITCH
WHATSAPP
SNAPCHAT
OTHER

`TrackingConsentType`

AFFIRMATIVE
AUTOMATIC

Scalars

Name	Description
Boolean	The `Boolean` scalar type represents `true` or `false`.
Float	The `Float` scalar type represents signed double-precision fractional values as specified by IEEE 754.
ID	The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID.
ISODateTime	ISO 8601 datetime. e.g. '1999-12-31T23:59:59Z'
Int	The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
String	The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
Upload	The `Upload` scalar type represents a file upload.