Create a profile

What you are creating

A profile is one kind of audit: which reviewers run, which legal sources each of them may cite, which document type it expects, and what language it answers in. Until now it existed only as something an administrator built in the web application; this endpoint builds the same object, and it is the same code that validates both.

You send the profile's name, the document type it audits, and the reviewers. A reviewer is a name, an instruction in its own words, and the legal sources it holds — provisions named directly, rule sets named by key, or both.

The id you get back is the id everything else takes

profileId is what the profile is called everywhere: it is how GET /v1/profiles lists it, what you send as profileId to POST /v1/analyze, and what addresses it for PATCH /v1/profiles/:id. Store that one string and use it for all three.

workerIds are the reviewers, and they are spelled differently — longer, and carrying your organisation's own identifier. That is not something to correct or trim: send each one back exactly as you were given it. It is the same string GET /v1/profiles lists for that reviewer, and the same one POST /v1/analyze takes — a reviewer is matched by the record it names rather than by the characters you send, so an id you cached earlier keeps working too.

It arrives as a draft, deliberately

A profile created here is a draft. Your own integration can run it immediately — GET /v1/profiles returns it and POST /v1/analyze accepts it — but the people who use the web application do not see it in their list until it is published.

That is the point of the draft: minting something already live is a different risk from changing something that is, so building a profile and putting it into circulation stay two separate acts. Sending status here is refused rather than ignored, so a request never comes back 201 having quietly not published anything.

Publishing is one more call, and it is yours to make: PATCH /v1/profiles/:id with {"status": "PUBLISHED"}. Nobody has to open the admin panel for it.

The legal orders are derived, not declared

Whichever jurisdictions your provisions belong to are the jurisdictions the profile is stored against. You do not send them, and sending them alongside cited provisions is a 400.

The one exception is a profile that cites no statute at all — a profile built entirely on your own rule sets. There is nothing to derive from, so jurisdictions is required, and if your organisation has a default it is used instead. If neither is there, the answer is a 400 naming jurisdictions: send it, or cite a provision and let it be derived.

Either way, a jurisdiction we do not carry is refused naming it and listing the ones we do. It is matched exactly: se is not SE.

A profile can answer on a shortcut

urlSlug is the address the profile opens at, as /p/{urlSlug}. It is optional and free text, and it is what a colleague pastes into a chat rather than a profile id. Two profiles in the same organisation may not hold the same shortcut — the second one is a 409 naming the profile that has it — but two different organisations may.

A profile can be kept out of the pickers

unlisted: true builds a profile that does not appear in the lists your organisation's own people choose from. It still exists, it still runs, and it is still reachable on its /p/{urlSlug} shortcut and through this API — it is simply not offered to everyone. This is the field to send when you are building a profile for one team rather than for the whole organisation.

Two things are worth knowing before you send it. A profile with unlisted: true and no urlSlug can be reached by your integration and by nothing else, which is a perfectly reasonable thing to build and a surprising thing to discover later. And listing is not the same control as publishing: a profile created here is a draft either way until it is published.

It defaults to false, and anything that is not true or false is a 400 rather than a silently ignored value. You can change it afterwards with PATCH /v1/profiles/:id.

A provision has two names, and only one of them works here

Each entry in rules names one provision with three fields — jurisdiction, work and pinpoint. The one to get right is pinpoint, because every provision carries two names:

• What it is called — 6 kap. 1 §, 7 §, 9 a §. This is the citation a lawyer writes and a report prints. It is not what you send.
• What it is addressed by — kap_6_par_1§, par_7§, par_9a§. This is the pinpoint.

They are matched exactly, character for character, and nothing translates between them. Sending the citation addresses no provision of that law, and the write is refused naming the reference you wrote — see Every provision must exist inside the statute it cites below.

Take a pinpoint from a response and send it back unchanged. The anchors on GET /v1/snippets/:snippetId carry it in exactly the form this endpoint expects. Never assemble one from a citation, and never adjust the one you were given — work and pinpoint are opaque, and their shape differs per legal order.

Request body

What will be refused

Every rule the web application applies applies here, and they are worth knowing before you write the request:

