# createDeal

Create a deal in a pipeline stage. Requires title and stageId (listPipelineStages); optional priceCents, closeDate, contact/property/user ids. Entering the stage can text or email a real person, as an updateDeal move can: confirm as updateDeal says. The stage must be in a pipeline owned by or shared with your organization, and any linked contactIds/userIds must belong to your organization. userIds is the deal’s TEAM, and My deals shows only deals the viewer is on. The app’s Create Deal form puts its creator on the team, so when acting for a person include the key owner (getMyProfile) unless they name a different team. MONEY AND CUSTOM FIELDS (the whole input is one variable, so discovery cannot expand it). Commission takes ONE source per side, never both: `commissionAmountCents` (a fixed dollar figure in cents) XOR `commissionPercentBps` (basis points (300 = 3%) applied to priceCents); and `teamSplitAmountCents` XOR `teamSplitPercentBps` (basis points applied to the resulting COMMISSION, not the price). Sending both halves of a pair with values is rejected; sending one explicitly as null CLEARS that side. The server derives `commissionCents` (GCI) and returns it: read it there. A percent re-derives when priceCents changes; an amount does not. `participantSplits` is [{ userId, splitAmountCents | splitPercentBps }] allocating what remains after the team fee, and it must not exceed the pool. `customFieldValues` is [{ customFieldId (from listDealCustomFields (deal fields are PER-PIPELINE), and exactly ONE of textValue (TEXT/LINK) | numberValue (NUMBER/DOLLAR, a plain number, NOT cents) | dateValue (DATE, ISO 8601) | dropdownSelectedValues (DROPDOWN) the option LABEL strings, not option ids) matching the field’s type }]. The response echoes the money and custom fields: confirm the write from it.

- Call: `POST https://server.goliathdata.com/api/v1/call` with `{ "operationId": "createDeal", "variables": {...} }`
- Scope: `WRITE`
- Type: mutation
- Idempotency: honors `Idempotency-Key` (24 h)
- Rate-limited: no

## Variables

- `input`: `CreatePipelineItemInput!` (required)
  - `title`: `String!` (required)
  - `stageId`: `ID!` (required)
  - `description`: `String`
  - `priceCents`: `BigInt`
  - `commissionAmountCents`: `BigInt`
  - `commissionPercentBps`: `Int`
  - `teamSplitAmountCents`: `BigInt`
  - `teamSplitPercentBps`: `Int`
  - `participantSplits`: `[PipelineItemParticipantSplitInput!]`
    - `userId`: `ID!` (required)
    - `splitAmountCents`: `BigInt`
    - `splitPercentBps`: `Int`
  - `closeDate`: `DateTime`
  - `propertyIds`: `[ID!]`
  - `propertyStrings`: `[String!]`
  - `contactIds`: `[ID!]`
  - `userIds`: `[ID!]`
  - `fileIds`: `[ID!]`
  - `customFieldValues`: `[PipelineItemCustomFieldValueInput!]`
    - `customFieldId`: `ID!` (required)
    - `textValue`: `String`
    - `dateValue`: `DateTime`
    - `numberValue`: `Float`
    - `dropdownSelectedValues`: `[String!]`

## Response (data, an example)

```json
{
  "dealMutation": {
    "createDeal": {
      "id": "<ID>",
      "title": "…",
      "priceCents": "…",
      "closeDate": "2026-01-01T00:00:00.000Z",
      "isArchived": true,
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "commissionCents": "…",
      "commissionAmountCents": "…",
      "commissionPercentBps": 0,
      "teamSplitAmountCents": "…",
      "teamSplitPercentBps": 0,
      "participantSplits": [
        {
          "user": {
            "id": "<ID>",
            "firstName": "…",
            "lastName": "…"
          },
          "splitAmountCents": "…",
          "splitPercentBps": 0
        }
      ],
      "customFieldValues": [
        {
          "id": "<ID>",
          "textValue": "…",
          "dateValue": "2026-01-01T00:00:00.000Z",
          "numberValue": 0,
          "dropdownSelectedValues": [
            "…"
          ],
          "dealCustomField": {
            "id": "<ID>",
            "name": "…",
            "type": "DROPDOWN"
          }
        }
      ],
      "stage": {
        "id": "<ID>",
        "name": "…"
      },
      "pipeline": {
        "id": "<ID>",
        "name": "…"
      },
      "contacts": [
        {
          "id": "<ID>",
          "name": "…"
        }
      ],
      "properties": [
        {
          "id": "<ID>",
          "address": {
            "addressFull": "…"
          }
        }
      ]
    }
  }
}
```

## Example

```bash
curl https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer $GOLIATH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "operationId": "createDeal",
    "variables": {
      "input": {
        "title": "<String>",
        "stageId": "<stageId>"
      }
    }
  }'
```