Integration

Consent Management

Collect TimeBack parental consent for a student from your own system. Instead of sending families through the in-app consent flow, your backend initiates the consent request, the platform emails each guardian a DocuSign signing link, and you poll for the result, all over machine-to-machine APIs.

Note: This guide covers the integration flow. See the API Reference for complete endpoint documentation, all parameters, and response schemas.

What This Provides

A partner system (for example, a school's own onboarding portal) can drive the full parental-consent lifecycle for an explicit student and guardian without the student ever opening the TimeBack App:

  • Initiate a consent request — the platform generates the DocuSign envelope and emails the guardian a signing link.
  • Track consent status through to granted by polling the student's consent records.
  • Record consent you collected out-of-band so it is reflected in TimeBack's audit trail.

The consent records form an immutable, append-only audit trail; each status change is a new record rather than an edit.

Prerequisites

  1. Register your App and obtain OAuth credentials — see Level 0: Register Your App and Authentication.

  2. Request the consent scopes for your M2M client (issued by the TimeBack Platform team, not self-serve):

    • consent.write — initiate a consent request and record a consent status.
    • consent.read — read a student's consent records.

    Each scope lives under the https://timeback-platform.trilogy.com/consent/scope resource server (for example, https://timeback-platform.trilogy.com/consent/scope/consent.write).

  3. Own the student's organization. The platform checks that your client owns the organization the student belongs to, and that consent management is enabled for that org. A caller that does not own the org, or whose org has consent management disabled, receives 403.

Exchange your credentials for an access token as described in Authentication, requesting the consent scopes:

curl -X POST https://platform.timeback.com/auth/1.0/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials&scope=https://timeback-platform.trilogy.com/consent/scope/consent.write https://timeback-platform.trilogy.com/consent/scope/consent.read"

Step 1: Initiate a Consent Request

Start the email consent flow for a student and one or more guardians:

POST /consent/1.0/students/{studentId}/consent-requests

Request body:

{
  "guardianIds": ["b1f6c2a0-7c2e-4b9a-9f3d-2a1c4e5d6f7a"],
  "returnUrl": "https://your-portal.example.com/consent/done"
}
Field Type Description
guardianIds string[] One or more guardian UUIDs to request consent from (at least one). Each guardian is emailed their own signing link.
returnUrl string Where the guardian's browser is redirected after they finish signing in DocuSign. Required — the platform hosts no landing page. Applies to every guardian in the request.

Response: 202 Accepted. The platform generates the DocuSign envelope and emails each guardian an HMAC-protected signing link.

Error responses:

  • 400 — invalid input (for example, an empty guardianIds or a missing returnUrl).
  • 403 — your client does not own the student's organization, or consent management is disabled for it.
  • 404 — the student or a guardian was not found.

This call requires the consent.write scope.

Step 2: The Guardian Signs (No Action Required From You)

Each guardian receives an email containing a signing link. When the guardian clicks it, the platform validates the HMAC-protected token and redirects the browser to a freshly generated DocuSign recipient-view page — no login required. After signing, the guardian lands on the returnUrl you supplied.

This step is handled entirely between the guardian and the platform; your integration does not call the redirect endpoint. You observe the outcome by polling the consent records in Step 3.

Step 3: Query Consent Status

Read a student's consent history, most recent first:

GET /consent/1.0/students/{studentId}/records

Query parameters:

Parameter Type Description
limit integer Maximum records to return (1–100, default 10).
offset integer Number of records to skip for pagination (default 0).

Response (200):

{
  "records": [
    {
      "id": "f0e9d8c7-b6a5-4321-8f0e-1d2c3b4a5e6f",
      "studentId": "9a8b7c6d-5e4f-3210-9a8b-7c6d5e4f3210",
      "guardianId": "b1f6c2a0-7c2e-4b9a-9f3d-2a1c4e5d6f7a",
      "consentStatus": "granted",
      "occurredAtTime": "2026-06-30T10:15:00.000Z",
      "dateCreated": "2026-06-30T10:15:01.482Z",
      "dateLastModified": "2026-06-30T10:15:01.482Z",
      "metadata": { "envelopeId": "..." }
    }
  ],
  "offset": 0,
  "limit": 10,
  "total": 1
}

Poll this endpoint until the relevant record's consentStatus reaches granted (or a terminal status such as denied). This call requires the consent.read scope.

Consent Status Values

Status Meaning
pending A consent request is outstanding; the guardian has not yet signed.
granted Consent was given.
denied The guardian declined consent.
expired The consent request lapsed before it was signed.
voided The consent request was invalidated before completion.
withdrawn Previously granted consent was later revoked.

When a request targets several guardians, each guardian produces its own record; query the records to see who has responded.

Recording Consent Collected Elsewhere

If you obtained parental consent out-of-band and want it reflected in TimeBack's audit trail, write a record directly:

POST /consent/1.0/students/{studentId}/records

Request body:

{
  "consentStatus": "granted",
  "occurredAtTime": "2026-06-30T09:00:00.000Z",
  "guardianId": "b1f6c2a0-7c2e-4b9a-9f3d-2a1c4e5d6f7a",
  "metadata": { "source": "school-onboarding-portal" }
}
Field Type Description
consentStatus enum One of the status values above. Required.
occurredAtTime ISO 8601 When the consent status change occurred. Required.
guardianId UUID, nullable The guardian who provided consent. Optional.
metadata object, nullable Free-form audit context (for example, the source system or a DocuSign envelope ID).

Response: 201 Created. This call requires the consent.write scope. Because the record store is append-only, this adds a new record rather than editing an existing one.

End-to-End Example 

# 1. Get an access token with the consent scopes
ACCESS_TOKEN=$(curl -s -X POST https://platform.timeback.com/auth/1.0/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials&scope=https://timeback-platform.trilogy.com/consent/scope/consent.write https://timeback-platform.trilogy.com/consent/scope/consent.read" \
  | jq -r .access_token)

# 2. Initiate the consent request for a student + guardian
curl -X POST "https://platform.timeback.com/consent/1.0/students/${STUDENT_ID}/consent-requests" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "guardianIds": ["'"${GUARDIAN_ID}"'"],
    "returnUrl": "https://your-portal.example.com/consent/done"
  }'
# → 202 Accepted; the guardian is emailed a signing link.

# 3. Poll status until granted
curl "https://platform.timeback.com/consent/1.0/students/${STUDENT_ID}/records?limit=10" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
# → inspect records[].consentStatus

Related Docs

Level 0: Register Your App

Register your App to get an App ID and OAuth credentials — the prerequisite for requesting consent scopes.

Authentication

Exchange your OAuth credentials for access tokens to call the consent APIs.

API Reference

Interactive API reference with full request/response schemas for the consent endpoints.

Previous
Webhooks