Countertop Studio

The Customer Resource

A customer represents a person or organization that interacts with your business.

Customers store contact information such as names, phone numbers, email addresses, and location details.
They can be linked to deals and activities to track interactions and business opportunities.

You want to know more about authentication?
POST/v1/customer

The Customer Object

    Required Attributes

  • Name
    last_name
    Type
    string
    Description

    Last name of the customer.

    • Optional Attributes

  • Name
    company
    Type
    string
    Description

    Company name.

  • Name
    website
    Type
    string
    Description

    Company website.

  • Name
    title
    Type
    string
    Description

    Title (e.g. Mr., Ms., Dr.).

  • Name
    first_name
    Type
    string
    Description

    First name of the customer.

  • Name
    phone_1
    Type
    string
    Description

    Primary phone number.

  • Name
    phone_2
    Type
    string
    Description

    Secondary phone number.

  • Name
    phone_3
    Type
    string
    Description

    Additional phone number.

  • Name
    phone_1_label
    Type
    string
    Description

    Label for the first phone number (e.g. Work, Mobile).

  • Name
    phone_2_label
    Type
    string
    Description

    Label for the second phone number.

  • Name
    phone_3_label
    Type
    string
    Description

    Label for the third phone number.

  • Name
    email
    Type
    string
    Description

    Email address.

  • Name
    postcode
    Type
    string
    Description

    Postal code.

  • Name
    address
    Type
    string
    Description

    Street address.

  • Name
    city
    Type
    string
    Description

    City.

  • Name
    country
    Type
    string
    Description

    Country.

  • Name
    state
    Type
    string
    Description

    State or region.

  • Name
    lead_origin
    Type
    string
    Description

    Source of the lead.

  • Name
    birthday
    Type
    date
    Description

    Birthday of the customer.

  • Name
    note
    Type
    string
    Description

    Additional notes.

    • Server-managed Attributes

  • Name
    id
    Type
    uuid
    Description

    Unique identifier of the customer, generated by the server.

  • Name
    tenant_id
    Type
    uuid
    Description

    Tenant the customer belongs to. Determined automatically by the authentication scope.

  • Name
    created_at
    Type
    datetime
    Description

    Timestamp when the customer was created, generated by the server.

  • Name
    updated_at
    Type
    datetime
    Description

    Timestamp of the last update, generated by the server.

Request

POST
/v1/customers
  curl -X POST https://studio.countertop.app/api/v1/integration/customers \
  -H "X-Api-Key: {your-secret}" \
  -H "X-Department-Id: {department-id}" \
  -H "Content-Type: application/json" \
  -d '{
    "last_name": "Doe",
    "first_name": "John",
    "phone_1_label": "Mobile",
    "phone_1": "+49 12345678"
}'

Response

{
    "id": "019cbd7f-679e-705d-b742-3c0d785c8c30",
    "company": null,
    "website": null,
    "title": null,
    "first_name": "John",
    "last_name": "Doe",
    "phone_1": "+49 12345678",
    "phone_2": null,
    "phone_3": null,
    "phone_1_label": "Mobile",
    "phone_2_label": null,
    "phone_3_label": null,
    "email": null,
    "postcode": null,
    "address": null,
    "address_addition": null,
    "city": null,
    "country": null,
    "state": null,
    "lead_origin": null,
    "birthday": null,
    "tenant_id": "2d6e54c6-a284-392c-b658-10af4d5989bb",
    "note": null,
    "created_at": "2026-03-05T10:16:09.000000Z",
    "updated_at": "2026-03-05T10:16:09.000000Z"
}

Resource Relationships

Tenant
   └ Customers
        ├ Deals
        └ Activities

This means:

  • a customer belongs to a tenant
  • a customer can be linked to multiple deals
  • a customer can have multiple activities