> ## Documentation Index > Fetch the complete documentation index at: https://technologychecker.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create audience API > Create an audience by uploading a domain list (free) or by computing a recipe from company, technology or signal criteria (1 credit). ## Frequently asked questions Upload a list when you already know the domains: a customer export, a conference attendee list, a portfolio. Use a recipe when you want us to find them: every US ecommerce company of 51–200 people, every domain running Shopify but not WooCommerce, or everyone who adopted a technology in the last 90 days. Uploading a list is free. Computing a recipe costs 1 credit, charged after the build completes rather than upfront. A build that fails costs nothing. A snapshot, taken when the audience is built. This is deliberate — it makes reporting reproducible and cheap. To refresh a computed audience, `PATCH` it with its definition again, which rebuilds and charges another credit. The `membership_at` field tells you how old the snapshot is. The build is rejected with a 403 that reports `matched_total` and your `cap`. It is never silently sampled, because a partial audience would make every downstream number wrong. Narrow the recipe or upgrade. Domains are lowercased, stripped of scheme, path and a leading `www.`, then deduped before the cap is checked — so pasting a raw export with duplicates does not eat your quota. Anything that still is not a valid domain comes back in `rejected_domains` with a sample of the offending values. Yes. Firmographic keys can be added alongside any `kind`. `{"kind": "technology", "technologies": {"and": [2184]}, "country": "united states", "employees": "51-200"}` builds US mid-market companies running Shopify. ## OpenAPI ````yaml POST /v1/segments openapi: 3.1.0 info: title: TechnologyChecker API description: >- Discover technology stacks, track market trends, and enrich data with company intelligence. version: 1.0.0 contact: name: TechnologyChecker Support email: support@technologychecker.io url: https://technologychecker.io servers: - url: https://api.technologychecker.io description: Production security: - bearerAuth: [] tags: - name: Domain technologies description: Look up technologies detected on any domain - name: Technology data description: Search, look up, and get details on tracked technologies - name: Market intelligence description: Technology stats, trends, and market share - name: Company data description: Firmographic and company intelligence - name: Live detection description: Real-time technology detection with browser rendering - name: Signals description: >- Intent signals derived from technology state transitions: who adopted, who churned, who switched, and who has a gap in their stack. - name: Alerts description: >- Saved signal queries delivered to your webhook. Every signal you can query, you can subscribe to. - name: Audiences description: >- Saved groups of domains — uploaded lists or computed recipes — that you can profile, slice and monitor. - name: Lead lists description: >- Build and export targeted domain lists combining technology detection with company data. paths: /v1/segments: post: tags: - Audiences summary: Create audience API description: >- Create an audience in one of two ways. **Upload a list** — pass `type: "list"` and a `domains` array. Domains are lowercased, stripped of scheme, path and a leading `www.`, then deduped before the plan cap is checked, so pasting a raw export with duplicates does not eat your cap. Uploads are **free**. **Compute a recipe** — pass a `definition` with a `kind` of `firmo`, `technology` or `signal`. The recipe is materialized into a membership snapshot at create time and **costs 1 credit**, charged after the build completes. A build that exceeds your plan's member cap is rejected rather than sampled, so an audience is always complete. Membership is a point-in-time snapshot, not a live query. Re-send the definition with `PATCH` to refresh it. operationId: createAudience requestBody: required: true content: application/json: schema: oneOf: - type: object title: Uploaded list required: - name - type - domains properties: name: type: string maxLength: 120 example: YC W25 portfolio type: type: string enum: - list domains: type: array items: type: string description: >- 1 to your plan's cap: 100 on Free, 2,500 on Pro, 10,000 on Scale, 100,000 on Enterprise. example: - acme.com - example.com - type: object title: Computed recipe required: - name - definition properties: name: type: string maxLength: 120 example: US ecommerce, 51-200 definition: $ref: '#/components/schemas/AudienceDefinition' example: name: US ecommerce, 51-200 definition: kind: technology technologies: and: - 2184 country: united states employees: 51-200 responses: '201': description: Audience created, with corpus coverage content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: segment: $ref: '#/components/schemas/Audience' coverage: type: object description: >- How many members we hold detection data for. Computed audiences are in-corpus by construction. properties: in_corpus: type: integer nullable: true example: 5114 total: type: integer example: 5914 rejected_domains: type: object description: Present when uploaded entries failed normalization. properties: count: type: integer example: 2 sample: type: array items: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/QueryTimeout' components: schemas: AudienceDefinition: type: object description: >- A computed audience recipe. `kind` selects which shape applies; firmographic keys may be combined with any kind to narrow it further. properties: kind: type: string enum: - firmo - technology - signal default: firmo description: >- `firmo` builds from company attributes alone. `technology` builds from a technology expression. `signal` builds from a saved adoption or churn query. technologies: type: object description: >- Required for `kind: technology`. Combine technology ids at domain grain. properties: or: type: array items: type: integer description: Domains running any of these. and: type: array items: type: integer description: Domains running all of these. and_not: type: array items: type: integer description: Domains running none of these. example: and: - 2184 and_not: - 402 signal: type: object description: >- Required for `kind: signal`. Only adoption and churn queries can be saved as audiences. properties: type: type: string enum: - adoption - churn technology_id: type: integer description: Exactly one of `technology_id` or `category_id`. category_id: type: integer window: type: integer default: 30 minimum: 1 maximum: 365 min_confidence: type: number format: float default: 0.5 include_first_seen: type: boolean default: false example: type: adoption technology_id: 2184 window: 90 country: type: string example: united states city: type: string state: type: string industry: type: string industry_code: type: integer employees: type: string example: 51-200 company_type: type: string founded_min: type: integer founded_max: type: integer has_email: type: boolean has_phone: type: boolean social: type: string language: type: string web_country: type: string Audience: type: object properties: id: type: string example: seg_8f3a2c1b name: type: string example: YC W25 portfolio type: type: string enum: - filter - list description: >- `list` for an uploaded set of domains, `filter` for a computed recipe. Immutable. example: list kind: type: string enum: - upload - firmo - technology - signal description: >- How membership was produced. `upload` is a pasted list; the rest are computed recipes. example: upload definition: type: object nullable: true description: The recipe that produced membership. `null`-ish for uploads. domain_count: type: integer description: Members in the current generation. example: 5914 status: type: string enum: - uploading - ready - failed example: ready membership_at: type: string nullable: true description: >- When membership was last built. Computed audiences are point-in-time snapshots — re-send the definition to refresh. example: '2026-07-29T10:14:02.000Z' matched_total: type: integer nullable: true crawl_cadence: type: string enum: - none - weekly - daily default: none example: none last_dispatched_at: type: string nullable: true created_at: type: string example: '2026-07-29T10:12:00.000Z' updated_at: type: string example: '2026-07-29T10:14:02.000Z' ApiError: type: object properties: success: type: boolean example: false error: type: object properties: code: type: string example: UNAUTHORIZED message: type: string example: Missing or invalid API key responses: BadRequest: description: Invalid or missing parameters content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: VALIDATION_ERROR message: >- Provide exactly one scope: technology_id, technology or category_id. Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiError' PaymentRequired: description: Not enough credits, or the plan does not include this feature content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: INSUFFICIENT_CREDITS message: Insufficient credits for this request. details: required: 1 available: 0 Forbidden: description: The plan does not allow this action, or a plan limit was reached content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: PLAN_LIMIT message: >- Your plan allows up to 2 saved audiences. Delete one to create another. NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ApiError' RateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiError' QueryTimeout: description: >- The query exceeded the 30-second server-side limit. Narrow the query and retry. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: success: false error: code: SEGMENT_QUERY_TIMEOUT message: The segment query exceeded the 30s server-side limit. details: suggestion: >- Narrow the segment — add an employees band, industry, or city — and try again. securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key in format `tapi_live_[32-char]` (live) or `tapi_test_[32-char]` (test) ````