Sales

Use the sales endpoints to list sales for an organization, fetch one sale by ID, create and update sales, list the organization's pipeline stages, and list sales owned by a specific agent.

List sales

GET /api/v2/organizations/{organization_id}/sales

This endpoint supports limit, cursor, start_date, and end_date. Date parameters are optional — omit them to return all sales regardless of time.

Example pagination block:

List sales request

curl -G https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/sales \
  -H "X-API-KEY: your-api-key" \
  --data-urlencode "limit=25" \
  --data-urlencode "start_date=2026-04-01T00:00:00Z" \
  --data-urlencode "end_date=2026-04-30T23:59:59Z"

Example response

{
  "data": [
    {
      "sale_id": "HR_id_example_sale_id",
      "associated_conversation_ids": [
        "HR_id_example_conversation_id"
      ],
      "company_id": "HR_id_example_company_id",
      "owner_id": "HR_id_example_agent_id",
      "associated_contacts": [
        {
          "contact_id": "HR_id_example_contact_id",
          "is_primary": true
        }
      ],
      "quote_details": {
        "output": {
          "currency": "USD",
          "total_price": "1200.00"
        },
        "arguments": {
          "products": [
            {
              "quantity": 1,
              "unit_price": "1200.00",
              "product_name": "Legacy Seed Service"
            }
          ]
        },
        "agent_overrides": {
          "products.unit_price": {
            "Legacy Seed Service": 1200
          }
        }
      },
      "custom_fields": {
        "notes": "Backfilled sale for new sales framework compatibility."
      },
      "current_status": {
        "label": "Accepted",
        "status": "accepted",
        "changed_at": "2026-03-13T01:28:41.829924Z"
      },
      "status_history": [
        {
          "label": "Qualified",
          "status": null,
          "changed_at": "2026-03-12T01:28:41.829924Z"
        },
        {
          "label": "Quoted",
          "status": "quote_sent",
          "changed_at": "2026-03-12T01:43:41.829924Z"
        },
        {
          "label": "Accepted",
          "status": "accepted",
          "changed_at": "2026-03-13T01:28:41.829924Z"
        }
      ],
      "created_at": "2026-03-12T01:28:41.829924Z",
      "last_activity_at": "2026-03-12T01:28:41.829924Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": "HR_tok_example_next_cursor",
    "has_more": true
  }
}

Get a sale

GET /api/v2/organizations/{organization_id}/sales/{sale_id}

Use a sale_id value from the sales collection response.

Get sale request

curl https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/sales/HR_id_example_sale_id \
  -H "X-API-KEY: your-api-key"

Example response

{
  "sale_id": "HR_id_example_sale_id",
  "associated_conversation_ids": [
    "HR_id_example_conversation_id"
  ],
  "company_id": "HR_id_example_company_id",
  "owner_id": "HR_id_example_agent_id",
  "associated_contacts": [
    {
      "contact_id": "HR_id_example_contact_id",
      "is_primary": true
    }
  ],
  "quote_details": {
    "output": {
      "currency": "USD",
      "total_price": "1200.00"
    },
    "arguments": {
      "products": [
        {
          "quantity": 1,
          "unit_price": "1200.00",
          "product_name": "Legacy Seed Service"
        }
      ]
    },
    "agent_overrides": {
      "products.unit_price": {
        "Legacy Seed Service": 1200
      }
    }
  },
  "custom_fields": {
    "notes": "Backfilled sale for new sales framework compatibility."
  },
  "current_status": {
    "label": "Accepted",
    "status": "accepted",
    "changed_at": "2026-03-13T01:28:41.829924Z"
  },
  "status_history": [
    {
      "label": "Qualified",
      "status": null,
      "changed_at": "2026-03-12T01:28:41.829924Z"
    },
    {
      "label": "Quoted",
      "status": "quote_sent",
      "changed_at": "2026-03-12T01:43:41.829924Z"
    },
    {
      "label": "Accepted",
      "status": "accepted",
      "changed_at": "2026-03-13T01:28:41.829924Z"
    }
  ],
  "created_at": "2026-03-12T01:28:41.829924Z",
  "last_activity_at": "2026-03-12T01:28:41.829924Z"
}

Create a sale

POST /api/v2/organizations/{organization_id}/sales

Sales created through the API are currently lead records only: they carry a pipeline stage, contacts, and custom fields, but cannot include a sale value or quote information yet.

Creates one sale in a specific pipeline stage. Provide:

status_id — an initial pipeline stage from List sale statuses.
company_id and/or associated_contacts — at least one linked company or contact.

Optional fields:

custom_fields — values keyed by field name, validated against the organization's custom field definitions. Fields with defaults are filled in automatically. Fields with the date presentation take a YYYY-MM-DD string.
conversation_ids — conversations to link to the sale.
owner_id — the agent who owns the sale.

The response is the canonical sale payload, identical to Get a sale.

Create sale request

curl -X POST https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/sales \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "associated_contacts": [
      {"contact_id": "HR_id_example_contact_id", "is_primary": true}
    ],
    "status_id": "HR_id_example_status_id",
    "custom_fields": {"notes": "Created via API"},
    "conversation_ids": ["HR_id_example_conversation_id"]
  }'

