Reference & appendix

The lookup material: field types and the typed value model, the error catalog, a glossary, the raw encryption spec for non-SDK integrators, and where to find the live API spec.

Field types & the typed value model

A contact-field type is a row, not a name this documentation lists. One route serves every type the platform carries, and everything below — what a value looks like, what makes it valid, which types a request row accepts — is read off those rows. Adding a type is a row, so a list printed here would be stale the day one is added.

The registry route

GET /api/contact-field-types answers a bare JSON array of RAW rows. Your service data client and your account client are both granted it (Authentication), and the SDKs fetch it beside the request-field catalog and hold it for the client's life. Each row:

A child INHERITS every column it leaves null from its nearest ancestor that sets one — input, lane, check, options, fields. validation is the exception and is additive: a value must match the regex of every ancestor that has one, root first, plus the type's own. Resolving a type means filling those columns in and collecting those regexes; every rule below applies to the RESOLVED definition, never to a raw row.

The tree, and what a request row accepts

Types form a tree. text is the root of the string-like types (email, phone, url, gender, country, nationality, personal_number, place_of_birth, date, and date_of_birth under date); number is the root of integer, decimal and float; document is the root of pdf_document; legal_document is the root of proof_of_identity, which is the parent of the ID-document types passport, photo_id, drivers_license and residence_permit. address, creditcard, bank, photo, select and multiselect are roots with no children today. Walk parent to read the current shape rather than trusting this paragraph.

The two vocabularies

Only two things about a type are fixed code rather than data. The primitives, which say what a value IS:

personal_number and place_of_birth are line strings. A verified place of birth is <city>, <alpha-2> (e.g. Amsterdam, NL) — a country CODE, not a name.

And the checks, which say what a value must satisfy beyond a regex:

A value is checked in one order: the primitive's own rule, then the resolved check, then every regex root-first, then the sub-field entries. The check's normalised value is what those regexes see; the primitive's is not. An empty value is valid — whether it is required is your request row's business — and a type your copy of the registry does not carry accepts anything, so an older integration never rejects a value it simply does not know yet.

Binary answers

A binary answer is one whose type resolves to the photo or document lane — today photo, document, pdf_document, legal_document, proof_of_identity and the four ID-document types. For those, the change feed, the webhook and a connection's detail row all carry a value_url instead of an inline value. Fetch it with your client token from GET /api/company-data/connections/{connectionId}/slots/{serviceFieldId}/file. The SDKs expose this as a lazy handle (.bytes() / .save()).

That endpoint has three response shapes, so branch on Content-Type first and then on the body's encrypted member: an answer from a private source field arrives as the familiar {"encrypted": true, "value": <wrapper>} JSON to decrypt off-platform; an answer from a non-private source whose type stores more than one file or declares metadata entries (the ID-document types and legal_document) arrives as {"encrypted": false, "value": "<envelope string>"} — the same envelope, in the clear; every other non-private answer arrives as the raw file with its own content type and nothing to decrypt. Which you get is the person's setting and their choice of field, not yours, and both can change. The envelope inlines every page (or the single file) as a data URI and carries every entry the type declares beside it, so an ID document delivers its pages, its document_number, its expiry_date, its issuing_country and the holder name. Every 200 carries X-Allus-Content-Sha256 over exactly what was served; an expired Share once answer answers 410 company_data.file_expired with that digest and its expired_at. Details: API → binary file.

The reserved type key plugin

plugin is never a registry row. A request row, flow field or claim whose type is plugin is answered through a plugin and carries a plugin spec instead of a registry type; its value is the plugin answer's self-describing JSON string, which the SDKs type as a PluginValue before they consult the registry. No type named plugin can be added to the registry.

The usertype gate

Fields carry a usertype of person, company, or any — it gates which profile type may fill a field, not which clients receive its definition. The field catalog from GET /api/contact-fields is owner-filtered but unfiltered by usertype (your client receives every definition so it can resolve any id in the data). Pass ?usertype=person|company|any for an explicitly filtered view.

The conclusions model (SDK output)

