Deal erstellen
Erstellt einen Deal. Pflicht: pipelines_id. Optional entweder einen Kontakt oder einen Partner verknüpfen — per ID oder als nested Create-Objekt (nie beide Formen). Optional phase_id (Alias pipelines_phases_id) setzt die Startphase; muss zu pipelines_id gehören (Standard: Startphase).
Hinweis
So senden Sie Kontakt / Partner
Pro Request eine Verknüpfungsart wählen: entweder Kontakt oder Partner — nie beides. Kontakt — genau eines von: • contacts_id / contact_id (muss in der DB existieren) • contact-Objekt (mindestens firstname, lastname oder display_name) Partner — genau eines von: • partners_id / partner_id (muss in der DB existieren) • partner-Objekt (partner.name ist Pflicht) Nested emails / phones / addresses werden auf dem gewählten nested Objekt unterstützt.
Bestehende Kontakt-ID
{
"pipelines_id": 1,
"phase_id": 3,
"name": "Solar Project Mustermann",
"contacts_id": 12
}
Bestehende Partner-ID
{
"pipelines_id": 1,
"name": "Solar Project Muster GmbH",
"partners_id": 5
}
Nested Kontakt anlegen
{
"pipelines_id": 1,
"name": "Solar Project Nested Contact",
"contact": {
"firstname": "Max",
"lastname": "Mustermann",
"display_name": "Max Mustermann",
"emails": [
{ "email": "max.mustermann@example.com", "is_primary": true }
]
}
}
Nested Partner anlegen
{
"pipelines_id": 1,
"name": "Solar Project Nested Partner",
"partner": {
"name": "Muster GmbH",
"emails": [
{ "email": "billing@muster-gmbh.example", "is_primary": true }
],
"addresses": [
{
"address_line_1": "Beispielweg 10",
"zip_code": "80331",
"city": "München",
"countries_id": 82,
"is_primary": true
}
]
}
}
post
/api/v1/deals
Sicherheit
Parameter
| Name | In | Typ | Details | |
|---|---|---|---|---|
Idempotency-Key |
header |
string
|
Optional | Unique key for safe create retries (Make/Zapier/n8n). Replays the stored successful response for the same key + request body within 7 days. |
Request-Body Pflicht
application/json
Schema
{
"type": "object",
"required": [
"pipelines_id"
],
"description": "Link either a contact or a partner (not both). For the chosen side, send either an existing id or a nested create object — never both forms. Optional `phase_id` sets the starting pipeline phase (must belong to pipelines_id).\n",
"properties": {
"pipelines_id": {
"type": "integer"
},
"phase_id": {
"type": "integer",
"description": "Starting pipeline phase id (alias `pipelines_phases_id`). Must belong to pipelines_id. Defaults to start phase."
},
"name": {
"type": "string",
"nullable": true
},
"tags_id": {
"type": "integer",
"nullable": true
},
"solar_sites_id": {
"type": "integer",
"nullable": true
},
"contacts_id": {
"type": "integer",
"description": "Existing contact id (alias `contact_id`). Mutually exclusive with `contact` and with any partner link."
},
"partners_id": {
"type": "integer",
"description": "Existing partner id (alias `partner_id`). Mutually exclusive with `partner` and with any contact link."
},
"contact": {
"allOf": [
{
"type": "object",
"description": "Contact upsert payload. Nested `addresses` / `phones` / `emails` create or sync nested emails, phones, and addresses on the contact.\n",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
},
"owner_users_id": {
"type": "integer"
},
"salutations_id": {
"type": "integer"
},
"titles_id": {
"type": "integer"
},
"firstname": {
"type": "string"
},
"lastname": {
"type": "string"
},
"display_name": {
"type": "string"
},
"source": {
"type": "string",
"example": "api"
},
"status": {
"type": "string",
"example": "active"
},
"lifecycle_stage": {
"type": "string"
},
"website": {
"type": "string"
},
"language_code": {
"type": "string"
},
"timezone": {
"type": "string"
},
"birthday": {
"type": "string",
"format": "date"
},
"national_id": {
"type": "string"
},
"tax_number": {
"type": "string"
},
"vat_number": {
"type": "string"
},
"preferred_channel": {
"type": "string"
},
"is_customer": {
"type": "boolean"
},
"is_vendor": {
"type": "boolean"
},
"is_lead": {
"type": "boolean"
},
"do_not_contact": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
},
"notes": {
"type": "string"
},
"meta": {
"type": "object",
"additionalProperties": true
},
"addresses": {
"type": "array",
"items": {
"type": "object",
"description": "Address fields for create/update (linked to a contact or partner).",
"required": [
"address_line_1"
],
"properties": {
"id": {
"type": "integer",
"description": "Existing address id (update only)"
},
"label": {
"type": "string"
},
"attention": {
"type": "string"
},
"address_line_1": {
"type": "string"
},
"address_line_2": {
"type": "string"
},
"zip_code": {
"type": "string"
},
"city": {
"type": "string"
},
"district": {
"type": "string"
},
"state": {
"type": "string"
},
"country_code": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"countries_id": {
"type": "integer"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"delivery_instructions": {
"type": "string"
},
"is_primary": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
}
}
}
},
"phones": {
"type": "array",
"items": {
"type": "object",
"description": "Phone fields for create/update (linked to a contact or partner).",
"required": [
"number"
],
"properties": {
"id": {
"type": "integer",
"description": "Existing phone id (update only)"
},
"contact_phone_types_id": {
"type": "integer"
},
"label": {
"type": "string"
},
"country_code": {
"type": "string"
},
"number": {
"type": "string"
},
"extension": {
"type": "string"
},
"e164_number": {
"type": "string"
},
"is_primary": {
"type": "boolean"
},
"is_whatsapp": {
"type": "boolean"
},
"is_sms_enabled": {
"type": "boolean"
},
"is_verified": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
}
}
}
},
"emails": {
"type": "array",
"items": {
"type": "object",
"description": "Email fields for create/update (linked to a contact or partner).",
"required": [
"email"
],
"properties": {
"id": {
"type": "integer",
"description": "Existing email id (update only)"
},
"contact_email_types_id": {
"type": "integer"
},
"label": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"is_primary": {
"type": "boolean"
},
"is_verified": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
}
}
}
}
}
}
],
"description": "Create a new contact and link it. Requires firstname, lastname, or display_name. Mutually exclusive with contacts_id and with any partner link.\n"
},
"partner": {
"allOf": [
{
"type": "object",
"required": [
"name"
],
"description": "Partner upsert payload. Nested `addresses` / `phones` / `emails` create or sync nested emails, phones, and addresses. Legacy flat street/email/phone fields are rejected.\n",
"properties": {
"name": {
"type": "string"
},
"code": {
"type": "string"
},
"tax_number": {
"type": "string"
},
"ust_id": {
"type": "string"
},
"notes": {
"type": "string"
},
"lexware_contact_id": {
"type": "string"
},
"addresses": {
"type": "array",
"items": {
"type": "object",
"description": "Address fields for create/update (linked to a contact or partner).",
"required": [
"address_line_1"
],
"properties": {
"id": {
"type": "integer",
"description": "Existing address id (update only)"
},
"label": {
"type": "string"
},
"attention": {
"type": "string"
},
"address_line_1": {
"type": "string"
},
"address_line_2": {
"type": "string"
},
"zip_code": {
"type": "string"
},
"city": {
"type": "string"
},
"district": {
"type": "string"
},
"state": {
"type": "string"
},
"country_code": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"countries_id": {
"type": "integer"
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"delivery_instructions": {
"type": "string"
},
"is_primary": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
}
}
}
},
"phones": {
"type": "array",
"items": {
"type": "object",
"description": "Phone fields for create/update (linked to a contact or partner).",
"required": [
"number"
],
"properties": {
"id": {
"type": "integer",
"description": "Existing phone id (update only)"
},
"contact_phone_types_id": {
"type": "integer"
},
"label": {
"type": "string"
},
"country_code": {
"type": "string"
},
"number": {
"type": "string"
},
"extension": {
"type": "string"
},
"e164_number": {
"type": "string"
},
"is_primary": {
"type": "boolean"
},
"is_whatsapp": {
"type": "boolean"
},
"is_sms_enabled": {
"type": "boolean"
},
"is_verified": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
}
}
}
},
"emails": {
"type": "array",
"items": {
"type": "object",
"description": "Email fields for create/update (linked to a contact or partner).",
"required": [
"email"
],
"properties": {
"id": {
"type": "integer",
"description": "Existing email id (update only)"
},
"contact_email_types_id": {
"type": "integer"
},
"label": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"is_primary": {
"type": "boolean"
},
"is_verified": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
}
}
}
}
}
}
],
"description": "Create a new partner and link it. Mutually exclusive with partners_id and with any contact link.\n"
}
}
}
Antworten
201
Deal erstellt
application/json
{
"allOf": [
{
"title": "API envelope",
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string",
"nullable": true
},
"errors": {
"nullable": true
},
"meta": {
"type": "object",
"nullable": true,
"additionalProperties": true
}
}
},
{
"type": "object",
"properties": {
"data": {
"title": "Deal",
"type": "object",
"required": [
"id",
"is_active"
],
"properties": {
"id": {
"type": "integer"
},
"deals_unique_id": {
"type": "string",
"nullable": true
},
"name": {
"type": "string",
"nullable": true
},
"is_active": {
"type": "boolean"
},
"deal_status": {
"type": "string",
"nullable": true
},
"pipelines_id": {
"type": "integer",
"nullable": true
},
"pipeline_name": {
"type": "string",
"nullable": true
},
"partners_id": {
"type": "integer",
"nullable": true
},
"partner_name": {
"type": "string",
"nullable": true
},
"contacts_id": {
"type": "integer",
"nullable": true
},
"contact_display_name": {
"type": "string",
"nullable": true
},
"phase_id": {
"type": "integer",
"nullable": true
},
"phase_name": {
"type": "string",
"nullable": true
},
"tags_id": {
"type": "integer",
"nullable": true
},
"solar_sites_id": {
"type": "integer",
"nullable": true
},
"started_on": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
}
}
]
}
401
Missing or invalid API key
application/json
{
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Missing API key (X-Api-Key)"
}
}
}
422
Validation failed
application/json
{
"title": "API envelope",
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string",
"nullable": true
},
"errors": {
"nullable": true
},
"meta": {
"type": "object",
"nullable": true,
"additionalProperties": true
}
}
}