Skip to main content
POST
/
identity-records
curl --request POST \
  --url https://api.central.consent/v1/identity-records \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pii-principal": {
    "mpxn": "1234567890123",
    "move-in-date": "2022-06-30",
    "address": {
      "addressLine1": "221B Baker Street",
      "townCity": "London",
      "postcode": "NW1 6XE"
    }
  },
  "expressed-by": "data-subject",
  "email": "customer@example.com",
  "initiate-passkey-registration": true,
  "principal-verification": {
    "method": "credit-card",
    "verified-at": "2023-11-07T05:30:45Z",
    "outcome": "verified",
    "reference": "ch_3ABC123xyz",
    "submitted": "XXXX-XXXX-XXXX-4242",
    "verified-against": "Stripe customer record cus_ABC123",
    "detail": {
      "last4": "4242",
      "brand": "visa",
      "stripe_customer": "cus_ABC123"
    }
  }
}
'
{
  "response": {
    "resource": "/v1/identity-records/ir_a3c5e7f9b1d3a3c5e7f9b1d3",
    "timestamp": "2024-01-15T09:30:00Z",
    "transaction-id": "tid_691df0c788ca043403b7fa90"
  },
  "ir": "ir_a3c5e7f9b1d3a3c5e7f9b1d3",
  "passkey-registration-redirect": {
    "redirect-url": "https://id.central.consent/passkey/register?session=pks_a1b2c3d4e5f6a1b2c3d4e5f6",
    "token-ref": "mlr_9f8e7d6c5b4a9f8e7d6c5b4a",
    "expires-at": "2024-01-15T09:35:00Z"
  }
}

Authorizations

​
Authorization
string
header
required

JWT from GET /auth/token. Pass as Authorization: Bearer <token>. Expires after 7200s.

Body

application/json

Request body for POST /identity-records. Extends the core IdentityRecord fields with email, initiate-passkey-registration, and passkey-return-url.

​
pii-principal
object
required

Identifies the customer and their property. MPxN is the primary identifier; personal name and email are excluded to minimise PII held centrally.

​
expressed-by
enum<string>
required

Who expressed consent or initiated the access registration — the data subject themselves, or an authorised representative.

Available options:
data-subject,
authorised-representative
​
principal-verification
object

How the Controller verified the identity of the principal. Strongly recommended. Null if no structured verification was performed.

​
email
string<email> | null

Customer email address. Stored as a one-way hash — never returned in plaintext in any response. Required if magic-link re-identification is to be used. Also enables email-based lookup via GET /identity-records?email=....

Example:

"customer@example.com"

​
initiate-passkey-registration
boolean
default:false

If true, the register generates a passkey registration session and returns a passkey-registration-redirect. Redirect the customer to the supplied URL; the register completes the WebAuthn ceremony on id.central.consent and redirects back to passkey-return-url with ?dar-passkey-token={token-ref} on success.

​
passkey-return-url
string<uri> | null

Required when initiate-passkey-registration is true. The URL the register redirects the customer to after the passkey ceremony completes. Must exactly match a URL pre-registered for the Data User's DUID. Ignored if initiate-passkey-registration is false or omitted.

Example:

"https://app.bright-energy.com/onboard/passkey-done"

Response

Identity record created successfully. If initiate-passkey-registration was true, passkey-registration-redirect is populated — redirect the customer to redirect-url. The register completes the WebAuthn ceremony on id.central.consent and sends the customer back to return-url with ?dar-passkey-token={token-ref}. Call GET /identity-records/{ir}/re-identify/{token-ref} once to confirm.

​
response
object
required
​
ir
string
required

Unique opaque identifier for an Identity Record, issued by the register on creation. Referenced from record-metadata.identity-record-ref on an AccessRecord to link the two resources.

Pattern: ^ir_[0-9a-f]{24}$
Example:

"ir_a3c5e7f9b1d3a3c5e7f9b1d3"

​
passkey-registration-redirect
object

Populated when initiate-passkey-registration was true. Redirect the customer to redirect-url — the register runs the WebAuthn registration ceremony on id.central.consent and returns them to return-url with ?dar-passkey-token={token-ref}. Call GET /identity-records/{ir}/re-identify/{token-ref} once to confirm. Null otherwise.

Last modified on March 25, 2026