Enterprise v1

Aram REST API

Automate your hiring pipeline. Push JDs from your ATS, pull match results into your HRIS, or build custom dashboards — all programmatically.

https://api.scootsign.com/api/v1 Get API Key →

Overview

The Aram Enterprise API gives you full programmatic access to your hiring data. Integrate with your existing ATS, HRIS, or internal tools to automate your recruitment pipeline.

API Key Auth

SHA-256 hashed keys with granular scopes. Never stored in plaintext.

Rate Limited

1,000 requests/hour per key. Configurable per enterprise tenant.

JSON REST

Standard REST with JSON request/response bodies. Paginated list endpoints.

Authentication

All API requests require an X-API-Key header. API keys are scoped to a tenant and can have granular permissions.

Request 
curl https://api.scootsign.com/api/v1/whoami \
  -H "X-API-Key: aram_ent_a1b2c3d4e5f6..."

Important: API keys are shown only once when created. Store them securely in your environment variables or secrets manager. Keys are SHA-256 hashed before storage — we cannot recover lost keys.

Rate Limits

Each API key is limited to 1,000 requests per hour by default. Enterprise tenants can request higher limits.

Header Description
X-RateLimit-Limit Max requests per hour
X-RateLimit-Remaining Remaining requests in current window
X-RateLimit-Reset Unix timestamp when the window resets

When rate limited, the API returns 429 Too Many Requests.

Scopes

API keys are scoped with granular permissions. Use broad scopes (read, write) or resource-specific scopes for least-privilege access.

Scope Description
read Read access to all resources (JDs, resumes, matches, candidates)
write Create and update resources
admin Manage API keys, full access
jd:read Read-only access to job descriptions
jd:write Create/update job descriptions
resume:read Read-only access to resumes
match:read Read-only access to AI match results
candidate:read Read-only access to candidate search

Authentication

POST /keys admin

Create an API key

Generate a new API key for your tenant. The full key is returned ONCE — save it immediately. Requires admin scope.

Request Body

{
  "name": "CI/CD Pipeline",
  "scopes": ["read", "write"],
  "expiresInDays": 90
}

Response

{
  "success": true,
  "data": {
    "id": "key_abc123",
    "name": "CI/CD Pipeline",
    "key": "aram_ent_a1b2c3d4e5f6...",
    "prefix": "aram_ent_a1b2",
    "scopes": ["read", "write"],
    "expiresAt": "2026-06-01T00:00:00.000Z",
    "warning": "Save this key now. It will not be shown again."
  }
}
GET /keys admin

List API keys

List all API keys for your tenant. Key values are never returned — only prefixes and metadata.

Response

{
  "success": true,
  "data": [
    {
      "id": "key_abc123",
      "name": "CI/CD Pipeline",
      "keyPrefix": "aram_ent_a1b2",
      "scopes": ["read", "write"],
      "isActive": true,
      "lastUsedAt": "2026-03-01T10:30:00.000Z",
      "usageCount": 1423
    }
  ]
}
DELETE /keys/:keyId admin

Revoke an API key

Permanently deactivate an API key. It can no longer be used for authentication.

Response

{ "success": true, "message": "API key revoked" }
GET /whoami any

Check API key identity

Returns the key's metadata, tenant info, scopes, and usage count. Useful for verifying your key works.

Response

{
  "success": true,
  "data": {
    "keyId": "key_abc123",
    "name": "CI/CD Pipeline",
    "prefix": "aram_ent_a1b2",
    "tenantId": "tenant_xyz",
    "tenant": "Acme Corp",
    "scopes": ["read", "write"],
    "rateLimit": 1000,
    "usageCount": 1423
  }
}

Job Descriptions

GET /jds read / jd:read

List job descriptions

Paginated list of JDs for your tenant. Optionally filter by status.

Query Parameters

?page=1&limit=20&status=PUBLISHED

Response

