Nominees

Nominees are individuals authorized to act on a data principal’s behalf when exercising privacy rights — for example, a legal guardian, spouse, or attorney. Each nominee record captures the relationship, contact details, and purpose of appointment. Nominees start with a "pending" status and can be updated or removed at any time.

All endpoints authenticate with X-API-Key.

List nominees for a user

GET /nominee/user/{user_id}

Retrieve all nominees registered for a specific user, ordered by creation date descending.

Path parameters

Parameter	Type	Required	Description
`user_id`	string	Yes	The `client_user_id` of the user whose nominees you want to retrieve

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your tenant API key

Response

200 OK — an array of UserNominee objects. Returns an empty array if the user has no registered nominees.

Field	Type	Description
`id`	string	UUID of the nominee record
`client_user_id`	string	Your application’s identifier for the data principal
`nominee_name`	string	Full name of the nominee
`nominee_email`	string	Email address of the nominee
`nominee_mobile`	string	Mobile phone number of the nominee
`relationship`	string	Relationship to the data principal (for example, `"spouse"` or `"legal_guardian"`)
`purpose_of_appointment`	string or `null`	Description of why this nominee was appointed
`status`	string	Verification status: `"pending"`, `"verified"`, or `"rejected"`
`verified_at`	string or `null`	ISO 8601 timestamp of when the nominee was verified
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 timestamp of the most recent update

curl --request GET \
  --url https://api.truConsent.io/nominee/user/usr_abc123 \
  --header "X-API-Key: YOUR_API_KEY"

const response = await fetch('https://api.truConsent.io/nominee/user/usr_abc123', {
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.truConsent.io/nominee/user/usr_abc123',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
    },
)
data = response.json()

[
  {
    "id": "d4e5f6a7-b8c9-0123-defg-345678901234",
    "client_user_id": "usr_abc123",
    "nominee_name": "Jane Doe",
    "nominee_email": "[email protected]",
    "nominee_mobile": "+919876543210",
    "relationship": "spouse",
    "purpose_of_appointment": "Acting on behalf during medical treatment",
    "status": "pending",
    "verified_at": null,
    "created_at": "2024-10-15T09:00:00",
    "updated_at": "2024-10-15T09:00:00"
  }
]

Register a nominee

POST /nominee

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your tenant API key

Body

Field	Type	Required	Description
`user_id`	string	Yes	Your application’s identifier for the data principal. Stored as `client_user_id`.
`nominee_name`	string	Yes	Full name of the nominee
`nominee_email`	string	Yes	Email address of the nominee
`nominee_mobile`	string	Yes	Mobile phone number of the nominee
`relationship`	string	Yes	Relationship between the nominee and the data principal
`purpose_of_appointment`	string	No	Optional description of why this nominee is being appointed

Response

201 Created — the newly created UserNominee record. status is always "pending" and verified_at is always null on creation.

curl --request POST \
  --url https://api.truConsent.io/nominee \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "user_id": "usr_abc123",
    "nominee_name": "Jane Doe",
    "nominee_email": "[email protected]",
    "nominee_mobile": "+919876543210",
    "relationship": "spouse",
    "purpose_of_appointment": "Acting on behalf during medical treatment"
  }'

const response = await fetch('https://api.truConsent.io/nominee', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_id: 'usr_abc123',
    nominee_name: 'Jane Doe',
    nominee_email: '[email protected]',
    nominee_mobile: '+919876543210',
    relationship: 'spouse',
    purpose_of_appointment: 'Acting on behalf during medical treatment',
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.truConsent.io/nominee',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'user_id': 'usr_abc123',
        'nominee_name': 'Jane Doe',
        'nominee_email': '[email protected]',
        'nominee_mobile': '+919876543210',
        'relationship': 'spouse',
        'purpose_of_appointment': 'Acting on behalf during medical treatment',
    },
)
data = response.json()

{
  "id": "d4e5f6a7-b8c9-0123-defg-345678901234",
  "client_user_id": "usr_abc123",
  "nominee_name": "Jane Doe",
  "nominee_email": "[email protected]",
  "nominee_mobile": "+919876543210",
  "relationship": "spouse",
  "purpose_of_appointment": "Acting on behalf during medical treatment",
  "status": "pending",
  "verified_at": null,
  "created_at": "2024-10-15T09:00:00",
  "updated_at": "2024-10-15T09:00:00"
}

Update a nominee

PUT /nominee/{nominee_id}

Update one or more fields on an existing nominee record. Only the fields listed below are accepted. At least one valid field must be provided.

Path parameters

Parameter	Type	Required	Description
`nominee_id`	string	Yes	UUID of the nominee record to update

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your tenant API key

Body

All fields are optional — provide only the fields you want to change.

Field	Type	Description
`nominee_name`	string	Updated full name
`nominee_email`	string	Updated email address
`nominee_mobile`	string	Updated mobile number
`relationship`	string	Updated relationship description
`purpose_of_appointment`	string	Updated purpose of appointment
`status`	string	Updated verification status

Response

200 OK — the full updated UserNominee record.

curl --request PUT \
  --url https://api.truConsent.io/nominee/d4e5f6a7-b8c9-0123-defg-345678901234 \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "status": "verified" }'

const response = await fetch('https://api.truConsent.io/nominee/d4e5f6a7-b8c9-0123-defg-345678901234', {
  method: 'PUT',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ status: 'verified' }),
});
const data = await response.json();

import requests

response = requests.put(
    'https://api.truConsent.io/nominee/d4e5f6a7-b8c9-0123-defg-345678901234',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={'status': 'verified'},
)
data = response.json()

{
  "id": "d4e5f6a7-b8c9-0123-defg-345678901234",
  "client_user_id": "usr_abc123",
  "nominee_name": "Jane Doe",
  "nominee_email": "[email protected]",
  "nominee_mobile": "+919876543210",
  "relationship": "spouse",
  "purpose_of_appointment": "Acting on behalf during medical treatment",
  "status": "verified",
  "verified_at": null,
  "created_at": "2024-10-15T09:00:00",
  "updated_at": "2024-10-15T10:15:00"
}

Delete a nominee

DELETE /nominee/{nominee_id}

Permanently remove a nominee record. This action cannot be undone.

Path parameters

Parameter	Type	Required	Description
`nominee_id`	string	Yes	UUID of the nominee record to delete

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your tenant API key

Response

200 OK

curl --request DELETE \
  --url https://api.truConsent.io/nominee/d4e5f6a7-b8c9-0123-defg-345678901234 \
  --header "X-API-Key: YOUR_API_KEY"

const response = await fetch('https://api.truConsent.io/nominee/d4e5f6a7-b8c9-0123-defg-345678901234', {
  method: 'DELETE',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
  },
});
const data = await response.json();

import requests

response = requests.delete(
    'https://api.truConsent.io/nominee/d4e5f6a7-b8c9-0123-defg-345678901234',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
    },
)
data = response.json()

{ "message": "Nominee deleted successfully" }

Errors

Status	Classification	Details
`400`	Validation Error	Request body failed validation, or no valid fields were provided for an update
`401`	Unauthenticated	Invalid or missing API key
`403`	Forbidden	API key lacks required scope
`404`	Not Found	No nominee with the given UUID exists (PUT and DELETE only)
`500`	Internal Error	Internal server error