{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"bc8ca9ea-7291-444a-9a7c-619b47e0708e","name":"Barb API V3 prod","description":"Welcome to the **Barb API V3 Production documentation**.\n\nBarb API V3 provides authorised users with secure access to Barb reference data, audience metrics, reach outputs and bulk data extracts through a structured set of API endpoints. The Production API is intended for approved business workflows, reporting pipelines, campaign analysis, data validation and downstream system integration.\n\nThis documentation is designed to help users understand what the API provides, how to authenticate, how to call the available endpoints, and how to interpret standard and bulk responses.\n\n**For API access issues, authentication queries, endpoint questions or support requests, please contact:**\n\n[https://support-api.barb.co.uk/](https://support-api.barb.co.uk/) \n \n\n## What the API Provides\n\nThe Barb API V3 collection is organised into the following functional areas:\n\n| **Area** | **Purpose** |\n| --- | --- |\n| **Auth** | Provides endpoints to manage authentication tokens, including refresh token handling when an access token expires. |\n| **Metadata** | Provides reference and lookup data such as panels, stations, viewing stations, households, panel members, advertisers, buyers, programme schedules, spot schedules, programme content details and audience categories. |\n| **Metrics** | Provides audience measurement outputs such as station audience data, spot impacts and programme ratings statistics. These endpoints support reporting, campaign analysis and programme performance analysis. |\n| **Bulk** | Provides high-performance retrieval of large datasets by returning temporary, secure download links, also known as SAS URLs, to pre-packaged files in cloud storage. This avoids large API payloads and helps users download viewing, schedule, ratings and impacts data efficiently. |\n\n# Sync API Limitations and Rate Limiting\n\nTo ensure that Barb API V3 remains stable, responsive and fair for all users, rate limits are applied to API requests.\n\nEach endpoint is assigned to a rate limit category based on expected processing cost, response size and system impact. These limits help protect the API from excessive request volumes and ensure that high-cost endpoints do not affect the performance of other users.\n\nRate limits are applied **per user** and **per endpoint category**.\n\nWhen a user exceeds the allowed number of requests for a category within the configured time window, the API will return:\n\n```\n{\n \"error\": \"RATE_LIMIT_EXCEEDED\",\n \"status\": 429,\n \"message\": \"You have exceeded the maximum request limit of 200 requests per minute for Medium endpoints.\",\n \"suggested_action\": \"Please try again in 18 seconds.\"\n}\n\n ```\n\nUsers should wait until the rate limit window resets before retrying the request.\n\n## Rate Limit Categories\n\n| **Category** | **Maximum Requests** | **Renewal Period** | **Description** |\n| --- | --- | --- | --- |\n| **Light** | No production limit currently required | 1 minute | Lower-cost endpoints, usually metadata or simple lookup endpoints. |\n| **Medium** | 200 requests per user | 1 minute | Moderate-cost endpoints or bulk request endpoints with manageable processing cost. |\n| **Heavy** | 30 requests per user | 1 minute | Higher-cost endpoints that require more complex processing or larger data retrieval. |\n| **Super Heavy** | 15 requests per user | 1 minute | Highest-cost endpoints, usually large metrics calculations or intensive reporting endpoints. |\n\n### Endpoint Rate Limit Classification:\n\n| **Category** | **Endpoints** |\n| --- | --- |\n| **Super Heavy** | `metrics/programme/ratings`
`metrics/spot/impacts` |\n| **Heavy** | `meta/advertisers`
`meta/programme/schedules`
`metrics/station/audiences`
`meta/spot/schedules` |\n| **Medium** | `bulk/programme/audiences`
`meta/households`
`bulk/viewing`
`meta/programme/content-details`
`meta/viewing-stations` |\n| **Light** | `meta/target-audience-categories`
`bulk/programme/ratings`
`meta/transmission-log/programme-details`
`bulk/programme/schedules`
`meta/split-station-factors`
`bulk/spot/schedules`
`meta/buyers`
`meta/panels`
`bulk/spot/impacts`
`bulk/spot/audiences`
`bulk/station/audiences`
`meta/stations`
`meta/panel-members` |\n\n# Getting Started: Authentication Guide\n\nAll protected **Metadata**, **Metrics**, **Reach** and **Bulk** endpoints require a valid OAuth 2.0 Bearer Access Token. \nBefore calling the API endpoints, users must authenticate and then include the returned `access_token` in API requests.\n\n### Prerequisites\n\nBefore you begin, make sure you have:\n\n- Accepted the B2C invitation sent by **Barb Audiences** (RSMB).\n \n\n\n\n#### Step 1: Open the Authorisation URL\n\nCopy and open the following URL in your web browser:\n\n```\nhttps://login.microsoftonline.com/71d36806-e815-4687-a9ab-26d3bf4325ae/oauth2/v2.0/authorize?\nclient_id=3c6d961a-ee1f-483e-ad47-6ad8de8b55d7\n&response_type=code\n&redirect_uri=https://api.barb.co.uk/api/v3/oauth/token\n&response_mode=query\n&scope=api://prod.barb.co.uk.api.v3.read/user_impersonation\n&state=12345\n&code_challenge=pCP-PzVm2qfMv6m68H6aytWeza57Jrvm1etOVNmc2DA\n&code_challenge_method=S256\n\n ```\n\n#### Step 2: Sign In\n\n- sign in with your shared email credentials.\n \n- Complete Multi-Factor Authentication (MFA).\n \n\n\n\n- Review and accept the requested app permissions.\n \n\n#### Step 3: Retrieve Tokens\n\nUpon successful authentication, the system redirects you to a token landing page displaying a token grid:\n\n- Copy the **`access_token`** value.\n \n- Copy the **`refresh_token`** value.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"52530320","team":13680302,"collectionId":"bc8ca9ea-7291-444a-9a7c-619b47e0708e","publishedId":"2sBYAswBkZ","public":true,"publicUrl":"https://documenter-api.postman.tech/view/52530320/2sBYAswBkZ","privateUrl":"https://go.postman.co/documentation/52530320-bc8ca9ea-7291-444a-9a7c-619b47e0708e","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.12.5","publishDate":"2026-08-24T08:02:31.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"Barb API 3.0","id":"430b30cf-b5d7-4158-b3a6-05726ab549ec","owner":"56705221","values":[{"key":"access_token","value":"","enabled":true,"type":"default"},{"key":"refresh_token","value":"","enabled":true,"type":"default"},{"key":"search_string","value":"","enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/aa9316a67b865bd5b8456ec6b7c23d0593bbead9ddea916410b8564a1b305a89","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Barb API 3.0","value":"56705221-430b30cf-b5d7-4158-b3a6-05726ab549ec"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sBYAswBkZ"}