• A profile must have at least one reviewer. A reviewer is what does the reading, so a profile with none would answer every analysis with nothing at all. Sending workers: [] is a 400 rather than a 201 for an empty audit.
• A reviewer must hold binding law. A reviewer whose sources are all guidance, general advice or preparatory works cannot substantiate a finding, and the profile is refused naming that reviewer. Which instrument types bind is a property of the jurisdiction, not of this API.
• Every source must already be in the library, and you can put it there. A provision from a statute we have not ingested is refused naming the work. This endpoint does not fetch one for you — GET /v1/laws/:jurisdiction/:work does, on the spot, so the fix for that refusal is one call and a retry.
• A rule set is named by its snippetKey, never by its id. GET /v1/snippets publishes both fields on every record, and an analysis looks a rule set up by the key alone — so snippetIds takes keys, in spite of what the field is called. A document id there is a 400 naming each value you sent beside the key that record answers to, rather than a 201 for a profile whose rule sets would be missing from every report it produces without anything saying so.
• Every provision must exist inside the statute it cites. A pinpoint is matched against the provision's stored address exactly — par_7§, never the 7 § a citation is printed as — and one that addresses nothing is refused naming the reference you wrote. This matters because a reference that resolves to no provision is dropped from the analysis without a word, so the audit would run against less law than you asked for and the report would not say so. Take the pinpoints from GET /v1/laws/:jurisdiction/:work, which lists every provision of a law with the address it answers to, or check one you already have with GET /v1/snippets?jurisdiction=…&work=…&pinpoint=…, which answers 404 when nothing is addressed.
• A repealed provision cannot be cited. A repeal leaves the section in the register as a numbered placeholder carrying no text, so a reviewer citing one holds a legal source with nothing in it — and it would pass every check above, because the provision exists and its statute binds. GET /v1/laws/:jurisdiction/:work marks each such provision with isRepealNotice. Only provisions you are adding are refused: a reviewer that already stores one keeps it, so an existing profile can still be edited — and cleaned up.
• There is a limit on reviewers per profile — three, unless your organisation is configured otherwise.
• There is a limit on legal sources per reviewer — 25, counting cited provisions and rule sets together. Split a reviewer that needs more into two.
• There is a limit on how long an instruction may be — 1000 characters.
• There is a ceiling on how many profiles your organisation may hold, answered by GET /v1/quotas. Creating one past it is a 409; editing the profiles you have is never affected.
• A value has to have the right shape, not just the right field name. The profile and its reviewers are checked against the stored data contract as the last step before the write, so a snippetIds entry that is not a string — or any other value of a type the table above does not name — is a 400 quoting the field and what was wrong with it, never a 201 with that field quietly dropped.
• The server owns some fields. id, status, workers[].id and the authorship fields are refused rather than accepted and overwritten.
• A field that is not in the table above is refused, naming it. The same goes for a field on a reviewer. Nothing is accepted and quietly ignored: a 201 means every field you sent was stored, so a typo is a 400 you can act on rather than a setting that silently never took effect.
• A jurisdiction has to be one we carry. SE, NO or EU, matched exactly. Anything else is a 400 naming what you sent, wherever you sent it — in a cited provision or in jurisdictions.
• We have to be able to weigh your sources at all. Deciding which of a reviewer's sources bind means reading the norm hierarchy of its legal orders, and when that read fails we refuse rather than guess — because with no hierarchy every source weighs as non-binding, so guessing would tell you to add binding law you already have. Nothing is wrong with your request; retry, and tell us if it repeats.

Nothing is written unless all of it passes: the profile and its reviewers are one atomic write.

Which check refused

Every refusal above answers with a stable name in error.details.refusal, and the values that refusal names in error.details.values:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The profile names 4 reviewers, which is more than the 3 this organisation allows.",
    "details": {
      "refusal": "too-many-reviewers",
      "values": { "count": 4, "limit": 3 }
    }
  }
}

Branch on details.refusal, never on message. The message is prose written for a person reading it once, and we reword it whenever we can say the same thing better; the name is the contract and does not move. values carries what the sentence interpolates, so you can build your own message without parsing ours.

Several names share one status — too-many-reviewers and record-fails-data-contract are both 400 — which is the whole reason this is here.

Errors