API Reference · v1

Signups API

The Consumer Voice Signup API. Submit supporter signups here as JSON — they are validated and stored, ready for processing.

Authentication

Every request must include your secret key in the X-API-Key header. Requests without a valid key receive 401 Unauthorized.

Create a signup

POST https://staging-consumer-voice-signups.c6digital.app/api/v1/signups

cURL

curl -X POST https://staging-consumer-voice-signups.c6digital.app/api/v1/signups \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "opt_in": "Y",
    "phone": "+447700900000",
    "country": "GB",
    "post_code": "SW1A 1AA",
    "signed_up_at": "2026-05-28T12:00:00+00:00",
    "utm_campaign": "spring-launch",
    "utm_medium": "email",
    "utm_source": "newsletter",
    "utm_content": "hero-cta",
    "utm_term": "climate",
    "custom_field1": "one",
    "custom_field2": "two",
    "custom_field3": "three"
  }'

Request fields

All fields are sent as a JSON body. Unknown fields are ignored.

Field	Type	Required	Description
first_name	string	required	Supporter first name.
last_name	string	required	Supporter last name.
email	string	required	Valid email address.
opt_in	boolean	required	Marketing opt-in (Y/N).
phone	string	optional	Phone number.
country	string	optional	Country — ISO 3166-1 alpha-2 code recommended (e.g. GB).
post_code	string	optional	Postal / ZIP code.
signed_up_at	datetime	optional	When the signup occurred (defaults to now if omitted).
utm_campaign	string	optional	Campaign attribution.
utm_medium	string	optional	Medium attribution.
utm_source	string	optional	Source attribution.
utm_content	string	optional	Content attribution.
utm_term	string	optional	Term attribution.
custom_field1	string	optional	Free-form custom value.
custom_field2	string	optional	Free-form custom value.
custom_field3	string	optional	Free-form custom value.

Responses

201

Created

Signup stored successfully.

401

Unauthorized

Missing or invalid API key.

422

Unprocessable

Validation failed. errors lists every field that failed (each with its own messages); message summarises the first one.

Example 201 body · Created

{
  "message": "success"
}

Example 401 body · Unauthorized

{
  "message": "Invalid or missing API key."
}

Example 422 body · Unprocessable

{
  "message": "The first name field is required. (and 2 more errors)",
  "errors": {
    "first_name": [
      "The first name field is required."
    ],
    "email": [
      "The email field must be a valid email address."
    ],
    "opt_in": [
      "The opt in field is required."
    ]
  }
}