> For the complete documentation index, see [llms.txt](https://help.paintscout.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.paintscout.com/developers/deals.md).

# Deals

## GET /deals

> List Deals

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Deal":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The unique ID for the Deal. Ignored when creating & updating deals."},"name":{"type":"string","nullable":true,"description":"The Name of the Deal."},"contact":{"type":"object","nullable":false,"description":"Contact details to create inline with the Deal","$ref":"#/components/schemas/Contact"},"jobAddress":{"type":"object","nullable":true,"additionalProperties":false,"description":"The Job Address of this Deal","properties":{"address":{"type":"string","nullable":true,"description":"The address component of the job address"},"city":{"type":"string","nullable":true,"description":"The city component of the job address"},"state":{"type":"string","nullable":true,"description":"The state component of the job address"},"zip":{"type":"string","nullable":true,"description":"The zip code component of the job address"}}},"pipeline":{"type":"string","nullable":true,"description":"The pipeline this Deal is in"},"stage":{"type":"string","nullable":true,"description":"The stage of the pipeline this Deal is in"},"value":{"type":"number","format":"float","nullable":true,"description":"The monetary value of this Deal"},"leadSource":{"type":"string","nullable":true,"description":"The lead source of this Deal"},"leadFormKey":{"type":"string","nullable":true,"readOnly":true,"description":"The key of the lead form this Deal was created from, if any. Ignored when creating & updating deals."},"owner":{"$ref":"#/components/schemas/OwnerNullable"},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"tags":{"type":"array","description":"Tags associated with this Deal","items":{"type":"string"}},"quoteType":{"type":"object","nullable":true,"additionalProperties":false,"description":"The Quote Type associated with this Deal","properties":{"id":{"type":"string","description":"The unique ID of the Quote Type"},"label":{"type":"string","description":"The display label of the Quote Type"}}},"linkedEstimateIds":{"type":"array","description":"List of linked Estimate IDs","items":{"type":"string"}},"linkedInvoiceIds":{"type":"array","description":"List of linked Invoice IDs","items":{"type":"string"}},"jobCosting":{"type":"object","nullable":true,"additionalProperties":false,"description":"The job costing figures for this Deal","properties":{"labour":{"type":"number","format":"float","nullable":true,"description":"The labour cost of this Deal"},"materials":{"type":"number","format":"float","nullable":true,"description":"The materials cost of this Deal"},"overhead":{"type":"number","format":"float","nullable":true,"description":"The overhead cost of this Deal"},"profit":{"type":"number","format":"float","nullable":true,"readOnly":true,"description":"The calculated profit of this Deal. Read-only."},"margin":{"type":"number","format":"float","nullable":true,"readOnly":true,"description":"The calculated profit margin (percentage) of this Deal. Read-only."}}}}},"Contact":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique ID of the Contact. Ignored when creating & updating contacts"},"firstName":{"type":"string","nullable":true,"description":"The First Name of the Contact."},"lastName":{"type":"string","nullable":true,"description":"The Last Name of the Contact"},"secondaryFirstName":{"type":"string","nullable":true,"description":"The secondary First Name of the Contact"},"secondaryLastName":{"type":"string","nullable":true,"description":"The secondary Last Name of the Contact"},"company":{"type":"string","nullable":true,"description":"The name of the Company this Contact is associated with"},"email":{"type":"string","nullable":true,"description":"The email address of this Contact"},"alternateEmail":{"type":"string","nullable":true,"description":"The alternate email address of this Contact"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of this Contact"},"phoneNumberExt":{"type":"string","nullable":true,"description":"The phone number extension of this Contact"},"alternatePhoneNumber":{"type":"string","nullable":true,"description":"The alternate phone number of this Contact"},"alternatePhoneNumberExt":{"type":"string","nullable":true,"description":"The alternate phone number extension of this Contact"},"preferredContactMethod":{"type":"string","nullable":true,"description":"The preferred contact method for this Contact"},"address":{"type":"string","nullable":true,"description":"The address of this Contact"},"city":{"type":"string","nullable":true,"description":"The city of this Contact"},"state":{"type":"string","nullable":true,"description":"The state of this Contact"},"zip":{"type":"string","nullable":true,"description":"The zip or postal code of this Contact"},"leadSource":{"type":"string","nullable":true,"description":"The lead source of this Contact"},"source":{"$ref":"#/components/schemas/Source"},"owner":{"type":"object","nullable":true,"$ref":"#/components/schemas/Owner"},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"note":{"type":"string","nullable":true,"description":"A note about this Contact"},"tags":{"type":"array","description":"Tags associated with this Contact","items":{"type":"string"}}}},"Source":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","nullable":true,"description":"The ID of the entity on the other side"},"provider":{"type":"string","nullable":true,"description":"The name of the provider this entity came from"}}},"Owner":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"}}},"OwnerNullable":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/deals":{"get":{"summary":"List Deals","operationId":"listDeals","tags":["Deals"],"parameters":[{"name":"page","in":"query","description":"Page number to fetch, 1-indexed. Defaults to 1.","schema":{"type":"integer","format":"int32","minimum":1}},{"name":"perPage","in":"query","description":"Number of results per page (1-100). Defaults to the API's standard page size if omitted.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":100}},{"name":"query","in":"query","allowReserved":true,"description":"Lucene-style filter query (e.g. `status:active AND createdAt:[2024-01-01 TO *]`). Field names match the Deal object's own fields. This syntax is part of an in-flight migration (see `docs/design/lucene-migration-json-filter-spec.md`) and may change.","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Field name to sort by - any top-level field of the Deal object returned by this endpoint. Defaults to the API's natural order if omitted.","schema":{"type":"string"}},{"name":"sortDir","in":"query","description":"Sort direction: `asc` or `desc`. Only takes effect when `sort` is set.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"List of deals","content":{"application/json":{"schema":{"type":"object","properties":{"totalRows":{"type":"number"},"page":{"type":"number"},"perPage":{"type":"number"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/Deal"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## POST /deals

