Skip to Content
Quotation Management API

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

MethodEndpointDescription
GET/api/public-v1/quotationGet all quotations
POST/api/public-v1/quotationCreate 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-actionsDelete, change status, or send several quotations
POST/api/public-v1/quotation/{id}/status-updateUpdate quotation status
POST/api/public-v1/quotation/publish/{id}Publish/unpublish quotation
GET/api/public-v1/quotation/{id}/downloadDownload 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

ValueMeaning
0Draft
1Sent
2Accepted
3Rejected
4Expired
5Pending Approval
6Closed
7Convert 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/quotation

Request Headers

X-Secret-Key: your-secret-key-here Content-Type: application/json

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number for pagination
itemintegerNoQuotations per page (default: 10). 0 returns all quotations without pagination
searchstringNoMatches 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
statusintegerNoFilter by status (0-7, see Value Reference)
fromstringNoStart date (YYYY-MM-DD). Must be used together with to
tostringNoEnd 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_no is set when the quotation is created and never changes afterwards. generatedId is the formatted display number, also frozen at creation, so later changes to your numbering settings do not renumber existing quotations.
  • slug is null and publish is false until the quotation is published.
  • status is the numeric code from the Value Reference.
  • meta.search is only present when search was used.
  • The selected tax details (taxes, total_tax, global_tax_id, tax_rate) and theme are not included in public API responses. Taxes are applied when you create or update a quotation, and they are reflected in total.

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/quotation

Request Headers

X-Secret-Key: your-secret-key-here Content-Type: application/json

Request Body

FieldTypeRequiredDescription
estimate_nostringYesQuotation number; must be unique. A purely numeric value is replaced by a random 10-character uppercase code. The number is frozen once created
subjectstringYesQuotation subject (max 191 characters)
currencystringYesCurrency code (max 191 characters)
contact_idintegerNoContact ID to bill
lead_idintegerNoLead ID to bill
company_idintegerNoCompany ID to bill
folder_idstringNoFolder ID the quotation is filed in (must exist)
expire_datestringNoExpiry date (date format, e.g. 2024-02-14)
turnaround_timesintegerNoTurnaround time in days
up_payment_amountintegerNoUpfront payment amount. Must not exceed 100 when up_payment_type is percent. A non-zero value enables the upfront payment
up_payment_typestringNoUpfront payment type (e.g. percent, fixed); only stored when up_payment_amount is set
subtotalintegerNoSubtotal in the smallest currency unit (cents)
discountnumberNoDiscount value
discount_typestringNoDiscount type (default: percent)
totalintegerNoTotal in the smallest currency unit (cents)
itemsstringNoLine items as a JSON-encoded string (see below)
logointegerNoLogo media ID. Validated but not attached on create; attach a logo with Update a Quotation
signatureintegerNoSignature media ID. Validated but not attached on create; attach with Update a Quotation
termsstringNoTerms text
statusintegerNoOnly 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

ParameterTypeRequiredDescription
idinteger or stringYesQuotation 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

ParameterTypeRequiredDescription
idinteger or stringYesQuotation ID or quotation number

Request Body

Send a JSON object with a single quotation key. The fields below go inside it.

FieldTypeRequiredDescription
quotation.quotation_nostringYesRequired by validation (max 191) but ignored: the quotation number is frozen at creation and cannot be changed
quotation.subjectstringYesSubject (max 255)
quotation.currencystringYesCurrency code (max 10)
quotation.subtotalnumberYesRequired by validation (min 0) but ignored: the server recalculates subtotal and total from the items, discount and taxes
quotation.totalnumberYesRequired by validation (min 0) but ignored (see above)
quotation.contactsintegerNoContact ID to bill (must exist)
quotation.lead_idintegerNoLead ID to bill (must exist)
quotation.company_idintegerNoCompany ID to bill (must exist)
quotation.templateintegerNoTemplate ID (default: 1)
quotation.expire_datestringNoExpiry date
quotation.itemsarrayNoLine items (see below)
quotation.discountnumberNoDiscount value (min 0)
quotation.discount_typestringNopercent or amount (default: percent)
quotation.taxarray of integerNoIDs of the global taxes to apply. Multiple taxes can be selected; their rates are added together
quotation.global_tax_idintegerNoLegacy single global tax ID; used only when tax is empty
quotation.tax_ratenumberNoManual tax rate (0-100); used only when neither tax nor global_tax_id resolves a tax
quotation.notesarrayNoNotes (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.themestringNoValidated but not stored
quotation.logointegerNoLogo media ID
quotation.signatureintegerNoSignature 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[]

FieldTypeRequiredDescription
idintegerNoItem ID
namestringNoItem name (max 255)
qtynumberNoQuantity (min 0)
ratenumberNoUnit price (min 0)
labelstringNoItem label (max 255)
taxnumberNoLegacy per-item tax percentage (max 100); used only when the quotation has no tax selection
taxesarray of integerNoGlobal tax IDs that replace the quotation-level taxes for this line only
service_uuidstringNoUUID of a service from your service catalog to link to this line (must exist)
package_idintegerNoID of a service package to link to this line (must exist)

quotation.notes[]

FieldTypeRequiredDescription
idintegerNoNote ID
titlestringYesNote title (max 255)
descriptionstringNoNote text. A note without a description is skipped
enablebooleanYesWhether 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

ParameterTypeRequiredDescription
idinteger or stringYesQuotation 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-update

Path Parameters

ParameterTypeRequiredDescription
idinteger or stringYesQuotation ID or quotation number

Request Body

FieldTypeRequiredDescription
statusintegerYesNew 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

ParameterTypeRequiredDescription
idinteger or stringYesQuotation ID or quotation number

Request Body

FieldTypeRequiredDescription
actionTypeintegerYes1 = 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}/download

Path Parameters

ParameterTypeRequiredDescription
idintegerYesNumeric 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.pdf

Response

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

ParameterTypeRequiredDescription
idinteger or stringYesQuotation ID or quotation number

Request Body

FieldTypeRequiredDescription
invoiceHtmlstringYesHTML of the quotation that is rendered to the PDF attached to the email
template_idintegerNoID 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-actions

Request Body

FieldTypeRequiredDescription
idsarray of integerYesNumeric quotation IDs (max 1000); each must exist
actionintegerYes1 = send to client, 2 = delete, 3 = update status
statusintegerFor action 3New status applied to every quotation (see Value Reference)
invoiceHtmlstringFor action 1HTML rendered to PDF for the email, as in Send Quotation to Client
template_idintegerNoCustom 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 CodeError TypeDescription
401UnauthorizedInvalid or missing X-Secret-Key
403ForbiddenPlan or module access restriction
404Not FoundQuotation not found
422Validation ErrorRequest data failed validation
429Too Many RequestsRate 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

  1. Create then update: create the quotation, then use update to attach taxes, notes, logo/signature and server-calculated totals.
  2. One billing party: provide exactly one of contact, lead or company.
  3. Pick a number you control: quotation_no is frozen at creation; use a non-numeric value if you want to keep it (numeric values are replaced by a random code).

Workflow Management

  1. Publish before sharing links: only published quotations have a public slug link.
  2. Update status explicitly: use status codes 2 (Accepted), 3 (Rejected), 4 (Expired) to track the lifecycle.
  3. Respect rate limits: sending is limited to 10 requests per minute.
Last updated on