Overview

The Adcyma API lets you create, update, look up, and offboard Entra ID users from your own systems.

Base URL: https://api.adcyma.com
Path prefix: /v1/api
Content type: application/json

All endpoints are mounted under the path prefix above. For example, the create-user endpoint is at https://api.adcyma.com/v1/api/user.

Authentication

Every request (except the health check) must include three headers:

• X-Company-ID: Your tenant identifier. You can find this under Settings > Company profile in Adcyma.
• X-Api-User: The username of an active API user from your tenant.
• X-Api-Key: The secret key paired with that API user.

API users and keys are managed in the System Users section of your Adcyma portal. The key is only shown once when you create it. Store it somewhere safe. If you lose it, generate a new one and revoke the old.

Example headers

X-Company-ID: AcmeAB-1f2c8a90
X-Api-User: integrations-bot
X-Api-Key: <your-secret-key>
Content-Type: application/json

Response envelope

Successful responses wrap the payload in a data object:

{
  "data": {
    "message": "User creation queued successfully"
  }
}

Errors come back in a consistent shape:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Missing required field: userPrincipalName"
  }
}

The HTTP status code matches the error code:

HTTP status	code	When it happens
400	BAD_REQUEST	A required field is missing, or a value fails validation.
401	UNAUTHORIZED	API credentials are missing, mistyped, or belong to a disabled API user.
404	NOT_FOUND	The user you referenced does not exist in your tenant.
429	RATE_LIMIT_EXCEEDED	You hit one of the rate limits described below.
500	INTERNAL_ERROR	Unexpected server-side error. Safe to retry after a short wait.

Rate limits

Limits are evaluated on a 60-second sliding window. When you hit a limit, the response is 429 RATE_LIMIT_EXCEEDED. Wait for the window to clear and retry.

Scope	Default limit	Notes
Per IP	200 requests / min	Counted across all tenants behind the same IP.
Per tenant	100 requests / min	Counted per X-Company-ID.
Failed auth	10 attempts / min	Per tenant. Triggered by missing or wrong X-Api-User / X-Api-Key.

Request body limits

• The maximum JSON request body is 16 KB. Larger payloads are rejected before they reach the route.
• All authenticated endpoints expect a JSON body (or query string on GET). Always send Content-Type: application/json.

Health check

One unauthenticated endpoint is available for uptime monitoring.

Endpoint: /v1/api/health
Method: GET
Description: Returns 200 OK when the API is running. Useful for liveness probes and external monitors.

Success Response (200 OK):

{
  "data": {
    "status": "ok"
  }
}