# Get Assessment
Source: https://v4-docs.alfaone.app/api-reference/assessments/get-assessment

GET /assessments/{assessmentId}
Returns detailed information about a specific assessment.



# List Assessments
Source: https://v4-docs.alfaone.app/api-reference/assessments/list-assessments

GET /assessments
Returns a paginated list of all assessments for the organization associated with the API key.



# List Questions
Source: https://v4-docs.alfaone.app/api-reference/assessments/list-questions

GET /assessments/{assessmentId}/questions
Returns a paginated list of questions for a specific assessment.



# API Reference
Source: https://v4-docs.alfaone.app/api-reference/introduction

Complete reference for the AlfaOne Public API

## Base URL

All API requests should be made to:

```
https://alfaone.app/api/v1
```

## Authentication

All endpoints require an API key passed in the `x-api-key` header:

```bash theme={null}
curl -X GET "https://alfaone.app/api/v1/assessments" \
  -H "x-api-key: ak_live_your_api_key_here"
```

See the [Authentication](/authentication) page for more details.

## Response Format

All responses are returned in JSON format. Successful responses will include the requested data, while error responses will include an `error` field with a descriptive message.

### Success Response

```json theme={null}
{
  "assessments": [
    {
      "id": "uuid",
      "name": "Assessment Name"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

### Error Response

```json theme={null}
{
  "error": "Error message describing what went wrong"
}
```

## HTTP Status Codes

| Status Code | Description                                             |
| ----------- | ------------------------------------------------------- |
| `200`       | Success - Request completed successfully                |
| `201`       | Created - Resource was created successfully             |
| `400`       | Bad Request - Invalid or missing request parameters     |
| `401`       | Unauthorized - Invalid or missing API key               |
| `404`       | Not Found - The requested resource doesn't exist        |
| `409`       | Conflict - The resource already exists                  |
| `429`       | Too Many Requests - Rate limit exceeded                 |
| `500`       | Internal Server Error - Something went wrong on our end |

## Available Endpoints

<CardGroup>
  <Card title="Assessments" icon="clipboard-list" href="/api-reference/assessments/list-assessments">
    List, retrieve, and view questions for assessments
  </Card>

  <Card title="Members" icon="users" href="/api-reference/members/list-members">
    Access organization member information
  </Card>

  <Card title="Invites" icon="envelope" href="/api-reference/invites/list-invites">
    Send assessment invites and track their status
  </Card>

  <Card title="Tags" icon="tag" href="/api-reference/tags/list-tags">
    Create, update, and manage organization tags
  </Card>
</CardGroup>

## Pagination

All list endpoints support pagination through query parameters. Results are returned alongside a `pagination` metadata object.

### Query Parameters

| Parameter | Type    | Default  | Description                                             |
| --------- | ------- | -------- | ------------------------------------------------------- |
| `page`    | integer | `1`      | Page number (1-indexed)                                 |
| `limit`   | integer | `20`     | Items per page (min 1, max 100)                         |
| `sort`    | string  | *varies* | Field to sort by (see each endpoint for allowed values) |
| `order`   | string  | `desc`   | Sort direction: `asc` or `desc`                         |

### Example Request

```bash theme={null}
curl -X GET "https://alfaone.app/api/v1/assessments?page=2&limit=10&sort=name&order=asc" \
  -H "x-api-key: ak_live_your_api_key_here"
