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 verification requests

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

Read request status

Retrieve the full assembled status of any verification request, 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/requests \
  -H "X-Api-Key: YOUR_API_KEY"

Getting your API key

1. Log in to Athenty Secure
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

Verification Requests

Method	Path	Description
POST	/requests	Create a new verification request
GET	/requests	List verification requests (paginated)
GET	/requests/:id	Get a request 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 /requests

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

curl -X POST https://api.athenty.com/v2/api/requests \
  -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 /requests

List verification requests for your organization. Results are paginated.

curl "https://api.athenty.com/v2/api/requests?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 requests created on or after this date
dateTo	string (ISO 8601)	Filter requests 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 /requests/:id

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

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

Returns the fully assembled request 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 Advanced Features guide for full webhook setup, payload structure, and signature verification.

Event	Triggered when
request.created	A new verification request is created
request.submitted	The subject completes all verification steps
request.approved	An operator approves the verification
request.rejected	An operator rejects the verification
request.canceled	A request is canceled
request.expired	A request 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

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

---

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.