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 User Permissions section of your Adcyma portal (create a user with the API role). The key is only shown once when you create it. Store it somewhere safe. If you lose it, create a new API user and delete the old one.

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.
403	FORBIDDEN	The action is not allowed, for example when your seat limit is reached.
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 for most endpoints. The /v1/api/user endpoint accepts up to 6 MB to allow a base64-encoded profile photo.
• 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"
  }
}