Skip to main content
POST
/
create-configuration
Create a Configuration
curl --request POST \
  --url https://api.heify.com/create-configuration \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "tag": "Customer Support - Technical Issues",
  "vocabulary": [
    "firewall",
    "VPN",
    "authentication"
  ],
  "extraction_fields": [
    {
      "name": "ticket_id",
      "type": "string",
      "description": "The support ticket number mentioned in the conversation"
    },
    {
      "name": "issue_resolved",
      "type": "boolean",
      "description": "Whether the technical issue was resolved during the call"
    }
  ],
  "webhooks": {
    "success_url": "https://myservice.com/webhooks/transcription/success",
    "error_url": "https://myservice.com/webhooks/transcription/error"
  },
  "summary": true,
  "custom_summary": "Focus on the technical issue reported and the resolution steps taken.",
  "summary_language": "en",
  "analytics_language": "en"
}
'
{
  "data": {
    "message": "Configuration created successfully",
    "configuration_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
}
For full details on the Configuration object, see Configuration.
Each account has a maximum of 20 configurations. Plan your templates to cover multiple use cases — you cannot exceed this limit.
tag is permanent — it cannot be changed after creation. Choose a clear, descriptive name.
The more specific the description on each extraction field, the more accurate the AI extraction will be. See Best Practices for Extraction Fields.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
tag
string
required

A descriptive name for the configuration (e.g., "Sales Call Analysis"). Permanent — cannot be changed after creation.

Maximum string length: 255
​
vocabulary
string[]

Custom terms (brand names, acronyms, technical words) that improve transcription accuracy. Example: ["Heify", "NLP", "SLA"].

​
extraction_fields
object[]

Structured data fields for the AI to extract from the transcript. Maximum 10 fields. Field names are auto-normalized on creation: lowercased and special characters replaced with _ (e.g. "Customer ID" → "customer_id").

Maximum array length: 10
​
webhooks
object

URLs for receiving completion/failure notifications via POST requests.

​
summary
boolean
default:false

If true, an AI summary of the transcription will be generated.

​
custom_summary
string

A custom prompt that guides how the AI generates the summary (e.g., "Focus on customer complaints and resolution steps"). Only takes effect when summary is true.

Maximum string length: 300
​
summary_language
string
default:df

Language for the generated summary. Use "df" for automatic detection based on the audio language. See Supported Languages.

​
analytics_language
string
default:df

Language for analytics reports. Use "df" for automatic detection. See Supported Languages.

Response

201 - application/json

Configuration created successfully.

​
data
object