# Proposals

## Create Proposal

<mark style="color:green;">`POST`</mark> `https://api.clients.icaal.co.uk/proposals`

Create a new proposal from a proposal template.

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th width="106.72265625" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>template</td><td>string</td><td>true</td><td>The reference for the proposal template.</td></tr><tr><td>name</td><td>string</td><td>true</td><td>The name (internal) for the new proposal.</td></tr><tr><td>heading</td><td>string</td><td>true</td><td>The heading for the new proposal.</td></tr><tr><td>subheading</td><td>string</td><td>true</td><td>The subheading for the new proposal.</td></tr><tr><td>action</td><td>string</td><td>true</td><td>The button label for the new proposal.</td></tr><tr><td>user_email</td><td>string</td><td>true</td><td>The email address of the user to assign as the author of the new proposal. The user must already have permissions to create proposals.</td></tr><tr><td>included_pages</td><td>array</td><td>false</td><td>List of pages to include in the new proposal from the template.</td></tr><tr><td>included_pages[0]</td><td>string</td><td>true</td><td>Page name to specify the page to be included from the template.</td></tr><tr><td>excluded_pages</td><td>array</td><td>false</td><td>List of pages to exclude in the new proposal from the template.</td></tr><tr><td>excluded_pages[0]</td><td>string</td><td>true</td><td>Page name to specify the page to be excluded from the template.</td></tr><tr><td>approval_url</td><td>string </td><td>false</td><td>The URL to be used for all "Approve" buttons for the new proposal. Recommended to use either this or <code>approval_redirect_url</code>.</td></tr><tr><td>approval_redirect_URL</td><td>string</td><td>false</td><td>The URL to redirect customers to after they complete the approval flow. Recommended to use either this or <code>approval_url</code>.</td></tr><tr><td>attachment_embeds</td><td>array</td><td>false</td><td>List of attachments (PDFs) to be embedded within the new proposal.</td></tr><tr><td>attachment_embeds[0][page]</td><td>string</td><td>true</td><td>The page name to embed the attachment within the new proposal.</td></tr><tr><td>attachment_embeds[0][attachment]</td><td>file</td><td>false</td><td>The file (PDF) to be embedded in the specified page in the new proposal. Use either this or <code>url</code>.</td></tr><tr><td>attachment_embeds[0][url]</td><td>string</td><td>false</td><td>The URL of the document (PDF) to be embedded in the specified page in the new proposal. Use either this or <code>attachment</code>.</td></tr><tr><td>attachment_images</td><td>array</td><td>false</td><td>List of attachments (images) to be included as within the new proposal.</td></tr><tr><td>attachment_images[0][page]</td><td>string</td><td>true</td><td>The page name to include the image within the new proposal. Images will be included in an "image" section type. If a page with a matching name does not already exist, it will be created.</td></tr><tr><td>attachment_iamges[0][order]</td><td>integer</td><td>false</td><td>The order of the page in the pages list. If the page name specific already exists, the page order will be updated. Omit to add the page at the end of the list (or use the existing page order if the page name specified already exists).</td></tr><tr><td>attachment_images[0][url]</td><td>string (URL)</td><td>true</td><td>The URL of the new image to include. Limited to jpg, png, webp, gif. Max 10MB per image.</td></tr><tr><td>attachment_images[0][size]</td><td>string</td><td>false</td><td>The display size for the new image. Choose from "full-width", "large", "medium" or "small". Omit to default to full-width.</td></tr><tr><td>cost_groups</td><td>array</td><td>false</td><td>Nested arrays to specify cost groups and cost items in the new proposal.</td></tr><tr><td>cost_groups[0][name]</td><td>string</td><td>true</td><td>Name of the cost group.</td></tr><tr><td>cost_groups[0][cost_items]</td><td>array</td><td>false</td><td>List of key value pairs to specify the contents of the cost group.</td></tr><tr><td>cost_groups[0][cost_items][0][name]</td><td>string</td><td>true</td><td>The name of the cost item.</td></tr><tr><td>cost_groups[0][cost_items][0][cost_type]</td><td>string</td><td>true</td><td>The type for the cost item. Accepts one_off|monthly|annual.</td></tr><tr><td>cost_groups[0][cost_items][0][amount]</td><td>numeric string</td><td>true</td><td>The amount for the cost item in GBP pounds and pence, e.g. "1000.00".</td></tr><tr><td>cost_groups[0][cost_items][0][tax_rate]</td><td>integer</td><td>true</td><td>The tax rate for the cost item, e.g. "20" for 20% tax.</td></tr><tr><td>cost_groups[0][cost_items][0][description]</td><td>string</td><td>false</td><td>The description for the cost item.</td></tr><tr><td>cost_groups[0][cost_items][0][quantity]</td><td>integer</td><td>true</td><td>The quantity of the cost item.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```json
{
    "message": "The proposal has been successfully created.",
    "reference": "xyz789abc",
    "edit_url": "https://clients.icaal.co.uk/proposals/xyz789abc/edit"
}
```

{% endtab %}
{% endtabs %}

## Update Proposal

<mark style="color:purple;">`PATCH`</mark> `https://api.clients.icaal.co.uk/proposals/[reference]`

Update a proposal by reference.

#### Headers

| Name          | Type   | Description                          |
| ------------- | ------ | ------------------------------------ |
| Authorization | string | Authenticate using the bearer token. |

#### Request Body

<table><thead><tr><th>Name</th><th>Type</th><th width="111.67578125" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>string</td><td>true</td><td>The new status for the proposal. Use either "unsent", "sent", "opened", "approved" or "paid".</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}

```json
{
    "message": "The proposal status has been successfully updated.",
    "reference": "xyz789abc",
    "status": "sent"
}
```

{% endtab %}
{% endtabs %}