API reference

A project is the product being researched. Studies hang off it, and contacts belong to it. Body: { name, website_url? }.

The only way to remove a project from your workspace. Refused with 409 while any study is active or launching — pause it first. Every remaining study is archived, then the project; both leave the dashboard but stay readable by id. Contacts are untouched, because consent attestations and opt-outs outlive the project they were collected for. Not reversible.

Body: { contacts: Contact[], consent: Consent }. Every request must carry a consent attestation; requests without one are rejected with 422.

A contact is a person on this product, not a participant in one study. Enrol them into a study with POST /v1/studies/{id}/enrolments. An opt-out is project-wide and permanent: it covers every study of that project, including ones created later.

A study is one interview effort against a project — one objective, one brief. Body: { project_id, name, brief } — see the Brief schema below. Returns 201 with the created study, 422 if validation fails, or 409 project_archived if the project has been archived — nothing can be created under an archived project. Adding contacts to an archived project, or enrolling anyone into an archived study, is refused the same way.

Add recurring: true and context_slots to run the study in repeated waves — the same people, interviewed again each round. Because a recurring study is quiet between waves by design, it is exempt from the exhaustion close and its quota counts per wave rather than across the whole study. That also means it needs some other way to finish, so it requires at least one of close_criteria.ends_at, close_criteria.spend_cap_cents or quota.

Briefs also accept two optional specificity levers: probes (up to 8 must-hit questions the interview cannot end without asking) and boundaries (up to 500 characters describing what the interviewer must not do).

Three optional fields decide how the study sounds. voice_id is an ElevenLabs voice id, for a study whose interviewer is a named character rather than a researcher; absent, every study shares the same default voice. first_message replaces the generated opening outright, and may carry {{slots}} declared in context_slots. consent_method only changes how the generated opening describes the consent it relies on — “you opted in” is true of a signup form and wrong for anything else. It never affects whether a contact may be interviewed; each contact's own consent attestation governs that.

Only the fields you send change: name, external_ref, brief, context_slots, close_criteria, quota and retention_days. brief is a whole Brief rather than a patch of one — GET the study, edit what you want, send it back. Merging a partial brief would mean you could set an optional field but never clear it again.

You can’t change project_id, recurring, status or research_mode. The project owns the contacts; recurring decides whether a quota counts per wave and whether a study can close on exhaustion, so changing it would reinterpret enrolments that already exist; status has its own launch and pause endpoints; and research mode is frozen once an interview has completed. Create a new study instead.

The rules are checked against the study as it would be after your change, not against the body you sent — so removing a context_slots entry the stored brief still uses is refused, the same as adding a slot nothing supplies.

Changing anything the interviewer is built from — the brief, the study name or retention_days — re-provisions the study’s voice agent, and the response carries agent_sync. If the provider rejects the update you get a 502 with study_updated: true: the study is saved but calls still use the previous voice and opening. Retry — PATCH replaces rather than accumulates, so repeating it is safe.

Body: { contact_ids: string[] }. The contacts must already exist on this study's project. A contact who has opted out is refused individually and reported in rejected — that refusal is enforced by the database and cannot be overridden, so the rest of the batch still enrols. It applies to every wave, including ones created later: a wave is a new round of contact, not new consent.

To run waves, send { enrolments: [{ contact_id, wave, context }] } instead. Exactly one of the two shapes must be present; a body carrying both is rejected rather than guessed at. The contact_ids shape is unchanged and enrols into the default wave.

wave is an opaque round label — "2026-08", "day-30". Nosie never parses it and never infers order from it; rounds are ordered by when their first enrolment was created, so your own naming scheme does not have to mean anything to us. The same person can be enrolled once per wave.

context carries per-person, per-wave values substituted into the interview, so two people in the same wave can be asked about different things. Every key must be declared in the study's context_slots and every declared slot must be supplied, or the enrolment is refused with 422 — an undeclared slot is never substituted, and the interviewer would read it aloud verbatim. Limits: 4,000 characters per value, 8,000 per enrolment.

