Deal & ticket forms

Save with a template

Saves a deal or a ticket and its open blocks in one request. Deal: company (created as a prospect if missing; a similar name returns 409 similar — pick the existing record or send confirm_new: true), name, type, owner, value, close date; blocks product and quantity, quote (recorded in offer history), forecast, source, decision makers (contact_ids), trial, first tasks (tasks), extra fields (cf) and custom object links (co). Without stage rules the template's starting stage is used. Ticket: the company may be unregistered (the ticket keeps the company name), contact (contact_id or contact_name + email + phone), subject, description, type (kind, the template's type when empty), priority (standard resolution time; the template's time when the priority matches the template), assignee (without assigned_to the template's rule applies: the team member with the fewest open tickets, the account owner, the creator or a given user), category; blocks product / lot, order, project, channel, site visit (a task for the assignee) and extra fields. Without blocks the template's open blocks and defaults are applied. An empty required block returns 400 invalid.

POST/api/v1/forms/{kind}

Authorization

Authorizationheaderrequired

Bearer token: API key (sk_…), OAuth access token (mcp_…) or mobile session (xk_…).

Scope: crm.write

Path parameters

kindstringrequired

Form.

Valuesoppticket

Body application/json

template_idintegeroptional

Template (/forms/{kind}/config → templates[].id); the user's default when empty.

customer_id / customerinteger / stringoptional

Company id or name (one is required for a deal).

blocksarray<string>optional

Open blocks (e.g. urun, teklif, gorev, co:uretim_hatti); their fields go in the body under blocks[].fields[].k keys (product, potential_kg, offer_price …).

name / type / user_id / value / currency / close_datestringoptional

Deal core: name, type, owner, annual value, currency, close date (YYYY-MM-DD).

subject / detail / kind / priority / category / assigned_tostringoptional

Ticket core: subject (required for a ticket), description, type, priority (Düşük, Normal, Yüksek, Acil), category, assignee.

contact_idsarray<integer>optional

The deal's decision makers (the company's contacts).

tasksarrayoptional

First tasks: "Numune gönder | 5 | Görev" (title | days | kind) or {title, days, kind}.

cfobjectoptional

Extra fields: {field key: value} (Settings › Custom fields).

coobjectoptional

Custom object links: {object key: record id}.

confirm_newbooleanoptional

Create even if a similarly named company exists.

Errors

HTTP	error	Meaning
`400`	`invalid`	Missing or invalid field (`message` explains).
`409`	`similar`	Similar names exist (`similar`); send `confirm_new: true` to create anyway.
`403`	`module`	The module is off in the licence or for the user.
`404`	`not_found`	Record not found.

Request

curl -X POST https://ornek.solk.app/api/v1/forms/opp \
  -H "Authorization: Bearer $SOLK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "template_id": 1,
  "customer_id": 1,
  "name": "Hat 3 şişirme projesi",
  "currency": "EUR",
  "close_date": "2027-01-04",
  "blocks": [
    "urun",
    "teklif",
    "gorev",
    "co:uretim_hatti"
  ],
  "product": "PU-SL 200 Solventsiz Laminasyon Yapıştırıcısı",
  "potential_kg": "15000",
  "offer_price": "1,85",
  "payment_days": "60",
  "tasks": [
    "Numune gönder | 5 | Görev",
    "Teklifi ara | 10 | Arama"
  ],
  "co": {
    "uretim_hatti": 1
  }
}'

const res = await fetch("https://ornek.solk.app/api/v1/forms/opp", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SOLK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "template_id": 1,
    "customer_id": 1,
    "name": "Hat 3 şişirme projesi",
    "currency": "EUR",
    "close_date": "2027-01-04",
    "blocks": [
      "urun",
      "teklif",
      "gorev",
      "co:uretim_hatti"
    ],
    "product": "PU-SL 200 Solventsiz Laminasyon Yapıştırıcısı",
    "potential_kg": "15000",
    "offer_price": "1,85",
    "payment_days": "60",
    "tasks": [
      "Numune gönder | 5 | Görev",
      "Teklifi ara | 10 | Arama"
    ],
    "co": {
      "uretim_hatti": 1
    }
  }),
});
const data = await res.json();

import os, requests

r = requests.post(
    "https://ornek.solk.app/api/v1/forms/opp",
    headers={"Authorization": f"Bearer {os.environ['SOLK_API_KEY']}"},
    json={
        "template_id": 1,
        "customer_id": 1,
        "name": "Hat 3 şişirme projesi",
        "currency": "EUR",
        "close_date": "2027-01-04",
        "blocks": [
            "urun",
            "teklif",
            "gorev",
            "co:uretim_hatti"
        ],
        "product": "PU-SL 200 Solventsiz Laminasyon Yapıştırıcısı",
        "potential_kg": "15000",
        "offer_price": "1,85",
        "payment_days": "60",
        "tasks": [
            "Numune gönder | 5 | Görev",
            "Teklifi ara | 10 | Arama"
        ],
        "co": {
            "uretim_hatti": 1
        }
    },
)
print(r.json())

Response

{
  "customer_created": false,
  "message": "Fırsat açıldı: #55 Hat 3 şişirme projesi · Alize Paketleme San. ve Tic. A.Ş.",
  "ok": true,
  "opp": {
    "bant": 0,
    "base_currency": "EUR",
    "close_date": "2027-01-04",
    "cur_sym": "€",
    "currency": "EUR",
    "customer": "Alize Paketleme San. ve Tic. A.Ş.",
    "customer_city": "İstanbul",
    "customer_id": 1,
    "days_in_stage": 0,
    "detail_status": "",
    "fc": "Pipeline",
    "health": {
      "grade": "success",
      "label": "sağlıklı",
      "score": 100
    },
    "health_color": "g",
    "health_manual": false,
    "health_note": "",
    "id": 55,
    "initials": "AP",
    "is_account": false,
    "is_open": true,
    "last_update": "2026-10-06",
    "lifetime_left": 180,
    "line": "",
    "name": "Hat 3 şişirme projesi",
    "next_step": "Karar verici / yetkili kişiyi belirle (Authority)",
    "offer_price": 1.85,
    "owner": {
      "full_name": "Deniz Aksoy",
      "id": 1,
      "role": "admin",
      "role_label": "Yönetici",
      "username": "admin"
    },
    "payment_days": 60,
    "potential_kg": 15000.0,
    "prob": 0.1,
    "probability": null,
    "product": "PU-SL 200 Solventsiz Laminasyon Yapıştırıcısı",
    "product_id": 1,
    "pu": "€/kg",
    "rid": "006ib7dvC23Bvtw",
    "sla_days": 30,
    "sla_left": 30,
    "source": "Bayi / distribütör",
    "stage": "Qualify",
    "stage_label": "Qualify",
    "start_date": "2026-10-06",
    "trend": "",
    "trend_label": "Otomatik",
    "type": "Yeni Müşteri",
    "unit": "kg",
    "unit_code": "kg",
    "value": 333000.0,
    "value_base": 333000.0,
    "value_short": "333K"
  },
  "parts": [
    "fırsat #55",
    "teklif kaydı"
  ],
  "tasks": 2,
  "template_id": 1
}

Example responses were captured from a v45d installation running sample data; lists are shortened to two items.