Enquiries

Create enquiries from forms built in your own application, and list a signed-in customer's enquiry history. First, complete the setup.

Creating enquiries

Use createEnquiry() as the submit handler for a custom form built in your application. The DOM Package does not render a generic form or expose Tiquo's form-schema builder; your application owns the fields, validation, consent text, success state, and error state.

If the visitor is already authenticated, the enquiry is linked to their customer profile. If not, Tiquo uses the public key and Website SDK website-domain configuration to accept the submission, find or create the customer by email, and attach the enquiry. Names and contact fields fill missing profile data but do not overwrite existing non-empty values. Creating an enquiry does not sign a visitor in.

const result = await tiquo.createEnquiry({
  customer: {
    email: 'customer@example.com',
    firstName: 'John',
    lastName: 'Smith',
    phone: '+44 7911 123456',
  },
  enquiry: {
    type: 'YOUR_ENQUIRY_TYPE_ID',
    enquiryParameterValues: [
      { enquiryParameterId: 'ENQUIRY_PARAMETER_SCHEMA_ID', value: '40 guests' },
    ],
    subject: 'Private event enquiry',
    message: 'I would like to book a private event for 40 guests.',
    source: 'website',
  },
});

console.log(result.enquiry.id);

customer.email is required. The enquiry must include either enquiry.message or enquiry.subject.

priority can be low, medium, high, or urgent. source can be online, website, phone, email, walk_in, social, referral, pos, or admin. Phone values are normalized before submission when possible. Use the phone number field helper (TiquoPhone.createField()) on the phone input so international numbers are formatted correctly, then send its e164 value as phone and its countryCode as phoneCountry.

Choose the enquiry type

Set enquiry.type to an enquiry type ID to route the enquiry to that type. To get the ID:

1. Go to Settings > Enquiries.
2. Open the ⋯ menu on the enquiry type and choose Copy enquiry type ID.
3. Paste it as enquiry.type, replacing YOUR_ENQUIRY_TYPE_ID.

The enquiry is created under that type, so it appears in that type's pipeline and uses its stages, enquiry parameters, and auto-assignment. Without a type, the enquiry goes to the General type (general). Renaming a type keeps its ID, so your code keeps working.

For ready-made code, choose Example form code in the same menu and pick DOM Package. It writes this call for that enquiry type in JavaScript or TypeScript, or a React form component, with its enquiry type ID and parameter IDs filled in. Switches beside the code add or remove each field and parameter.

Spam screening and rate limits

Enquiries from visitors who aren't signed in with a customer profile are screened for spam. A reserved test phone number, or HTML or script in a name, subject, message, or answer, makes createEnquiry() throw with the message "This enquiry could not be submitted." An enquiry from a throwaway email address still resolves normally, but result.customer.id is an empty string: the enquiry waits in the dashboard's spam list and no customer is created until staff mark it Not spam. Repeated submissions are rate limited (5 per email address or phone number every 10 minutes for visitors who aren't signed in) and throw with a 429 statusCode. See Spam screening and rate limits.

Enquiry parameters

enquiry.enquiryParameterValues stores answers on the new enquiry only. Configure these fields under Settings > Enquiries, when creating or editing the enquiry type. Each entry is { enquiryParameterId, value }, where the ID belongs to that enquiry type and organisation. These are not customer parameter IDs. Even an enquiry field named "Marketing Opt-In" does not change customer consent.

To copy a parameter's ID, choose Edit Enquiry Type in the type's ⋯ menu under Settings > Enquiries, then open the ⋯ menu on the parameter and choose Copy enquiry parameter ID. A new parameter gets its ID once the enquiry type is saved.

Use strings for text, dropdown, date (YYYY-MM-DD), and datetime (ISO datetime) values; booleans for Yes/No fields; and string arrays for multiselects. Dropdown and multiselect options must match the configured options. Up to 100 distinct parameters are allowed, with at most 10,000 serialized characters per value. Empty values are omitted rather than rejected, including an empty string for a dropdown, date, or datetime, so optional parameters can be left blank. false is saved. Invalid, duplicate, deleted, wrong-type, or foreign-organisation IDs reject the whole submission. enquiry.parameterValues and entry parameterId are not accepted; use the explicit enquiry-prefixed names above.

The enquiry.created event includes normalized values in enquiryParameters.<enquiryParameterId>. Values are strings, including "true"/"false" for booleans and JSON strings for multiselects. No customer parameter payload is included. See the Customer API enquiry reference.

Customer parameters

An enquiry can also fill in customer profile values with customer.customerParameterValues.

await tiquo.createEnquiry({
  customer: {
    email: 'guest@example.com',
    customerParameterValues: [
      { customerParameterId: 'YOUR_CUSTOMER_PARAMETER_ID', value: 'Example Ltd' },
    ],
    // Legacy alternative: details: { YOUR_CUSTOMER_PARAMETER_ID: 'Example Ltd' }
  },
  enquiry: { type: 'YOUR_ENQUIRY_TYPE_ID', subject: 'Waitlist' },
});

Use a customer parameter schema ID for customerParameterId, not an enquiry parameter ID. Values accept strings, finite numbers, booleans, null, or string arrays (for multiselects). At most 100 entries across both fields and 10,000 serialized characters per value are accepted. Enquiry answers remain separate under enquiry.enquiryParameterValues with enquiryParameterId.

• Customer parameters can be initialized through customer.customerParameterValues only when no stored value exists and the parameter is customer editable.
• Existing rows are never overwritten, even when the stored value is empty, false, or a system default. This applies to guests and authenticated enquiry submissions.
• customer.details remains supported as a legacy object keyed by customer parameter ID, name, or normalized key.
• Explicit array entries are processed first; the first non-empty value for a missing schema wins.
• Null, empty text, and empty arrays are ignored. Invalid or non-editable parameters reject the whole submission.

Listing enquiries

After sign-in, getEnquiries() returns the customer's own enquiries.

const { enquiries, hasMore, nextCursor } = await tiquo.getEnquiries({ limit: 20 });

for (const enquiry of enquiries) {
  console.log(enquiry.enquiryNumber, enquiry.subject, enquiry.status);
}

if (hasMore) {
  const nextPage = await tiquo.getEnquiries({ limit: 20, cursor: nextCursor });
}

getEnquiries() accepts limit, cursor, and status options. The maximum page size is 100 and the default is 50. See List Enquiries for every field.

Tiquo forms

Tiquo forms created in the platform are a separate feature and can be sent or embedded through their configured customer-facing flow. Use createEnquiry() when you need a completely custom website form whose result should create an enquiry. See Documents and Forms.