> Create Deal

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Deal":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The unique ID for the Deal. Ignored when creating & updating deals."},"name":{"type":"string","nullable":true,"description":"The Name of the Deal."},"contact":{"type":"object","nullable":false,"description":"Contact details to create inline with the Deal","$ref":"#/components/schemas/Contact"},"jobAddress":{"type":"object","nullable":true,"additionalProperties":false,"description":"The Job Address of this Deal","properties":{"address":{"type":"string","nullable":true,"description":"The address component of the job address"},"city":{"type":"string","nullable":true,"description":"The city component of the job address"},"state":{"type":"string","nullable":true,"description":"The state component of the job address"},"zip":{"type":"string","nullable":true,"description":"The zip code component of the job address"}}},"pipeline":{"type":"string","nullable":true,"description":"The pipeline this Deal is in"},"stage":{"type":"string","nullable":true,"description":"The stage of the pipeline this Deal is in"},"value":{"type":"number","format":"float","nullable":true,"description":"The monetary value of this Deal"},"leadSource":{"type":"string","nullable":true,"description":"The lead source of this Deal"},"leadFormKey":{"type":"string","nullable":true,"readOnly":true,"description":"The key of the lead form this Deal was created from, if any. Ignored when creating & updating deals."},"owner":{"$ref":"#/components/schemas/OwnerNullable"},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"tags":{"type":"array","description":"Tags associated with this Deal","items":{"type":"string"}},"quoteType":{"type":"object","nullable":true,"additionalProperties":false,"description":"The Quote Type associated with this Deal","properties":{"id":{"type":"string","description":"The unique ID of the Quote Type"},"label":{"type":"string","description":"The display label of the Quote Type"}}},"linkedEstimateIds":{"type":"array","description":"List of linked Estimate IDs","items":{"type":"string"}},"linkedInvoiceIds":{"type":"array","description":"List of linked Invoice IDs","items":{"type":"string"}},"jobCosting":{"type":"object","nullable":true,"additionalProperties":false,"description":"The job costing figures for this Deal","properties":{"labour":{"type":"number","format":"float","nullable":true,"description":"The labour cost of this Deal"},"materials":{"type":"number","format":"float","nullable":true,"description":"The materials cost of this Deal"},"overhead":{"type":"number","format":"float","nullable":true,"description":"The overhead cost of this Deal"},"profit":{"type":"number","format":"float","nullable":true,"readOnly":true,"description":"The calculated profit of this Deal. Read-only."},"margin":{"type":"number","format":"float","nullable":true,"readOnly":true,"description":"The calculated profit margin (percentage) of this Deal. Read-only."}}}}},"Contact":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique ID of the Contact. Ignored when creating & updating contacts"},"firstName":{"type":"string","nullable":true,"description":"The First Name of the Contact."},"lastName":{"type":"string","nullable":true,"description":"The Last Name of the Contact"},"secondaryFirstName":{"type":"string","nullable":true,"description":"The secondary First Name of the Contact"},"secondaryLastName":{"type":"string","nullable":true,"description":"The secondary Last Name of the Contact"},"company":{"type":"string","nullable":true,"description":"The name of the Company this Contact is associated with"},"email":{"type":"string","nullable":true,"description":"The email address of this Contact"},"alternateEmail":{"type":"string","nullable":true,"description":"The alternate email address of this Contact"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of this Contact"},"phoneNumberExt":{"type":"string","nullable":true,"description":"The phone number extension of this Contact"},"alternatePhoneNumber":{"type":"string","nullable":true,"description":"The alternate phone number of this Contact"},"alternatePhoneNumberExt":{"type":"string","nullable":true,"description":"The alternate phone number extension of this Contact"},"preferredContactMethod":{"type":"string","nullable":true,"description":"The preferred contact method for this Contact"},"address":{"type":"string","nullable":true,"description":"The address of this Contact"},"city":{"type":"string","nullable":true,"description":"The city of this Contact"},"state":{"type":"string","nullable":true,"description":"The state of this Contact"},"zip":{"type":"string","nullable":true,"description":"The zip or postal code of this Contact"},"leadSource":{"type":"string","nullable":true,"description":"The lead source of this Contact"},"source":{"$ref":"#/components/schemas/Source"},"owner":{"type":"object","nullable":true,"$ref":"#/components/schemas/Owner"},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"note":{"type":"string","nullable":true,"description":"A note about this Contact"},"tags":{"type":"array","description":"Tags associated with this Contact","items":{"type":"string"}}}},"Source":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","nullable":true,"description":"The ID of the entity on the other side"},"provider":{"type":"string","nullable":true,"description":"The name of the provider this entity came from"}}},"Owner":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"}}},"OwnerNullable":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/deals":{"post":{"summary":"Create Deal","operationId":"createDeal","tags":["Deals"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"responses":{"200":{"description":"Details about the new Deal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## GET /deals/{id}

