Developers

Ethica Public API

The Ethica Public API allows you to programmatically manage employees and assignments, and retrieve requirement information. You can also subscribe to Webhooks to receive real-time notifications when training and policies are assigned or completed.

Not writing code? Connect Ethica to Zapier to add, update and deactivate employees from your HR system.

Authentication

All API endpoints require a Bearer token. You can generate API keys from the Settings > API & Webhooks tab in your dashboard (available to organization owners). Changes made with a key appear in the dashboard's activity log under the key's name.

Authorization: Bearer YOUR_API_KEY

Pagination

All index endpoints support pagination via ?page= and ?per_page= query parameters. The default per_page is 50, maximum is 100. Responses include a meta object with pagination details.

Endpoints

Organization

  • GET https://www.getethica.com/api/v1/me

    The organization the key belongs to. For an app connected with OAuth, it also names the admin who connected it.

    View Example Response
    {
      "organization": {
        "name": "Acme Corp"
      },
      "connected_as": null,
      "connection_label": "Acme Corp"
    }
  • GET https://www.getethica.com/api/v1/roles

    The organization's active roles, as a list.

    View Example Response
    [
      {
        "id": 4,
        "name": "Developer"
      },
      {
        "id": 5,
        "name": "Manager"
      }
    ]

Employees

  • GET https://www.getethica.com/api/v1/employees

    List all employees in your organization. Deactivated employees are included with a deactivated_at date and can't be assigned.

    View Example Response
    {
      "data": [
        {
          "id": 123,
          "name": "Jane Doe",
          "email": "jane@example.com",
          "hired_at": "2026-01-15",
          "created_at": "2026-02-25T14:32:00.000Z",
          "updated_at": "2026-02-25T14:32:00.000Z",
          "role": {
            "id": 4,
            "name": "Developer"
          },
          "deactivated_at": null
        }
      ],
      "meta": {
        "current_page": 1,
        "total_pages": 5,
        "total_count": 234,
        "has_next_page": true,
        "has_previous_page": false
      }
    }
  • POST https://www.getethica.com/api/v1/employees

    Create a new employee. Smart Assignments send them their training. language (en, es or fr) is optional.

    Body: { "name": "Jane Doe", "email": "o@org.com", "hired_at": "2026-01-15", "role_name": "Developer", "language": "es" }

    View Example Response
    {
      "id": 124,
      "name": "Jane Doe",
      "email": "o@org.com",
      "hired_at": "2026-01-15",
      "created_at": "2026-02-26T10:00:00.000Z",
      "updated_at": "2026-02-26T10:00:00.000Z",
      "role": {
        "id": 4,
        "name": "Developer"
      },
      "deactivated_at": null
    }
  • PATCH https://www.getethica.com/api/v1/employees/:id

    Update an existing employee. You can send an empty string for role_name to remove their assigned role. Send "active": false when someone leaves: they stop getting training, free their seat, and keep every record. "active": true brings them back if a seat is free.

    Body: { "name": "Jane Smith" }

    View Example Response
    {
      "id": 123,
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "hired_at": "2026-01-15",
      "created_at": "2026-02-25T14:32:00.000Z",
      "updated_at": "2026-03-02T09:10:00.000Z",
      "role": {
        "id": 5,
        "name": "Manager"
      },
      "deactivated_at": null
    }
  • PATCH https://www.getethica.com/api/v1/employees/by_email

    The same update, finding the employee by current_email instead of their ID. Fields sent empty or null are left unchanged. Returns 404 if no employee has that email.

    Body: { "current_email": "jane@example.com", "email": "jane.smith@example.com", "role_name": "Manager" }

    View Example Response
    {
      "id": 123,
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "hired_at": "2026-01-15",
      "created_at": "2026-02-25T14:32:00.000Z",
      "updated_at": "2026-03-02T09:10:00.000Z",
      "role": {
        "id": 5,
        "name": "Manager"
      },
      "deactivated_at": null
    }

Requirements

  • GET https://www.getethica.com/api/v1/requirements

    List all requirements: SCORM training, policy documents and external training (requirement_type is training, policy_document or external_training). Archived requirements are included with an archived_at date and can't be assigned.

    View Example Response
    {
      "data": [
        {
          "id": 456,
          "title": "Harassment Prevention",
          "requirement_type": "training",
          "effective_on": null,
          "archived_at": null,
          "created_at": "2026-01-10T09:00:00.000Z",
          "updated_at": "2026-01-15T11:20:00.000Z"
        }
      ],
      "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 12,
        "has_next_page": false,
        "has_previous_page": false
      }
    }

