AlfaOne API overview

API overview

The AlfaOne public API is a RESTful JSON API that lets you work with assessments, invites, organization users, and tags from your own systems using standard HTTP/JSON.

The GET endpoints support an optional depth query parameter; setting depth=2 returns nested related objects alongside the primary resources in the response.

Prerequisites

Before you start making requests, ensure you have:

• An active AlfaOne account.
• An API key. You can obtain this from the AlfaOne Admin Portal
• A secure server-side environment to store your credentials (for example, environment variables in your backend or serverless platform).

Available APIs

The AlfaOne public API exposes four main endpoints for working with assessments, invites, organization users, and tags.

Assessment invites

An assessment invite is a concrete invite instance created when you invite a candidate to take an assessment. It ties together the candidate's email, the assessment configuration, limits on how many times they can play questions or record answers, identity checks, tags, and (optionally) the grader who will review the session.

Required request fields (create)

When calling POST /assessment_invites (or the organization-scoped variant), all of the following fields must be present in the JSON body:

• email – candidate's email address. Must be a valid, correctly formatted email.
• assessment – ID/UUID of the assessment to be taken. You can retrieve available IDs using GET /assessments.
• question_play_limit – integer > 0 indicating how many times a candidate may play each question.
• answer_record_limit – integer > 0 indicating how many answer recordings are allowed.
• face_photo_required – boolean specifying whether a face photo is required.
• id_photo_required – boolean specifying whether an ID document photo is required.
• tags – list of tag IDs (can be empty but the field itself must be present). Tag IDs can be discovered via GET /tags.
• assigned_grader – ID/UUID of the grader who should evaluate this invite. The field must be present in the payload; depending on your configuration it may be allowed to be null, or you can supply an organization user ID from GET /organization_users.

If any required field is missing or invalid (for example, an empty email, zero/negative limits, or missing booleans), the API will return a 400 Bad Request with field-level error messages.

Fetching assessment invites

Use GET /assessment_invites or the organization-scoped path to retrieve invites for an organization, with support for pagination, filtering, and search. Using the example base URL, the list endpoint is:

https://docs.alfaone.app/alfaone/v1/assessment_invites

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/assessment_invites" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>"

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/assessment_invites?page=1&page_size=20&search=candidate@example.com" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>"

The page, page_size, and search query parameters are optional; omit them to use default pagination and return all invites matching your other filters.

Creating an assessment invite (POST)

To create a new assessment invite, send a POST request to the same endpoint with a JSON body that includes all required fields:

curl -X POST \
  "https://docs.alfaone.app/alfaone/v1/assessment_invites" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@gmail.com",
    "question_play_limit": 2,
    "answer_record_limit": 2,
    "assessment": "f854bc8e-0898-427b-a571-9cd6ca294903",
    "assigned_grader": "897edc27-17df-44e3-9ad0-c9bd652ddd5f",
    "tags": [
      "8909e990-896c-4869-a234-281d1055cf54",
      "e7acd15a-c323-48c5-924e-17c14cd6a53e"
    ],
    "id_photo_required": true,
    "face_photo_required": true
  }'

On success, the API will return the created invite, including its unique id and resolved status:

{
  "id": "a6abaa20-6006-49a9-be9e-d9f523539877",
  "assessment_session": null,
  "deleted": false,
  "created_at": "2025-12-22T03:16:34.403851Z",
  "updated_at": "2025-12-22T03:16:34.403883Z",
  "email": "pepor77779@gamintor.com",
  "status": "pending",
  "face_photo_required": true,
  "id_photo_required": true,
  "question_play_limit": 2,
  "answer_record_limit": 2,
  "expires_at": null,
  "organization": "0c249901-156d-4792-850e-cf2dc96f5f3d",
  "assessment": "f854bc8e-0898-427b-a571-9cd6ca294903",
  "user": null,
  "created_by": "user_2yuBNMu0DnEOSoXrYxpcjdwzaSB",
  "assigned_grader": "897edc27-17df-44e3-9ad0-c9bd652ddd5f",
  "tags": [
    "8909e990-896c-4869-a234-281d1055cf54",
    "e7acd15a-c323-48c5-924e-17c14cd6a53e"
  ]
}

