Docs

API reference

The Nosie API is a small REST surface — seven resources over plain JSON — for creating interview projects, adding consented contacts, launching outreach, and reading results. Base URL: https://nosie.app/api/v1. The machine-readable OpenAPI 3.1 spec lives at /api/v1/openapi.json.

Last updated: 6 July 2026

Authentication & limits

Authenticate every request with an API key in the Authorization header. Keys are created in the dashboard under Developers, shown once, and prefixed nk_live_.

Authorization: Bearer nk_live_...

Rate limit: 60 requests/minute per key. Exceeding it returns 429 with a Retry-After: 60 header.
Content type: application/json for all request bodies.
IDs are UUIDs.

Endpoints

POST/v1/projects

Create a project

Body: { name, brief } — see the Brief schema below. Returns 201 with the created project, or 422 if validation fails.

GET/v1/projects/{id}

Get a project

POST/v1/projects/{id}/contacts

Add contacts (consent required)

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

If the project is active, outreach for these contacts 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.

GET/v1/projects/{id}/contacts

List contacts

GET/v1/projects/{id}/quota

Live quota state

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 project has no quota configured. Interviews beyond a target still complete and still count, but are absorbed by Nosie rather than billed to you.

POST/v1/projects/{id}/launch

Launch outreach

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

POST/v1/projects/{id}/pause

Pause outreach

GET/v1/contacts/{id}/result

Get a contact's interview result

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

GET/v1/webhooks

List webhooks

POST/v1/webhooks

Create a webhook

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

DELETE/v1/webhooks/{id}

Delete a webhook

Brief schema

The brief is the interview's contract: what to learn, from whom, and exactly which attributes to extract.

Field	Type	Description
objective *	string	What you want to learn.
audience_description *	string	Who is being interviewed.
key_topics *	string[]	3–6 topics the conversation must cover.
success_criteria *	string	What a successful interview produces.
identity_label *	string	Who Nosie says it's calling on behalf of.
tone	string	Conversation tone. Default: "warm, concise, respectful".
allowed_modes *	("call"\|"sms"\|"email")[]	Channels Nosie may use.
timebox_seconds	integer	Interview length cap. Default: 180.
output_schema *	object	Map of attribute key → { type: string\|number\|boolean, description }. Extracted answers are returned under these exact keys.
schedule	object	Optional scheduling constraints.

Contact schema

Field	Type	Description
name *	string	Contact's name.
phone	string	E.164 format, e.g. +64211234567. Required for call/sms modes.
email	string	Required for email mode.
allowed_modes *	("call"\|"sms"\|"email")[]	Channels this contact may be reached on.
timezone	string	IANA timezone, e.g. Pacific/Auckland. Used for local calling hours.
country	"NZ" \| "AU" \| "US"	Contact's country.
custom_fields	object	String key-value pairs carried through to results.

Required on every contact-create request. Requests without a valid consent attestation are rejected with 422. Opt-outs are permanent and cannot be reversed via the API.

Field	Type	Description
attested *	true	Literal true — you attest these contacts agreed to be contacted.
basis *	string	How consent was collected, minimum 10 characters. Stored in the consent audit log.
method *	enum	One of: signup_form, verbal, written, existing_relationship, other.

Errors

Errors are JSON: { "error": "<message>" }.

Field	Type	Description
401	unauthorized	Missing, invalid, or revoked API key.
404	not found	Resource doesn't exist or belongs to another account.
422	validation	Body failed validation — including any contact-create without a consent attestation.
429	rate limited	More than 60 requests/minute. Retry after the Retry-After header (60s).

Machine-readable versions: OpenAPI spec · llms.txt · llms-full.txt. Questions? hello@nosie.app