Create customer

externalId is a hard dedupe key (same contract as issues’ externalRef): when a customer with the same externalId exists the call returns that customer with 200 instead of creating a duplicate. Pass dedupe=block to get 409 with the existing record in details.customer instead — the hard guarantee importers need.

POST/workspaces/{organizationId}/customers

Authorization

AuthorizationBearer token · headerrequired

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

Path parameters

organizationIdstringrequired

Query parameters

dedupestring

Allowed:warnblock

Request body

application/json

namestringrequired

min length 1

urlstring

domainstring

bookingUrlstring | null

notesstring | null

logoUrlstring

externalIdstring

min length 1 · max length 255

phonestring

addressstring

verticalstring

neighborhoodstring

sourcestring

readinessstring

nextActionstring

fitstring

fitScorenumber

fitStatusstring

processorstring

evidenceUristring

tierIdstring

statusIdstring

ownerIdstring

nextStepTextstring | null

nextStepDueAtstring | null

needsHumanboolean | null

needsHumanReasonstring | null

priorityScorenumber | null

customFieldsobject

Responses

200

Existing customer with the same externalId (idempotent create)

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

201

Customer created

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

409

dedupe=block and externalId is already used

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

organizationIdpath*dedupequery

Bodyapplication/json

Request body

Request

curl -X POST 'https://pile.nyc/workspaces/string/customers' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "url": "string",
  "domain": "string",
  "bookingUrl": "string",
  "notes": "string",
  "logoUrl": "string",
  "externalId": "string",
  "phone": "string",
  "address": "string",
  "vertical": "string",
  "neighborhood": "string",
  "source": "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"
  }
}'

const response = await fetch("https://pile.nyc/workspaces/string/customers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"name\": \"string\",\n  \"url\": \"string\",\n  \"domain\": \"string\",\n  \"bookingUrl\": \"string\",\n  \"notes\": \"string\",\n  \"logoUrl\": \"string\",\n  \"externalId\": \"string\",\n  \"phone\": \"string\",\n  \"address\": \"string\",\n  \"vertical\": \"string\",\n  \"neighborhood\": \"string\",\n  \"source\": \"string\",\n  \"readiness\": \"string\",\n  \"nextAction\": \"string\",\n  \"fit\": \"string\",\n  \"fitScore\": 0,\n  \"fitStatus\": \"string\",\n  \"processor\": \"string\",\n  \"evidenceUri\": \"string\",\n  \"tierId\": \"string\",\n  \"statusId\": \"string\",\n  \"ownerId\": \"string\",\n  \"nextStepText\": \"string\",\n  \"nextStepDueAt\": \"string\",\n  \"needsHuman\": true,\n  \"needsHumanReason\": \"string\",\n  \"priorityScore\": 0,\n  \"customFields\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  }\n}"
});

import requests

response = requests.post(
    "https://pile.nyc/workspaces/string/customers",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"name\": \"string\",\n  \"url\": \"string\",\n  \"domain\": \"string\",\n  \"bookingUrl\": \"string\",\n  \"notes\": \"string\",\n  \"logoUrl\": \"string\",\n  \"externalId\": \"string\",\n  \"phone\": \"string\",\n  \"address\": \"string\",\n  \"vertical\": \"string\",\n  \"neighborhood\": \"string\",\n  \"source\": \"string\",\n  \"readiness\": \"string\",\n  \"nextAction\": \"string\",\n  \"fit\": \"string\",\n  \"fitScore\": 0,\n  \"fitStatus\": \"string\",\n  \"processor\": \"string\",\n  \"evidenceUri\": \"string\",\n  \"tierId\": \"string\",\n  \"statusId\": \"string\",\n  \"ownerId\": \"string\",\n  \"nextStepText\": \"string\",\n  \"nextStepDueAt\": \"string\",\n  \"needsHuman\": true,\n  \"needsHumanReason\": \"string\",\n  \"priorityScore\": 0,\n  \"customFields\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  }\n}",
)

Response

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

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