---
title: "Create customer descriptions (v3)"
method: POST
path: "/api/v1/business/customer-descriptions/create-v3"
tags: ["business"]
---

# Create customer descriptions (v3)

`POST /api/v1/business/customer-descriptions/create-v3`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/business/customer-descriptions/create-v3`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Describe the customers you want in plain text for one business profile (a member or an API key with business:write); Point11 reads it against the profile's customer mix (trigger types among it) and returns the review to confirm and, when it could interpret it, the Manual Profile card (version 3) to pass unchanged to business_manual_profiles_create_v2 (when it names employerAccounts, give those customers as rows to business_customers_generate, source rows, instead): its mixes, its customers' employers, and the group's given facts by the customer model's keys (a statement about the group, Location country and region codes, the household, a number such as annualRevenue, its labels). dropped names facts the card leaves out because its audiences' buyer type lacks them. A product the profile lacks may be named: products holds the Product mix with each new name, and the card omits its revenue mix until each is created with business_revenue_lines_create_v2 and set on the card by id. Anything it leaves unnamed comes from the Profile.

## Headers

- `Point11-Organization` string, uuid
- `Idempotency-Key` string, uuid, required

## Request body

- BusinessCustomerDescriptionsCreateV3Request
  - `businessProfileId` string, uuid, required
  - `description` string, required
  - `profileName` string, required: The name the resulting Manual Profile takes
  - `contentLanguage` 'en' | 'fr' | 'es' | 'de' | 'pt' | 'ja' | 'it' | 'nl' | 'sv' | 'cs' | 'pl' | 'tr' | 'ru' | 'zh-Hans' | 'ko' | 'ar', required

## Response `200`

Success.

- BusinessCustomerDescriptionsCreateV3Response
  - `descriptionId` string, uuid, required
  - `outcome` 'interpreted' | 'no_customers_described' | 'language_unsupported', required
  - `review` object[], required
    - `dimensionId` 'job_mix' | 'trigger_type_mix' | 'audience_mix' | 'channel_mix' | 'revenue_mix' | 'intent_stage_mix' | 'age_mix' | 'gender_mix' | 'education_mix' | 'household_income_mix' | 'urbanicity_mix' | 'regional_mix' | 'life_stage_mix' | 'language_mix' | 'occupation_mix' | 'company_size_mix' | 'buyer_role_mix' | 'seniority_mix' | 'job_title_mix' | 'years_in_role_mix', required
    - `label` string, required
    - `outcome` 'mapped' | 'new' | 'inherited', required
    - `selections` object[], required
      - `label` string, required
      - `weightPct` number, required
      - `kind` 'ref' | 'authored', required
      - `templateId` string, nullable, required
      - `purchaseMode` 'on_premises' | 'local_service_area' | 'remote_direct' | 'third_party' | 'sales_led', nullable, required
      - `fit` 'exact' | 'nearest', required
      - `said` string, nullable, required
    - `phrase` string, nullable, required
  - `unresolved` object[], required
    - `phrase` string, required
    - `explanation` string, required
  - `manifest` BusinessCard, nullable, required
    - `version` 3, required
    - `baseGenerationProfileId` string, required
    - `baseSourceHash` string, required
    - `profileName` string, required
    - `overrides` object, required
    - `employerAccounts` object[]
      - `name` string, required
      - `domain` string, nullable, required
    - `givenFacts` DiscoveryGivenFacts
      - `age` object
        - `value` number, nullable, required
        - `band` string, nullable, required
      - `location` object
        - `countryCode` string, required
        - `subdivisionCode` string, nullable, required
        - `locality` string, nullable
        - `postalCode` string, nullable
      - `household` union
        - object
          - `adults` integer, nullable, required
          - `children` integer, nullable, required
          - `pets` integer, nullable, required
        - object
          - `statement` string, required
      - `householdIncome` object
        - `value` number, nullable, required
        - `band` string, nullable, required
      - `jobTitle` string
      - `employer` string
      - `yearsInRole` object
        - `value` number, required
      - `companySize` object
        - `value` number, nullable, required
        - `band` string, nullable, required
      - `annualRevenue` object
        - `value` number, required
      - `stakeholders` string
      - `budget` string
      - `constraints` string
      - `situation` string
      - `trigger` string
      - `functionalNeed` string
      - `emotionalNeed` string
      - `socialNeed` string
      - `desiredOutcome` string
      - `labels` string[]
  - `dropped` string[], required
  - `products` union[], nullable, required: The customers' Product mix when the description names a product the business profile does not have yet (kind new, with the name it gives and the words that name it), each product with its share (weightPct); the card then leaves its revenue mix out. Create each new product with business_revenue_lines_create_v2, then set the card's overrides.revenue_mix to these shares, each product as a ref (a new one by the created revenue line's id and name), and pass that card to business_manual_profiles_create_v2. Null when every product it names is the profile's own
    - union
      - object
        - `kind` 'ref', required
        - `id` string, required
        - `label` string, required
        - `weightPct` number, required
      - object
        - `kind` 'new', required
        - `name` string, required
        - `phrase` string, required
        - `weightPct` number, required

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `402`: Billing refused the write: the code names the reason and `details.reason` carries it.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/5241805fe425?raw)