Examplary
    • Start for free
    Developer docs/Guides

    Import intent URL

    To offer users an option to import a test from your application into Examplary, you can use the import intent URL.

    The import intent URL has the following format:

    https://app.examplary.ai/intent/import?url={url}&name={name}&externalId={externalId}

    Where:

    • url: The URL where the test file can be downloaded from
      • This file should be in a supported format (e.g., Moodle XML, QTI)
      • The file's content type isn't inspected for this flow, so a Moodle XML or bare QTI XML file is only recognized as such if .xml appears somewhere in the URL's path or filename (a query string like ?token=... after it is fine) — otherwise it falls back to a slower, AI-based import. QTI packages (.zip) are unaffected by this.
      • The URL must be HTTPS with no custom port and no basic auth credentials, and it can't resolve to a private, loopback, or link-local address. It's fetched server-side with a plain request, so cookies or a browser session aren't forwarded; if the file needs authentication, put a token in the URL itself (e.g. ?token=...).
    • name: Optional parameter to specify the name of the exam in Examplary. It's only used when the user creates a new test — an existing test keeps its own name.
    • externalId: Optional identifier of your own for this test (any string, e.g. your database ID). Examplary stores it on the test it creates and uses it to recognize repeat imports of the same test.

    Choosing where the questions go

    When a user clicks on this URL, they will be redirected to Examplary, where they are asked where the questions should go:

    OptionWhen it's offeredWhat happens
    Into a new testAlwaysA new test is created. If you passed an externalId, it's stored on that test.
    Replace an existing testA test the user can edit carries the same externalIdThat test's questions are replaced with the imported ones. It keeps its ID, share link and settings.
    Add to an existing testNo externalId match — the five most recently created tests the user can edit are offeredThe questions are appended to that test, which keeps its settings.

    When an externalId match is found, replacing that test is preselected, so a returning user only has to confirm.

    Things to know

    • Matching is per user. Only tests the user can edit (owner, manager or editor) are considered, so a colleague's test that hasn't been shared with them won't match — each user ends up with their own copy.
    • Only new tests are tagged. The externalId is stored when a test is created through this flow. If the user instead adds the questions to an existing test, that test isn't tagged, and a later import with the same externalId will offer a new test again.
    • Replacing swaps out the questions only. Imported questions get new IDs, so results from sessions that were already taken no longer line up with the test's questions. Use externalId for tests you may re-export before they're taken, rather than to patch a test that's already in use.
    • You can read and write the same value through the API as metadata.externalId on an exam, so your integration can look up what it previously imported without relying on the user's choice.
    • The underlying import endpoint is rate limited to 5 requests per minute per user — this is only a concern if you're triggering the import programmatically rather than through a single user click.