The provider technical guide.
Every provider is fronted by a connector that implements one provider-neutral contract. Here is what that contract asks of you.
The connector interface
A connector describes datasets and proxies search, record fetch, citation resolution and downloads to your API, mapping results into neutral shapes with provenance on every record.
interface Connector {
readonly id: string;
readonly provider: ProviderInfo;
listDatasets(): DatasetDescriptor[];
getDataset(slug: string): DatasetDescriptor;
search(params: SearchParams): Promise<SearchResult>;
getRecord(id: string): Promise<LegalRecord>;
resolveCitation(citation: string): Promise<CitationResolution>;
requestDownload(slug: string, format?: string): Promise<DownloadPlan>;
}Illustrative example · final API surface documented in /docs
Fields in a catalog listing
| Field | Notes |
|---|---|
| slug, title, description | Stable identifier and human description. |
| sources | Each upstream origin, with URL and description. |
| license | Id, name, URL, redistribution (public / paid / restricted / unknown), attribution. |
| coverage, dateRange | Jurisdictions, geography; start/end or null when unverified. |
| recordCount | Null until verified. Never an estimate. |
| accessMethods | Per channel (web, rest, mcp, download): status, formats, and why. |
| schemaFields | Name, type, nullable, derived flag, description. |
| updateFrequency, qualityNotes, pricingTier | Cadence, known limitations, pricing tier. |
What each status means
| Status | Meaning | Effect |
|---|---|---|
| available | Working now | Requests are served |
| awaiting-credentials | Provider has not issued a service credential | Requests fail with not-configured; listing stays visible |
| awaiting-rights-confirmation | Rights for this channel are not confirmed | Blocked; shown with the reason |
| unavailable | Not offered | Blocked; shown as not offered |
How connector errors reach buyers
Connectors raise typed errors. The API maps each one to a stable code in the v1 envelope, so buyers can handle it without knowing which provider is behind the dataset.
| Connector error | API response | Typical cause |
|---|---|---|
| NotConfiguredError | 503 not_configured | Service credential not set; the channel is not live |
| RightsRestrictedError | 403 rights_restricted | License or channel status blocks the request |
| UnsupportedOperationError | 501 unsupported_operation | The provider cannot back the operation, such as citation resolution |
| NotFoundError | 404 not_found | Unknown dataset or record id |
| UpstreamError | 502 upstream | Your API failed, timed out or rejected the credential |
| InvalidParamsError | 400 invalid_params | A filter your API cannot accept |
Download rules enforced in code
- Redistribution restricted or unknown → no download
- Channel awaiting rights confirmation → no download
- Channel awaiting credentials → not configured
- Missing or unavailable channel → unsupported
- Demo records are never billed
- AI enrichment carries its own license id
Building against demo fixtures
When a connector's credentials are not set, it runs a demo adapter that returns clearly fake fixture records. Responses then carry meta.demo: true and an X-Dataco-Demo header, every record is flagged demo, and the resulting usage events are recorded at zero cost. This lets buyers and the Data.co team build and test against the listing before your live channel opens, without any risk of a fixture being mistaken for or billed as real data.
Mapping your records to the neutral shape
- 1
Identify the layers
Separate original text and facts from anything you generated or edited. Each layer gets its own provenance block and license id.
- 2
Choose stable ids
Prefix your record ids with the connector id, such as lawco:case:<id>, so they are unique across providers and can be fetched again.
- 3
Fill provenance honestly
Set fields you know and leave the rest null. A null upstream URL is better than a guessed one.
- 4
Drop what is not cleared
Fields whose rights are unconfirmed are omitted by the connector rather than served with a caveat.
Questions buyers ask
Do I need to change my API to publish?
Not necessarily. A connector can map your existing API. For large corpora we may propose a small read-only service namespace with keyset pagination and per-token rate limits.
How are requests authenticated to my API?
With a dedicated service credential you issue to Data.co, scoped read-only, plus a request id header for reconciliation.
Is the connector contract legal-specific?
The record shape was designed with the first provider's legal data, but provenance, descriptors, access statuses and rights gating are provider-neutral. New domains extend the record fields, not the rules.
Can my search return a total count?
Yes, and it is passed through as meta.total. If your API cannot report one, the total is null and buyers are told it is unknown.
What should I do about upstream caveats?
Describe them. A connector can attach warnings to responses — LAW.co's sampled search does — and quality notes in the descriptor explain known limitations.
Who writes the connector?
Usually Data.co, against your documentation and a test credential. You review the field mapping and the provenance values before listing.
How do you test a connector before listing?
With real requests against a test credential: search with each filter, single-record fetch, unknown ids, invalid input and rate-limit behavior. Each channel's status is set from the results.
List your data on Data.co.
We review every provider for licensing, provenance and quality. You keep control of terms and pricing.