Skip to content

Test safely

Before you wire anything into your MIS, run the whole flow end to end and see a real assessment result come back, without touching a single real learner. The pattern is simple: be your own test learner. Create a learner with contact details you control, walk the flow to a result, then delete the record when you are done. Because you own the inbox, no real learner is ever contacted, and you get a genuinely end-to-end trial including the invitation email and the live assessment.

The sequence is create to invite to complete to read to delete. The recipe below walks each step.

Is there a sandbox?

There is one live environment, and every example on this site runs against it:

https://api.uk.cognassist.com

There is no documented sandbox, test tenant, or dry-run mode, and no throwaway test credentials. So you test safely by controlling the data you send, not by pointing at a different URL. In practice that means each call creates real records in your organisation, and inviting a learner sends a real email, so you trial with data you own. The rest of this page is the recipe.

If your change process requires a dedicated non-production environment

If your security or change-control process needs an isolated environment before you can integrate, raise it with your Cognassist contact. Environments and credentials are arranged directly with Cognassist, so confirm what is available for your account rather than assuming. See Get access for how credentials are issued.

The recipe

1. Use email addresses you control

The email on a learner is the address the invitation is sent to, so the one rule that keeps you safe is: never put a real learner's address on a test record. Use your own mailbox, or plus-addressing if your mail system supports it, so every test invite lands with you.

  • you+test1@yourorg.ac.uk, you+test2@yourorg.ac.uk, and so on give each test learner a distinct, real inbox you own.
  • Set clientReference to something obviously non-production, such as TEST-001, so your test records are easy to spot and clean up. clientReference is your primary cross-system join key; see Core concepts.

Every call creates real data

There is no dry-run mode. A create call makes a real learner and an invite call sends a real email. Keep test data controlled: your own addresses, obvious references, and a small number of records.

2. Invite yourself, then complete the assessment

Inviting yourself is what makes the walkthrough genuinely end to end: you receive the same email a real learner would, follow the same link, and complete the same assessment, so you see the full journey before a single real learner is involved. This is the create-then-invite flow from Getting started, run against an address you own.

# Create a test learner with an address you own
curl -X POST https://api.uk.cognassist.com/v1/learners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Test", "lastName": "Learner",
    "email": "you+test1@yourorg.ac.uk",
    "gender": "Female", "postcode": "NE1 6BF", "dateOfBirth": "2000-02-24",
    "clientReference": "TEST-001",
    "primaryTutorEmail": "you@yourorg.ac.uk"
  }'

# Invite the learner to their assessment
curl -X POST \
  https://api.uk.cognassist.com/v1/learners/{learnerId}/assessment/invite \
  -H "Authorization: Bearer $TOKEN"

In a Microsoft shop you can drive the same two calls from a flow before you build anything permanent:

  1. HTTP action, method POST, URI https://api.uk.cognassist.com/v1/learners, with your bearer token in the Authorization header and the test learner as the JSON body.
  2. Parse the response and read learnerId from it.
  3. A second HTTP action, POST to https://api.uk.cognassist.com/v1/learners/{learnerId}/assessment/invite, using that learnerId.

See the Worked example with Power Automate for the full flow.

The create call returns learnerId and learnerUserId; keep the learnerId, because you need it to invite the learner, read the result, and delete the record. For the full create schema and returned fields, see the API reference and Core concepts.

Now open the invitation in your own inbox and complete the assessment. Once you finish, read the result back with GET /v1/learners/{learnerId}/assessment to confirm the whole round trip works before going near real data.

Why a repeat invite might not arrive

The invite endpoint will not send to the same learner twice within three days. That guard stops a retry or a loop from ever spamming a learner, and it applies to your test learners exactly as in production. If a repeat invite does not arrive, this is usually why, not a failure. See Troubleshooting.

3. Clean up your test records

When you have seen the flow work, remove the records you created so your organisation's data stays clean. DELETE /v1/learners/{learnerId} returns 204 No Content and is intended for exactly this: records created in error.

curl -X DELETE https://api.uk.cognassist.com/v1/learners/{learnerId} \
  -H "Authorization: Bearer $TOKEN"

Reserve delete for genuine mistakes and test data. For real learners who move tutor or programme, update the record with PUT /v1/learners/{learnerId} instead; see Create and manage learners.

A safe first-run checklist

Run through this once and you have proven the integration end to end without risk:

  • [ ] Point at the live base URL https://api.uk.cognassist.com and confirm you understand it creates real records.
  • [ ] Confirm the primaryTutorEmail you use belongs to a tutor who already exists in Cognassist.
  • [ ] Create a test learner with an email address you control and an obvious clientReference such as TEST-001.
  • [ ] Invite the learner, open the email in your own inbox, and complete the assessment.
  • [ ] Read the result back with GET /v1/learners/{learnerId}/assessment.
  • [ ] Delete the test record with DELETE /v1/learners/{learnerId}.

Next steps