Skip to main content

Getting Started

The developer API enables server-side integrations to work with services provided through NeonNow. The generated reference documents available resources, request fields, and response schemas. See Authentication for authentication requirements.

Environments and Base URLs​

Each environment has its own API base URL and credentials. Production credentials must only be used with the production base URL. Credentials and data from a non-production environment do not carry over to production.

Each API's base URL follows the pattern {service}.{region}.cw-neon.com, where {service} identifies the API and {region} is the deployment region. The base URL, including the regions available for that API, is shown in the selector at the top of each API reference, and is authoritative. An integration should keep the base URL in environment-specific configuration rather than embedding it in application code.

Requests use HTTPS and append the operation path from the reference to the base URL. For example:

https://{service}.{region}.cw-neon.com/rest/v1/{organisationId}/keys

Replace the {service} and {region} tokens, and path parameters such as {organisationId}, with their actual values and do not include the braces.

Finding the Path Parameter IDs​

Nearly every operation includes two identifiers as path parameters. Both are read from the NeonNow Admin app.

  • Organisation ID (organisationId): the Admin app URL has the form .../o/{ID}. Sign in to the NeonNow Admin app and copy the ID segment that follows /o/ in the URL.
  • Contact centre ID (contactCenterId): the Admin app lists contact centres in a table with a CX contact centre column. Read the ID from that column for the contact centre the request targets.

These two values fill the {organisationId} and {contactCenterId} path segments in the API URLs.

Versioning​

The API version appears in the request path, for example rest/v1. Changes that break existing integrations are introduced under a new major path version. Compatible fields and operations can be added to the current version, so clients should ignore response fields they do not recognise.

An integration should pin requests to the documented version and review release information before moving to a newer major version.

Authentication​

The API uses two authentication models, and which one applies depends on the endpoint:

  • The API key management endpoints take a bearer token copied from an active NeonNow Admin app session. See Admin session bearer token.
  • Scope-gated service endpoints use an API key exchanged for a short-lived access token. See API key and access token.

In both cases the token is sent in the Authorization header:

Authorization: Bearer TOKEN

Credentials must be stored in a server-side secret manager and must never be embedded in browser code, mobile applications, source control, or logs. For a full explanation of both models, see Authentication.

Read the API Reference​

The reference is organised by product, resource group, and operation:

  1. Select a product in the sidebar.
  2. Choose an operation under its resource group.
  3. Check the method and path, required path or query parameters, and request body.
  4. Expand the response and schema sections to see fields, types, and status codes.
  5. Use the request examples as templates, replacing all example identifiers and credentials.

The reference is rendered for documentation only. It does not send live requests. Calls should be made from the integration's server using the base URL for its environment.

Operational Expectations​

Integrations should apply timeouts, retry transient failures with exponential backoff, and avoid retrying validation or authentication failures without first correcting the request. A 429 response indicates that the caller should reduce its request rate and honour any retry guidance in the response.

Secrets should be rotated regularly. If a secret may have been exposed, revoke or delete it immediately and create a replacement.