Seshnova Partner API
Partner-facing contract for the Seshnova API Gateway REST API.
The public surface is the API Gateway/Lambda facade exposed to partners. All operations are JSON POST endpoints on the deployed API Gateway stage.
Post-call HTTPS callbacks and Flow Blocks delivery features are outside this Gateway contract. Contact Seshnova if you need those integration patterns.
Environment-specific connection details are issued during partner onboarding (not published on the public docs host).
Connection details
API hostname, AWS region, Cognito app client ID, and credentials are issued per partner during onboarding. They are not published on this public reference.
Public contract base URL for documentation:
https://api.seshnova.com
Balance
Balance read/write operations.
Usage
Read-only usage and billed call history.
Accounts
Account lifecycle and caller ID management.
Calls
Call setup operations.
Number Lookup
Allocation-only Number DB lookup operations.
Operations
POST /call_history
Recent billed call history for an account
Returns up to 10 most recent billed calls for the account within the last 30 days (UTC). Each row exposes called_number, duration_seconds, and amount_charged. Tenant is always taken from the JWT; product_id and currency in the JSON body take precedence over Cognito claims when present. Send currency explicitly when it is not on the token. Empty history returns 200 with an empty calls array.
Request body
{
"account": "123456789012",
"product_id": "prepaid_uk",
"currency": "GBP"
}Responses
200History retrieved (possibly empty).400Invalid request body, invalid idempotency key, tenant_id in body, or validation error.403Missing or invalid authorization, inactive membership, tenant inactive, or insufficient route permission.500Unexpected server error.
POST /change_cli
Change account caller ID
Updates the account external_user_id, also referred to as CLI or caller id. Clients may send either external_user_id or cli. If both are sent, they must match.
Request body
{
"account": "123456789012",
"product_id": "prepaid_uk",
"cli": "+441234567890"
}Responses
200CLI updated.400Invalid request body, invalid idempotency key, tenant_id in body, or validation error.403Missing or invalid authorization, inactive membership, tenant inactive, or insufficient route permission.404Requested account or resource was not found.409Business conflict such as duplicate external_user_id, or idempotency conflict.502The API could not complete an upstream dependency request.503A required internal dependency or Lambda configuration is unavailable.
POST /create_account
Create account
Creates a prepaid account for the authenticated tenant. This operation is idempotent by tenant, operation, and Idempotency-Key.
Request body
{
"product_id": "prepaid_uk",
"initial_balance": 0,
"requires_pin": true,
"external_user_id": "+441234567890"
}Responses
201Account created.400Invalid request body, invalid idempotency key, tenant_id in body, or validation error.403Missing or invalid authorization, inactive membership, tenant inactive, or insufficient route permission.409Business conflict such as duplicate external_user_id, or idempotency conflict.502The API could not complete an upstream dependency request.503A required internal dependency or Lambda configuration is unavailable.
POST /debit_balance
Debit monetary balance
Debits credit from an existing account. This operation is idempotent by tenant, operation, and Idempotency-Key.
Request body
{
"account": "123456789012",
"amount": 1.25,
"product_id": "prepaid_uk",
"currency": "GBP"
}Responses
200Balance debited.400Invalid request body, invalid idempotency key, tenant_id in body, or validation error.403Missing or invalid authorization, inactive membership, tenant inactive, or insufficient route permission.409Idempotency-Key has already been used with a different request body.500Unexpected server error.
POST /delete_account
Deactivate account
Soft-deletes or deactivates an account. This does not hard-delete account rows. Idempotent by tenant, operation, and Idempotency-Key.
Request body
{
"account": "123456789012",
"product_id": "prepaid_uk",
"reason": "customer requested closure"
}Responses
200Account deactivated, or already inactive.400Invalid request body, invalid idempotency key, tenant_id in body, or validation error.403Missing or invalid authorization, inactive membership, tenant inactive, or insufficient route permission.404Requested account or resource was not found.409Idempotency-Key has already been used with a different request body.502The API could not complete an upstream dependency request.503A required internal dependency or Lambda configuration is unavailable.
POST /get_balance
Get account balance
Returns the current monetary balance for a 12-digit account code. Tenant, product, and currency context are derived from the authenticated partner credential and authorizer claims.
Request body
{
"account": "123456789012",
"product_id": "prepaid_uk",
"currency": "GBP"
}Responses
200Balance found.400Invalid request body, invalid idempotency key, tenant_id in body, or validation error.403Missing or invalid authorization, inactive membership, tenant inactive, or insufficient route permission.404Requested account or resource was not found.500Unexpected server error.
POST /number_lookup
Look up a number allocation
Looks up allocation data for a number. This v1 endpoint is allocation-only: requests for live are rejected and no billed lookup source is called. Tenant scope and numberdb:lookup are resolved from the Cognito credential and the Portal permission record; tenant_id is never accepted in the body.
Request body
{
"number": "+442071234567",
"sources": [
"allocation"
],
"country": "GB"
}Responses
200Allocation lookup completed. A source can report no-match or an upstream error without turning the whole request into a 5xx response.400Invalid request body, invalid idempotency key, tenant_id in body, or validation error.403Missing or invalid authorization, inactive membership, tenant inactive, or insufficient route permission.429Soft per-tenant and per-credential request rate limit reached.502The API could not complete an upstream dependency request.503A required internal dependency or Lambda configuration is unavailable.
200 response example
{
"contract_version": "1.0",
"number": "442071234567",
"sources": {
"allocation": {
"status": "ok",
"data": {
"assignee_original_name": "Example Carrier"
},
"error": null
},
"live": {
"status": "skipped",
"data": null,
"error": {
"code": "SOURCE_NOT_REQUESTED",
"message": "Live network lookup was not requested"
}
}
},
"comparison": {
"both_sources_answered": false,
"ported_away_from_range_owner": null
},
"correlation_id": "partner-trace-123"
}POST /setup_call
Store number translation for a call
Stores a short-lived number translation for the calling path. The default partner contract is Cognito authorization plus Lambda partner RBAC. An API Gateway key gate is not part of the default partner contract.
Request body
{
"a_number": "+441234567890",
"b_number": "+442071234567",
"access_number": "+442038355820",
"account_number": "123456789012",
"ttl": 300,
"product_id": "prepaid_uk",
"currency": "GBP"
}Responses
200Call setup saved.400Invalid request body, invalid idempotency key, tenant_id in body, or validation error.403Missing or invalid authorization, inactive membership, tenant inactive, or insufficient route permission.409Idempotency-Key has already been used with a different request body.500Unexpected server error.
POST /topup
Add monetary balance
Adds credit to an existing account. This operation is idempotent by tenant, operation, and Idempotency-Key.
Request body
{
"account": "123456789012",
"amount": 10.0,
"product_id": "prepaid_uk",
"currency": "GBP"
}Responses
200Balance added.400Invalid request body, invalid idempotency key, tenant_id in body, or validation error.403Missing or invalid authorization, inactive membership, tenant inactive, or insufficient route permission.404Requested account or resource was not found.409Idempotency-Key has already been used with a different request body.500Unexpected server error.