Skip to main content

​
Overview

The Contextual API enables retrieval of contextual cohort targeting values without processing user data. Use it to pass targeting values to ad servers like Google Ad Manager. This API is designed to work independently of the main Permutive SDK, allowing you to retrieve contextual targeting even when user consent is not available.
If you don’t need to target unconsented users with your contextual signals, the Permutive SDK will call these endpoints and segment contextual cohorts automatically.

​
Base URL

https://api.permutive.com/ctx/v1

​
Authentication

The API uses API key authentication. Pass your Permutive API key as a query parameter: 
?k=YOUR_API_KEY
This is the same API key used for your main Permutive SDK deployment.

​
Use Cases

  • Privacy-safe contextual targeting: Target ads based on page content without user identifiers
  • Cookie-less advertising: Enable ad targeting in environments where cookies are blocked or unavailable
  • Server-side targeting value retrieval: Fetch targeting values for integration with any ad server
  • Consent-free operation: Retrieve targeting values without requiring user consent for personal data processing

​
Available Endpoints

EndpointMethodDescription
/segmentPOSTRetrieve contextual cohort codes for a given URL and page properties

​
Response Format

All responses are returned in JSON format. Successful responses include cohort codes and activation mappings. The endpoint also returns content classification data if any classification provider is enabled in the account. 
{
  "cohorts": ["abc", "def", "ghi"],
  "activations": {
    "target_dfp": ["abc", "def"],
    "appnexus_adserver": ["ghi"]
  },
  "contextual_data": {
    "classifications": {
      "categories": [
        {
          "value": "155",
          "confidence": 0.5,
          "taxonomy": "iab_3.0",
          "provider": "ibm_watson"
        }
      ],
      "keywords": [
        {
          "value": "museum",
          "confidence": 0.7,
          "provider": "ibm_watson"
        }
      ],
      "entities": [
        {
          "value": "British Museum",
          "confidence": 0.9,
          "provider": "ibm_watson"
        }
      ],
      "sentiment": [
        {
          "value": "positive",
          "confidence": 0.9,
          "provider": "ibm_watson"
        }
      ],
      "emotion": [
        {
          "value": "joy",
          "confidence": 0.4,
          "provider": "ibm_watson"
        }
      ],
      "concepts": [
        {
          "value": "Vincent van Gogh",
          "confidence": 0.6,
          "provider": "ibm_watson"
        }
      ]
    }
  }
}

​
Error Handling

The API returns standard HTTP status codes:
Status CodeDescription
200Success
400Bad Request - Invalid request body or parameters
401Unauthorized - Invalid or missing API key
500Internal Server Error

​
Rate Limits

Contact your Customer Success Manager for information about rate limits applicable to your account.

​
Next Steps

Get Contextual Segments

Learn how to retrieve contextual cohort codes using the segment endpoint.