```

### Paginated Response

Every list response includes a `pagination` object alongside the resource array:

```json theme={null}
{
  "assessments": [
    {
      "id": "uuid",
      "name": "Assessment Name"
    }
  ],
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 87,
    "totalPages": 9
  }
}
```

| Field        | Description                                |
| ------------ | ------------------------------------------ |
| `page`       | The current page number                    |
| `limit`      | The number of items per page               |
| `total`      | The total number of items across all pages |
| `totalPages` | The total number of pages                  |

## Versioning

The API is versioned via the URL path (`/api/v1/`). When breaking changes are introduced, a new version will be released while maintaining support for previous versions during a deprecation period.


# Create Invite
Source: https://v4-docs.alfaone.app/api-reference/invites/create-invite

POST /invites
Sends an assessment invite to a candidate. The invite email is dispatched automatically after creation.

One invite is created per request. To send multiple invites, make separate requests for each recipient.




# Get Invite
Source: https://v4-docs.alfaone.app/api-reference/invites/get-invite

GET /invites/{inviteId}
Returns detailed information about a specific assessment invite.



# List Invites
Source: https://v4-docs.alfaone.app/api-reference/invites/list-invites

GET /invites
Returns a paginated list of all assessment invites for the organization. Supports optional filtering by assessment ID or status.



# List Members
Source: https://v4-docs.alfaone.app/api-reference/members/list-members

GET /members
Returns a paginated list of all members in the organization associated with the API key.



# Create Tag
Source: https://v4-docs.alfaone.app/api-reference/tags/create-tag

POST /tags
Creates a new tag for the organization. Tag names must be unique within the organization.




# Delete Tag
Source: https://v4-docs.alfaone.app/api-reference/tags/delete-tag

DELETE /tags/{tagId}
Permanently deletes a tag. The tag will also be removed from any assessments, invites, and member assignments that reference it.




# Get Tag
Source: https://v4-docs.alfaone.app/api-reference/tags/get-tag

GET /tags/{tagId}
Returns detailed information about a specific tag.



# List Tags
Source: https://v4-docs.alfaone.app/api-reference/tags/list-tags

GET /tags
Returns a paginated list of all tags for the organization associated with the API key.



# Update Tag
Source: https://v4-docs.alfaone.app/api-reference/tags/update-tag

PATCH /tags/{tagId}
Updates an existing tag. At least one field (name, color, or description) must be provided.
Tag names must remain unique within the organization.




# Authentication
Source: https://v4-docs.alfaone.app/authentication

Learn how to authenticate with the AlfaOne API

## API Key Authentication

All AlfaOne API endpoints require authentication using an API key. API keys are scoped to a single organization, and all data returned will be filtered to that organization.

### Obtaining an API Key

1. Log in to your AlfaOne admin dashboard
2. Navigate to **Settings → Integrations**
3. Click **Generate API Key**
4. Give your key a descriptive name (e.g., "Production Integration", "Development Testing")
5. Copy and securely store the generated key

<Warning>
  API keys are shown only once at creation. Store them securely in your environment variables or secrets manager.
</Warning>

### Using your API Key

Include your API key in the `x-api-key` header with every request:

```bash theme={null}
curl -X GET "https://alfaone.app/api/v1/assessments" \
  -H "x-api-key: ak_live_your_api_key_here"
```

### API Key Format

AlfaOne API keys follow this format:

| Environment     | Format                     | Example                                    |
| --------------- | -------------------------- | ------------------------------------------ |
| Live/Production | `ak_live_` + 32 characters | `ak_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6` |
| Test/Sandbox    | `ak_test_` + 32 characters | `ak_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6` |

## Error Responses

If authentication fails, the API will return one of the following errors:

<ResponseField name="error" type="string">
  Description of the authentication error
</ResponseField>

### Common Authentication Errors

<AccordionGroup>
  <Accordion title="401 - Missing API Key">
    ```json theme={null}
    {
      "error": "API key is required"
    }
    ```

    **Solution:** Include the `x-api-key` header in your request.
  </Accordion>

  <Accordion title="401 - Invalid API Key">
    ```json theme={null}
    {
      "error": "Invalid API key"
    }
    ```

    **Solution:** Verify that your API key is correct and hasn't been mistyped.
  </Accordion>

  <Accordion title="401 - Expired API Key">
    ```json theme={null}
    {
      "error": "API key has expired"
    }
    ```

    **Solution:** Generate a new API key from the Integrations page.
  </Accordion>

  <Accordion title="401 - Revoked API Key">
    ```json theme={null}
    {
      "error": "API key has been revoked"
    }
    ```

    **Solution:** This key has been manually revoked. Generate a new API key.
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup>
  <Card title="Use Environment Variables" icon="shield">
    Never hardcode API keys in your source code. Use environment variables or a secrets manager.
  </Card>

  <Card title="Rotate Keys Regularly" icon="arrows-rotate">
    Periodically rotate your API keys and revoke old ones to minimize security risks.
  </Card>

  <Card title="Use Separate Keys" icon="key">
    Use different API keys for development, staging, and production environments.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Regularly review API usage in your dashboard to detect any unusual activity.
  </Card>
</CardGroup>

## Rate Limiting

API requests are rate limited to ensure fair usage:

| Tier       | Rate Limit           |
| ---------- | -------------------- |
| Standard   | 100 requests/minute  |
| Enterprise | 1000 requests/minute |

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Rate limit exceeded. Please try again later."
}
```

<Tip>
  Implement exponential backoff in your integration to gracefully handle rate limiting.
</Tip>


# Introduction
Source: https://v4-docs.alfaone.app/introduction

Welcome to the AlfaOne API documentation

AlfaOne is a comprehensive assessment platform designed for evaluating candidates through customizable assessments. Our public API enables third-party integrations to seamlessly interact with the AlfaOne platform.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started with the AlfaOne API in minutes
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn how to authenticate your API requests
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all available API endpoints
  </Card>
