Prospects

A prospect represents a potential customer that your business is working to convert into a customer.

The prospect object

Field	Type	Description
`id`	string	Unique prospect UUID.
`object`	string	Always `prospect`.
`customer_number`	integer	Account-assigned number shared with the customer sequence.
`name`	string	Prospect name.
`office_email`	string or null	Primary office email address.
`office_phone`	string or null	Primary office telephone number.
`office_fax`	string or null	Primary fax number.
`url`	string or null	Prospect website URL.
`billing_address_1`	string or null	First billing-address line.
`billing_address_2`	string or null	Second billing-address line.
`billing_city`	string or null	Billing city.
`billing_region`	string or null	Billing state, province, or region.
`billing_postal_code`	string or null	Billing postal or ZIP code.
`billing_country`	string or null	Billing country.
`shipping_address_1`	string or null	First shipping-address line.
`shipping_address_2`	string or null	Second shipping-address line.
`shipping_city`	string or null	Shipping city.
`shipping_region`	string or null	Shipping state, province, or region.
`shipping_postal_code`	string or null	Shipping postal or ZIP code.
`shipping_country`	string or null	Shipping country.
`vat_number`	string or null	VAT or tax registration number.
`document_count`	integer	Number of documents associated with the prospect.
`archived`	boolean	Whether the prospect is archived.
`pricing_tier_id`	string or null	Assigned pricing-tier UUID.
`owner_user_id`	string or null	UUID of the assigned SalesBinder user.
`created_at`	string	ISO 8601 creation timestamp.
`updated_at`	string	ISO 8601 modification timestamp.
`sale_opportunity`	string or null	Description of the potential sale.
`closing_percentage`	integer	Estimated likelihood of closing the opportunity.
`prospect_date`	string or null	Prospect date in `YYYY-MM-DD` format.

List prospects

GET/api/v3/prospects

Required scope: prospects:read

Returns prospects ordered by name and limited by the current user's record visibility.

Query parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number. Defaults to `1`.
`limit`	integer	No	Records per page. Defaults to `20`; maximum `100`.
`q`	string	No	Searches prospect name and office email. A numeric value also matches an exact account number.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/prospects?q=example&page=1&limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "object": "list",
  "url": "/api/v3/prospects",
  "has_more": false,
  "data": [
    {
      "id": "8b17e608-366f-4c02-a510-98f9cc810406",
      "object": "prospect",
      "customer_number": 528,
      "name": "Example Prospect",
      "office_email": "contact@example.com",
      "office_phone": "604-555-0142",
      "office_fax": "",
      "url": "https://example.com",
      "billing_address_1": "200 Main Street",
      "billing_address_2": "",
      "billing_city": "Vancouver",
      "billing_region": "British Columbia",
      "billing_postal_code": "V6B 2B2",
      "billing_country": "Canada",
      "shipping_address_1": "200 Main Street",
      "shipping_address_2": "",
      "shipping_city": "Vancouver",
      "shipping_region": "British Columbia",
      "shipping_postal_code": "V6B 2B2",
      "shipping_country": "Canada",
      "vat_number": "",
      "document_count": 0,
      "archived": false,
      "pricing_tier_id": null,
      "owner_user_id": "693ab0a0-d0f1-4dd1-a462-d8f9867d3747",
      "created_at": "2026-07-18T02:42:19+00:00",
      "updated_at": "2026-07-18T02:42:19+00:00",
      "sale_opportunity": "Annual supply agreement",
      "closing_percentage": 60,
      "prospect_date": "2026-07-18"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_records": 1
  }
}

Retrieve a prospect

GET/api/v3/prospects/{prospect_id}

Required scope: prospects:read

Returns one prospect within the current user's account and record-visibility boundary.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/prospects/8b17e608-366f-4c02-a510-98f9cc810406" \
  --header "Authorization: Bearer YOUR_API_KEY"

The response is a prospect object. If the prospect is unavailable to the current user, the API returns 404 resource_missing.

Create a prospect

POST/api/v3/prospects

Required scope: prospects:write

The name field is required. SalesBinder assigns the account number and current API user.

Writable fields

Field	Type	Required	Notes
`name`	string	Yes	Maximum 255 characters.
`office_email`	string	No	Maximum 255 characters.
`office_phone`	string	No	Maximum 255 characters.
`office_fax`	string	No	Maximum 255 characters.
`url`	string	No	Valid URL, maximum 255 characters.
`billing_address_1`	string	No	Maximum 255 characters.
`billing_address_2`	string	No	Maximum 255 characters.
`billing_city`	string	No	Maximum 255 characters.
`billing_region_id`	integer	No	SalesBinder region identifier.
`billing_region`	string	No	Maximum 255 characters.
`billing_postal_code`	string	No	Maximum 255 characters.
`billing_country_id`	integer	No	SalesBinder country identifier.
`billing_country`	string	No	Maximum 255 characters.
`shipping_address_1`	string	No	Maximum 255 characters.
`shipping_address_2`	string	No	Maximum 255 characters.
`shipping_city`	string	No	Maximum 255 characters.
`shipping_region_id`	integer	No	SalesBinder region identifier.
`shipping_region`	string	No	Maximum 255 characters.
`shipping_postal_code`	string	No	Maximum 255 characters.
`shipping_country_id`	integer	No	SalesBinder country identifier.
`shipping_country`	string	No	Maximum 255 characters.
`vat_number`	string	No	Maximum 24 characters.
`tax_rate1`	number	No	Primary default tax rate.
`tax_rate2`	number	No	Secondary default tax rate.
`customer_label_id`	string	No	Account-label UUID.
`pricing_tier_id`	string	No	Pricing-tier UUID belonging to the account.
`sale_opportunity`	string	No	Opportunity description, maximum 255 characters.
`closing_percentage`	integer	No	Estimated likelihood of closing. Defaults to `0`.
`prospect_date`	string	No	Date in `YYYY-MM-DD` format.

Account-owned references are validated when assigned or changed. A missing UUID or a UUID belonging to another account returns 422 validation_failed without exposing the other account's data.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/prospects" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-example-prospect-001" \
  --data '{
    "name": "Example Prospect",
    "office_email": "contact@example.com",
    "sale_opportunity": "Annual supply agreement",
    "closing_percentage": 60,
    "prospect_date": "2026-07-18"
  }'

Response

Returns the created prospect object with 201 Created. See idempotent requests before automatically retrying creates.

Update a prospect

PATCH or PUT/api/v3/prospects/{prospect_id}

Required scope: prospects:write

Send only the writable fields that should change. Both PATCH and PUT preserve omitted writable fields.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/prospects/8b17e608-366f-4c02-a510-98f9cc810406" \
  --request PATCH \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "closing_percentage": 75,
    "sale_opportunity": "Expanded annual agreement"
  }'

Returns the updated prospect object with 200 OK.

Delete a prospect

DELETE/api/v3/prospects/{prospect_id}

Required scope: prospects:delete

A prospect can be deleted only when it has no associated documents. Deleting a prospect with documents returns 422 validation_failed with document_count validation details.

Example request

curl "https://yourbusiness.salesbinder.com/api/v3/prospects/8b17e608-366f-4c02-a510-98f9cc810406" \
  --request DELETE \
  --header "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": "8b17e608-366f-4c02-a510-98f9cc810406",
  "object": "prospect",
  "deleted": true
}