> Retrieve Deal

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Deal":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The unique ID for the Deal. Ignored when creating & updating deals."},"name":{"type":"string","nullable":true,"description":"The Name of the Deal."},"contact":{"type":"object","nullable":false,"description":"Contact details to create inline with the Deal","$ref":"#/components/schemas/Contact"},"jobAddress":{"type":"object","nullable":true,"additionalProperties":false,"description":"The Job Address of this Deal","properties":{"address":{"type":"string","nullable":true,"description":"The address component of the job address"},"city":{"type":"string","nullable":true,"description":"The city component of the job address"},"state":{"type":"string","nullable":true,"description":"The state component of the job address"},"zip":{"type":"string","nullable":true,"description":"The zip code component of the job address"}}},"pipeline":{"type":"string","nullable":true,"description":"The pipeline this Deal is in"},"stage":{"type":"string","nullable":true,"description":"The stage of the pipeline this Deal is in"},"value":{"type":"number","format":"float","nullable":true,"description":"The monetary value of this Deal"},"leadSource":{"type":"string","nullable":true,"description":"The lead source of this Deal"},"leadFormKey":{"type":"string","nullable":true,"readOnly":true,"description":"The key of the lead form this Deal was created from, if any. Ignored when creating & updating deals."},"owner":{"$ref":"#/components/schemas/OwnerNullable"},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"tags":{"type":"array","description":"Tags associated with this Deal","items":{"type":"string"}},"quoteType":{"type":"object","nullable":true,"additionalProperties":false,"description":"The Quote Type associated with this Deal","properties":{"id":{"type":"string","description":"The unique ID of the Quote Type"},"label":{"type":"string","description":"The display label of the Quote Type"}}},"linkedEstimateIds":{"type":"array","description":"List of linked Estimate IDs","items":{"type":"string"}},"linkedInvoiceIds":{"type":"array","description":"List of linked Invoice IDs","items":{"type":"string"}},"jobCosting":{"type":"object","nullable":true,"additionalProperties":false,"description":"The job costing figures for this Deal","properties":{"labour":{"type":"number","format":"float","nullable":true,"description":"The labour cost of this Deal"},"materials":{"type":"number","format":"float","nullable":true,"description":"The materials cost of this Deal"},"overhead":{"type":"number","format":"float","nullable":true,"description":"The overhead cost of this Deal"},"profit":{"type":"number","format":"float","nullable":true,"readOnly":true,"description":"The calculated profit of this Deal. Read-only."},"margin":{"type":"number","format":"float","nullable":true,"readOnly":true,"description":"The calculated profit margin (percentage) of this Deal. Read-only."}}}}},"Contact":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique ID of the Contact. Ignored when creating & updating contacts"},"firstName":{"type":"string","nullable":true,"description":"The First Name of the Contact."},"lastName":{"type":"string","nullable":true,"description":"The Last Name of the Contact"},"secondaryFirstName":{"type":"string","nullable":true,"description":"The secondary First Name of the Contact"},"secondaryLastName":{"type":"string","nullable":true,"description":"The secondary Last Name of the Contact"},"company":{"type":"string","nullable":true,"description":"The name of the Company this Contact is associated with"},"email":{"type":"string","nullable":true,"description":"The email address of this Contact"},"alternateEmail":{"type":"string","nullable":true,"description":"The alternate email address of this Contact"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of this Contact"},"phoneNumberExt":{"type":"string","nullable":true,"description":"The phone number extension of this Contact"},"alternatePhoneNumber":{"type":"string","nullable":true,"description":"The alternate phone number of this Contact"},"alternatePhoneNumberExt":{"type":"string","nullable":true,"description":"The alternate phone number extension of this Contact"},"preferredContactMethod":{"type":"string","nullable":true,"description":"The preferred contact method for this Contact"},"address":{"type":"string","nullable":true,"description":"The address of this Contact"},"city":{"type":"string","nullable":true,"description":"The city of this Contact"},"state":{"type":"string","nullable":true,"description":"The state of this Contact"},"zip":{"type":"string","nullable":true,"description":"The zip or postal code of this Contact"},"leadSource":{"type":"string","nullable":true,"description":"The lead source of this Contact"},"source":{"$ref":"#/components/schemas/Source"},"owner":{"type":"object","nullable":true,"$ref":"#/components/schemas/Owner"},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"note":{"type":"string","nullable":true,"description":"A note about this Contact"},"tags":{"type":"array","description":"Tags associated with this Contact","items":{"type":"string"}}}},"Source":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","nullable":true,"description":"The ID of the entity on the other side"},"provider":{"type":"string","nullable":true,"description":"The name of the provider this entity came from"}}},"Owner":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"}}},"OwnerNullable":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/deals/{id}":{"get":{"summary":"Retrieve Deal","operationId":"getDeal","tags":["Deals"],"parameters":[{"name":"id","in":"path","description":"ID of the Deal","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Details about the deal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## PUT /deals/{id}

