Target Audience Lifecycle

This guide walks you through the full lifecycle of a target audience: bootstrapping from a URL, creating, updating, and deleting.

What you'll build

Bootstrap a demographic profile from a URL
Create a target audience from that profile
Retrieve, update, and delete it

Prerequisites

A neuroflash account with API access
Your client_id and client_secret (see Authentication)

Step 1: Authenticate

cURL
Python
Node.js
Go

curl -X POST https://id.neuroflash.com/oauth/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=openid"

import requests
BASE_URL = "https://app.neuroflash.com/api"
token = requests.post(
    "https://id.neuroflash.com/oauth/v2/token",
    data={"grant_type": "client_credentials", "client_id": "YOUR_CLIENT_ID",
          "client_secret": "YOUR_CLIENT_SECRET", "scope": "openid"},
).json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

const BASE_URL = "https://app.neuroflash.com/api";
const { access_token } = await fetch("https://id.neuroflash.com/oauth/v2/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
    scope: "openid",
  }),
}).then((r) => r.json());
const headers = { Authorization: `Bearer ${access_token}` };

data := url.Values{
    "grant_type": {"client_credentials"},
    "client_id": {"YOUR_CLIENT_ID"},
    "client_secret": {"YOUR_CLIENT_SECRET"},
    "scope": {"openid"},
}
resp, _ := http.Post("https://id.neuroflash.com/oauth/v2/token",
    "application/x-www-form-urlencoded", strings.NewReader(data.Encode()))
defer resp.Body.Close()

Step 2: Get Your Workspace

cURL
Python
Node.js
Go

curl "https://app.neuroflash.com/api/workspace-service/v1/workspaces" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

workspaces = requests.get(f"{BASE_URL}/workspace-service/v1/workspaces", headers=headers).json()
workspace_id = workspaces["_embedded"]["workspaces"][0]["id"]

const workspaces = await fetch(`${BASE_URL}/workspace-service/v1/workspaces`, { headers })
  .then((r) => r.json());
const workspaceId = workspaces._embedded.workspaces[0].id;

req, _ := http.NewRequest("GET", baseURL+"/workspace-service/v1/workspaces", nil)
req.Header.Set("Authorization", "Bearer "+token)

Step 3: Bootstrap from a URL (fastest path)

This returns a prepared demographic profile, not a saved audience. Pass the response fields directly to the create endpoint in the next step.

cURL
Python
Node.js
Go

curl -X POST "https://app.neuroflash.com/api/audience-service/v1/workspaces/{workspace_id}/target-audiences-url-imports" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "audienceModelId": "538b1efc6f88ad88feebf7acd8c618facb54fe82",
      "urls": ["https://your-brand.com"]
  }'

profile = requests.post(
    f"{BASE_URL}/audience-service/v1/workspaces/{workspace_id}/target-audiences-url-imports",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "audienceModelId": "538b1efc6f88ad88feebf7acd8c618facb54fe82",
        "urls": ["https://your-brand.com"],
    },
).json()

const profile = await fetch(
  `${BASE_URL}/audience-service/v1/workspaces/${workspaceId}/target-audiences-url-imports`,
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      audienceModelId: "538b1efc6f88ad88feebf7acd8c618facb54fe82",
      urls: ["https://your-brand.com"],
    }),
  }
).then((r) => r.json());

body, _ := json.Marshal(map[string]any{
    "audienceModelId": "538b1efc6f88ad88feebf7acd8c618facb54fe82",
    "urls": []string{"https://your-brand.com"},
})
req, _ := http.NewRequest("POST",
    baseURL+"/audience-service/v1/workspaces/"+workspaceID+"/target-audiences-url-imports",
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

Step 4: Create the Audience

Gender distribution must sum to 1.0

The four genderDistribution fields (female, male, nonBinary, preferNotToSay) are all required and their values must sum to exactly 1.0. The API returns a 400 error if any field is missing or the sum is incorrect.

cURL
Python
Node.js
Go

curl -X POST "https://app.neuroflash.com/api/audience-service/v1/workspaces/{workspace_id}/target-audiences" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "country": "US",
      "genderDistribution": {
        "female": 0.5,
        "male": 0.4,
        "nonBinary": 0.07,
        "preferNotToSay": 0.03
      },
      "interests": ["AI", "content marketing"],
      "maxAge": 45,
      "minAge": 25,
      "name": "Marketing leaders",
      "nativeLanguage": "en",
      "needs": ["scale content production"],
      "painPoints": ["manual workflows"],
      "residence": "Berlin",
      "shared": true
  }'

created = requests.post(
    f"{BASE_URL}/audience-service/v1/workspaces/{workspace_id}/target-audiences",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "country": "US",
        "genderDistribution": {"female": 0.5, "male": 0.4, "nonBinary": 0.07, "preferNotToSay": 0.03},
        "interests": ["AI", "content marketing"],
        "maxAge": 45,
        "minAge": 25,
        "name": "Marketing leaders",
        "nativeLanguage": "en",
        "needs": ["scale content production"],
        "painPoints": ["manual workflows"],
        "residence": "Berlin",
        "shared": True,
    },
).json()
target_audience_id = created["id"]

