For AI agents: the documentation index is at /docs/payerbox/llms.txt. A Markdown version of this page is available at /docs/payerbox/api-reference/resources/consent.md or by requesting it with the Accept: text/markdown header.
Payerbox Docs

Consent

A member's data-sharing decisions are FHIR Consent resources in Payerbox's Aidbox, under two Da Vinci profiles:

DecisionProfileIG
Provider Access opt-out, or a return to sharingPDex Provider Consent, http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-provider-consentDa Vinci PDex STU 2.1
Payer-to-Payer opt-inHRex Consent, http://hl7.org/fhir/us/davinci-hrex/StructureDefinition/hrex-consentDa Vinci HRex STU 1.1

The records arrive in three ways:

  • members record them on the member portal (Consent Panel);
  • the plan's data feed delivers them (Member Consent);
  • a system writes them through the FHIR API, as described on this page.

Provider Access checks the opt-outs in $provider-member-match and in every $davinci-data-export. The Payer-to-Payer opt-ins say which other plans the plan may ask for the member's history.

Endpoints

InteractionMethodURL
ReadGET/fhir/Consent/<id>
SearchGET/fhir/Consent?<search-params>
CreatePOST/fhir/Consent
Create or updatePUT/fhir/Consent/<id>
PatchPATCH/fhir/Consent/<id>
HistoryGET/fhir/Consent/<id>/_history
Batch or transactionPOST/fhir

The general behavior of these interactions, including conditional requests and If-Match, is in FHIR RESTful API.

Auth

A SMART Backend Services or Client Credentials client whose access policy allows the interaction on Consent. Members reach their own records only through the member portal. See Authentication and Access policies.

Search parameters

ParameterTypeElementUse
patientreferenceConsent.patientPatient/<id> or <id>.
statustokenConsent.statusactive for records in force; inactive for retired ones.
categorytokenConsent.categoryhttp://hl7.org/fhir/us/davinci-pdex/CodeSystem/pdex-consent-api-purpose|provider-access or |payer-to-payer picks the switch; both kinds also carry http://terminology.hl7.org/CodeSystem/v3-ActCode|IDSCL.
provision-typetokenConsent.provision.typedeny or permit. Added by Payerbox; not a base FHIR parameter.
_profileurimeta.profileThe PDex or HRex canonical above.
scopetokenConsent.scopehttp://terminology.hl7.org/CodeSystem/consentscope|patient-privacy.
datedateConsent.dateTimeWhen the decision was made.
perioddateConsent.provision.periodIn force on a day: period=le<day>&period=ge<day>, which also matches periods without an end.
organizationreferenceConsent.organizationThe plan's Organization.
actorreferenceConsent.provision.actor.referenceA Payer-to-Payer source or recipient payer, for example Organization/<id>.
source-referencereferenceConsent.source[x]The consent document.

The base R4 parameters action, consentor, data, identifier, purpose and security-label are available too.

GET /fhir/Consent?patient=Patient/example-member&category=http://hl7.org/fhir/us/davinci-pdex/CodeSystem/pdex-consent-api-purpose|provider-access&status=active&provision-type=deny
Authorization: Bearer <token>
GET /fhir/Consent?patient=Patient/example-member&category=http://hl7.org/fhir/us/davinci-pdex/CodeSystem/pdex-consent-api-purpose|payer-to-payer&status=active&period=le2027-06-01&period=ge2027-06-01
Authorization: Bearer <token>
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Consent",
        "id": "67d8623c-9af9-4dac-a40d-f5f30bb856ea",
        "meta": { "profile": ["http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-provider-consent"] },
        "status": "active",
        "provision": { "type": "deny", "period": { "start": "2026-10-06" } }
      }
    }
  ]
}

Provider Access opt-out

ElementRule
meta.profileThe PDex Provider Consent canonical, without a version.
meta.lastUpdatedSet by the server on every write; a value in the request is replaced.
statusactive: the profile fixes it, so a record carries the profile only while it is in force.
scopepatient-privacy.
categoryIDSCL, and the PDex API purpose provider-access.
patient, performerThe member's Patient. PDex STU 2.1 allows only the Patient as performer.
organizationThe plan's Organization.
provision.actorThe plan's Organization in the role performer (the source of the data). A representative who completed the form can be added in their authority role, for example POWATT.
policyRulecric, with the display Common Rule Informed Consent, as the profile fixes it.
provision.typedeny to opt out, permit to share again.
provision.period.startThe day the decision takes effect.
provision.actiondisclose.
PUT /fhir/Consent/67d8623c-9af9-4dac-a40d-f5f30bb856ea
Authorization: Bearer <token>
Content-Type: application/fhir+json

