Quotation Management API
The Quotation Management API allows you to manage quotations/estimates in your TaskIP CRM system. You can create, read, update, and delete quotations, change their status, publish them to a shareable public link, download them as PDF, and send them to clients by email.
There is no endpoint to convert a quotation into an invoice. Quotations and invoices are managed separately; set the quotation status to 7 (Convert To Invoice) with Update Quotation Status only if you want to mark it that way.
Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
GET | /api/public-v1/quotation | Get all quotations |
POST | /api/public-v1/quotation | Create a new quotation |
GET | /api/public-v1/quotation/{id} | Get a specific quotation |
PUT / PATCH | /api/public-v1/quotation/{id} | Update a quotation |
DELETE | /api/public-v1/quotation/{id} | Delete a quotation |
POST | /api/public-v1/quotation/bulk-actions | Delete, change status, or send several quotations |
POST | /api/public-v1/quotation/{id}/status-update | Update quotation status |
POST | /api/public-v1/quotation/publish/{id} | Publish/unpublish quotation |
GET | /api/public-v1/quotation/{id}/download | Download quotation PDF |
POST | /api/public-v1/quotation/sent/{id} | Send quotation to client (rate limited) |
Wherever {id} is used (except download), you can pass either the numeric quotation ID or the quotation number (quotation_no, e.g. QUO-001). The download endpoint accepts the numeric ID only.
Value Reference
Quotation status
| Value | Meaning |
|---|---|
0 | Draft |
1 | Sent |
2 | Accepted |
3 | Rejected |
4 | Expired |
5 | Pending Approval |
6 | Closed |
7 | Convert To Invoice |
Money amounts: amounts are stored in the smallest currency unit (cents). Responses return subtotal and total already divided by 100 (decimal currency units). On create, subtotal and total are the raw stored integers; on update they are recalculated by the server (see Update a Quotation).
Get All Quotations
Retrieve a paginated list of quotations, newest first.
GET /api/public-v1/quotationRequest Headers
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
item | integer | No | Quotations per page (default: 10). 0 returns all quotations without pagination |
search | string | No | Matches the quotation number (quotation_no), subject, the contact’s name/email, or the contact company’s email. If the term exactly equals a quotation’s generatedId, only that quotation is returned |
status | integer | No | Filter by status (0-7, see Value Reference) |
from | string | No | Start date (YYYY-MM-DD). Must be used together with to |
to | string | No | End date (YYYY-MM-DD). Matches quotations whose creation date or expiry date falls inside the range |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/quotation?page=1&item=20&status=1&search=website" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"JavaScript Example
const response = await fetch('https://public-api.taskip.net/api/public-v1/quotation?page=1&item=20', {
method: 'GET',
headers: {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
}
});
const quotations = await response.json();Example Response
{
"message": "Quotation list",
"data": [
{
"id": 1,
"quotation_no": "QUO-001",
"generatedId": "QUO-2024-001",
"slug": "website-development-quotation-9b1f2c6e-...",
"company_id": null,
"company": {
"id": 15,
"name": "Acme Corporation",
"email": "billing@acme.com"
},
"folder_id": "5",
"folder": {
"id": 5,
"name": "Q1 2024 Quotations"
},
"contact_id": 45,
"contacts": {
"id": 45,
"first_name": "John",
"last_name": "Smith",
"email": "john@acme.com"
},
"lead_id": null,
"lead": null,
"subject": "Website Development Quotation",
"up_payment_status": true,
"up_payment_amount": 1000,
"up_payment_type": "fixed",
"turnaround_times": 30,
"expire_date": "2024-02-14",
"currency": "USD",
"subtotal": 4500.00,
"currentNote": {
"id": "QUO-001",
"note": "Payment Terms",
"term": "50% upfront payment required"
},
"notes": [
{
"id": 1,
"note_id": 12,
"title": "Payment Terms",
"description": "50% upfront payment required",
"enable": 1,
"order_number": 1,
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-01-15T10:30:00.000000Z"
}
],
"total": 4950.00,
"items": [
{
"id": 1,
"name": "Web Development Services",
"qty": 1,
"rate": 4500,
"label": "Project"
}
],
"logo": null,
"signature": null,
"discount": 0,
"discount_type": "percent",
"template": 1,
"status": 1,
"publish": true,
"activities": [],
"reminders": {},
"created_by": {
"first_name": "Admin",
"last_name": "User",
"full_name": "Admin User",
"name": "Admin",
"email": "admin@taskip.com",
"image": null
},
"updated_by": {
"first_name": "Admin",
"last_name": "User",
"full_name": "Admin User",
"name": "Admin",
"email": "admin@taskip.com",
"image": null
},
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-01-15T10:30:00.000000Z",
"deleted_at": null
}
],
"links": {
"first": "https://public-api.taskip.net/api/public-v1/quotation?page=1",
"last": "https://public-api.taskip.net/api/public-v1/quotation?page=2",
"prev": null,
"next": "https://public-api.taskip.net/api/public-v1/quotation?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 2,
"path": "https://public-api.taskip.net/api/public-v1/quotation",
"per_page": 20,
"to": 20,
"total": 25,
"search": "website"
}
}Notes on the response object:
quotation_nois set when the quotation is created and never changes afterwards.generatedIdis the formatted display number, also frozen at creation, so later changes to your numbering settings do not renumber existing quotations.slugisnullandpublishisfalseuntil the quotation is published.statusis the numeric code from the Value Reference.meta.searchis only present whensearchwas used.- The selected tax details (
taxes,total_tax,global_tax_id,tax_rate) andthemeare not included in public API responses. Taxes are applied when you create or update a quotation, and they are reflected intotal.
Create a Quotation
Create a new quotation. Exactly one billing party (contact_id, lead_id or company_id) may be provided.
POST /api/public-v1/quotationRequest Headers
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
estimate_no | string | Yes | Quotation number; must be unique. A purely numeric value is replaced by a random 10-character uppercase code. The number is frozen once created |
subject | string | Yes | Quotation subject (max 191 characters) |
currency | string | Yes | Currency code (max 191 characters) |
contact_id | integer | No | Contact ID to bill |
lead_id | integer | No | Lead ID to bill |
company_id | integer | No | Company ID to bill |
folder_id | string | No | Folder ID the quotation is filed in (must exist) |
expire_date | string | No | Expiry date (date format, e.g. 2024-02-14) |
turnaround_times | integer | No | Turnaround time in days |
up_payment_amount | integer | No | Upfront payment amount. Must not exceed 100 when up_payment_type is percent. A non-zero value enables the upfront payment |
up_payment_type | string | No | Upfront payment type (e.g. percent, fixed); only stored when up_payment_amount is set |
subtotal | integer | No | Subtotal in the smallest currency unit (cents) |
discount | number | No | Discount value |
discount_type | string | No | Discount type (default: percent) |
total | integer | No | Total in the smallest currency unit (cents) |
items | string | No | Line items as a JSON-encoded string (see below) |
logo | integer | No | Logo media ID. Validated but not attached on create; attach a logo with Update a Quotation |
signature | integer | No | Signature media ID. Validated but not attached on create; attach with Update a Quotation |
terms | string | No | Terms text |
status | integer | No | Only 0 (Draft) or 1 are accepted. Defaults to 0 |
The create endpoint does not calculate totals, taxes or notes. It stores subtotal, total and items exactly as you send them. To select taxes (one or many), add notes, or have totals recalculated by the server, follow up with Update a Quotation.
items string: items must be a JSON string, for example "[{\"name\":\"Web Development\",\"qty\":1,\"rate\":4500,\"label\":\"Project\"}]".
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/quotation" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"estimate_no": "QUO-001",
"contact_id": 45,
"subject": "Website Development Quotation",
"currency": "USD",
"expire_date": "2024-02-14",
"turnaround_times": 30,
"subtotal": 450000,
"total": 450000,
"discount": 0,
"discount_type": "percent",
"items": "[{\"name\":\"Web Development Services\",\"qty\":1,\"rate\":4500,\"label\":\"Project\"}]",
"status": 0
}'Python Example
import json
import requests
headers = {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
}
quotation_data = {
"estimate_no": "QUO-001",
"contact_id": 45,
"subject": "Website Development Quotation",
"currency": "USD",
"subtotal": 450000,
"total": 450000,
"items": json.dumps([
{"name": "Web Development Services", "qty": 1, "rate": 4500, "label": "Project"}
])
}
response = requests.post(
'https://public-api.taskip.net/api/public-v1/quotation',
headers=headers,
json=quotation_data
)
result = response.json()Example Response
Status: 200 OK
{
"msg": "Quotation Created",
"status": 200,
"quotation_no": "QUO-001",
"quotation": {
"id": 26,
"quotation_no": "QUO-001",
"generatedId": "QUO-2024-026",
"subject": "Website Development Quotation",
"currency": "USD",
"subtotal": 4500.00,
"total": 4500.00,
"status": 0,
"publish": false
}
}The quotation object has the same shape as in Get All Quotations (abbreviated above). Validation failures return 422 with { "error": { "<field>": ["..."] } }; choosing none or more than one billing party returns an error on contact_id.
Get a Specific Quotation
GET /api/public-v1/quotation/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Quotation ID or quotation number |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/quotation/26" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
The response is the quotation object itself (not wrapped in data), with the same fields as an item in Get All Quotations:
{
"id": 26,
"quotation_no": "QUO-001",
"generatedId": "QUO-2024-026",
"slug": null,
"company_id": null,
"company": null,
"folder_id": "",
"folder": null,
"contact_id": 45,
"contacts": { "id": 45, "first_name": "John", "last_name": "Smith", "email": "john@acme.com" },
"lead_id": null,
"lead": null,
"subject": "Website Development Quotation",
"up_payment_status": false,
"up_payment_amount": "",
"up_payment_type": null,
"turnaround_times": 30,
"expire_date": "2024-02-14",
"currency": "USD",
"subtotal": 4500.00,
"currentNote": { "id": "QUO-001", "note": null, "term": null },
"notes": [
{ "id": 1, "title": "Default Note", "description": "Default description", "enable": true }
],
"total": 4500.00,
"items": [
{ "name": "Web Development Services", "qty": 1, "rate": 4500, "label": "Project" }
],
"logo": null,
"signature": null,
"discount": 0,
"discount_type": "percent",
"template": 1,
"status": 0,
"publish": false,
"activities": [],
"reminders": {},
"created_by": { "full_name": "Admin User", "email": "admin@taskip.com" },
"updated_by": { "full_name": "Admin User", "email": "admin@taskip.com" },
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2024-01-15T10:30:00.000000Z",
"deleted_at": null
}When a quotation has no saved notes, notes falls back to the workspace’s default quotation notes.
A missing quotation returns 404 with { "status": 404, "msg": "Quotation not found" }.
Update a Quotation
Update an existing quotation. Supports both PUT and PATCH. All data is wrapped in a top-level quotation object.
PUT /api/public-v1/quotation/{id}
PATCH /api/public-v1/quotation/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Quotation ID or quotation number |
Request Body
Send a JSON object with a single quotation key. The fields below go inside it.
| Field | Type | Required | Description |
|---|---|---|---|
quotation.quotation_no | string | Yes | Required by validation (max 191) but ignored: the quotation number is frozen at creation and cannot be changed |
quotation.subject | string | Yes | Subject (max 255) |
quotation.currency | string | Yes | Currency code (max 10) |
quotation.subtotal | number | Yes | Required by validation (min 0) but ignored: the server recalculates subtotal and total from the items, discount and taxes |
quotation.total | number | Yes | Required by validation (min 0) but ignored (see above) |
quotation.contacts | integer | No | Contact ID to bill (must exist) |
quotation.lead_id | integer | No | Lead ID to bill (must exist) |
quotation.company_id | integer | No | Company ID to bill (must exist) |
quotation.template | integer | No | Template ID (default: 1) |
quotation.expire_date | string | No | Expiry date |
quotation.items | array | No | Line items (see below) |
quotation.discount | number | No | Discount value (min 0) |
quotation.discount_type | string | No | percent or amount (default: percent) |
quotation.tax | array of integer | No | IDs of the global taxes to apply. Multiple taxes can be selected; their rates are added together |
quotation.global_tax_id | integer | No | Legacy single global tax ID; used only when tax is empty |
quotation.tax_rate | number | No | Manual tax rate (0-100); used only when neither tax nor global_tax_id resolves a tax |
quotation.notes | array | No | Notes (see below). Notes missing from the array are deleted; omit or send empty to remove all notes. An entry whose id belongs to this quotation is updated in place; entries without an id are created |
quotation.theme | string | No | Validated but not stored |
quotation.logo | integer | No | Logo media ID |
quotation.signature | integer | No | Signature media ID |
If any of contacts, lead_id or company_id is present in the request, exactly one of them must have a value (error on quotation.contacts otherwise). Billing fields you leave out are cleared.
quotation.items[]
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | No | Item ID |
name | string | No | Item name (max 255) |
qty | number | No | Quantity (min 0) |
rate | number | No | Unit price (min 0) |
label | string | No | Item label (max 255) |
tax | number | No | Legacy per-item tax percentage (max 100); used only when the quotation has no tax selection |
taxes | array of integer | No | Global tax IDs that replace the quotation-level taxes for this line only |
service_uuid | string | No | UUID of a service from your service catalog to link to this line (must exist) |
package_id | integer | No | ID of a service package to link to this line (must exist) |
quotation.notes[]
| Field | Type | Required | Description |
|---|---|---|---|
id | integer | No | Note ID |
title | string | Yes | Note title (max 255) |
description | string | No | Note text. A note without a description is skipped |
enable | boolean | Yes | Whether the note is shown |
How totals are calculated: subtotal is the sum of qty x rate over the items; the discount is applied to the subtotal; the selected taxes (sum of their rates) are applied to the discounted amount. A line with its own taxes array uses those taxes instead, with the discount allocated pro-rata across lines.
Example Request
curl -X PUT "https://public-api.taskip.net/api/public-v1/quotation/26" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"quotation": {
"quotation_no": "QUO-001",
"contacts": 45,
"subject": "Website Development Quotation - Revised",
"currency": "USD",
"expire_date": "2024-03-01",
"items": [
{
"name": "Web Development Services",
"qty": 1,
"rate": 4500,
"label": "Project",
"service_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
{ "name": "Hosting (1 year)", "qty": 1, "rate": 300, "label": "Service", "package_id": 12 }
],
"discount": 10,
"discount_type": "percent",
"tax": [1, 3],
"notes": [
{ "title": "Payment Terms", "description": "50% upfront payment required", "enable": true }
],
"subtotal": 4800,
"total": 4800
}
}'Example Response
Status: 200 OK
{
"msg": "Quotation update success"
}Errors: 422 { "msg": "Quotation Does not Exists" } when the quotation is not found; 422 { "error": { "quotation.subject": ["..."] } } for validation failures.
Delete a Quotation
DELETE /api/public-v1/quotation/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Quotation ID or quotation number |
Warning: Deleting a quotation also removes its notes and tax rows. This action cannot be undone through the API.
Example Request
curl -X DELETE "https://public-api.taskip.net/api/public-v1/quotation/26" \
-H "X-Secret-Key: your-secret-key-here"Example Response
{
"msg": "Quotation Deleted Successfully",
"status": 200
}A missing quotation returns 404 with { "status": 404, "msg": "Quotation not found" }.
Update Quotation Status
POST /api/public-v1/quotation/{id}/status-updatePath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Quotation ID or quotation number |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
status | integer | Yes | New status (0-7, see Value Reference). Must be a valid quotation status code, otherwise 422 in the standard Laravel validation shape (message / errors) |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/quotation/26/status-update" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "status": 2 }'Example Response
{
"status": true,
"msg": "Quotation Status Updated",
"activities": [
{
"id": 88,
"user": { "id": 1, "first_name": "Admin", "last_name": "User" },
"subject_type": "Modules\\Estimate\\Models\\Estimate",
"task": "changed the status",
"status": 2,
"type": "status",
"created_at": "2024-01-26T14:30:00.000000Z",
"updated_at": "2024-01-26T14:30:00.000000Z"
}
]
}activities lists the quotation’s activity log, newest first. A missing quotation returns 404 with { "msg": "Quotation not found" }.
Publish/Unpublish Quotation
Publish a quotation to generate a public shareable link, or remove that link.
POST /api/public-v1/quotation/publish/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Quotation ID or quotation number |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
actionType | integer | Yes | 1 = publish, 0 = unpublish |
Publishing a quotation for the first time also sets its status to Sent. Publishing an already published quotation returns the existing link. Only workspace administrators can publish/unpublish; other users receive an error.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/quotation/publish/26" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "actionType": 1 }'Example Response
{
"msg": "Quotation published successfully",
"slug": "https://your-workspace-link/public/your-tenant/quotation/website-development-quotation-9b1f2c6e-..."
}Other messages: Quotation already published (with slug) and Quotation unpublished (no slug). The slug field in the response is the full public URL.
Download Quotation PDF
Download a quotation as a PDF file.
GET /api/public-v1/quotation/{id}/downloadPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Numeric quotation ID (quotation numbers are not accepted) |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/quotation/26/download" \
-H "X-Secret-Key: your-secret-key-here" \
--output quotation_26.pdfResponse
Returns a PDF file download. The file is named invoice-<dd-mm-yy>.pdf (the same name pattern is used for quotations). If no quotation exists with the given ID, the API returns 422 with { "error": { "msg": ["Quotation not found"] } }.
Send Quotation to Client (Rate Limited)
Email the quotation to the client’s contact.
This endpoint is rate limited to 10 requests per minute. In addition, the same quotation can only be emailed a limited number of times in a short period; exceeding it returns 429.
POST /api/public-v1/quotation/sent/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | Quotation ID or quotation number |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
invoiceHtml | string | Yes | HTML of the quotation that is rendered to the PDF attached to the email |
template_id | integer | No | ID of a custom email template to use instead of the default email |
The email is sent to the quotation’s contact. If the quotation has no contact, nothing is emailed, but the quotation is still marked as sent. A public share link is created automatically if the quotation was not yet published, and the status is set to Sent.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/quotation/sent/26" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"invoiceHtml": "<html><body><h1>Quotation QUO-001</h1></body></html>",
"template_id": 4
}'Example Response
"Quotation sent successfully"The response body is a plain JSON string with status 200. When the per-document email limit is hit, 429 is returned with the limiter message as the JSON string body. A missing quotation returns 404 with { "status": 404, "msg": "quotation not found" }.
Bulk Actions
Perform an action on up to 1000 quotations at once.
POST /api/public-v1/quotation/bulk-actionsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of integer | Yes | Numeric quotation IDs (max 1000); each must exist |
action | integer | Yes | 1 = send to client, 2 = delete, 3 = update status |
status | integer | For action 3 | New status applied to every quotation (see Value Reference) |
invoiceHtml | string | For action 1 | HTML rendered to PDF for the email, as in Send Quotation to Client |
template_id | integer | No | Custom email template ID for action 1 |
Action 1 is limited to 10 bulk-send requests per minute.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/quotation/bulk-actions" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"ids": [20, 21, 22],
"action": 3,
"status": 4
}'JavaScript Example
const response = await fetch('https://public-api.taskip.net/api/public-v1/quotation/bulk-actions', {
method: 'POST',
headers: {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
},
body: JSON.stringify({ ids: [20, 21, 22], action: 2 })
});
const result = await response.json();Example Response
{
"msg": "Quotation bulk actions successful"
}An unknown action value returns 422 with { "msg": "Quotation bulk actions not found" }. Exceeding the send limit returns 429.
Error Responses
Common Error Codes
| Status Code | Error Type | Description |
|---|---|---|
401 | Unauthorized | Invalid or missing X-Secret-Key |
403 | Forbidden | Plan or module access restriction |
404 | Not Found | Quotation not found |
422 | Validation Error | Request data failed validation |
429 | Too Many Requests | Rate limit exceeded |
Validation Error Shapes
Create, update and (for the update endpoint) nested-field failures use:
{
"error": {
"subject": ["The subject field is required."],
"contact_id": ["Select exactly one of contact, lead, or company to bill."]
}
}Bulk-actions and publish requests use the standard Laravel shape:
{
"message": "The action field is required.",
"errors": {
"action": ["The action field is required."]
}
}Best Practices
Quotation Creation
- Create then update: create the quotation, then use update to attach taxes, notes, logo/signature and server-calculated totals.
- One billing party: provide exactly one of contact, lead or company.
- Pick a number you control:
quotation_nois frozen at creation; use a non-numeric value if you want to keep it (numeric values are replaced by a random code).
Workflow Management
- Publish before sharing links: only published quotations have a public
sluglink. - Update status explicitly: use status codes
2(Accepted),3(Rejected),4(Expired) to track the lifecycle. - Respect rate limits: sending is limited to 10 requests per minute.