opportunities

Create /opportunities

Create an opportunity. Required: subject, total, and either contact (client UUID) or lead. Optional: stage, process, dates, description, currency, addresses, line items. organization, stage, and process use tenant defaults when omitted. Returns record with the detail projection.

POST

/opportunities

curl --request POST \
  --url https://default.hannacrm.app/api/v4/opportunities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "billing_city": "<string>",
  "billing_country": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "billing_state": "<string>",
  "billing_street": "<string>",
  "billing_zip": "<string>",
  "contact": "<string>",
  "contact_person": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currency": "<string>",
  "custom_fields": [
    {
      "slug": "<string>",
      "value": "<any>"
    }
  ],
  "date": "<string>",
  "description": "<string>",
  "discount_percent": "<string>",
  "discount_total": "<string>",
  "discount_type": "<string>",
  "due_date": "<string>",
  "include_shipping": "<string>",
  "items": [
    {
      "code": "<string>",
      "description": "<string>",
      "item": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "item_code": "<string>",
      "long_description": "<string>",
      "product_discount": 123,
      "qty": 123,
      "rate": 123,
      "unit": "<string>",
      "vat_percent": 123
    }
  ],
  "lead": "<string>",
  "lead_contact_person": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "process": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "shipping_city": "<string>",
  "shipping_country": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "shipping_state": "<string>",
  "shipping_street": "<string>",
  "shipping_zip": "<string>",
  "stage": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "subject": "<string>",
  "subtotal": "<string>",
  "total": "<string>",
  "total_tax": "<string>",
  "warehouse": "<string>"
}
'

{
  "record": {
    "assignees": [
      {}
    ],
    "billing_address": {
      "city": "<string>",
      "country": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zip": "<string>"
    },
    "client": [
      {}
    ],
    "contact_person": [
      {}
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "created_by": {
      "name": "<string>",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "currency": [
      {}
    ],
    "custom_fields": [
      {
        "slug": "<string>",
        "value": "<any>"
      }
    ],
    "date": "<string>",
    "datecreated": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "discount_percent": "<string>",
    "discount_total": "<string>",
    "discount_type": "<string>",
    "document_full_number": "<string>",
    "due_date": "<string>",
    "estimate_uuid": "<string>",
    "invoice_uuid": "<string>",
    "items": [
      {}
    ],
    "lead": [
      {}
    ],
    "lead_contact_person": [
      {}
    ],
    "organization": [
      {}
    ],
    "organization_name": "<string>",
    "planned_value": "<string>",
    "process": [
      {}
    ],
    "shipping_address": {
      "city": "<string>",
      "country": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zip": "<string>"
    },
    "stage": [
      {}
    ],
    "subject": "<string>",
    "subtotal": "<string>",
    "total": "<string>",
    "total_tax": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "updated_by": {
      "name": "<string>",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "uuid": "<string>",
    "warehouse": [

Authorizations

Authorizationstringheaderrequired

API key (Bearer token) created in Setup → API & MCP.

Body

billing_citystring

Billing city.

billing_countrystring

Billing country UUID.

billing_statestring

Billing state/region.

billing_streetstring

Billing street address.

billing_zipstring

Billing ZIP/postal code.

contactstring

Client UUID (required on create if lead is omitted).

contact_personstring

Client contact person UUID.

currencystring

Currency name (e.g. EUR). Uses tenant default when omitted on create.

custom_fieldsobject[]

Custom field values by slug.

Show child attributes

datestring

Opportunity date (Y-m-d).

descriptionstring

Opportunity description.

discount_percentstring

Discount percent.

discount_totalstring

Discount total amount.

discount_typestring

Discount type.

due_datestring

Planned sale / due date (Y-m-d).

include_shippingstring

Include shipping address on documents.

itemsobject[]

Opportunity line items to create.

Show child attributes

leadstring

Lead UUID (required on create if contact is omitted).

lead_contact_personstring

Lead contact person UUID.

organizationstring

Organization UUID. Optional; tenant default organization is used when omitted.

processstring

Process picklist value UUID. When omitted on create, the tenant default process is used.

shipping_citystring

Shipping city.

shipping_countrystring

Shipping country UUID.

shipping_statestring

Shipping state/region.

shipping_streetstring

Shipping street address.

shipping_zipstring

Shipping ZIP/postal code.

stagestring

Opportunity stage UUID. When omitted on create, the tenant default stage is used.

subjectstringrequired

Opportunity subject/title.

subtotalstring

Subtotal amount.

totalstringrequired

Total amount.

total_taxstring

Total tax amount.

warehousestring

Warehouse UUID (as listed by GET /warehouses), or its codename (e.g. vilnius). Name is also accepted but is neither unique nor stable.

any

Response

Success

recordobject

Fields enabled for this documentation instance (projection enabled: feature, option, subdomain, closures) plus account-level form field visibility. Role- and user-level field overrides are not applied here, so an API key whose staff user has such overrides may receive fewer fields. A disabled field is omitted from the response object entirely; a present key with a null value means the record simply has no value.

Show child attributes

Still need help? Ask the team