{
  "resourceType": "Consent",
  "id": "67d8623c-9af9-4dac-a40d-f5f30bb856ea",
  "meta": {
    "profile": ["http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-provider-consent"]
  },
  "status": "active",
  "scope": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/consentscope", "code": "patient-privacy" }] },
  "category": [
    { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "IDSCL" }] },
    { "coding": [{ "system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/pdex-consent-api-purpose", "code": "provider-access" }] }
  ],
  "patient": { "reference": "Patient/example-member" },
  "dateTime": "2026-10-06T14:22:00Z",
  "performer": [{ "reference": "Patient/example-member" }],
  "organization": [{ "reference": "Organization/example-health-plan" }],
  "policyRule": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/consentpolicycodes", "code": "cric", "display": "Common Rule Informed Consent" }] },
  "provision": {
    "type": "deny",
    "period": { "start": "2026-10-06" },
    "actor": [{
      "role": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type", "code": "performer" }] },
      "reference": { "reference": "Organization/example-health-plan" }
    }],
    "action": [{ "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/consentaction", "code": "disclose" }] }]
  }
}
{
  "resourceType": "Consent",
  "id": "67d8623c-9af9-4dac-a40d-f5f30bb856ea",
  "meta": {
    "profile": ["http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-provider-consent"],
    "versionId": "3927",
    "lastUpdated": "2026-10-06T14:22:00.112Z"
  },
  "status": "active",
  "...": "..."
}

Payer-to-Payer opt-in

ElementRule
meta.profileThe HRex Consent canonical, without a version.
statusactive, fixed by the profile.
scope, categorypatient-privacy; IDSCL, and the PDex API purpose payer-to-payer.
policy.urihttp://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#sensitive for all information, …#regular for non-sensitive information only. The names are the profile's: #sensitive is the wider grant.
sourceReferenceA DocumentReference for the completed form. HRex requires a source document. Load it before the Consent, or in the same transaction, see Load in bulk.
provision.typepermit.
provision.periodstart, and an end set by the plan's policy.
provision.actorEach previous or concurrent payer in the role performer (the source), and the plan's Organization in the role IRCP (the recipient).
performerThe member's Patient, or the RelatedPerson who acted for them.
The elements that differ from the opt-out
{
  "meta": { "profile": ["http://hl7.org/fhir/us/davinci-hrex/StructureDefinition/hrex-consent"] },
  "category": [
    { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "IDSCL" }] },
    { "coding": [{ "system": "http://hl7.org/fhir/us/davinci-pdex/CodeSystem/pdex-consent-api-purpose", "code": "payer-to-payer" }] }
  ],
  "policy": [{ "uri": "http://hl7.org/fhir/us/davinci-hrex/StructureDefinition-hrex-consent.html#sensitive" }],
  "sourceReference": { "reference": "DocumentReference/3f534529-49b7-4de8-b51c-e9f0d6831242" },
  "provision": {
    "type": "permit",
    "period": { "start": "2026-10-06", "end": "2027-12-31" },
    "actor": [
      { "role": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/provenance-participant-type", "code": "performer" }] },
        "reference": { "reference": "Organization/lakeside-health-plan" } },
      { "role": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType", "code": "IRCP" }] },
        "reference": { "reference": "Organization/example-health-plan" } }
    ],
    "action": [{ "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/consentaction", "code": "disclose" }] }]
  }
}

Retire a record

The member portal never edits a decision in place: a new decision is a new Consent, and the one it replaces is retired. (A plan that writes its consents as FHIR may instead keep one record per member and switch and update it, see Member Consent (FHIR).) A Payer-to-Payer withdrawal only retires the opt-in. Both profiles fix status to active, so a retirement sets status to inactive and removes the profile in the same JSON merge patch. A patch that changes only the status is refused.

PATCH /fhir/Consent/67d8623c-9af9-4dac-a40d-f5f30bb856ea
Authorization: Bearer <token>
Content-Type: application/merge-patch+json
If-Match: W/"3927"

{ "status": "inactive", "meta": { "profile": null } }
{
  "resourceType": "Consent",
  "id": "67d8623c-9af9-4dac-a40d-f5f30bb856ea",
  "meta": { "versionId": "3931", "lastUpdated": "2026-10-07T09:10:00.204Z" },
  "status": "inactive",
  "...": "..."
}
{
  "resourceType": "OperationOutcome",
  "issue": [{ "severity": "error", "code": "invalid", "diagnostics": "The value 'inactive' does not match the expected pattern 'active'" }]
}

