# Collective Audience API

Collective Audience™ has opened an API that allows external application to retrieve some information.

## Usage

### Allowed method

Currently, the only action that is allowed is the **READ** action through `HTTP GET` requests that return JSON responses. Initially, the API endpoints just give access to statistics.

The base url to access the API is `https://data.collectiveaudience.co/api`

```http
GET https://data.collectiveaudience.co/api

RESPONSE 200 OK
```

## Security

Access to Collective Audience™ API is protected by a personal **API KEY** that must be passed in every request as a query param `?api_key={YOUR_API_KEY}`. The access to and management of API keys depend on whether you want to access stats for a *Managed* account or a *Self* one.

### Managed account

If you are a Collective Audience™ customer but **not handling your own** *account* / *creatives* / *campaigns*, you can [contact](mailto:contact@collectiveaudience.co?subject=API%20key%20request) our team and ask for an API key in order to integrate it in your workflows.

### Self account

If you are managing your own *account* / *creatives* / *campaigns*

In your Collective Audience™ [Account](https://desk.collectiveaudience.co/settings/account/api), you will be able to find a section in the settings to manage your API keys

 ![](https://s3.eu-west-1.amazonaws.com/outline-assets.collectiveaudience.co/uploads/a579229e-61bc-476b-887f-f4ebec869d46/67bcd8b1-07d1-4d21-a80b-e53398bf60ac/account-settings.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIA4G6VWWYWENBOMIQL%2F20261016%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20261016T230000Z&X-Amz-Expires=86400&X-Amz-Security-Token=IQoJb3JpZ2luX2VjECYaCWV1LXdlc3QtMSJGMEQCIFIVLlTsgTg96wh%2B13hbcBBtTjtouLzGHYFUQwAMyGCgAiBZQvQLCUm0fJPROIy9UX0zelwKaJXHduvgCeOJjz9zHirGBQjv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAIaDDgzOTU3NzQxNzI2MCIM0yab%2Fsb9UPYpqt2CKpoFuB%2BEa5MwONKzFCbtf5wiVAAVRaYR9GmGt6NdMSaKWAK2%2BOb%2BLlpx%2F7ratzmo5gOwnpVXaX%2FyyDJmygkNiMOc%2BgpZ%2FhbNJEfn8TloAI3BYdgaAX5xIMxfElG1K1uLvqeo%2F6U%2FmVj2%2BFlCBT9JxUJDO19Xuaen5xUsRewtRqOWeD9x47bV4x5%2BB3O9QDZOk2LC%2Bu7J1NSYWN3qnLJDOWv5tNMbN%2FKBj0FHzZDzZH7Wx80eg81oATJXexfevFkg0pXRaTrdloHnNhzBft1Jrn9Etddl5rA754DWiTULdpjC%2BCcYhEZNmJcWNnzvkFAZZIleU5QyGSJvlUlWAVzPswAhXPHyvnSu27cxmTKXgphDOHTN3Voxp%2FxYNTJk83LqQzjoTrOdS4q4phhD3Hz5eJm9nJkc2ImiYxz2UBGhRx8Zeb4j%2Fi1ml%2BrnZbxzsNegZdlIYVLCr9vbTpCNpOXisVtb%2FBOzaF7YL6fnhiEzCuuHVDISjdVDV46UnRfpFlvSjO15nPzRHDGbfLfADew7iMYlQVec4B3GZp0QCpnqFDXYPKAxUHbIot%2BjO9NK0qaQOMNqkI3fL6IOXYGz0GMTXqL4mPhd3ET5Jb9SwWRUbnOfY1rrkt7JD6Zu%2BgmijASDdnpvxeMND7EvJ9hBwn7eEWbX9VkBVpSM0T7pUbFtsKzecam6yDn6EwCFw2QO1AfSnYyeG%2FFxsQUzj0cXEMuCk%2FryoSOxY2MVnEkK2dQn9cM74B8SQfCRq%2B0c8TK6Mch3CQ29OkUEeGtIh9j%2F4JF3NcqkBAntcbbvH%2BJDXMakkwybgisr7GwsMoidrDxI%2FAwyPpDADt9e8%2BQweALbpQY0mo4GZNaEu0Rc5nAqH1J5OjBbEydoiIMSQHah2UgHMOu0ytYGOrIBA7%2BJIQPrc8lI3Xk%2FuX9wOXXeLdPxQv0gQ5r10iRjh1hC9aT3%2BK%2BLKUDZo0SxrxFWA7bcxdNYA9kBsmm%2F9gA25vfZ4quNROTqd17T3k3NJT7JJGWCTIt3KxpyePhbKVJEXcfWhVOEL2EwBC7cBAcqe5PlBwWAgwnqhyVopkionYKI49pKBD4BxaU0zkBWmMjB0UdxMqY8L8%2Bc0CC3wpqY75IKUc7Y6yqARbgBVuNlQyiHzA%3D%3D&X-Amz-Signature=e2ff26463633d1af8a6c2930f39c17aaafaa90dc889488a0d6910eb1516fb3d6&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject " =1074x656")

Learn how to manage your API keys in the next page *(→ api-generate-key)*

## Entities

To perform its mission, Collective Audience™ is managing some object/entities such as ***Accounts***, ***Campaigns***, ***Creatives***, ...

A call to Collective Audience™ open API must include the name of the entities after the base url.

### List items

```http
GET https://data.collectiveaudience.co/api/{entityName}?api_key={yourToken}

RESPONSE LIST OF RESOURCES OF THAT {entityName} TYPE
```

### GET one item

```http
GET https://data.collectiveaudience.co/api/{entityName}/{id}?api_key={yourToken}

RESPONSE ONE ITEM IDENTIFIED BY {id}
```

### Progress

Already developed enpoints cover :

* [Campaigns](https://../api-campaigns)

## General stats

Based on these entities, Collective Audience™ is providing a route per entity to get statistics that are available in real-time. To use it, you just have to add `/stats/` between `/api/` and `{entityName}`

### List items

```http
GET https://data.collectiveaudience.co/api/stats/{entityName}?api_key={yourToken}

RESPONSE LIST OF RESOURCES OF THAT {entityName} TYPE
```

### GET one item

```http
GET https://data.collectiveaudience.co/api/stats/{entityName}/{id}?api_key={yourToken}

RESPONSE ONE ITEM IDENTIFIED BY {id}
```

### Progress

* [Campaigns](https://../api-stats#campaigns)
* [Insertions](https://../api-stats#insertions)
* [Contents](https://../api-stats#contents)

---

**Documents**

- [Key management](https://outline.collectiveaudience.co/s/public/doc/key-management-FGsdrQOF9T)
- [General statistics](https://outline.collectiveaudience.co/s/public/doc/general-statistics-AZzpKGkVHk)
- [Campaigns](https://outline.collectiveaudience.co/s/public/doc/campaigns-v1Cngvt3b3)