The SDKs return conclusions, not raw rows: for each connected person, your request-field slug → the typed plaintext value, plus whether it is live (auto-updating), its updatedAt, and a verified boolean (verified values — true only when the recomputed sha256(verified_salt ‖ plaintext) matches the server binding; false means "not attested", not "wrong"). Field definitions (label, type, flags) come from a separate call. The person's source field is never exposed — you address everything by your own request-field slug. See SDKs for the per-language shapes.

Plugin routes

The routes behind plugins. The registry routes under /api/account/plugins serve the portal's Configuration › Plugins screen for a company caller; the two pass routes are the ones an integration calls — see Contract flows → Answering a plugin field. A plugin itself is only ever called by the platform's forwarder, never by the API.

Error keys

Errors return a stable error_key string. The ones you'll encounter integrating the service + portal APIs:

A plugin call refused by the forwarder carries its own plugin.* keys — see Contract flows → Answering a plugin field.

Raw encryption spec (non-SDK integrators)

If you decrypt person data without an SDK, here is the exact contract. The SDKs implement all of this for you — this section is for teams writing their own decryption.

The {"_enc":1,…} value wrapper

Every person→service value is a hybrid-encrypted JSON wrapper, encrypted for your service public key:

{
  "_enc": 1,
  "k": "base64( RSA-OAEP-SHA256( aes_key, service_public_key ) )",
  "iv": "base64( 12-byte AES-GCM IV )",
  "d": "base64( AES-256-GCM ciphertext, 16-byte tag appended )"
}

To decrypt:

1. Base64-decode k and RSA-OAEP-decrypt it with your service private key to recover the 32-byte AES key. OAEP uses SHA-256 (MGF1-SHA256) — pin the hash explicitly; do not accept a SHA-1 default.
2. Base64-decode iv (12 bytes) and d. The last 16 bytes of d are the GCM tag.
3. AES-256-GCM-decrypt d with the AES key + IV → the plaintext (a string, or JSON to parse per the field type).

The service private key (PEM)

Your service private key is downloaded from the service's Overview tab in the portal as an OpenSSL-compatible encrypted PKCS#8 PEM (PBES2: PBKDF2-SHA256 + AES-256-CBC), protected by the passphrase shown once at service creation (recoverable from a saved copy — Recovery). Decrypt it to a usable key with the passphrase, e.g.:

# decrypt the downloaded service PEM with its passphrase
openssl pkcs8 -in service-CRM.pem -passin pass:"$ALLUS_KEY_PASSPHRASE"
# → -----BEGIN PRIVATE KEY----- … (use this to RSA-OAEP-decrypt the "k" field above)

The SDKs load this PEM in memory at startup (from service_private_key + key_passphrase in config.json) and never write the decrypted key back to disk.

Glossary

Status

• Company-data API — connections, the drain-on-fetch change feed, binary answers, request-fields, logs, documents and contracts, connect requests, messaging and contract-flow runs, behind registered-client whitelisting.
• Webhooks — push delivery of all seventeen change events, the per-webhook circuit-breaker and the account-key envelope.
• Account automation, Sign in with allme, the OIDC provider, 2FA by allme and plugins — each on its own page in this guide.
• SDKs — six languages (Python, TypeScript, Go, C#/.NET, Java, PHP) wrapping the company-data API with transparent decryption, the crash-safe changes pump, and webhook helpers.

The API surface is defined by the generated OpenAPI specs — those are the source of truth. They are generated from the code and regenerated as part of every change that touches an endpoint, so treat the spec as authoritative over any prose on this site.

The live API spec

The interactive OpenAPI explorer hosts five specs in one dropdown: service (the primary integration surface), portal (the advanced config API), plus complete, client, and admin. Deep-link to a spec with ?spec=:

• Service API — every endpoint your registered client is granted
• Portal API — /api/services/*
• Complete API (public)

“Complete API (public)” is complete for public use. It documents every endpoint of the platform except the internal administration surface (/api/admin/*) and the development-only debug routes, which are not part of any integration and are deliberately not published. Nothing an integration can call is missing from it.

The service spec is generated from the same pattern list your registered client is actually granted (the whitelist table), so it documents your whole reach and nothing you cannot call.