Skip to main content

NG-SOS API

The NG-SOS API is hosted by NG-SOS and called by partner systems. It provides operations for submitting emergency call notifications, working with existing incidents, coordinating collaboration between agencies, and reading agency information.

This is the inbound half of an integration:

  • Partner → NG-SOS: use the API described on this page.
  • NG-SOS → Partner: implement the NG-SOS Connector to receive incident data and updates.

Use the base URL supplied for your environment during onboarding. Requests and responses use JSON unless an operation states otherwise. The complete request and response schemas are in the API Reference.

Choose the correct API area​

AreaPurpose
AgencyIdentify the agency represented by an access token and list agencies configured for collaboration.
CallCreate and update an external emergency call notification. A call notification is not an incident.
IncidentUpdate or activate features on an existing incident.
Incident collaborationRequest, accept, or reject agency collaboration on an existing incident.

Authentication​

Partner server applications​

Most partner integrations use a Bearer access token issued by the NG-SOS Identity Server. Follow the Identity Server guide for the complete token flow, token response, error handling, and user-context tokens.

During onboarding, NG-SOS supplies:

  • client_id
  • client_secret
  • allowed scopes
  • allowed agency IDs
  • environment-specific API base URLs

Request the token from POST https://identity.ng-sos.com/connect/token using the client_credentials grant and application/x-www-form-urlencoded data:

curl --request POST "https://identity.ng-sos.com/connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \
  --data-urlencode "scope=YOUR_REQUIRED_SCOPES" \
  --data-urlencode "psap_id=YOUR_AGENCY_ID"

Include psap_id when calling Agency, Call, Incident, or Incident collaboration operations. The resulting token contains the agency context used to identify the agency and authorize access to incidents. Request a separate token for each agency context.

Send the access token with each request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Cache the token until shortly before its expires_in time. Do not request a new token for every API call.

Caller interaction, incident field updates, and incident collaboration require a user-context token containing the agency and a concrete NG-SOS user. Closing an incident requires only PSAP context. See Request a user-context token.

Agency​

Get agency information​

GET /agency/info resolves the psap_id context from the Bearer token and returns:

  • the agency ID, display name, and emergency service type;
  • agencies configured as available collaboration targets.

Use this operation after obtaining a token to verify that the application is acting for the intended agency. The relatedAgencies collection can also populate agency choices when requesting collaboration.

curl --request GET "$EMS_BASE_URL/agency/info" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

Call​

The Call API receives call metadata from an external call or emergency-data source. It maintains a call notification identified by a CallNotificationId.

It does not create an NG-SOS incident and it does not activate caller chat, location, or live video.

Create a call notification​

POST /v1/call/create records:

  • caller phone number;
  • owner agency;
  • call start time and optional end time;
  • latest caller position;
  • call notification source.

The response is the call notification identifier. Keep this identifier for later updates.

The implementation treats a notification with the same caller number, start time, and owner agency as the same call and returns its existing identifier.

Update a call notification​

PUT /v1/call/update updates the latest caller position and, when supplied, records the call end time. The end time is set only while the call is still open.

Use the identifier returned by the create operation. Call updates are separate from Incident updates.

Incident​

Incident operations act on an incident that already exists. The {id} path value is the incident UUID, not a call notification identifier.

Before changing an incident, NG-SOS verifies that the agency from the token has access to it. Depending on the authenticated user, access is derived from the agency configuration or from incident IDs explicitly allowed by the token.

MethodEndpointActual effect
POST/v1/incident/{id}/caller-nameReplaces the caller name stored on the incident.
POST/v1/incident/{id}/manual-caller-positionAdds a dispatcher-supplied WGS84 position with source Manual.
POST/v1/incident/{id}/locate-callerSends the caller an SMS link to a web page that obtains the device location and submits it to the incident.
POST/v1/incident/{id}/activate-chatCreates and assigns a chat, then sends the caller an SMS link for the web chat.
POST/v1/incident/{id}/activate-live-videoInitializes a live-video session and returns its VideoId.
POST/v1/incident/{id}/call-signReplaces the incident call sign.
POST/v1/incident/{id}/incident-labelReplaces the incident label.
POST/v1/incident/{id}/dispatcher-noteReplaces the dispatcher note.
POST/v1/incident/{id}/closeMarks the incident as closed.

Caller interaction​

locate-caller sends the caller a link to an NG-SOS web page. When the caller opens the page and grants location access, it obtains the device location and submits it to NG-SOS so the agency can locate the caller. This flow operates independently of chat.

activate-chat creates the incident chat and sends the caller a link that opens the NG-SOS web application.

activate-live-video first initializes a video session. When supported, NG-SOS attempts to request EED live video from a capable caller phone number. Otherwise it creates a web-app live-video session. If that fallback does not yet have a chat, chat is activated automatically so the caller can receive the web link.

Incident collaboration​

Collaboration adds another agency to an existing incident through an explicit request and response workflow.

MethodEndpointActual effect
PUT/v1/incident/{id}/request-collaborationCreates a collaboration request for the psapId supplied in the body.
POST/v1/incident/{id}/accept-collaborationAccepts the pending request for the agency represented by the token.
POST/v1/incident/{id}/reject-collaborationRejects the pending request for the agency represented by the token.

The requesting agency must already have access to the incident. Accept and reject operate for the authenticated agency; the target agency is therefore not supplied in those request bodies.

Use GET /agency/info to obtain the agencies configured for collaboration rather than maintaining a separate hard-coded agency list.

Positions and timestamps​

Coordinates use WGS84 latitude and longitude. Position accuracy and altitude values are expressed in meters. captureAtUtc is the time at which the source captured the position, not the time at which NG-SOS received it.

Send timestamps as ISO 8601 UTC values, for example:

2026-07-16T10:30:00Z

Responses and errors​

Successful mutation operations normally return 200 OK. Create Call and Activate Live Video return their created identifiers in the response body.

Error response bodies follow the native endpoint and ASP.NET Core behavior. Use the HTTP status and the exact operation responses in the API reference rather than depending on one shared error-body shape. Typical responses include:

StatusMeaning
400 Bad RequestThe request is invalid or conflicts with the current domain state.
401 UnauthorizedAuthentication is missing or invalid, the required token context is absent, or the agency cannot access the incident.
403 ForbiddenThe token does not satisfy an authorization policy required by the operation.
404 Not FoundThe referenced domain object does not exist.
415 Unsupported Media TypeA JSON operation was called with an unsupported content type.
500 Internal Server ErrorAn unexpected server error occurred.

Use the exact operation schemas and documented responses from the API Reference.

For a server-to-server agency integration:

  1. Obtain credentials, allowed scopes, agency IDs, and environment URLs from NG-SOS.
  2. Follow the Identity Server guide to request a Bearer token.
  3. Call GET /agency/info to verify the token's agency context.
  4. Implement only the API areas agreed during onboarding.
  5. Implement the NG-SOS Connector when NG-SOS must deliver incidents and updates to your system.
  6. Cache tokens and use the OpenAPI contract to generate or validate your client.

For credentials or technical support, contact mdybal@medicalit.eu.