</CardGroup>

## What can you do with the API?

The AlfaOne Public API allows you to:

* **List and retrieve assessments** - Access all assessments in your organization
* **View assessment questions** - Get detailed information about questions for each assessment
* **Manage invites** - List and view assessment invite details and statuses
* **Access member information** - Retrieve organization member details and roles

## Use Cases

<AccordionGroup>
  <Accordion title="ATS Integration">
    Integrate AlfaOne with your Applicant Tracking System to automatically trigger assessments when candidates reach a specific stage.
  </Accordion>

  <Accordion title="Reporting Dashboard">
    Build custom reporting dashboards by pulling assessment data and invite statuses into your business intelligence tools.
  </Accordion>

  <Accordion title="Automated Workflows">
    Create automated workflows that respond to assessment completions and route candidates based on results.
  </Accordion>
</AccordionGroup>

## Getting Help

If you need assistance with the API, you can:

* Check our [API Reference](/api-reference/introduction) for detailed endpoint documentation
* Contact [support@alfaone.app](mailto:support@alfaone.app) for direct assistance


# Quickstart
Source: https://v4-docs.alfaone.app/quickstart

Get started with the AlfaOne API in under 5 minutes

## Setup your API Key

Before you can make API requests, you'll need to generate an API key from your AlfaOne dashboard.

<Steps>
  <Step title="Navigate to Integrations">
    Log in to your AlfaOne admin dashboard and navigate to **Settings → Integrations**.
  </Step>

  <Step title="Create an API Key">
    Click on **Generate API Key**, provide a descriptive name for your key, and save it.

    <Warning>
      Store your API key securely. You won't be able to see the full key again after creation.
    </Warning>
  </Step>

  <Step title="Copy your API Key">
    Copy the generated API key. It will be in the format: `ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
  </Step>
</Steps>

## Make your first API call

Now that you have your API key, let's make your first request to list all assessments in your organization.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://alfaone.app/api/v1/assessments" \
    -H "x-api-key: ak_live_your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://alfaone.app/api/v1/assessments', {
    method: 'GET',
    headers: {
      'x-api-key': 'ak_live_your_api_key_here'
    }
  });

  const data = await response.json();
  console.log(data.assessments);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://alfaone.app/api/v1/assessments',
      headers={'x-api-key': 'ak_live_your_api_key_here'}
  )

  assessments = response.json()['assessments']
  print(assessments)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "assessments": [
    {
      "id": "7cac8eb9-09a8-4cec-b28e-dfc50db8d0f9",
      "name": "Software Engineer Assessment",
      "defaultQuestionFormat": "audio",
      "defaultAnswerFormat": "audio",
      "languages": ["en", "es"],
      "questionCount": 10,
      "inviteCount": 25,
      "createdAt": "2025-01-01T10:00:00.000Z",
      "updatedAt": "2025-01-02T15:30:00.000Z"
    }
  ]
}
```

## Send an assessment invite

Once you have an assessment ID, you can programmatically invite a candidate to take it.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://alfaone.app/api/v1/invites" \
    -H "x-api-key: ak_live_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "assessmentId": "7cac8eb9-09a8-4cec-b28e-dfc50db8d0f9",
      "recipientEmail": "candidate@example.com"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://alfaone.app/api/v1/invites', {
    method: 'POST',
    headers: {
      'x-api-key': 'ak_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      assessmentId: '7cac8eb9-09a8-4cec-b28e-dfc50db8d0f9',
      recipientEmail: 'candidate@example.com'
    })
  });

  const data = await response.json();
  console.log(data.invite);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://alfaone.app/api/v1/invites',
      headers={'x-api-key': 'ak_live_your_api_key_here'},
      json={
          'assessmentId': '7cac8eb9-09a8-4cec-b28e-dfc50db8d0f9',
          'recipientEmail': 'candidate@example.com'
      }
  )

  invite = response.json()['invite']
  print(invite)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "invite": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "assessmentId": "7cac8eb9-09a8-4cec-b28e-dfc50db8d0f9",
    "assessmentName": "Software Engineer Assessment",
    "recipientEmail": "candidate@example.com",
    "recipientName": null,
    "status": "pending",
    "questionReplayLimit": 1,
    "answerRecordLimit": 1,
    "sentAt": "2025-01-15T12:00:00.000Z",
    "expiresAt": "2025-02-14T12:00:00.000Z",
    "acceptedAt": null,
    "startedAt": null,
    "completedAt": null
  }
}
```

The candidate will automatically receive an email with a link to start the assessment.

## Next Steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn more about API authentication and security
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore all available endpoints
  </Card>
</CardGroup>