{
  "success": true,
  "data": [
    {
      "id": "jd_abc123",
      "title": "Senior Backend Engineer",
      "status": "PUBLISHED",
      "department": "Engineering",
      "location": "Remote",
      "experience": "5-8 years",
      "createdAt": "2026-03-01T09:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 42, "pages": 3 }
}
GET /jds/:jdId read / jd:read

Get a job description

Get full JD details including applications.

Response

{
  "success": true,
  "data": {
    "id": "jd_abc123",
    "title": "Senior Backend Engineer",
    "description": "We are looking for...",
    "status": "PUBLISHED",
    "department": "Engineering",
    "applications": [
      { "id": "app_1", "status": "SCREENING" },
      { "id": "app_2", "status": "SHORTLISTED" }
    ]
  }
}
POST /jds write / jd:write

Create a job description

Create a new JD in DRAFT status. Use the dashboard or API to publish it later.

Request Body

{
  "title": "Senior Backend Engineer",
  "description": "Build scalable APIs with Node.js and TypeScript...",
  "department": "Engineering",
  "location": "Remote",
  "experience": "5-8 years",
  "type": "full-time",
  "salary": "₹25-35 LPA",
  "requirements": "Node.js, TypeScript, PostgreSQL",
  "createdById": "user_abc123"
}

Response

{
  "success": true,
  "data": {
    "id": "jd_new123",
    "title": "Senior Backend Engineer",
    "status": "DRAFT"
  }
}

Resumes

GET /resumes read / resume:read

List resumes

Paginated list of parsed resumes for your tenant.

Query Parameters

?page=1&limit=20

Response

{
  "success": true,
  "data": [
    {
      "id": "res_abc123",
      "fileName": "john_doe_resume.pdf",
      "parseStatus": "COMPLETED",
      "metadata": { "skills": ["Node.js", "React"], "experience": "6 years" },
      "createdAt": "2026-03-01T09:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 156, "pages": 8 }
}
GET /resumes/:resumeId read / resume:read

Get a resume

Get full resume details including parsed metadata, skills, and experience.

Response

{
  "success": true,
  "data": {
    "id": "res_abc123",
    "fileName": "john_doe_resume.pdf",
    "parseStatus": "COMPLETED",
    "metadata": {
      "name": "John Doe",
      "email": "[email protected]",
      "skills": ["Node.js", "React", "PostgreSQL"],
      "experience": "6 years",
      "education": "B.Tech Computer Science"
    }
  }
}

AI Matching

GET /matches/:jdId read / match:read

Get AI match results

Get all applications for a JD with AI scores, ranked by score descending. Includes candidate name, email, and application status.

Response

{
  "success": true,
  "data": [
    {
      "applicationId": "app_1",
      "resumeId": "res_abc123",
      "candidate": "John Doe",
      "email": "[email protected]",
      "aiScore": 92.5,
      "status": "SHORTLISTED"
    },
    {
      "applicationId": "app_2",
      "resumeId": "res_def456",
      "candidate": "Jane Smith",
      "email": "[email protected]",
      "aiScore": 87.3,
      "status": "SCREENING"
    }
  ]
}

Candidates

GET /candidates read / candidate:read

Search candidates

Search across all resumes with their application history and AI scores. Useful for building custom dashboards.

Query Parameters

?page=1&limit=20&search=john

Response

{
  "success": true,
  "data": [
    {
      "id": "res_abc123",
      "fileName": "john_doe_resume.pdf",
      "parseStatus": "COMPLETED",
      "metadata": { "skills": ["Node.js", "React"] },
      "applications": [
        {
          "id": "app_1",
          "status": "SHORTLISTED",
          "aiScores": [{ "overallScore": 92.5 }],
          "jobDescription": { "id": "jd_abc123", "title": "Senior Backend Engineer" }
        }
      ]
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "pages": 1 }
}

Error Codes

Code Meaning
400 Bad Request — invalid or missing parameters
401 Unauthorized — missing or invalid API key
403 Forbidden — key does not have required scope
404 Not Found — resource doesn't exist or not in your tenant
429 Too Many Requests — rate limit exceeded
500 Internal Server Error — contact support

All error responses follow the format: { "success": false, "error": "description" }

Ready to integrate?

Enterprise API access is available on the Enterprise plan. Contact us or sign up to get started.

Get Started Contact Sales