Create customer interaction

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

Authorization

AuthorizationBearer token · headerrequired

Workspace API key (Authorization: Bearer <key>). Issue keys under Settings → Developer or POST /workspaces/{organizationId}/tokens.

Path parameters

organizationIdstringrequired

idstringrequired

Request body

application/json

outcomestringrequired

Canonical knock outcome — drives the next-step defaults and stage auto-advance

Allowed:talkedsent_infoneeds_emailquotedcallbackno_answernot_interestedspam

notestring

max length 4000

nextStepTextstring | null

nextStepDueAtstring | null

quotedAmountCentsinteger

max 1000000000

dealTitlestring

min length 1 · max length 200

Responses

201

Interaction logged

interactionobjectrequired

Show properties

idstringrequired

customerIdstringrequired

outcomestringrequired

Allowed:talkedsent_infoneeds_emailquotedcallbackno_answernot_interestedspam

notestring | nullrequired

createdAtstringrequired

customerobjectrequired

Show properties

idstringrequired

organizationIdstringrequired

namestringrequired

urlstring | nullrequired

domainstring | nullrequired

bookingUrlstring | nullrequired

notesstring | nullrequired

logoUrlstring | nullrequired

externalIdstring | nullrequired

phonestring | nullrequired

addressstring | nullrequired

verticalstring | nullrequired

neighborhoodstring | nullrequired

sourcestring | nullrequired

sourceSessionIdstring | nullrequired

sourceAgentSlugstring | nullrequired

readinessstring | nullrequired

nextActionstring | nullrequired

fitstring | nullrequired

fitScorenumber | nullrequired

fitStatusstring | nullrequired

processorstring | nullrequired

evidenceUristring | nullrequired

tierIdstring | nullrequired

statusIdstring | nullrequired

ownerIdstring | nullrequired

nextStepTextstring | nullrequired

nextStepDueAtstring | nullrequired

needsHumanboolean | nullrequired

needsHumanReasonstring | nullrequired

priorityScorenumber | nullrequired

customFieldsobjectrequired

createdAtstringrequired

updatedAtstringrequired

stageAdvancedbooleanrequired

stageBlockedbooleanrequired

dealobject | nullrequired

Show properties

idstringrequired

organizationIdstringrequired

customerIdstringrequired

namestringrequired

externalIdstring | nullrequired

stagestringrequired

Allowed:leadqualifiedproposalnegotiationwonlost

amountCentsnumber | nullrequired

currencystring | nullrequired

expectedCloseAtstring | nullrequired

descriptionstring | nullrequired

closedAtstring | nullrequired

archivedAtstring | nullrequired

nextStepTextstring | nullrequired

nextStepDueAtstring | nullrequired

needsHumanboolean | nullrequired

needsHumanReasonstring | nullrequired

priorityScorenumber | nullrequired

contactIdsstring[]required

customFieldsobjectrequired

createdAtstringrequired

updatedAtstringrequired

404

Customer not found

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

organizationIdpath*idpath*

Bodyapplication/json

outcomestring*Canonical knock outcome — drives the next-step defaults and stage auto-advancenotestringnextStepTextstringnextStepDueAtstringquotedAmountCentsintegerdealTitlestring

Request

curl -X POST 'https://pile.nyc/workspaces/string/customers/string/interactions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "outcome": "talked",
  "note": "string",
  "nextStepText": "string",
  "nextStepDueAt": "string",
  "quotedAmountCents": 1,
  "dealTitle": "string"
}'

const response = await fetch("https://pile.nyc/workspaces/string/customers/string/interactions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"outcome\": \"talked\",\n  \"note\": \"string\",\n  \"nextStepText\": \"string\",\n  \"nextStepDueAt\": \"string\",\n  \"quotedAmountCents\": 1,\n  \"dealTitle\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://pile.nyc/workspaces/string/customers/string/interactions",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"outcome\": \"talked\",\n  \"note\": \"string\",\n  \"nextStepText\": \"string\",\n  \"nextStepDueAt\": \"string\",\n  \"quotedAmountCents\": 1,\n  \"dealTitle\": \"string\"\n}",
)

Response

{
  "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"
  }
}