> Update Deal

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"OwnerNullable":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Deal":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The unique ID for the Deal. Ignored when creating & updating deals."},"name":{"type":"string","nullable":true,"description":"The Name of the Deal."},"contact":{"type":"object","nullable":false,"description":"Contact details to create inline with the Deal","$ref":"#/components/schemas/Contact"},"jobAddress":{"type":"object","nullable":true,"additionalProperties":false,"description":"The Job Address of this Deal","properties":{"address":{"type":"string","nullable":true,"description":"The address component of the job address"},"city":{"type":"string","nullable":true,"description":"The city component of the job address"},"state":{"type":"string","nullable":true,"description":"The state component of the job address"},"zip":{"type":"string","nullable":true,"description":"The zip code component of the job address"}}},"pipeline":{"type":"string","nullable":true,"description":"The pipeline this Deal is in"},"stage":{"type":"string","nullable":true,"description":"The stage of the pipeline this Deal is in"},"value":{"type":"number","format":"float","nullable":true,"description":"The monetary value of this Deal"},"leadSource":{"type":"string","nullable":true,"description":"The lead source of this Deal"},"leadFormKey":{"type":"string","nullable":true,"readOnly":true,"description":"The key of the lead form this Deal was created from, if any. Ignored when creating & updating deals."},"owner":{"$ref":"#/components/schemas/OwnerNullable"},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"tags":{"type":"array","description":"Tags associated with this Deal","items":{"type":"string"}},"quoteType":{"type":"object","nullable":true,"additionalProperties":false,"description":"The Quote Type associated with this Deal","properties":{"id":{"type":"string","description":"The unique ID of the Quote Type"},"label":{"type":"string","description":"The display label of the Quote Type"}}},"linkedEstimateIds":{"type":"array","description":"List of linked Estimate IDs","items":{"type":"string"}},"linkedInvoiceIds":{"type":"array","description":"List of linked Invoice IDs","items":{"type":"string"}},"jobCosting":{"type":"object","nullable":true,"additionalProperties":false,"description":"The job costing figures for this Deal","properties":{"labour":{"type":"number","format":"float","nullable":true,"description":"The labour cost of this Deal"},"materials":{"type":"number","format":"float","nullable":true,"description":"The materials cost of this Deal"},"overhead":{"type":"number","format":"float","nullable":true,"description":"The overhead cost of this Deal"},"profit":{"type":"number","format":"float","nullable":true,"readOnly":true,"description":"The calculated profit of this Deal. Read-only."},"margin":{"type":"number","format":"float","nullable":true,"readOnly":true,"description":"The calculated profit margin (percentage) of this Deal. Read-only."}}}}},"Contact":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique ID of the Contact. Ignored when creating & updating contacts"},"firstName":{"type":"string","nullable":true,"description":"The First Name of the Contact."},"lastName":{"type":"string","nullable":true,"description":"The Last Name of the Contact"},"secondaryFirstName":{"type":"string","nullable":true,"description":"The secondary First Name of the Contact"},"secondaryLastName":{"type":"string","nullable":true,"description":"The secondary Last Name of the Contact"},"company":{"type":"string","nullable":true,"description":"The name of the Company this Contact is associated with"},"email":{"type":"string","nullable":true,"description":"The email address of this Contact"},"alternateEmail":{"type":"string","nullable":true,"description":"The alternate email address of this Contact"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of this Contact"},"phoneNumberExt":{"type":"string","nullable":true,"description":"The phone number extension of this Contact"},"alternatePhoneNumber":{"type":"string","nullable":true,"description":"The alternate phone number of this Contact"},"alternatePhoneNumberExt":{"type":"string","nullable":true,"description":"The alternate phone number extension of this Contact"},"preferredContactMethod":{"type":"string","nullable":true,"description":"The preferred contact method for this Contact"},"address":{"type":"string","nullable":true,"description":"The address of this Contact"},"city":{"type":"string","nullable":true,"description":"The city of this Contact"},"state":{"type":"string","nullable":true,"description":"The state of this Contact"},"zip":{"type":"string","nullable":true,"description":"The zip or postal code of this Contact"},"leadSource":{"type":"string","nullable":true,"description":"The lead source of this Contact"},"source":{"$ref":"#/components/schemas/Source"},"owner":{"type":"object","nullable":true,"$ref":"#/components/schemas/Owner"},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"note":{"type":"string","nullable":true,"description":"A note about this Contact"},"tags":{"type":"array","description":"Tags associated with this Contact","items":{"type":"string"}}}},"Source":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","nullable":true,"description":"The ID of the entity on the other side"},"provider":{"type":"string","nullable":true,"description":"The name of the provider this entity came from"}}},"Owner":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/deals/{id}":{"put":{"summary":"Update Deal","parameters":[{"name":"id","in":"path","description":"ID of the Deal","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","nullable":true,"description":"The Name of the Deal."},"contact":{"type":"object","nullable":true,"description":"Contact id to associate with the Deal","properties":{"id":{"type":"string","format":"uuid","description":"A unique ID for the Contact."}}},"jobAddress":{"type":"object","nullable":true,"additionalProperties":false,"description":"The Job Address of this Deal","properties":{"address":{"type":"string","nullable":true,"description":"The address component of the job address"},"city":{"type":"string","nullable":true,"description":"The city component of the job address"},"state":{"type":"string","nullable":true,"description":"The state component of the job address"},"zip":{"type":"string","nullable":true,"description":"The zip code component of the job address"}}},"pipeline":{"type":"string","nullable":true,"description":"The pipeline this Deal is in"},"stage":{"type":"string","nullable":true,"description":"The stage of the pipeline this Deal is in"},"leadSource":{"type":"string","nullable":true,"description":"The lead source of this Deal"},"owner":{"$ref":"#/components/schemas/OwnerNullable"},"tags":{"type":"array","description":"Tags associated with this Deal","items":{"type":"string"}},"jobCosting":{"type":"object","nullable":true,"additionalProperties":false,"description":"The job costing figures for this Deal","properties":{"labour":{"type":"number","format":"float","nullable":true,"description":"The labour cost of this Deal"},"materials":{"type":"number","format":"float","nullable":true,"description":"The materials cost of this Deal"},"overhead":{"type":"number","format":"float","nullable":true,"description":"The overhead cost of this Deal"}}}}}}}},"operationId":"updateDeal","tags":["Deals"],"responses":{"200":{"description":"The updated deal","content":{"application/json":{"schema":{"additionalProperties":false,"$ref":"#/components/schemas/Deal"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## DELETE /deals/{id}

> Delete Deal

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/deals/{id}":{"delete":{"summary":"Delete Deal","parameters":[{"name":"id","in":"path","description":"ID of the Deal","required":true,"schema":{"type":"string"}}],"operationId":"deleteDeal","tags":["Deals"],"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Add Checklist to Deal

> Adds a checklist to a deal. It creates one task per checklist entry, in order. The tasks are unassigned and have no due date, the same as adding a checklist in the app. List the available checklists with \`GET /settings/taskTemplates\`.

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"DealChecklist":{"type":"object","additionalProperties":false,"properties":{"dealId":{"type":"string","description":"The ID of the deal the checklist was added to."},"templateId":{"type":"string","description":"The ID of the checklist template that was applied."},"templateLabel":{"type":"string","description":"The display label of the checklist template."},"checklistId":{"type":"string","description":"The ID of this checklist on the deal. Every task in `tasks` carries it."},"tasks":{"type":"array","description":"The tasks that were created, in checklist order. They are unassigned and have no due date.","items":{"$ref":"#/components/schemas/Task"}}},"required":["dealId","templateId","templateLabel","checklistId","tasks"]},"Task":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","nullable":false,"description":"The ID of the Task. Ignored when creating & updating tasks."},"title":{"type":"string","nullable":false,"description":"The title of the Task."},"dealId":{"type":"string","nullable":false,"description":"The deal ID this task is associated with"},"owner":{"type":"object","nullable":false,"$ref":"#/components/schemas/Owner"},"notes":{"type":"string","nullable":true,"description":"A note about this task"},"completed":{"type":"boolean","nullable":true,"description":"Whether the task has been completed"},"timestamp":{"type":"object","nullable":false,"$ref":"#/components/schemas/TaskTimestamp"}}},"Owner":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"TaskTimestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"The timestamp when this entity was created"},"updated":{"type":"number","description":"The timestamp when this entity was last updated"},"start":{"type":"number","description":"The timestamp when this task is scheduled to start"},"completed":{"type":"number","description":"The timestamp when this task was completed"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/deals/{id}/checklists":{"post":{"summary":"Add Checklist to Deal","description":"Adds a checklist to a deal. It creates one task per checklist entry, in order. The tasks are unassigned and have no due date, the same as adding a checklist in the app. List the available checklists with `GET /settings/taskTemplates`.","operationId":"createDealChecklist","tags":["Deals"],"parameters":[{"name":"id","in":"path","description":"ID of the Deal","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"templateId":{"type":"string","description":"The ID of the checklist to add, from `GET /settings/taskTemplates`."}},"required":["templateId"]}}}},"responses":{"200":{"description":"The checklist and the tasks it created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealChecklist"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Deal or checklist not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.paintscout.com/developers/deals.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.