API Reference

Note

API access is available on Professional, Business, and Enterprise plans. Starter plan accounts cannot generate or use API keys.

The Athenty REST API lets you integrate identity verification directly into your applications, workflows, and back-office systems — without a manual operator in the loop.

Create verifications

Trigger Smart IDV or Smart KYC verifications programmatically and receive results via webhook.

Read verification status

Retrieve the full assembled status of any verification, including scores and decisions.

Manage clients

Create and retrieve client records from your CRM, case management, or loan origination platform.

Receive webhooks

Subscribe to real-time events for verification milestones. See Webhook Events below.

---

Base URL

https://api.athenty.com/v2/api

---

Authentication

All API requests must include your organization’s API key in the X-Api-Key header.

curl https://api.athenty.com/v2/api/verifications \
  -H "X-Api-Key: YOUR_API_KEY"

Getting your API key

1. Log in to the Athenty admin portal
2. Go to Settings → General
3. Scroll to the API Key section
4. Click Generate Key

Your key is shown once — copy it immediately. You can rotate or revoke it at any time from the same screen.

Caution

Treat your API key like a password. Never commit it to source control or expose it in client-side code. Rotate immediately if compromised.

---

Endpoints

Verifications

Method	Path	Description
POST	/verifications	Create a new verification
GET	/verifications	List verifications (paginated)
GET	/verifications/:id	Get a verification with full assembled detail

Clients

Method	Path	Description
POST	/clients	Create a new client record
GET	/clients	List clients (paginated)
GET	/clients/:id	Get a client record

---

POST /verifications

Create a new verification. The subject receives an email invitation to complete their verification (if subjectEmail is provided).

curl -X POST https://api.athenty.com/v2/api/verifications \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "idv",
    "requirements": ["document", "person", "biometric_face"],
    "subjectName": "Jane Smith",
    "subjectEmail": "jane@example.com",
    "expiresDays": 7
  }'

Request body

Field	Type	Required	Description
type	"idv" | "kyc" | "share"	✅	Verification type
requirements	string[]	✅	Ordered list of steps to collect. At least one required.
clientId	string (UUID)	—	Link to an existing client record
matterId	string (UUID)	—	Link to a matter
subjectName	string	—	Full name of the subject being verified
subjectEmail	string	—	Email address — used to send the verification invitation
subjectPhone	string	—	Phone number
expiresDays	integer (1–90)	—	Days until the link expires (default: 7)
config	object	—	Step-specific configuration overrides
thirdParties	array	—	Third parties to auto-share with on approval

Available requirements: document, person, location, contact, biometric_face, business, pep_hio, financial, consent, attestation, estate

Response 201

{
  "id": "req_01j9abc123",
  "orgId": "org_01j9abc000",
  "type": "idv",
  "status": "initiated",
  "requirements": ["document", "person", "biometric_face"],
  "subjectName": "Jane Smith",
  "subjectEmail": "jane@example.com",
  "expiresDays": 7,
  "expiresAt": "2025-04-12T00:00:00.000Z",
  "accessToken": "a1b2c3...",
  "createdAt": "2025-04-05T12:00:00.000Z"
}

---

GET /verifications

List verifications for your organization. Results are paginated.

curl "https://api.athenty.com/v2/api/verifications?status=pending_review&limit=25" \
  -H "X-Api-Key: YOUR_API_KEY"

Query parameters

Parameter	Type	Description
type	"idv" | "kyc" | "share"	Filter by verification type
status	string	Filter by status. Accepts comma-separated values: initiated,in_progress
clientId	string (UUID)	Filter by client
matterId	string (UUID)	Filter by matter
search	string	Search by subject name or email
dateFrom	string (ISO 8601)	Filter verifications created on or after this date
dateTo	string (ISO 8601)	Filter verifications created on or before this date
sort	"created_at" | "updated_at" | "status"	Sort order (default: created_at desc)
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)

Available statuses: initiated, in_progress, submitted, pending_review, approved, rejected, canceled, expired

Response 200