external_ref is your own idempotency key for the enrolment, unique within the study. If a batch fails partway through, retry it unchanged: an entry whose external_ref already exists is returned in enrolled with the existing row's id — as { contact_id, wave, enrolment_id, external_ref } — instead of being inserted a second time, and outreach is not started again for it. Two entries in one request sharing an external_ref, or one reusing an external_ref that already belongs to a different contact, are refused individually via rejected rather than erroring.

If the study is active, outreach for these enrolments starts immediately — you do not need to launch again. The response includes scheduled and held; “held” means a contact's quota group is already full, so they stay pending and start automatically if you raise that target. This is what makes a continuously-refreshing cohort work without a weekly re-launch.

Contacts belong to a project, not a study. Create them with POST /v1/projects/{id}/contacts, then enrol them with POST /v1/studies/{id}/enrolments.

Per-stratum progress: completed vs target, which groups are full, how many contacts are held, and how many were screened out. Returns 404 when the study has no quota configured. Interviews beyond a target still complete and still count, but are absorbed by Nosie rather than billed to you.

Starts contacting every eligible contact within their local calling hours. Returns a launch summary.

The terminal state you choose, as opposed to completed, which a study reaches when a close criterion stops it. Allowed from draft, paused and completed; refused with 409 while outreach is running — pause first. Cancels any outreach still scheduled and hides the study from the dashboard. Interview content still expires on the study’s retention schedule. Not reversible.

Schedules exactly one call for this enrolment — nobody else is called — at the next time inside the study’s calling window. Body: { phone? } in E.164; it is written to the contact, whose modes are never changed — so no later launch or enrolment will call them. Omit it to use the number already on the contact (422 phone_required if there is none). Calling this endpoint asserts the participant asked, or agreed, to be phoned. Returns 202 { outcome: "call", scheduled_for }. When Nosie’s own rules refuse, it returns 202 { outcome: "skipped", reason } and writes nothing: opted_out, study_not_active, call_not_allowed_for_study (add call to the study’s allowed_modes), enrolment_finished, or call_already_scheduled.

A shortcut across contact create, enrolment and session mint. Body: { study_id, external_ref, contact: { …, consent }, mode, host_origin, wave?, context? }. contact.consent is the same mandatory consent attestation as on contact create. Returns 201 { embed_url, expires_at, enrolment_id }. A repeat call with the same external_ref in the same study returns 200 with reused: true and a fresh URL, ignoring the contact and consent fields. Nosie never invites or calls a participant enrolled this way — they are reached only through your embed. Refusals: 403 origin_not_allowed, 409 contact_opted_out, enrolment_finished, study_not_active, study_archived or project_archived, 422 context_slots_mismatch, and 503 study_launching with Retry-After.

Returns a short-lived URL to frame in your own page. Body: { mode: "web_voice"|"web_text", host_origin }. host_origin must be one of the frame_ancestors registered on your API key — it becomes the sole origin permitted to frame the session; the chosen mode is carried on the returned URL and preselected in the frame. An unregistered origin is refused with 403 origin_not_allowed. Refused with 409 if the contact has opted out (contact_opted_out), the enrolment has already finished (enrolment_finished), or the enrolment’s study is not active (study_not_active). Returns { embed_url, expires_at } on success.

Returns the transcript, summary, extracted attributes, quality signals, and outreach history.

For an opt-out the person gave you directly — by email, on a call, in person. Body: { channel: "email"|"phone"|"in_person"|"other", note? }. Same cascade as an SMS STOP: the contact is opted out of the whole project, permanently; scheduled outreach is cancelled; and contact.opted_out is delivered to your webhooks. Returns { opted_out: true, already_opted_out: false }, or already_opted_out: true if they already were and nothing changed. Nothing reverses it, including Nosie staff.

The signing secret is returned once, on creation. See Webhooks for events and signature verification.

Body: { active: boolean }. Pausing stops deliveries without deleting the endpoint or rotating its secret; events that occur while it is paused are not queued for later. Returns the webhook.