API Reference v1

Ayla API

The Ayla API is a set of REST endpoints that expose the intelligence stack to your application. All endpoints return JSON. Authentication is via bearer token. Base URL: https://api.ayla.ai/v1

Authentication

Include your API key in every request as a bearer token in the Authorization header.

Authorization: Bearer ayla_live_sk_xxxxxxxxxxxxxxxxxxxx

API keys are scoped per environment. Use ayla_test_sk_ keys for sandbox and ayla_live_sk_ for production. Keys are generated in the developer dashboard.

POST /v1/analyze

Score a message for fraud risk before dispatch. Returns a fraud score between 0 (clean) and 1 (highly suspicious), and an action recommendation.

POST/v1/analyze

Request parameters

Parameter	Type	Description
sender_idrequired	string	The sender ID of the message (e.g. "GTBANKNG")
msisdnrequired	string	Recipient phone number in E.164 format
message_typerequired	string	One of: otp, transactional, promotional, alert
corridoroptional	string	Carrier corridor identifier (e.g. "MTN-NG")
volume_1hoptional	number	Messages sent from this sender in the past hour

Response

"fraud_score": 0.12,
"action": "ALLOW", // ALLOW | REVIEW | BLOCK
"signals_fired": ["velocity_nominal", "corridor_healthy"],
"latency_ms": 0.8,
"request_id": "req_01HVKQZT9XN4P2F8"

POST /v1/channel/decide

Get the optimal channel and route for a given message. Returns the recommended primary channel, route score, and failover chain.

POST/v1/channel/decide

Request parameters

Parameter	Type	Description
message_typerequired	string	One of: otp, transactional, promotional, alert
msisdnrequired	string	Recipient phone number in E.164 format
urgencyoptional	string	One of: high, medium, low. Default: medium
allowed_channelsoptional	array	Restrict to specific channels: ["sms","whatsapp","email"]

Response

"primary_channel": "sms",
"route_score": 0.94,
"action": "MAINTAIN", // MAINTAIN | FAILOVER | DEGRADE
"failover_chain": ["whatsapp", "email", "voice"],
"sla_risk": "LOW",
"request_id": "req_01HVKR2M8WJ5N9G1"

POST /v1/sender/verify

Run a Sender ID through the 3-layer verification pipeline: rules engine, Claude AI compliance check, and external registry lookup.

POST/v1/sender/verify

Request parameters

Parameter	Type	Description
sender_idrequired	string	The sender ID to verify (max 11 characters)
country_coderequired	string	ISO 3166-1 alpha-2 country code (e.g. "NG", "GH")
organisation_typeoptional	string	Hint for compliance engine: bank, fintech, telco, other

Response

"decision": "APPROVE", // APPROVE | REVIEW | REJECT
"confidence": 0.97,
"layers_passed": 3,
"reasoning": "Licensed financial institution. Registry match confirmed.",
"latency_ms": 210

GET /v1/carriers/health

Retrieve current health scores for all monitored carrier corridors. Useful for building dashboards or triggering application-level routing logic.

GET/v1/carriers/health

Query parameters

Parameter	Type	Description
countryoptional	string	Filter by country code (e.g. "NG")
min_scoreoptional	number	Return only corridors above this score threshold

Response

"corridors": [
  {
    "id": "MTN-NG",
    "composite_score": 0.96,
    "dlr_1h": 0.97,
    "sla_risk": "LOW"
  },
  { "id": "GLO-NG", "composite_score": 0.71, "sla_risk": "HIGH" }
]

Rate limits

Default rate limits by plan:

Plan	Requests/sec	Requests/day
Developer	10	10,000
Growth	100	500,000
Enterprise	Custom	Unlimited

Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset. Exceeded limits return HTTP 429.

Errors

All errors follow a consistent structure:

"error": {
  "code": "invalid_sender_id",
  "message": "Sender ID exceeds 11 characters",
  "status": 422,
  "request_id": "req_01HVKQZT9XN4P2F8"
}

Common status codes: 400 Bad request · 401 Unauthorized · 422 Validation error · 429 Rate limited · 500 Internal error