ClientSphereDocs
API reference/Accounts

Create account

Creates an account and returns it with its generated id. Send your own id as externalId and the call becomes find-or-create: an account already carrying that id is returned with 200 and nothing is created, otherwise 201. Name is never used for matching.

POST
/accounts

Authorization

AuthorizationRequiredBearer <token>

API key as Bearer token: Authorization: Bearer sk_live_.... Use sk_live_ prefixed keys for production data and sk_test_ prefixed keys for sandbox/test data.

In: header

X-API-Key<token>

API key via header: X-API-Key: sk_live_.... Use sk_live_ prefixed keys for production data and sk_test_ prefixed keys for sandbox/test data.

In: header

Request Body

application/jsonRequired
externalIdstring

Your own id for the organisation — a customer or tenant id from your system. Send it on every create and the endpoint becomes find-or-create: if a live account in this workspace already carries this id, that account is returned with 200 and nothing is created or changed. Otherwise the account is created with 201.

Name is never used for matching. Two organisations with the same name and different ids are two accounts, on purpose — matching on name would attach one customer's signup to another customer's record. Omit the field and the endpoint always creates.

nameRequiredstring
websitestring
industrystring
sizestring
Value in: "small" | "medium" | "large" | "enterprise"
phonestring
addressstring
extraInformationstring
statusstring
Default: "active"Value in: "active" | "inactive" | "prospect" | "customer" | "churned"
tagsarray<string>
curl -X POST "https://clientsphere.io/api/v1/accounts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "org_8f2c1",
    "name": "Acme Corp",
    "website": "https://acme.com",
    "industry": "Technology",
    "size": "small",
    "phone": "string",
    "address": "string",
    "extraInformation": "VIP customer; renewal in Q3.",
    "status": "active",
    "tags": [
      "enterprise",
      "priority"
    ]
  }'

An account with this externalId already existed in the workspace. It is returned unchanged; the request body was not applied. Use the update endpoint to change it.

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
    "name": "string",
    "website": "string",
    "industry": "string",
    "size": "small",
    "phone": "string",
    "address": "string",
    "extraInformation": "string",
    "status": "active",
    "assignedTo": 0,
    "ownerId": 0,
    "tags": [
      "string"
    ],
    "externalId": "org_8f2c1",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}