Quickstart

Verify your API key, then inspect a subject-creation example. Ferretly does not provide a separate integration test environment: requests use your organization’s data. Coordinate real test work with your Ferretly contact.

Prerequisites

1. An existing Ferretly organization and a private API key from Request access (or your Ferretly contact). Confirm whether the organization has Analyst Assistance.
2. A terminal with curl, or a server-side environment for the example language. The Python examples use the requests package; the C# examples use .NET HTTP and JSON namespaces.

Base URL: https://api.ferretly.com

1. Verify your key

Use GET /api/ApiClient as your first authenticated call. It returns client configuration such as permissions and the configured webhook URL.

curl

curl --fail -sS https://api.ferretly.com/api/ApiClient \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript

const res = await fetch('https://api.ferretly.com/api/ApiClient', {
  headers: {
    'X-Api-Key': process.env.FERRETLY_API_KEY,
    Accept: 'application/json',
  },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const client = await res.json();
console.log(client);

C#

using System;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.ferretly.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", Environment.GetEnvironmentVariable("FERRETLY_API_KEY"));
http.DefaultRequestHeaders.Accept.ParseAdd("application/json");

var client = await http.GetFromJsonAsync<JsonElement>("/api/ApiClient");
Console.WriteLine(client);

Python

import os, requests

r = requests.get(
    "https://api.ferretly.com/api/ApiClient",
    headers={"X-Api-Key": os.environ["FERRETLY_API_KEY"], "Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

A successful response means your key is valid and associated with an organization.

2. Create a subject (debug)

Replace the example name, external ID, and API key with your own test values.

POST /api/Subjects requires subjectData. Identity is a single name field (not firstName / lastName).

Debug mode

These request-shape examples use isDebug: true, so no subject is saved. Fetching the returned ID later will return an error because that subject does not exist. Keep assignToFerretlyAnalyst: false and omit continuous screening when trying these examples; debug mode does not make other options a separate sandbox.

curl

curl --fail -sS -X POST https://api.ferretly.com/api/Subjects \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "subjectData": {
      "name": "Ada Lovelace"
    },
    "externalSystemId": "candidate-001",
    "assignToFerretlyAnalyst": false,
    "isDebug": true
  }'

JavaScript

const res = await fetch('https://api.ferretly.com/api/Subjects', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.FERRETLY_API_KEY,
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    subjectData: { name: 'Ada Lovelace' },
    externalSystemId: 'candidate-001',
    assignToFerretlyAnalyst: false,
    isDebug: true,
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

C#

var payload = new {
    subjectData = new { name = "Ada Lovelace" },
    externalSystemId = "candidate-001",
    assignToFerretlyAnalyst = false,
    isDebug = true
};
var res = await http.PostAsJsonAsync("/api/Subjects", payload);
res.EnsureSuccessStatusCode();
Console.WriteLine(await res.Content.ReadAsStringAsync());

Python

r = requests.post(
    "https://api.ferretly.com/api/Subjects",
    headers={
        "X-Api-Key": os.environ["FERRETLY_API_KEY"],
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "subjectData": {"name": "Ada Lovelace"},
        "externalSystemId": "candidate-001",
        "assignToFerretlyAnalyst": False,
        "isDebug": True,
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

The C# create example reuses the http client from step 1. The Python example reuses its imports. A successful non-debug create returns a Subject with HTTP 200; debug returns a constructed subject without inserting it.

Follow the workflow already configured for your organization when moving from this debug example to a saved subject. For Analyst Assistance, use the analyst-managed guide; do not call initiateBackgroundCheck. For an organization without Analyst Assistance, follow the separate lifecycle, including its verified-handle prerequisites. A start request using a debug response’s ID returns an error because no subject was saved.

3. Next steps

Goal	Guide
Integrate with Analyst Assistance	Add and assign a subject
Integrate without Analyst Assistance	Screening lifecycle
Map your system IDs	Identity & IDs
Receive status callbacks	Webhook setup
Explore every endpoint	API Reference

Common mistakes

• Using firstName / lastName instead of name
• Omitting Content-Type: application/json on POST/PUT
• Calling initiateBackgroundCheck if your org uses Analyst Assistance (analysts run the screen)
• Sending an invalid body. The examples use application/json; consult each endpoint’s documented media types.