---
search:
  tags:
    - customers
    - POST
seo:
  description: >-
    Log a field-sales touch (door knock / call… Reference for the POST
    /workspaces/{organizationId}/customers/{id}/interactions endpoint in the
    Pile API.
sidebar:
  label: Create customer interaction
  badge: POST
title: Create customer interaction
type: openapi-operation
---
Log a field-sales touch (door knock / call outcome). Writes the interaction to customer memory, applies the outcome's default nextStepText/nextStepDueAt/needsHuman unless the body overrides them, and auto-advances statusId per the outcome→status-key map resolved against this workspace's customer_statuses. When the PILE-412 stage gate refuses the advance, the touch still lands and the response flags stageBlocked.

`POST /workspaces/{organizationId}/customers/{id}/interactions`

**Request body** (`application/json`)

- `outcome` (string, required) — Canonical knock outcome — drives the next-step defaults and stage auto-advance
- `note` (string)
- `nextStepText` (string | null)
- `nextStepDueAt` (string | null)
- `quotedAmountCents` (integer)
- `dealTitle` (string)

Request body example:

```json
{
  "outcome": "talked",
  "note": "string",
  "nextStepText": "string",
  "nextStepDueAt": "string",
  "quotedAmountCents": 1,
  "dealTitle": "string"
}
```

**Responses**

- `201` — Interaction logged
- `404` — Customer not found

Response example, 201:

```json
{
  "interaction": {
    "id": "string",
    "customerId": "string",
    "outcome": "talked",
    "note": "string",
    "createdAt": "string"
  },
  "customer": {
    "id": "string",
    "organizationId": "string",
    "name": "string",
    "url": "string",
    "domain": "string",
    "bookingUrl": "string",
    "notes": "string",
    "logoUrl": "string",
    "externalId": "string",
    "phone": "string",
    "address": "string",
    "vertical": "string",
    "neighborhood": "string",
    "source": "string",
    "sourceSessionId": "string",
    "sourceAgentSlug": "string",
    "readiness": "string",
    "nextAction": "string",
    "fit": "string",
    "fitScore": 0,
    "fitStatus": "string",
    "processor": "string",
    "evidenceUri": "string",
    "tierId": "string",
    "statusId": "string",
    "ownerId": "string",
    "nextStepText": "string",
    "nextStepDueAt": "string",
    "needsHuman": true,
    "needsHumanReason": "string",
    "priorityScore": 0,
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "createdAt": "string",
    "updatedAt": "string"
  },
  "stageAdvanced": true,
  "stageBlocked": true,
  "deal": {
    "id": "string",
    "organizationId": "string",
    "customerId": "string",
    "name": "string",
    "externalId": "string",
    "stage": "lead",
    "amountCents": 0,
    "currency": "string",
    "expectedCloseAt": "string",
    "description": "string",
    "closedAt": "string",
    "archivedAt": "string",
    "nextStepText": "string",
    "nextStepDueAt": "string",
    "needsHuman": true,
    "needsHumanReason": "string",
    "priorityScore": 0,
    "contactIds": [
      "string"
    ],
    "customFields": {
      "property1": "string",
      "property2": "string"
    },
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```