Custom field values are strictly validated: unknown keys, wrong value types, and enum values outside the configured options are rejected with a 400 that names the offending field.

Update a sale

PATCH /api/v2/organizations/{organization_id}/sales/{sale_id}

Updates one sale and returns the canonical sale payload. Omitted fields are left unchanged. Set nullable fields to null to clear them.

Provide status_id to move the sale to a new pipeline stage from List sale statuses. Status history is preserved, so a stage that is already in the sale's history cannot be applied again unless it is already the current stage.

Providing associated_contacts replaces the sale's contact associations. Providing conversation_ids replaces the sale's associated conversations. At least one linked company or contact must remain after the update.

Update sale request

curl -X PATCH https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/sales/HR_id_example_sale_id \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "owner_id": "HR_id_example_agent_id",
    "status_id": "HR_id_example_status_id_2",
    "custom_fields": {"notes": "Updated via API"},
    "associated_contacts": [
      {"contact_id": "HR_id_example_contact_id", "is_primary": true}
    ]
  }'

List sale statuses

GET /api/v2/organizations/{organization_id}/sale-statuses

Lists the pipeline stages configured for the organization, ordered by position. Use a stage's status_id as the status_id when creating a sale in a specific pipeline stage.

List sale statuses request

curl https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/sale-statuses \
  -H "X-API-KEY: your-api-key"

Example response

{
  "data": [
    {
      "status_id": "HR_id_example_status_id",
      "label": "Qualified",
      "status": "qualified",
      "position": 0
    },
    {
      "status_id": "HR_id_example_status_id_2",
      "label": "Quoted",
      "status": "quote_sent",
      "position": 1
    },
    {
      "status_id": "HR_id_example_status_id_3",
      "label": "Accepted",
      "status": "accepted",
      "position": 2
    },
    {
      "status_id": "HR_id_example_status_id_4",
      "label": "Fulfilled",
      "position": 3
    }
  ]
}

List agent sales

GET /api/v2/organizations/{organization_id}/agents/{agent_id}/sales

Use this endpoint when you only want sales owned by one agent. Use the agent_id returned by the agent endpoints.

List agent sales request

curl -G https://api.hyperrep.ai/api/v2/organizations/HR_id_example_organization_id/agents/HR_id_example_agent_id/sales \
  -H "X-API-KEY: your-api-key" \
  --data-urlencode "limit=25"

Example response

{
  "data": [
    {
      "sale_id": "HR_id_example_sale_id",
      "associated_conversation_ids": [
        "HR_id_example_conversation_id"
      ],
      "company_id": "HR_id_example_company_id",
      "owner_id": "HR_id_example_agent_id",
      "associated_contacts": [
        {
          "contact_id": "HR_id_example_contact_id",
          "is_primary": true
        }
      ],
      "quote_details": {
        "output": {
          "currency": "USD",
          "total_price": "1200.00"
        },
        "arguments": {
          "products": [
            {
              "quantity": 1,
              "unit_price": "1200.00",
              "product_name": "Legacy Seed Service"
            }
          ]
        }
      },
      "custom_fields": {
        "notes": "Backfilled sale for new sales framework compatibility."
      },
      "current_status": {
        "label": "Accepted",
        "status": "accepted",
        "changed_at": "2026-03-13T01:28:41.829924Z"
      },
      "status_history": [
        {
          "label": "Qualified",
          "status": null,
          "changed_at": "2026-03-12T01:28:41.829924Z"
        },
        {
          "label": "Quoted",
          "status": "quote_sent",
          "changed_at": "2026-03-12T01:43:41.829924Z"
        },
        {
          "label": "Accepted",
          "status": "accepted",
          "changed_at": "2026-03-13T01:28:41.829924Z"
        }
      ],
      "created_at": "2026-03-12T01:28:41.829924Z",
      "last_activity_at": "2026-03-12T01:28:41.829924Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": null,
    "has_more": false
  }
}

Key response fields

Name
sale_id
Description
Unique identifier for the sale.
Name
associated_conversation_ids
Description
List of encoded conversation IDs linked to this sale.
Name
company_id
Description
Identifier for the company associated with the sale.
Name
owner_id
Description
Identifier for the agent who owns the sale.
Name
associated_contacts
Description
Contacts linked to the sale. Each entry includes contact_id and is_primary — only one contact will have is_primary: true.
Name
quote_details
Description
Quote information attached to the sale. Contains these fields:
- output — the computed quote result, including currency and total_price as a decimal string
- arguments — the inputs used to generate the quote; products is an array of line items each with product_name, quantity, and unit_price
- agent_overrides — agent-entered quote overrides, when present
Name
custom_fields
Description
Custom sales field values keyed by field name.
Name
current_status
Description
The sale's latest status event. Contains label (display name), status (status tag), and changed_at (ISO 8601 timestamp). null if no status has been set yet.
Name
status_history
Description
Ordered list of all status events, ascending by changed_at. Each entry has the same shape as current_status. Imported sales can begin at the status_id supplied on create.
Name
created_at
Description
ISO 8601 timestamp when the sale was created.
Name
last_activity_at
Description
ISO 8601 timestamp of the most recent activity. Used as the sort key for list and pagination responses.