Assessments

The /assessments endpoint exposes read-only assessment available to your organization. Each assessment describes a test that can be used when creating invites, including its name, configuration, and other metadata.

The full URL for this endpoint, using the example base URL above, is https://docs.alfaone.app/alfaone/v1/assessments. You will typically append query parameters such as ?organization=<org-uuid> and optional filters like &name=<assessment-name>.

Filtering assessments with query parameters

You can use these parameters to let you narrow results and find exactly the assessment ID you need. All comma-separated parameters (for example, tags=tag1,tag2) match any of the provided values.

• organization – An organization ID of your organization.
• created_by – filter by the ID of the user who created the assessment (organization user ID).
• audience – Explains the audience of the assessment. Either invite_only or public.
• question_count – filters to assessments whose total number of questions exactly equals this value (using an internal num_questions annotation).
• tags – tag IDs (comma-separated) to return assessments that have any of the specified tags attached.
• type – assessment type such as audio or video
• answer_type – Expected answer type of the assessment such as audio or text
• name – name of the assessment. this is case sensitive. It should be exactly as it appears in your organization

By combining these filters (for example, organization=<org-uuid>&name=English Level Test), you can narrow down to one or a few matching assessments and then read their id from the response to use in the assessment field when creating invites.

Fetching assessments

Use GET /assessments with your API key. You can combine page, page_size, search, filter parameters, and depth (for example, depth=2) for more detailed nested data.

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/assessments" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/assessments?page=1&page_size=10&search=english&name=Audio Only Assessment COPY COPY COPY COPY" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

The page, page_size,search, and depth query parameters are optional helpers for pagination and filtering.

Concrete example: fetch a specific assessment by name

For example, this request targets a specific assessment called Audio Only Assessment COPY COPY COPY COPY for a given organization. You can then take the returned id from that assessment and use it as the assessment field when creating an invite:

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/assessments?name=Audio Only Assessment COPY COPY COPY COPY" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

A successful call will return a paginated result set; for example:

{
  "count": 1,
  "next": null,
  "previous": null,
  "num_pages": 1,
  "current_page": 1,
  "results": [
    {
      "id": "f854bc8e-0898-427b-a571-9cd6ca294903",
      "question_count": 4,
      "tags": [],
      "clients": [],
      "client_count": 0,
      "time_limit_minutes": 0,
      "time_limit_seconds": 0,
      "deleted": false,
      "created_at": "2025-12-10T10:45:44.896220Z",
      "updated_at": "2025-12-10T10:45:46.216008Z",
      "name": "Audio Only Assessment COPY COPY COPY COPY",
      "type": "audio",
      "audience": "invite_only",
      "answer_type": "audio",
      "time_limit": 0,
      "instruction": "3a224ec5-8d38-4b31-8ad3-7a5e409d7f3a",
      "organization": "0c249901-156d-4792-850e-cf2dc96f5f3d",
      "created_by": "user_2ymgXu0ZuNs9QzKsxk0eJZyyykP",
      "languages": [
        "57014e3b-8d99-4385-b990-004583d8f732",
        "85a03b85-4aa8-440b-b7b7-001559688ef5"
      ],
      "categories": [
        "23c1e60c-22d8-450c-b892-05f71cf5a899",
        "98afa5c9-ab98-447f-a118-2df6f97bb77f"
      ],
      "skill_type": []
    }
  ]
}

In this response, the assessment identifier you must use in the invite payload is id: f854bc8e-0898-427b-a571-9cd6ca294903, which becomes the value of the assessment field when creating an assessment invite.

Organization users

The /organization_users endpoint returns active users belonging to your organization. These records are useful when you need IDs for fields like assigned_grader when creating invites.

Using the example base URL above, the full endpoint URL is https://docs.alfaone.app/alfaone/v1/organization_users. You will typically call it with ?organization=<org-uuid> and any additional filters you need.

You can use query parameters to filter organization users via an internal OrganizationUserFilter:

