Create consent link

POST /api/outside-app/consent-link/create

Use this endpoint to generate a magic consent link for a data principal. The link directs the user to a hosted consent flow where they verify their identity via OTP and submit their consent preferences.

Authentication

Note

Requires Authorization: Bearer <token> — use a user-scoped token, not an API key.

Body

Field	Type	Required	Description
collection_point_id	string	Yes	UUID or display_id of the collection point for this consent request
phone	string	Yes	The data principal’s phone number in E.164 format (for example, +917299424311). Receives the OTP during the consent flow.
email	string	No	If provided, a branded consent email with the magic link is sent to this address. The address is deleted immediately after sending.
expiry_hours	integer	No	How long the link remains valid. Between 1 and 24. Default: 24.
send_sms	boolean	No	Whether to deliver the link via SMS. Default: true.
success_message	string	No	Custom message shown to the data principal after they submit consent.
data_collection_timestamp	string	No	ISO 8601 timestamp recording when the underlying data was collected.

Response

201 Created

Field	Type	Description
request_id	string	Stable identifier for this consent request. Use to check status, regenerate, or correlate consent outcomes.
event_id	string	Unique identifier for this specific link instance. Each regeneration produces a new event_id while preserving the same request_id.
consent_link	string	The magic link URL to share with the data principal.
expires_at	string	ISO 8601 timestamp of when the link expires.
delivery_status	object	Outcome of any delivery attempts made during link creation.

delivery_status fields:

Field	Type	Description
email	string	Present when email was provided. Either "sent" or "failed".
sms	string	Present when send_sms is true. Value is "pending" while the SMS is being dispatched.

Note

When email is provided, the address is used solely to dispatch the consent email and is immediately deleted from the database after sending. truConsent never retains the recipient’s email address.

Errors

Status	Description
400	Tenant context could not be resolved from the provided token
404	No collection point found matching collection_point_id
422	Request body failed validation. The response includes a details array describing each invalid field.
500	Unexpected internal error

Example

curl --request POST \
  --url https://api.truConsent.io/api/outside-app/consent-link/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "collection_point_id": "cp_onboarding_v2",
    "phone": "+917299424311",
    "email": "priya.sharma@example.com",
    "expiry_hours": 12,
    "send_sms": true,
    "success_message": "Thank you for providing your consent.",
    "data_collection_timestamp": "2026-04-21T08:30:00Z"
  }'

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "consent_link": "https://collect.truConsent.io/acme/cp_onboarding_v2/f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "expires_at": "2026-04-21T20:30:00+00:00",
  "delivery_status": {
    "email": "sent",
    "sms": "pending"
  }
}