About This API
The Data Taxonomy API enables secure data sharing and audience taxonomy synchronization between StackAdapt and external data providers. This API allows partners to integrate their data seamlessly with StackAdapt's advertising platform for enhanced targeting and analytics capabilities. At the moment, this API only supports sending custom audience taxonomies to specific accounts in StackAdapt. The actual data transfer is handled through a direct S3 integration.
To access the StackAdapt Data Taxonomy API, specify the following base URL:
Base URL for Data Taxonomy API
http
https://api.stackadapt.com/data-partner/graphqlYou must authenticate API calls by attaching the AUTHORIZATION header. If you do not have an API key, reach out to the StackAdapt team for help.
GraphQL Auth Header
graphql
"Authorization": "Bearer <YOUR_API_TOKEN_HERE>"The Data Taxonomy API implements requests per second rate limiting to ensure optimal performance and fair usage across all partners.
10 requests per 1 second
To receive an API key, reach out to the StackAdapt team.
Returns metadata for an audience segment owned by the requesting provider, identified by
segmentId. Use this to look up the current name and description for a segment you have previously registered with StackAdapt.Request Body:
query {
audienceMetadata(segmentId: "id-123-abc") {
segmentId
name
description
}
}Arguments:
segmentId(required): The identifier of the audience - String!
Response:
audienceMetadata Success Response
json
{
"data": {
"audienceMetadata": {
"segmentId": "id-123-abc",
"name": "AudienceNew",
"description": "This audience is new"
}
}
}
Response Fields:
segmentId(String!): The identifier of the audience.name(String!): The name of the audience.description(String, nullable): A description of the audience. May benullif the segment has no description.
Not Found Response:
The query returns
null when no segment with that segmentId exists for the requesting provider. This includes segments owned by a different provider (cross-provider isolation) and soft-deleted segments. No GraphQL error is raised in these cases.audienceMetadata Not Found Response
json
{
"data": {
"audienceMetadata": null
}
}
Create a new audience for StackAdapt.
Note: This endpoint will not update existing audiences. Use
updateAudienceMetadata to update existing audiences.Request Body:
mutation {
createAudienceMetadata(input: {
# Arguments
segmentId: "id-123-abc", # Required, String
name:"AudienceNew", # Required, String
providerSource: "StackAdaptSource", # Required, String
internalPrice: 1.24, # Required, Float (2 decimal places)
accountIds: [4], # Optional, Array of numbers
description: "This audience is new", # Optional, String
}) {
success # Boolean
userErrors {
message
path
}
}
}Arguments:
segmentId(required): The identifier of the audience - String!name(required): The name of the audience - String!providerSource(required): The provider name of the audience - String!internalPrice(required): CPM rate of the audience - Float! (2 decimal places)accountIds(optional): A list of StackAdapt account IDs to be associated with the audience - [ID!]description(optional): A description of the audience - String
Response:
createAudienceMetadata Success Response
json
{
"data": {
"createAudienceMetadata": {
"success": true,
"userErrors": []
}
}
}
Response Fields:
success(Boolean): Indicates whether the audience metadata creation was successfuluserErrors(Array): Contains validation errors or other issues encountered during creation. Empty array if successfulmessage(String): Descriptive error message explaining what went wrongpath(Array): Array of strings indicating which field caused the error
Error Responses:
{
"data": {
"createAudienceMetadata": {
"success": false,
"userErrors": [
{
"message": "Segment with ID: id-123-abc already exists for this provider.",
"path": [
"segmentId"
]
}
]
}
}
}
{
"errors": [{
"message": "Argument 'segmentId' on InputObject 'CreateAudienceMetadataInput' has an invalid value (123). Expected type 'String!'.",
"locations": [{
"line": 1,
"column": 33
}],
"path": [
"createAudienceMetadata",
"input",
"segmentId"
],
"extensions": {
"code": "argumentLiteralsIncompatible",
"typeName": "InputObject",
"argumentName": "segmentId"
}
}]
}
Update an existing audience's metadata in StackAdapt.
Request Body:
mutation {
updateAudienceMetadata(input: {
# Required Arguments
segmentId: "id-123-abc", # Required, String
# Optional Arguments - if not provided, existing values are preserved
providerSource: "StackAdaptSource", # Optional, String - cannot be blank if provided
name: "Updated Audience Name", # Optional, String - cannot be blank if provided
internalPrice: 2.50, # Optional, Float (2 decimal places) - cannot be null or negative if provided
description: "Updated description", # Optional, String
appendAccountIds: [5, 6], # Optional, Array of IDs - appends to existing account IDs
}) {
success # Boolean
userErrors {
message
path
}
}
}Arguments:
segmentId(required): The identifier of the audience - String!providerSource(optional): The provider name of the audience - String. If not provided, the existing segment's provider source will be used. Cannot be blank (empty string or whitespace-only) if provided.name(optional): The name of the audience - String. If not provided, the existing segment's name will be used. Cannot be blank (empty string or whitespace-only) if provided.internalPrice(optional): CPM rate of the audience - Float (2 decimal places). If not provided, the existing segment's internal price will be used. Cannot be blank (null) or negative if provided. Zero (0.0) is a valid value.description(optional): A description of the audience - String. If not provided, the existing segment's description will be used.appendAccountIds(optional): A list of StackAdapt account IDs to be appended to the audience - [ID!]. If not provided, no account IDs will be appended.
Note: This mutation enables a partial update to the segment. You only need to provide the fields you want to modify, as all other fields (like cost, description, and providerSource in an example where only name is provided) will keep their current values. The appendAccountIds field behaves uniquely: the provided account IDs will be added to the existing list instead of replacing it entirely.
Response:
updateAudienceMetadata Success Response
json
{
"data": {
"updateAudienceMetadata": {
"success": true,
"userErrors": []
}
}
}
Response Fields:
success(Boolean): Indicates if the audience metadata update was successful.userErrors(Array): Contains validation errors or other issues encountered during update. Returns an empty array if successful.message(String): Provides a descriptive error message explaining what went wrong.path(Array): Array of strings indicating which field caused the error.
Error Responses:
User Error Response - Segment Not Found
json
{
"data": {
"updateAudienceMetadata": {
"success": false,
"userErrors": [
{
"message": "Segment with ID: id-123-abc does not exist for this provider.",
"path": [
"segmentId"
]
}
]
}
}
}
User Error Response - Invalid Price
json
{
"data": {
"updateAudienceMetadata": {
"success": false,
"userErrors": [
{
"message": "Internal price cannot be negative",
"path": [
"internalPrice"
]
}
]
}
}
}
User Error Response - Blank Provider Source
json
{
"data": {
"updateAudienceMetadata": {
"success": false,
"userErrors": [
{
"message": "Provider source cannot be blank",
"path": [
"providerSource"
]
}
]
}
}
}
User Error Response - Blank Name
json
{
"data": {
"updateAudienceMetadata": {
"success": false,
"userErrors": [
{
"message": "Name cannot be blank",
"path": [
"name"
]
}
]
}
}
}
User Error Response - Blank Internal Price
json
{
"data": {
"updateAudienceMetadata": {
"success": false,
"userErrors": [
{
"message": "Internal price cannot be blank",
"path": [
"internalPrice"
]
}
]
}
}
}
- 200 OK: Request successful
- 400 Bad Request: Invalid request parameters
- 401 Unauthorized: Invalid or missing API key
- 404 Not Found: Resource not found
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Server error
Was this page useful?