Send consent links

A consent link is a one-time magic link that lets a user complete a consent form outside your application. You generate the link server-side, truConsent delivers it via SMS or email, and the user opens it in their browser to verify their identity with an OTP and submit their choices.

This is useful for call center agents collecting consent over the phone, post-purchase confirmations, and re-consent campaigns.

Note

Privacy-by-design: when you provide an email address, truConsent sends the consent link and then immediately deletes the email address from the database. The address is never stored at rest.

Authentication

Management endpoints require a Bearer token in the Authorization header. The public endpoints your consent collection app calls (context, send-otp, verify-otp, submit) require no authentication.

Full workflow

1. Create a consent link

   Generate a new consent link for a specific user and collection point.

   curl -X POST https://api.truConsent.io/api/outside-app/consent-link/create \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "collection_point_id": "cp_phone_signup",
       "phone": "+919876543210",
       "email": "user@example.com",
       "expiry_hours": 24,
       "send_sms": true,
       "success_message": "Thank you for providing your consent."
     }'

   Field	Type	Required	Description
   collection_point_id	string	Yes	The collection point ID or display_id
   phone	string	Yes	The user’s phone number for OTP verification
   email	string	No	If provided, a consent link email is sent to this address
   expiry_hours	integer	No	How long the link stays valid, between 1 and 24 hours (default: 24)
   send_sms	boolean	No	Whether to send an SMS with the link (default: true)
   success_message	string	No	Custom message shown to the user after they submit consent

   The response returns the link and delivery status:

   {
     "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "event_id": "550e8400-e29b-41d4-a716-446655440000",
     "consent_link": "https://collect.truConsent.io/acmecorp/cp_phone_signup/550e8400-e29b-41d4-a716-446655440000",
     "expires_at": "2026-04-22T10:30:00+00:00",
     "delivery_status": {
       "email": "sent",
       "sms": "pending"
     }
   }

   Save the request_id — you need it to track status and regenerate the link if it expires.

2. The user opens the link and verifies their identity

   The consent collection app (served at the URL in consent_link) handles the OTP flow on the user’s behalf. Your backend does not need to call any endpoints during this step.

   The app calls the following public endpoints in sequence:

   1. GET /api/outside-app/context/{org_id}/{event_id} — fetches the consent form and organization branding.
   2. POST /api/outside-app/send-otp/{org_id}/{event_id} — sends an OTP to the phone number on file.
   3. POST /api/outside-app/verify-otp/{org_id}/{event_id} — verifies the OTP and returns the full consent form data.
   4. POST /api/outside-app/submit/{org_id}/{event_id} — records the user’s consent decision.

   These endpoints are public and do not require authentication. They are designed to be called by the browser-based consent collection app, not by your server.

3. Track the status of a consent link

   Poll this endpoint to find out whether the user has completed, the link is still pending, or it has expired.

   curl https://api.truConsent.io/api/outside-app/status/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
     -H "Authorization: Bearer YOUR_TOKEN"

   {
     "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "status": "completed",
     "is_verified": true,
     "completed_at": "2026-04-21T11:05:33+00:00",
     "consent_action": "approved"
   }

   status value	Meaning
   pending	The link is active but the user has not yet submitted
   completed	The user submitted their consent decision
   expired	The link passed its expires_at time before the user acted

4. Regenerate an expired link

   If the link expires before the user completes the flow, regenerate it using the original request_id. The same request_id is preserved so your tracking is not interrupted.

   curl -X POST https://api.truConsent.io/api/outside-app/consent-link/regenerate/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "expiry_hours": 24,
       "send_sms": true
     }'

   {
     "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "event_id": "660e9511-f30c-52e5-b827-557766551111",
     "consent_link": "https://collect.truConsent.io/acmecorp/cp_phone_signup/660e9511-f30c-52e5-b827-557766551111",
     "expires_at": "2026-04-23T10:30:00+00:00",
     "delivery_status": {
       "sms": "pending"
     },
     "regeneration_count": 1,
     "previous_event_id": "550e8400-e29b-41d4-a716-446655440000"
   }

   Caution

   You can regenerate a link a maximum of five times per request_id. After five regenerations, the API returns HTTP 429. If consent has already been submitted, regeneration returns HTTP 410.

5. View consent link history

   Retrieve all consent links created for your organization, with masked phone numbers and collection point details.

   curl https://api.truConsent.io/api/outside-app/consent-link/history \
     -H "Authorization: Bearer YOUR_TOKEN"

   [
     {
       "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
       "event_id": "660e9511-f30c-52e5-b827-557766551111",
       "phone": "+*********3210",
       "expires_at": "2026-04-23T10:30:00+00:00",
       "is_completed": true,
       "is_regenerated": true,
       "regeneration_count": 1,
       "created_at": "2026-04-21T10:30:00+00:00",
       "collection_point_name": "Phone Sign-up",
       "collection_point_display_id": "cp_phone_signup",
       "consent_link": "https://collect.truConsent.io/acmecorp/cp_phone_signup/660e9511-f30c-52e5-b827-557766551111"
     }
   ]

   Phone numbers in the history response are always masked — only the last four digits are visible.