Send profile: null; an empty array is refused.

Referenced records

Aidbox checks every reference a profile constrains. The referenced record must exist, be of the right type, and declare the profile the target names in its meta.profile, without a version:

ReferenceThe record must declare
patient, and performer when it is the memberhttp://hl7.org/fhir/us/core/StructureDefinition/us-core-patient
organization and the provision actorshttp://hl7.org/fhir/us/davinci-hrex/StructureDefinition/hrex-organization
sourceReferenceAny DocumentReference

Aidbox checks only the declaration, not the record's content. A declaration with a version (us-core-patient|6.1.0) matches only when that is the version the plain URL resolves to on the deployment.

Records written alongside

Records captured on the member portal come with:

ResourceContent
DocumentReferenceThe consent document, LOINC 59284-0 Consent Document: Consent.sourceReference points to it, and its attachment points to the QuestionnaireResponse.
QuestionnaireResponseThe answered form, US Core QuestionnaireResponse profile.
ProvenanceWho submitted it, how (activity CREATE, ONLINEWRIT), and the form's canonical; a review adds one with the administrator as verifier.
RelatedPerson, DocumentReferenceFor a representative: the RelatedPerson (US Core RelatedPerson profile, relationship POWATT, GUARD or RESP), and the document of authority.

Load in bulk

Plans usually write consent records from their own systems in bulk, one resource type at a time: for example 1,000 documents, then 1,000 Consents. Post each set to /fhir in bundles of type: batch or type: transaction, up to about 1,000 entries each.

Load order

Aidbox checks the references of every record it writes, so a record can be loaded only after the records it points to. Loaded the other way round, every Consent that points to a missing document fails with 422: Referenced resource DocumentReference/<id> does not exist.

StepRecords
1Patient, RelatedPerson for representatives, and Organization for your plan and the other payers. The Patients and Organizations must declare their profiles, see Referenced records.
2DocumentReference: the consent forms that Payer-to-Payer opt-ins point to.
3Consent: the new decisions.
4PATCH entries that retire the Consents the new decisions replace.
5Provenance, if you record one: it points to the Consent.

To send Consents before their documents, put both in one transaction. Inside a transaction a reference may point to any record in the same bundle, before or after the entry.

Batch or transaction

BundleBehavior
batchAidbox writes the entries one by one, in order, each on its own. A failed entry does not stop the others, and a later entry may point to a record an earlier one wrote. The bundle answers 200 with a status for every entry and an OperationOutcome for each failure, so you fix and resend only the failed entries.
transactionAll the entries or none. One failed entry rolls back the whole bundle, and Aidbox answers 400 naming the entry. Use it for records that must arrive together, such as Consents with their documents.

Retire what the new decisions replace

A new Consent does not retire the one it replaces. Send a retirement for every Consent a new decision supersedes, including ones the member recorded on the member portal — or update one record per member and switch in place, as Member Consent (FHIR) does. Provider Access treats a member as opted out while any opt-out is in force (status active and a provision.period that covers today, or no period at all), so a permit changes nothing until the opt-out before it is retired. Retire after the new Consents are written: an opt-out then never lapses before its replacement is in. The first search example above finds a member's opt-outs in force.

In a backfill of past decisions, load the ones no longer in force as retired records: status: inactive and no profile.

Bundle rules

  • Ids. Write each record with PUT and an id made from your system's key, such as Consent/P2P-000342. A re-run, or a resend of the failed entries, then updates the same records instead of adding copies.
  • Retirements. A PATCH entry carries the JSON merge patch from Retire a record as its resource. Add request.ifMatch with the version you read to refuse a record that changed since. A FHIRPath Patch Parameters resource works too.
  • Access. Aidbox authorizes every entry as a request of its own, such as PUT /fhir/Consent/<id>. The client's access policy must allow POST /fhir and each interaction in the bundle; an entry it refuses fails with 403.
  • Responses. With Prefer: return=minimal the response leaves the records out: each entry keeps its status, and a failed batch entry its OperationOutcome. Do not send it with a transaction, see Current limitations.

The batch below is shortened to the elements that matter here; the full records are in Provider Access opt-out and Payer-to-Payer opt-in. The document for P2P-000343 was not loaded yet, so that entry fails and the other two are written. Sent as a transaction, the same bundle writes nothing.

POST /fhir
Authorization: Bearer <token>
Content-Type: application/fhir+json
Prefer: return=minimal