{
  "data": [
    {
      "id": "req_01j9abc123",
      "type": "idv",
      "status": "pending_review",
      "subjectName": "Jane Smith",
      "createdAt": "2025-04-05T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

---

GET /verifications/:id

Get a verification with full assembled detail including step data, scores, and decisions.

curl https://api.athenty.com/v2/api/verifications/req_01j9abc123 \
  -H "X-Api-Key: YOUR_API_KEY"

Returns the fully assembled verification object including identity, documents, biometrics, location, score, and review decisions.

---

POST /clients

Create a new client record in your organization.

curl -X POST https://api.athenty.com/v2/api/clients \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nameFirst": "Jane",
    "nameLast": "Smith",
    "email": "jane@example.com",
    "memberType": "individual",
    "country": "CA"
  }'

Request body

Field	Type	Required	Description
nameFirst	string	—	First name
nameLast	string	—	Last name
businessName	string	—	Business name (for memberType: "business")
email	string	—	Email address
phone	string	—	Phone number
externalId	string	—	Your internal system ID for this client
memberType	"individual" | "business"	—	Default: individual
addressLine1	string	—
addressLine2	string	—
city	string	—
region	string	—	Province / state
postalCode	string	—
country	string (ISO 3166-1 alpha-2)	—	Default: CA
metadata	object	—	Arbitrary key-value pairs for your own reference

Response 201

{
  "id": "clt_01j9abc456",
  "orgId": "org_01j9abc000",
  "nameFirst": "Jane",
  "nameLast": "Smith",
  "email": "jane@example.com",
  "memberType": "individual",
  "country": "CA",
  "active": true,
  "requestCount": 0,
  "createdAt": "2025-04-05T12:00:00.000Z"
}

---

GET /clients

List client records for your organization.

curl "https://api.athenty.com/v2/api/clients?search=jane&limit=25" \
  -H "X-Api-Key: YOUR_API_KEY"

Query parameters

Parameter	Type	Description
search	string	Search by name, email, or externalId
memberType	"individual" | "business"	Filter by member type
active	"true" | "false"	Filter by active status
sort	"name" | "created_at" | "request_count"	Sort order
page	integer	Page number
limit	integer	Results per page

---

GET /clients/:id

Get a single client record.

curl https://api.athenty.com/v2/api/clients/clt_01j9abc456 \
  -H "X-Api-Key: YOUR_API_KEY"

---

Pagination

All list endpoints return a consistent pagination envelope:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Use page and limit query parameters to navigate pages.

---

Rate limits

Plan	Rate limit
Professional	200 requests / minute
Business	200 requests / minute
Enterprise	Custom — contact us

Exceeded requests return 429 Too Many Requests with a Retry-After header (seconds until the next window resets).

---

Error responses

All errors return a JSON body with code, message, and statusCode:

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API key.",
  "statusCode": 401
}

Status	Code	Meaning
400	BAD_REQUEST	Malformed request
401	UNAUTHORIZED	Missing or invalid API key
402	PAYMENT_REQUIRED	Subscription inactive
403	FORBIDDEN	Plan does not include API access
404	NOT_FOUND	Resource not found or does not belong to your organization
422	VALIDATION_ERROR	Request body failed validation — errors array included
429	RATE_LIMITED	Too many requests

Validation error shape

{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "statusCode": 422,
  "errors": [
    { "field": "type", "message": "Required" },
    { "field": "requirements", "message": "Array must contain at least 1 element(s)" }
  ]
}

---

Webhook events

Subscribe to real-time events to avoid polling the API. See the Webhooks settings page for full webhook setup, payload structure, and signature verification.

Event	Triggered when
verification.created	A new verification is created
verification.submitted	The subject completes all verification steps
verification.approved	An operator approves the verification
verification.rejected	An operator rejects the verification
verification.canceled	A verification is canceled
verification.expired	A verification reaches its expiry date
client.created	A new client is created
client.updated	A client record is updated
client.deleted	A client record is soft-deleted

Deprecated alias events

For backward compatibility, every verification.* event above is also delivered as the deprecated request.* equivalent (e.g. request.created, request.approved). Both names are signed and dispatched for the same underlying event. Subscribe to the verification.* names in new integrations — the request.* aliases will be removed no sooner than api@2.19.0.

All webhook payloads are signed with X-Athenty-Signature (HMAC-SHA256). Always verify the signature before processing.

---

Deprecated aliases

The following legacy URL paths remain active and return identical responses to their canonical counterparts. They are retained so that existing integrations continue to work during the transition window.

Deprecated path	Canonical path
POST /requests	POST /verifications
GET /requests	GET /verifications
GET /requests/:id	GET /verifications/:id

The aliases will be removed no sooner than api@2.19.0. Please update your integrations to use /v2/verifications/* at your next release cycle. You may need to recreate webhook subscriptions that still filter on request.* event names — the verification.* names are the canonical replacements.

---

OpenAPI spec

Download the machine-readable OpenAPI 3.1 spec for use with Postman, Insomnia, or SDK generation tools:

openapi.yaml

---

Need help integrating? Contact us or book a demo and our team will walk you through your specific use case.