• organization – ID of your organization; optional filter to scope results when supported.
• tags – filter users by attached tags (provide tag ids separated by commas).
• is_admin – boolean; when true, returns users whose roles include admin. When false, excludes those users.
• is_grader – boolean; when true, returns users whose roles include grader.
• is_client – boolean; when true, returns users whose roles include client; when false, excludes those users.
• first_name – This is the first name of the user
• last_nameThis is the last name of the user
• email This is the email of the user

Fetching organization users

Use GET /organization_users with your organization query parameter. You can search by name or email and include nested user details with depth (for example, depth=2):

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/organization_users" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/organization_users?search=jane&page=1&page_size=20&depth=1" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

As with other list endpoints, page, page_size, search, and depth are optional.

Concrete example: fetch a specific organization user by email

The following request filters by organization and email:

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/organization_users?email=test@example.com" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

A successful call will return a paginated list of organization users. For example:

{
  "count": 1,
  "next": null,
  "previous": null,
  "num_pages": 1,
  "current_page": 1,
  "results": [
    {
      "id": "30115221-da9b-4bea-be30-0aa29fe6057f",
      "tags": [],
      "assigned_assessments_count": 2,
      "deleted": false,
      "created_at": "2025-07-16T12:27:12.622707Z",
      "updated_at": "2025-09-25T06:37:23.728286Z",
      "roles": [
        "admin",
        "grader",
        "client"
      ],
      "can_view_transcription": true,
      "organization": "0c249901-156d-4792-850e-cf2dc96f5f3d",
      "user": "user_2ymgXu0ZuNs9QzKsxk0eJZyyykP",
      "grading_languages": []
    }
  ]
}

In this response, the organization user identifier you must use for assigned_grader is id: 30115221-da9b-4bea-be30-0aa29fe6057f.

Tags

The /tags endpoint exposes tags that can be attached to invites and assessments for classification and reporting. Each tag belongs to an organization and may also track who created it.

Using the example base URL above, the full endpoint URL is https://docs.alfaone.app/alfaone/v1/tags. You will typically call it with ?organization=<org-uuid> and, when needed, &name=<tag-name> or other filters.

Fetching tags

Use GET /tags with your organization query parameter, and optionally filter by name (exact, case-sensitive match as it appears in your organization) or created_by. Tag IDs from this endpoint are used in the tags field when creating invites.

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/tags" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/tags?name=priority&page=1&page_size=50" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

The name, page, and page_size parameters are optional filters; call /tags without them to list all tags for the key.

Concrete example: fetch a specific tag by name

The following request looks up a tag called Advanced Level - Difficulty 9 for a specific organization. Note that the name value must match exactly (including capitalization and spacing):

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/tags?name=Advanced Level - Difficulty 9" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

{
  "count": 1,
  "next": null,
  "previous": null,
  "num_pages": 1,
  "current_page": 1,
  "results": [
    {
      "id": "8909e990-896c-4869-a234-281d1055cf54",
      "name": "Advanced Level - Difficulty 9",
      "color": "#FF5733",
      "organization": "0c249901-156d-4792-850e-cf2dc96f5f3d",
      "created_by": null,
      "created_at": "2025-06-25T11:02:27.802223Z",
      "updated_at": "2025-06-25T11:02:27.802250Z",
      "icon": null
    }
  ]
}

In this response, the tag identifier you must use in the tags array of the assessment invite payload is id: 8909e990-896c-4869-a234-281d1055cf54.

Authentication

All exposed endpoints are secured with an organization-level API key sent in the request headers. Access control is based solely on this key; organization IDs are used only as regular query parameters to scope or filter results on specific endpoints, not for authentication.

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/assessments" \
  -H "X-ALFAONE-DOCS-API-KEY: <org-api-key>" \
  -H "Accept: application/json"

curl -X GET \
  "https://docs.alfaone.app/alfaone/v1/assessments"

{
  "detail": "Authentication credentials were not provided."
}

HTTP status codes & implementation notes

• 200 OK – successful GET list/detail.
• 201 Created – successful POST (e.g., creating an invite).
• 400 Bad Request – validation or filter errors with field-level details.
• 401 / 403 – missing or invalid API key, or missing/invalid organization parameter.
• 404 Not Found – resource does not exist.
• 405 Method Not Allowed – using unsupported HTTP methods.

Next steps