{
  "resourceType": "Bundle",
  "type": "batch",
  "entry": [
    {
      "request": { "method": "PUT", "url": "Consent/P2P-000342" },
      "resource": {
        "resourceType": "Consent",
        "id": "P2P-000342",
        "meta": { "profile": ["http://hl7.org/fhir/us/davinci-hrex/StructureDefinition/hrex-consent"] },
        "sourceReference": { "reference": "DocumentReference/DOC-55192" },
        "...": "..."
      }
    },
    {
      "request": { "method": "PUT", "url": "Consent/P2P-000343" },
      "resource": {
        "resourceType": "Consent",
        "id": "P2P-000343",
        "meta": { "profile": ["http://hl7.org/fhir/us/davinci-hrex/StructureDefinition/hrex-consent"] },
        "sourceReference": { "reference": "DocumentReference/DOC-55193" },
        "...": "..."
      }
    },
    {
      "request": { "method": "PUT", "url": "Consent/PAC-000117" },
      "resource": {
        "resourceType": "Consent",
        "id": "PAC-000117",
        "meta": { "profile": ["http://hl7.org/fhir/us/davinci-pdex/StructureDefinition/pdex-provider-consent"] },
        "...": "..."
      }
    }
  ]
}
{
  "resourceType": "Bundle",
  "type": "batch-response",
  "entry": [
    { "response": { "status": "201", "location": "<base>/fhir/Consent/P2P-000342/_history/5120", "etag": "5120" } },
    {
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [{
          "severity": "fatal",
          "code": "invalid",
          "expression": ["Consent.sourceReference"],
          "diagnostics": "Referenced resource DocumentReference/DOC-55193 does not exist"
        }]
      },
      "response": { "status": "422" }
    },
    { "response": { "status": "201", "location": "<base>/fhir/Consent/PAC-000117/_history/5122", "etag": "5122" } }
  ]
}
POST /fhir
Authorization: Bearer <token>
Content-Type: application/fhir+json
Prefer: return=minimal

{
  "resourceType": "Bundle",
  "type": "batch",
  "entry": [
    {
      "request": { "method": "PATCH", "url": "Consent/P2P-000298" },
      "resource": { "status": "inactive", "meta": { "profile": null } }
    },
    {
      "request": { "method": "PATCH", "url": "Consent/PAC-000090" },
      "resource": { "status": "inactive", "meta": { "profile": null } }
    }
  ]
}
{
  "resourceType": "OperationOutcome",
  "id": "processing",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Transaction failed at entry[1]. Response status is 422. Response body is {…}.</p></div>"
  },
  "issue": [{
    "severity": "fatal",
    "code": "invalid",
    "expression": ["Consent.sourceReference"],
    "diagnostics": "Referenced resource DocumentReference/DOC-55193 does not exist"
  }]
}

Errors

StatusWhendiagnostics
400An entry of a transaction failed, so nothing in the bundle was written. The narrative names the entry and its own status.The failed entry's
401, 403The token is missing or invalid, or the access policy does not allow the interaction.
404No Consent with that id.
412If-Match names a version that is not the current one.Version ID validation failed. Requested versionId W/"999999"; versionId 3927
422The record breaks its profile.The value 'draft' does not match the expected pattern 'active'
422A referenced record does not exist, for example a document not loaded yet.Referenced resource DocumentReference/DOC-55193 does not exist
422A referenced record does not declare the target profile.Referenced resource Patient/example-member content doesn't conform to any of target profiles: http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient
422An HRex Consent without a recognized policy.uri.Invalid slice cardinality 'hrex'. Current count is '0', expected between '1' and 'Infinity'.

In a batch, an entry's failure comes in its own response.status, and the bundle itself answers 200.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Referenced resource Patient/example-member content doesn't conform to any of target profiles: http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
    }
  ]
}

Current limitations

  • The profile canonicals carry no version. Aidbox validates against the versions the deployment has loaded: PDex 2.1.0 and its HRex dependencies.
  • A record carries its PDex or HRex profile only while active. A representative's draft has none until it is approved, and retired or rejected records lose it.
  • The member portal shows only Consents with scope patient-privacy that are either profiled or carry one of the two PDex API purposes, for the plan organization set in Consent Settings or for none.
  • period=<day> without a prefix matches only periods that fit inside that day; use le and ge as above.
  • A failed transaction sent with Prefer: return=minimal answers 400 with an empty body. Leave the header out to see which entry failed and why.
  • An opt-in for non-sensitive information only moves no data until sensitive data is labeled: other payers return the member as consent-constrained.

Last updated: