Campaign Reference
The External API lets you display an Activoice campaign on your own website, with your own design, without embedding our widget. It is read-only, needs no API key, and accepts calls from any domain — both from a browser and from your own server.
Enabling access
Access is granted per organization by the Activoice team. Contact support to have it enabled; there is no self-service switch in the backoffice.
Once enabled, any campaign of the organization can be read by anyone holding its identifier. Drafts included, so you can build and test your integration before the campaign goes live — a draft has no public page, so its identifier only circulates if you share it.
Endpoint
GET https://api.activoice.org/external/v1/campaigns/{campaign_id}/
campaign_id is the campaign UUID, visible in the backoffice URL and in the embed panel. Slugs are not accepted: they can be changed or left empty, while the UUID never changes.
Example
curl https://api.activoice.org/external/v1/campaigns/3f2b1c7e-1a4d-4f9e-9c11-8a0f7b2d5e63/
{
"id": "3f2b1c7e-1a4d-4f9e-9c11-8a0f7b2d5e63",
"name": "Stop concreting over farmland",
"description": "<p>Every year, an area the size of a county…</p>",
"cover_image": "https://medias.activoice.org/campaigns/cover-abc.jpg",
"cover_image_mobile": null,
"state": "active",
"deactivation_reason": "",
"language": "en-GB",
"slug": "stop-concreting-farmland",
"progress": { "count": 1234, "target": 2000 }
}
When the campaign publishes no figure, the object stays in place with null fields:
{
"progress": { "count": null, "target": null }
}
Fields
| Field | Type | Description |
|---|---|---|
id | string | The campaign UUID. |
name | string | Campaign title. |
description | string | Rich text — contains HTML. Insert it as HTML rather than escaping it, or your page will show raw tags. The markup is sanitised on our side. |
cover_image | string | null | Absolute URL of the desktop cover image. |
cover_image_mobile | string | null | Absolute URL of the mobile cover image. |
state | "draft" | "active" | "ended" | See below. |
deactivation_reason | string | Contains HTML. The message to show once the campaign is over. Only display it when state is ended. |
language | string | Language code of the campaign content, e.g. fr, en-GB. |
slug | string | null | URL-friendly name, when one is set. |
progress | object | { "count": number | null, "target": number | null }. Always present. |
Campaign state
active means the campaign is running. ended means it is over: our embed stops rendering at that point, so if you built your own page you should switch it to a closing message yourself — deactivation_reason holds the text to display.
draft means the campaign is still being prepared and has no public page yet. It is returned so you can develop your integration ahead of the launch, but do not publish it to your visitors: its content is not final.
Progress
progress reports how many people have taken part, and the next milestone the campaign is aiming for. The milestone is computed automatically: a round number a little above the current count (for instance 11123 participants aim for 12000), which moves up as soon as it is reached.
Both fields are null when the organization chose not to publish its collective progress, or while fewer than 100 people have taken part.
Errors
| Status | Meaning |
|---|---|
404 | The campaign does not exist, or its organization has not enabled the External API. The two cases are deliberately indistinguishable. |
405 | Only GET is supported. |
429 | Too many requests. Wait for the delay given in the Retry-After header. |
Caching
Responses are cached on our CDN for five minutes, and carry Cache-Control headers so browsers and your own server-side cache can reuse them. Campaign edits purge the cache immediately, so a change is visible without waiting out the delay.
Calling the endpoint with a changing query string does not bypass the cache and offers no benefit.
Stability
v1 is a frozen contract. Fields are never removed, renamed, or narrowed. New fields may be added, so parse responses tolerantly and ignore keys you do not know.