Our APIs support the use of External IDs to help clients maintain a consistent link between their own systems and resources managed within our platform. An External ID is a client-defined identifier that can be attached to resources when they are created or updated.
External IDs must be unique within the client’s scope for each resource type. They are always provided and managed by the client, and our APIs treat them as opaque values.
In addition to the default lookup by system-generated resource ID, our APIs support fetching resources using alternative lookup keys through the Quinyx Lookup Syntax.
The syntax uses a prefix (lookup key) followed by a colon and the lookup value:
lookup-key:lookup-valueExamples:
GET /api/v1/employees/8348
GET /api/v1/employees/xrefID:my-external-id-7
GET /api/v1/employees/badgeNumber:56789This allows resources to be retrieved using identifiers such as internal and external IDs, badge numbers, or other supported keys.
Lookup values must match the following regex:
^[a-zA-Z0-9._-]{1,64}$This means only letters, digits, periods (.), underscores (_) and hyphens (-) are allowed.
This pattern is based on the unreserved character set defined in RFC 3986, which specifies the URI structure.
The xrefId field is the default external identifier field in our apis. However, different resources may support different fields as external identifiers. The supported identifiers and lookup keys can be found on the API specification.
If your identifiers contain characters outside the supported set (for example: spaces, @, #, = or accented letters), you should normalize or encode them before storing them in Quinyx.
Replace unsupported characters with a supported substitute (e.g. replace spaces with _).
Example: employee id 123 → employee_id_123
Use a reversible encoding (such as Base58 or URL-safe Base64) to map the original ID into a compliant value. Quinyx will treat it as opaque value.
Example: emp#123 → ZW1wIzEyMw
Keep a mapping table in your system between the original identifier and the Quinyx identifier.