Smart references

Many Qualy API endpoints include fields that point to another record, such as contact, service, supplier, tax, or template. When the API Reference describes one of these fields as accepting a reference, you can send either the record's ObjectId or a supported natural identifier.

Use ObjectIds when you already store them. Use natural identifiers when your integration is driven by human-entered names, emails, partnership codes, or AI-generated payloads.

Supported identifiers

Record type	Accepted reference values
Contact	ObjectId or contact email. Email matching is case-insensitive.
Partnership	ObjectId, partnership code, exact partnership name, or partnership name prefix.
Service	ObjectId, exact service name, or service name prefix.
Tax	ObjectId, exact tax name, or tax name prefix.
Template	ObjectId, exact template name, or template name prefix.

Only fields documented as reference fields support this behavior. If the API Reference says a field requires an ObjectId, continue sending an ObjectId.

Example

This payment intent uses natural identifiers for the contact, supplier, item service, tax rate, and template:

const response = await fetch('https://api.qualyhq.com/v1/payment-intents/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'ApiKey your-api-key-here',
    'X-TENANT-ID': 'your-tenant-id-here',
  },
  body: JSON.stringify({
    intentType: 'ad-hoc',
    contact: 'jane@example.com',
    currency: 'AUD',
    suppliers: ['usyd'],
    tax: 'GST 10%',
    template: 'Standard Tuition Plan',
    items: [
      {
        name: 'Tuition fee',
        amount: 100000,
        service: 'Diploma of Business',
      },
    ],
  }),
});

Qualy resolves each reference before the endpoint runs. The stored object still contains ObjectIds, and response payloads keep the same shape as ObjectId-based requests.

Matching rules

ObjectId values are accepted directly. Natural identifiers are resolved against the tenant's records before the request is processed.

Reference values must be strings between 3 and 256 characters. Arrays of references use the same rules for each item.

For exact names and prefixes, Qualy must find exactly one matching record. A unique prefix is accepted; a prefix that matches multiple records is rejected so you can disambiguate the request.

Prefer stable identifiers

For automated integrations, store ObjectIds or unique natural identifiers such as contact email and partnership code when possible. Prefix matching is convenient, but it can become ambiguous when similarly named records are added later.

Errors

Scenario	HTTP status	Result
No record matches the reference	`404`	The request fails with `Reference not found`.
More than one record matches the reference	`409`	The request fails with `Reference is ambiguous` and includes matching candidate identifiers and display fields.
A reference value is invalid	`400`	The request fails before the endpoint runs.
Multiple reference fields fail in one request	`422`	The response includes the field-level reference errors.

Idempotent requests

For idempotent endpoints, Qualy fingerprints the raw request body before smart references are resolved. A retry with the same Idempotency-Key and the same body returns the cached response, even if a natural identifier would resolve differently later.

If you want Qualy to resolve the reference again after a contact email, partnership name, service name, tax name, or template name changes, send a new Idempotency-Key.