Audiences API | Genaya API Reference

Marketing

Audiences

Campaign audiences and their contacts - push signups into a marketing audience.

GET/audiences

List audiences

Returns a cursor-paginated list of the organization's campaign audiences (metadata only - the recipient contacts are paginated separately via the contacts sub-resource). Soft-deleted audiences are excluded. Requires scope: audiences:read.

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/audiences \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "9KdxQwErTyUiOpAsDfGh",
      "object": "audience",
      "name": "Website Signups",
      "source": "api",
      "count": 128,
      "createdAt": "2026-06-30T15:04:21.000Z",
      "updatedAt": "2026-06-30T18:22:10.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

POST/audiences

Create an audience

Provisions a new, empty audience so you can push contacts into it from your own systems. The audience is created with source "api" and zero recipients; add contacts with the contacts sub-resource. Supports idempotent retries via the Idempotency-Key header. Requires scope: audiences:write.

Request body

FieldTypeDescription

namerequired

string

A name for the audience (1-120 characters).

Response 201

FieldTypeDescription

idrequired

string

Unique identifier for the audience. Use this as the audienceId in contact calls.

objectrequired

string

The object type. Always "audience".

namerequired

string

Human-readable name of the audience.

sourcerequired

string

How the audience was built - "clients", "leads", or "upload" for the in-app builders, or "api" when provisioned via this API.

countrequired

integer

Number of contacts currently in the audience's send pool.

createdAt

string <date-time>

ISO-8601 timestamp of when the audience was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp of when the audience was last updated.nullable

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

409Idempotency-Key reused with a different body

429Rate limited

500Unexpected server error

curl -X POST https://api.genaya.com/v1/audiences \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Website Signups"
}'

Example response

{
  "data": {
    "id": "9KdxQwErTyUiOpAsDfGh",
    "object": "audience",
    "name": "Website Signups",
    "source": "api",
    "count": 128,
    "createdAt": "2026-06-30T15:04:21.000Z",
    "updatedAt": "2026-06-30T18:22:10.000Z"
  }
}

GET/audiences/{audienceId}

Retrieve an audience

Returns a single audience by id (metadata only). Returns 404 if the audience is missing, soft-deleted, or belongs to another organization. Requires scope: audiences:read.

Parameters

Path

audienceIdrequired

string

The id of the audience.

Response 200

FieldTypeDescription

idrequired

string

Unique identifier for the audience. Use this as the audienceId in contact calls.

objectrequired

string

The object type. Always "audience".

namerequired

string

Human-readable name of the audience.

sourcerequired

string

How the audience was built - "clients", "leads", or "upload" for the in-app builders, or "api" when provisioned via this API.

countrequired

integer

Number of contacts currently in the audience's send pool.

createdAt

string <date-time>

ISO-8601 timestamp of when the audience was created.nullable

updatedAt

string <date-time>

ISO-8601 timestamp of when the audience was last updated.nullable

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/audiences/{audienceId} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "9KdxQwErTyUiOpAsDfGh",
    "object": "audience",
    "name": "Website Signups",
    "source": "api",
    "count": 128,
    "createdAt": "2026-06-30T15:04:21.000Z",
    "updatedAt": "2026-06-30T18:22:10.000Z"
  }
}

GET/audiences/{audienceId}/contacts

List audience contacts

Returns a cursor-paginated list of the contacts in an audience's send pool, ordered by email. Each contact carries a `suppressed` flag reflecting the organization's suppression list - a suppressed address stays listed but is skipped at send. The cursor (`starting_after`) is a contact's email. Requires scope: audiences:read.

Parameters

Path

audienceIdrequired

string

The id of the audience.

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/audiences/{audienceId}/contacts \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "object": "audience_contact",
      "audienceId": "9KdxQwErTyUiOpAsDfGh",
      "email": "jordan.rivera@example.com",
      "firstName": "Jordan",
      "lastName": "Rivera",
      "suppressed": false
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

POST/audiences/{audienceId}/contacts

Add a contact to an audience

Adds or upserts a contact into the audience's send pool. Fire this on each new signup to auto-sync your audience: new emails are added, and pushing an email that already exists updates its name fields instead of duplicating (the response `created` flag tells you which happened). Email match is case-insensitive. A suppressed/unsubscribed address is NOT added to the send pool - the response returns success with `suppressed: true` so you know it will not receive mail. Supports idempotent retries via the Idempotency-Key header. Requires scope: audiences:write.

Parameters

Path

audienceIdrequired

string

The id of the audience.

Request body

FieldTypeDescription

emailrequired

string

The contact's email address (required). Matched case-insensitively.

firstName

string

Optional first name (max 80 characters).

lastName

string

Optional last name (max 80 characters).

Response 200

FieldTypeDescription

objectrequired

string

The object type. Always "audience_contact".

audienceIdrequired

string

The id of the audience.

emailrequired

string

The contact's email address, lowercased.

firstName

string

The contact's first name as stored.

lastName

string

The contact's last name as stored.

createdrequired

boolean

True if the contact was newly added; false if it already existed or was suppressed.

addedrequired

boolean

True if the contact was added to the send pool (false when suppressed).

suppressedrequired

boolean

True if the address is suppressed and was therefore not added to the send pool.

countrequired

integer

The audience's recipient count after the operation.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

409Idempotency-Key reused with a different body

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X POST https://api.genaya.com/v1/audiences/{audienceId}/contacts \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "email": "new.signup@example.com",
  "firstName": "Jordan",
  "lastName": "Rivera"
}'

Example response

{
  "data": {
    "object": "audience_contact",
    "audienceId": "9KdxQwErTyUiOpAsDfGh",
    "email": "new.signup@example.com",
    "firstName": "Jordan",
    "lastName": "Rivera",
    "created": true,
    "added": true,
    "suppressed": false,
    "count": 129
  }
}

DELETE/audiences/{audienceId}/contacts/{email}

Remove a contact from an audience

Removes a contact from the audience's send pool by email. Idempotent: removing an email that is not in the audience returns a clean result with `removed: false` (never a 404). Updates the audience count. Requires scope: audiences:write.

Parameters

Path

audienceIdrequired

string

The id of the audience.

emailrequired

string

The email address of the contact to remove (case-insensitive).

Response 200

FieldTypeDescription

objectrequired

string

The object type. Always "audience_contact".

audienceIdrequired

string

The id of the audience.

emailrequired

string

The email address that was targeted, lowercased.

deletedrequired

boolean

Always true on a successful call.

removedrequired

boolean

True if the contact was present and removed; false if it was not in the audience.

countrequired

integer

The audience's recipient count after the removal.

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X DELETE https://api.genaya.com/v1/audiences/{audienceId}/contacts/{email} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "object": "audience_contact",
    "audienceId": "9KdxQwErTyUiOpAsDfGh",
    "email": "jordan.rivera@example.com",
    "deleted": true,
    "removed": true,
    "count": 127
  }
}