const created = await fetch(
  `${BASE_URL}/audience-service/v1/workspaces/${workspaceId}/target-audiences`,
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      country: "US",
      genderDistribution: { female: 0.5, male: 0.4, nonBinary: 0.07, preferNotToSay: 0.03 },
      interests: ["AI", "content marketing"],
      maxAge: 45,
      minAge: 25,
      name: "Marketing leaders",
      nativeLanguage: "en",
      needs: ["scale content production"],
      painPoints: ["manual workflows"],
      residence: "Berlin",
      shared: true,
    }),
  }
).then((r) => r.json());
const targetAudienceId = created.id;

body, _ := json.Marshal(map[string]any{
    "country": "US",
    "genderDistribution": map[string]float64{
        "female": 0.5, "male": 0.4, "nonBinary": 0.07, "preferNotToSay": 0.03,
    },
    "interests": []string{"AI", "content marketing"},
    "maxAge": 45, "minAge": 25,
    "name": "Marketing leaders",
    "nativeLanguage": "en",
    "needs": []string{"scale content production"},
    "painPoints": []string{"manual workflows"},
    "residence": "Berlin",
    "shared": true,
})
req, _ := http.NewRequest("POST",
    baseURL+"/audience-service/v1/workspaces/"+workspaceID+"/target-audiences",
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

Step 5: Get the Audience

cURL
Python
Node.js
Go

curl "https://app.neuroflash.com/api/audience-service/v1/workspaces/{workspace_id}/target-audiences/{target_audience_id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

audience = requests.get(
    f"{BASE_URL}/audience-service/v1/workspaces/{workspace_id}/target-audiences/{target_audience_id}",
    headers=headers,
).json()

const audience = await fetch(
  `${BASE_URL}/audience-service/v1/workspaces/${workspaceId}/target-audiences/${targetAudienceId}`,
  { headers }
).then((r) => r.json());

req, _ := http.NewRequest("GET",
    baseURL+"/audience-service/v1/workspaces/"+workspaceID+"/target-audiences/"+targetAudienceID, nil)
req.Header.Set("Authorization", "Bearer "+token)

Step 6: Update the Audience

Full profile required on every update

The update endpoint uses PUT semantics — you must supply the complete demographic profile on every call, even if you only want to change one field. Fetch the audience first, then re-send all existing values with your change applied.

cURL
Python
Node.js
Go

curl -X PUT "https://app.neuroflash.com/api/audience-service/v1/workspaces/{workspace_id}/target-audiences/{target_audience_id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "...": "full demographic profile here" }'

audience["name"] = "Senior marketing leaders"
requests.put(
    f"{BASE_URL}/audience-service/v1/workspaces/{workspace_id}/target-audiences/{target_audience_id}",
    headers={**headers, "Content-Type": "application/json"},
    json=audience,
)

audience.name = "Senior marketing leaders";
await fetch(
  `${BASE_URL}/audience-service/v1/workspaces/${workspaceId}/target-audiences/${targetAudienceId}`,
  {
    method: "PUT",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify(audience),
  }
);

// Re-serialise the previously fetched audience with your modifications, then PUT it back.
req, _ := http.NewRequest("PUT",
    baseURL+"/audience-service/v1/workspaces/"+workspaceID+"/target-audiences/"+targetAudienceID,
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

Step 7: Delete the Audience

Ownership

Only the user who created a target audience can update or delete it. Attempting to modify a resource owned by another user returns 403 Forbidden.

cURL
Python
Node.js
Go

curl -X DELETE "https://app.neuroflash.com/api/audience-service/v1/workspaces/{workspace_id}/target-audiences/{target_audience_id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

requests.delete(
    f"{BASE_URL}/audience-service/v1/workspaces/{workspace_id}/target-audiences/{target_audience_id}",
    headers=headers,
)

await fetch(
  `${BASE_URL}/audience-service/v1/workspaces/${workspaceId}/target-audiences/${targetAudienceId}`,
  { method: "DELETE", headers }
);

req, _ := http.NewRequest("DELETE",
    baseURL+"/audience-service/v1/workspaces/"+workspaceID+"/target-audiences/"+targetAudienceID, nil)
req.Header.Set("Authorization", "Bearer "+token)

The `genderDistribution` Object

All four keys are required and the values must sum to exactly 1.0:

Key	Description
`female`	Fraction identifying as female
`male`	Fraction identifying as male
`nonBinary`	Fraction identifying as non-binary
`preferNotToSay`	Fraction preferring not to disclose

A common starting point: female: 0.5, male: 0.4, nonBinary: 0.07, preferNotToSay: 0.03.

What you'll build​

Prerequisites​

Step 1: Authenticate​

Step 2: Get Your Workspace​

Step 3: Bootstrap from a URL (fastest path)​

Step 4: Create the Audience​

Step 5: Get the Audience​

Step 6: Update the Audience​

Step 7: Delete the Audience​

The genderDistribution Object​