Countertop Studio

The Deal Resource

A deal represents a potential business opportunity.

Deals are used to track sales opportunities and potential revenue as they move through different stages of a department's workflow.

Each deal belongs to a department and a step, and can optionally be assigned to an employee.

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

The Deal Object

A deal object represents a single opportunity within the system.

    Required Attributes

  • Name
    name
    Type
    string
    Description

    Name or title of the deal.

    • Optional Attributes

  • Name
    volume
    Type
    integer
    Description

    Monetary value of the deal.

  • Name
    note
    Type
    string
    Description

    Optional note attached to the deal.

  • Name
    customers
    Type
    array
    Description

    List of customers associated with the deal. Each customer object should include:

    • last_name (string, required)
    You want to see all attributes for a Customer ?

    • Server-managed attributes

  • Name
    id
    Type
    uuid
    Description

    Unique identifier of the deal, generated by the server.

  • Name
    employee_id
    Type
    uuid
    Description

    Assigned employee responsible for the deal, can be null if unassigned.

  • Name
    step_id
    Type
    uuid
    Description

    Identifier of the pipeline step the deal belongs to, generated by the server.

  • Name
    department_id
    Type
    uuid
    Description

    Department the deal belongs to, generated by the server.

  • Name
    created_at
    Type
    datetime
    Description

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

  • Name
    updated_at
    Type
    datetime
    Description

    Timestamp of the last update to the deal, generated by the server.

Request

POST
/v1/deals
    curl -X POST https://studio.countertop.app/api/v1/integration/deals \
    -H "X-Api-Key: {your-secret}" \
    -H "X-Department-Id: {department-id}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Example Dealname",
      "volume": 15000,
      "note": "Important enterprise customer",
      "customers":
      [
        {
          "last_name": "Doe",
          "first_name": "John"
        },
          {
            "last_name": "Doe",
            "first_name": "Jane"
          }
      ]
    }'

Response

{
    "id": "019cbd8b-dd90-7119-b13e-f99dc519c4ad",
    "name": "Example Dealname",
    "volume": 15000,
    "employee_id": null,
    "employee_name": null,
    "step_id": "019c19a9-4350-71f1-9027-8ebbbc5cd4fd",
    "department_id": "019c19a9-34be-71d1-9152-100d38b983ab",
    "note": "Important enterprise customer",
    "created_at": "2026-03-05T10:29:46.000000Z",
    "updated_at": "2026-03-05T10:29:46.000000Z",
    "customers": [
        {
            "id": "019cbd8b-dd89-7267-b306-ee2b7796de53",
            "company": null,
            "website": null,
            "title": null,
            "first_name": "John",
            "last_name": "Doe",
            // ... other customer attributes
        },
        {
            "id": "019cbd8b-dd8c-7129-8673-23bbd595c344",
            "company": null,
            "website": null,
            "title": null,
            "first_name": "Jane",
            "last_name": "Doe",
            // ... other customer attributes

        }
    ]
}

Resource Relationships

Tenant
  └ Departments
       └ Steps
            └ Deals

This means:

  • a deal belongs to a department
  • a deal belongs to a step
  • a step defines the deal's current stage