Great Question

Customer research platform. Sync candidate data from your warehouse to Great Question to keep your research panel up to date with the latest customer attributes, contact information, and opt-in status.

Prerequisites

A Great Question account on a Team or Enterprise plan (API access is not available on free plans)
A Great Question API key generated by an account administrator
The API key must be created from Settings > API Tokens in Great Question

Authentication

Great Question uses API Key authentication with Bearer token authorization.

Log in to Great Question as an account administrator
Navigate to Settings > API Tokens
Click Create Token to generate a new API key
Copy the API key immediately — store it securely as it may not be viewable again
In Zeotap, select API Key as the authentication method and paste your token

Important: API tokens inherit the permissions of the administrator who creates them. Ensure the admin account has full access to candidate management.

Configuration

Great Question does not require additional configuration fields beyond authentication. All API requests are routed to https://api.greatquestion.co.

Target Settings

Field	Type	Required	Description
Object Type	Select	Yes	The type of data to sync. Currently supports Candidates.

Supported Operations

Sync Modes

Mode	Supported
Upsert	Yes
Insert	Yes
Update	Yes
Mirror	—

Audience Sync Modes

Mode	Supported
Add	—
Upsert	—
Remove	—
Mirror	—

Great Question does not expose a list or segment membership API, so audience sync modes are not supported. Use standard sync modes to keep candidate records up to date.

Features

Field Mapping: Yes
Schema Introspection: No

Required Mapping Fields

Field	Description
`email`	Email address used as the unique identifier to upsert candidates. Every row must include an email.

Default Destination Fields

Field	Type	Description
`email`	string	Candidate email address (upsert key)
`name`	string	Full name of the candidate
`phone_number`	string	Phone number for the candidate
`opted_in`	boolean	Whether the candidate has opted in to research participation
`timezone`	string	IANA timezone identifier (e.g., `America/New_York`). Invalid timezones are ignored by the API.

How It Works

Candidate Sync

Zeotap syncs candidate data to the Great Question REST API v1. Candidates are upserted by email address — if a candidate with the given email exists, their attributes are updated; otherwise, a new candidate record is created.

The following fields are mapped to top-level Great Question candidate attributes:

email — The unique identifier for upserting candidates
name — The candidate’s full name
phone_number — Contact phone number
opted_in — Research participation opt-in status
timezone — IANA timezone string

All other mapped fields are sent as custom attributes (additional properties). Custom attributes must be configured in your Great Question account under Settings > Candidate Attributes before they can be populated via the API.

Sync Mode Behavior

Upsert: Creates new candidates or updates existing ones, matched by email address (POST /v1/candidates/bulk)
Insert: Same as upsert — the Great Question API always performs an upsert by email, so new candidates are created and existing ones are updated
Update: Updates existing candidates only (PUT /v1/candidates/bulk). Candidates not found by email are skipped.

Batch Processing

Zeotap sends candidate data in batches of up to 100 records per API request. The Great Question bulk endpoints process records asynchronously as background tasks — the API returns a task object with a status that progresses from pending through processing to finished.

Failed batches are retried automatically with exponential backoff. If the candidate limit for your account is exceeded, the API returns a 422 error.

Rate Limits

Great Question does not publish explicit rate limits for the REST API. However, bulk operations are processed as background tasks, and submitting too many concurrent bulk requests may cause queueing or failures.

Zeotap automatically retries on HTTP 429 responses with exponential backoff
For large syncs, data is chunked into batches of 100 to avoid exceeding the undocumented candidate limit per request
If you encounter 422 errors about candidate limits, check your account plan limits under Settings > Account Management

Best Practices

Configure custom attributes first: Before syncing custom fields, ensure the corresponding candidate attributes are created in Great Question under Settings > Candidate Attributes
Use valid IANA timezones: The timezone field expects IANA timezone identifiers (e.g., America/New_York, Europe/London). Invalid timezones are silently ignored by the API
Manage opt-in status carefully: The opted_in field controls whether candidates can be contacted for research. Only set this to true for candidates who have explicitly consented to participate
Keep emails consistent: Email is the upsert key — ensure email addresses in your warehouse match the format used in Great Question to avoid creating duplicate candidate records
Monitor bulk task status: Bulk operations run asynchronously. Large syncs may take several minutes to fully process in Great Question

Troubleshooting

Authentication failed: invalid API key

Verify that your API key was copied correctly from Settings > API Tokens in Great Question. Ensure the key was generated by an account administrator on a Team or Enterprise plan. If the key has been revoked or the admin account deactivated, generate a new token.

422 Candidate limit exceeded

Your Great Question account has reached its candidate limit. Check your plan limits under Settings > Account Management > Subscription. You may need to upgrade your plan or remove inactive candidates before syncing additional records.

Custom attributes not appearing on candidates

Custom attributes must be created in Great Question before they can be populated via the API. Navigate to Settings > Candidate Attributes and create the attribute with the matching key name. Then re-run your sync.

Candidates created but fields are empty

Ensure your field mapping in Zeotap matches the exact field names expected by the Great Question API (name, phone_number, opted_in, timezone). Field names are case-sensitive.

Duplicate candidates created

Great Question upserts candidates by email address. If duplicate records are being created, verify that the email field mapping is correct and that email values are consistent (e.g., no extra whitespace, consistent casing). Great Question treats email matching as case-insensitive.

Sync appears successful but data not updated in Great Question

Bulk operations are processed asynchronously as background tasks. Allow a few minutes for the task to complete. If data still hasn’t updated, check that the candidate records exist in Great Question (for update sync mode) and that the mapped fields match configured candidate attributes.