Assignments

  • GET https://www.getethica.com/api/v1/assignments

    List all assignments. Supports identical search parameters as the dashboard. paused is true for open assignments whose employee is deactivated or whose requirement is archived; Ethica sends nothing for them. certificate_link is set for completed SCORM training and is null otherwise.

    Example: /api/v1/assignments?search=overdue+role%3ADeveloper

    View Example Response
    {
      "data": [
        {
          "id": 10423,
          "status": "active",
          "paused": false,
          "due_date": "2026-03-25",
          "exempt": false,
          "completed_outside_ethica": false,
          "completed_at": null,
          "created_at": "2026-02-25T14:32:00.000Z",
          "scorm_data": {
            "cmi.core.score.raw": "85",
            "cmi.core.score.max": "100"
          },
          "updated_at": "2026-02-25T14:32:00.000Z",
          "employee": {
            "id": 123,
            "name": "Jane Doe",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane@example.com",
            "role": "Developer"
          },
          "requirement": {
            "id": 456,
            "title": "Harassment Prevention",
            "requirement_type": "training",
            "kind": "Course"
          },
          "certificate_link": null,
          "ethica_url": "https://www.getethica.com/dashboard/assignments/789"
        }
      ],
      "meta": {
        "current_page": 1,
        "total_pages": 3,
        "total_count": 139,
        "has_next_page": true,
        "has_previous_page": false
      }
    }
  • POST https://www.getethica.com/api/v1/assignments

    Assign a requirement to an employee. They get the same assignment email as assignments made in the dashboard.

    Body: { "employee_id": 123, "requirement_id": 456, "due_date": "2026-04-15" }

    View Example Response
    {
      "id": 10424,
      "status": "active",
      "paused": false,
      "due_date": "2026-04-15",
      "exempt": false,
      "completed_outside_ethica": false,
      "completed_at": null,
      "created_at": "2026-02-26T10:00:00.000Z",
      "scorm_data": {},
      "updated_at": "2026-02-26T10:00:00.000Z",
      "employee": {
        "id": 123,
        "name": "Jane Doe",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "role": "Developer"
      },
      "requirement": {
        "id": 456,
        "title": "Harassment Prevention",
        "requirement_type": "training",
        "kind": "Course"
      },
      "certificate_link": null,
      "ethica_url": "https://www.getethica.com/dashboard/assignments/789"
    }
  • GET https://www.getethica.com/api/v1/employees/:id/assignments

    List assignments for a specific employee. Supports ?status=active or ?status=completed.

    View Example Response
    {
      "data": [
        {
          "id": 10423,
          "status": "active",
          "paused": false,
          "due_date": "2026-03-25",
          "exempt": false,
          "completed_outside_ethica": false,
          "completed_at": null,
          "created_at": "2026-02-25T14:32:00.000Z",
          "scorm_data": {},
          "updated_at": "2026-02-25T14:32:00.000Z",
          "employee": {
            "id": 123,
            "name": "Jane Doe",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane@example.com",
            "role": "Developer"
          },
          "requirement": {
            "id": 456,
            "title": "Harassment Prevention",
            "requirement_type": "training",
            "kind": "Course"
          },
          "certificate_link": null,
          "ethica_url": "https://www.getethica.com/dashboard/assignments/789"
        }
      ],
      "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 4,
        "has_next_page": false,
        "has_previous_page": false
      }
    }

Webhooks

Configure Webhooks in your dashboard to receive HTTP POST payloads when specific events occur. Webhooks are delivered in JSON format. We send requests to your endpoint containing an X-Ethica-Signature: sha256=<hex digest> header: an HMAC-SHA256 of the raw request body, keyed with your endpoint's signing secret. Verify the sender by computing the same digest on your side.

Supported Events

  • assignment.assigned — Dispatched when a requirement is assigned to an employee, including each automatic renewal cycle.
  • assignment.completed — Dispatched when an assignment is completed: a course finished, a policy acknowledged, a certificate uploaded, work done outside Ethica recorded by an admin (a signed copy or certificate, "completed_outside_ethica": true), or the assignment marked exempt ("exempt": true).

Payload Format

View Example Webhook Payload
{
  "event": "assignment.completed",
  "timestamp": "2026-02-25T14:32:00Z",
  "data": {
    "id": 10423,
    "status": "completed",
    "paused": false,
    "due_date": "2026-03-25",
    "exempt": false,
    "completed_outside_ethica": false,
    "completed_at": "2026-02-25T14:32:00Z",
    "created_at": "2026-02-01T09:00:00.000Z",
    "scorm_data": {
      "cmi.core.score.raw": "100",
      "cmi.core.score.max": "100",
      "cmi.core.lesson_status": "completed"
    },
    "updated_at": "2026-02-25T14:32:00.000Z",
    "employee": {
      "id": 123,
      "name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "role": "Developer"
    },
    "requirement": {
      "id": 456,
      "title": "Harassment Prevention",
      "requirement_type": "training",
      "kind": "Course"
    },
    "certificate_link": "https://www.getethica.com/certificate/123e4567-e89b-12d3-a456-426614174000",
    "ethica_url": "https://www.getethica.com/dashboard/assignments/789"
  }
}