Migrate from v1

To move an integration from v1 to v2, start with the authentication, list and error changes that every integration hits. Then read the page for each resource your integration calls. v2 keeps the client-credentials grant and every v1 resource except electronic health record (EHR) ids. v2 lives under https://api.brellium.com/v2; the endpoints and the request and response shapes change.

Changes every integration hits

Change	Read
Tokens come from POST /v2/oauth/token, which is rate limited per client_id, so mint one token per key and cache it.	Migrate authentication from v1
v2 lists are GET requests with a cursor (starting_after) and at most 100 items a page; v1 pages with POST, page and pageSize, or returns everything at once.	Migrate list calls from v1
Every error response is one JSON envelope.	Migrate error handling from v1
A flag update replaces the audit's flags instead of adding to them.	Migrate audit calls from v1
An audit carries only the ids of its related records (set_id, documents[], people[].person_id) and no people_emails, so fetch each record from its own endpoint.	Migrate audit calls from v1

Pick your resource

Each page below covers every v1 call of one resource and starts with a checklist you can hand to the person who changes the integration.

If your integration calls	Read
GET /v1/audits/:audit_id, POST /v1/audits, POST /v1/update-audits-flags	Migrate audit calls from v1
POST /v1/documents, POST /v1/documents-multiple, POST /v1/documents/upload-url, GET /v1/documents/:document_id	Migrate document uploads from v1
GET /v1/question-sets	Migrate question set calls from v1
POST /v1/coding, GET /v1/coding/:coding_eval_id	Migrate coding evaluation calls from v1
POST /v1/users, GET /v1/users, and GET, POST or DELETE /v1/users/:user_id	Migrate user calls from v1
POST /v1/link-providers	Migrate provider linking (link-providers) from v1

Every v1 endpoint at a glance

v1 paths are relative to your v1 host, and v2 paths are relative to https://api.brellium.com. Send Content-Type: application/json with every v2 request body; any other content type, or none, returns 400 INVALID_CONTENT_TYPE. Each row names the change that matters most; the linked page under the table has every field and error.

Token, health and EHR ids

v1	v2	What changes
POST /v1/auth	POST /v2/oauth/token	The request adds grant_type and audience; mint one token per key and cache it.
GET /v1/	GET /health	It needs no token.
POST /v1/ehr-ids	no v2 equivalent	Contact Brellium support before you stop calling it on v1.

For the token request and its rate limit, see Migrate authentication from v1.

Audits

v1	v2	What changes
GET /v1/audits/:audit_id	GET /v2/audits/{audit_id}	Timestamps and nested fields are renamed; people_emails, reviewed_by and metadata are dropped.
POST /v1/audits with {"documents": [...]}	GET /v2/audits?documents=0f8e7d6c-5b4a-4938-8271-605f4e3d2c1b	documents becomes a query parameter of up to 100 document_id values.
POST /v1/audits with other filters	GET /v2/audits?...	Date filters are renamed, status and set_id take one value each, and page becomes a cursor.
POST /v1/audits with session dates, score bounds or a status array	no v2 equivalent	Filter by score in your own code and make one call per status value; ask Brellium support about session dates.
POST /v1/audits with includeTestAudits	no v2 equivalent	v2 never returns test audits.
POST /v1/update-audits-flags with audit_ids	PATCH /v2/audits/{audit_id} for one audit, POST /v2/audits/batch_update for up to 100	The flags you send replace the audit's flags.
POST /v1/update-audits-flags with filter	no v2 equivalent	List the audits, then batch_update them by audit_id.

For every audit field, filter and error, see Migrate audit calls from v1.

Users

v1	v2	What changes
POST /v1/users	POST /v2/users	The body requires name, email and attributes; a known address returns 409.
GET /v1/users	GET /v2/users	The response is the list envelope, with email and creation time filters.
GET /v1/users/:user_id	GET /v2/users/{user_id}	The response is the bare user; org_id is gone, and a deleted user returns 404.
POST /v1/users/:user_id	PATCH /v2/users/{user_id}	Send all of name, email and attributes; they replace the stored values.
DELETE /v1/users/:user_id	DELETE /v2/users/{user_id}	The response is 204 with no body, after the user's invitation or sign-in is revoked.

For the invitation flow in code, see Invite and manage users. For every user field and error, see Migrate user calls from v1.

Link providers to email recipients

v1	v2	What changes
POST /v1/link-providers (multipart CSV)	POST /v2/email_recipients, one call per row	v2 matches on email only, and a known address returns 409 EMAIL_RECIPIENT_EXISTS.

For code that manages recipients, see Manage email recipients. For every field and error, and a script that converts your CSV, see Migrate provider linking (link-providers) from v1.

Coding evaluations

v1	v2	What changes
POST /v1/coding (filter body)	GET /v2/coding_evaluations	Filters take one value each, and a page holds at most 100 items.
POST /v1/coding with a code, level or score filter, timeBased, upcoded or downcoded	no v2 equivalent	Filter on em_evaluation and icd_evaluation in your own code.
GET /v1/coding/:coding_eval_id	GET /v2/coding_evaluations/{coding_eval_id}	timestamp, em_eval and icd_eval are renamed; responses and people_emails are gone.

For code that lists and retrieves coding evaluations, see List and retrieve coding evaluations. For every field and filter, see Migrate coding evaluation calls from v1.

Question sets

v1	v2	What changes
GET /v1/question-sets	GET /v2/question_sets, GET /v2/question_sets/{set_id}	v2 pages the sets, renames name to set_name, and sends null where v1 sends "".

To follow an audit's set_id in code, see Retrieve an audit's question set. For every field and error, see Migrate question set calls from v1.

Documents

v1's three upload endpoints become one, POST /v2/documents, which takes a JSON body of 1 to 100 documents and returns an upload URL for each. You then PUT each file to its URL, and the document moves from pending_upload to todo once its file arrives. For the request and response, external_id retries and the 24-hour expiry of a batch with a missing file, see Upload documents.

v1	v2	What changes
POST /v1/documents (multipart, one file)	POST /v2/documents with one document, then PUT the file	Extra form fields become the external_metadata object.
POST /v1/documents-multiple (multipart files)	POST /v2/documents with up to 100 documents and "grouping": "group"	Send one item per file; the response lists them with one group_id.
POST /v1/documents/upload-url	POST /v2/documents	presigned_url becomes upload.url, valid 15 minutes; content_type is required, and doc_type is dropped.
GET /v1/documents/:document_id	GET /v2/documents/{document_id}	Your metadata becomes external_metadata; org_id, handler, audit_created and needs_audit are gone.
(none)	GET /v2/documents, PATCH /v2/documents/{document_id}	List by group_id, status or creation time; PATCH changes external_id and external_metadata.

For every document field and error, see Migrate document uploads from v1.

Next