Evident Labs

AtteStaff API

External API integration contract.

Versioned clinician validation, async bulk jobs, scoped API keys, and stable response shapes for customer integrations.

Authentication

Use organization-scoped API keys from `/api-keys`. Send keys with `Authorization: Bearer ats_live_...` or `x-api-key`.

Versioning

Public routes live under `/api/v1`. Dashboard routes are internal and should not be treated as an API contract.

Rate Limits

Single validation: 60/hour. Bulk jobs: 5/hour. Bulk jobs accept up to 100 NPIs.

Scopes

validate:writeCall POST /api/v1/validate.Live
bulk:writeCreate async bulk jobs.Live
jobs:readPoll jobs and download job results.Live
reports:readDownload JSON and CSV report artifacts.Live
rosters:read/writeList, create, update, and delete rosters.Live

Single Validation

POST /api/v1/validate
Authorization: Bearer ats_live_...
Content-Type: application/json

{
  "npi": "1234567890"
}
{
  "request_id": "req_...",
  "status": "ok",
  "result": {
    "provider": {},
    "nppesProfile": {},
    "cmsEnrollment": {},
    "compliance": {},
    "activityPrediction": {},
    "webEvidence": [],
    "warnings": []
  }
}

Async Bulk Jobs

POST /api/v1/bulk
Authorization: Bearer ats_live_...
Content-Type: application/json

{
  "npis": ["1234567890", "1098765432"]
}
{
  "request_id": "req_...",
  "job_id": "job_...",
  "status": "queued",
  "summary": null,
  "npi_count": 2,
  "result_url": null,
  "report_urls": null
}

Polling And Results

GET /api/v1/jobs/job_...
Authorization: Bearer ats_live_...
GET /api/v1/jobs/job_.../result
GET /api/v1/jobs/job_.../result?format=csv
GET /api/v1/reports/job_abc123.json
GET /api/v1/reports/job_abc123.csv

Roster Management

GET /api/v1/rosters
POST /api/v1/rosters
GET /api/v1/rosters/roster_...
PUT /api/v1/rosters/roster_...
DELETE /api/v1/rosters/roster_...
{
  "name": "Monthly pediatric roster",
  "npis": ["1962772541", "1164699773"]
}

Error Shape

{
  "request_id": "req_...",
  "status": "error",
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please try again later."
  }
}
api_key_requiredNo API key was sent.401
api_key_invalidKey is invalid, revoked, or expired.401
api_key_scope_deniedKey lacks the required scope.403
invalid_requestInput was invalid.400
rate_limitedRate limit exceeded.429
job_not_completeJob result is not ready.409

Client Workflow

  1. Create an organization-scoped API key.
  2. Use `POST /api/v1/validate` for one clinician.
  3. Use `POST /api/v1/bulk` for multiple clinicians.
  4. Poll `GET /api/v1/jobs/:id` until complete.
  5. Download JSON or CSV results from `GET /api/v1/jobs/:id/result`.
  6. Store `request_id` and `job_id` for support.