{ "openapi": "3.1.1", "info": { "title": "NetworkAssist360 Integration API", "description": "Read-only, key-authenticated access to the N360 provider network: search providers with the same engine, scope and ranking the coordinator front end uses, read a provider record, the location briefs for a country, and the platform's vocabulary. Within v1 changes are additive only; anything breaking is v2 with v1 kept running for a stated period. Every timestamp is UTC ISO 8601 ending in Z. Errors are application/problem+json with a stable `code`.", "contact": { "name": "neo optic - NetworkAssist360", "url": "https://www.networkassist360.co.uk/" }, "version": "v1" }, "servers": [ { "url": "https://api.networkassist360.co.uk", "description": "Production" } ], "paths": { "/v1/providers/search": { "get": { "tags": [ "Providers" ], "summary": "Search the provider network", "description": "The same search engine, scope and ranking the coordinator front end uses: a coordinator and an integration asking the same question of the same network get the same providers in the same order. Every filter is optional; with none, the first page of the whole network the key may see. Distance filters need lat, lng and radiusKm together.", "operationId": "SearchProviders", "parameters": [ { "name": "lat", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "lng", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "radiusKm", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "subCategory", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "specialism", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "language", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "accessMethod", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } }, { "name": "text", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSearchResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/providers/{id}": { "get": { "tags": [ "Providers" ], "summary": "Read one provider record", "description": "Everything a search result carries plus contacts, accreditations, specialisms, payment terms and currencies, status, alert text and website - what the provider page shows an External User. Excluded on purpose: contract values and dates, internal notes, feedback comments, documents and the audit trail. A provider outside the key's scope answers 404, the same as an unknown id.", "operationId": "GetProvider", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiProviderDetail" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/countries/{iso2}/notes": { "get": { "tags": [ "Countries" ], "summary": "The location briefs for a country", "description": "The country-wide and category notes the network team maintains - as the integration's notes role would see them on the results page, most severe and most specific first. Add ?category= for the category-specific notes as well.", "operationId": "GetCountryNotes", "parameters": [ { "name": "iso2", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiCountryNote" } } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/lookups/{name}": { "get": { "tags": [ "Lookups" ], "summary": "The platform's vocabulary", "description": "One of: countries (with ISO alpha-2 codes), categories, subcategories (parentId = category), specialisms, languages, accessmethods. Use the ids in search filters so a form never hardcodes our vocabulary.", "operationId": "GetLookup", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiLookupItem" } } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "ApiAccreditation": { "required": [ "name", "description" ], "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "null", "string" ] } } }, "ApiAddress": { "required": [ "lines", "city", "postcode", "country", "countryCode" ], "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "string" } }, "city": { "type": [ "null", "string" ] }, "postcode": { "type": [ "null", "string" ] }, "country": { "type": [ "null", "string" ] }, "countryCode": { "type": [ "null", "string" ] } } }, "ApiContact": { "required": [ "role", "name", "telephone", "email", "isMain" ], "type": "object", "properties": { "role": { "type": [ "null", "string" ] }, "name": { "type": "string" }, "telephone": { "type": [ "null", "string" ] }, "email": { "type": [ "null", "string" ] }, "isMain": { "type": "boolean" } } }, "ApiCountryNote": { "required": [ "id", "title", "text", "severity", "categorySpecific", "roleSpecific" ], "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "title": { "type": [ "null", "string" ] }, "text": { "type": "string" }, "severity": { "type": "string" }, "categorySpecific": { "type": "boolean" }, "roleSpecific": { "type": "boolean" } } }, "ApiLocation": { "required": [ "lat", "lng" ], "type": "object", "properties": { "lat": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" }, "lng": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "number", "string" ], "format": "double" } } }, "ApiLookupItem": { "required": [ "id", "name" ], "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "name": { "type": "string" }, "code": { "type": [ "null", "string" ] }, "parentId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" } } }, "ApiPaymentTerms": { "required": [ "term", "methods", "currencies" ], "type": "object", "properties": { "term": { "type": [ "null", "string" ] }, "methods": { "type": "array", "items": { "type": "string" } }, "currencies": { "type": "array", "items": { "type": "string" } } } }, "ApiProviderDetail": { "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "name": { "type": "string" }, "categoryPath": { "type": [ "null", "string" ] }, "address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApiAddress" } ] }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApiLocation" } ] }, "switchboard": { "type": [ "null", "string" ] }, "languages": { "type": "array", "items": { "type": "string" } }, "accessMethods": { "type": "array", "items": { "type": "string" } }, "tier": { "type": [ "null", "string" ] }, "lastVerifiedUtc": { "type": [ "null", "string" ], "format": "date-time" }, "localTimeZone": { "type": [ "null", "string" ] }, "openingHoursText": { "type": [ "null", "string" ] }, "hasAlert": { "type": "boolean" }, "alertText": { "type": [ "null", "string" ] }, "status": { "type": [ "null", "string" ] }, "website": { "type": [ "null", "string" ] }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ApiContact" } }, "accreditations": { "type": "array", "items": { "$ref": "#/components/schemas/ApiAccreditation" } }, "specialisms": { "type": "array", "items": { "type": "string" } }, "paymentTerms": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApiPaymentTerms" } ] }, "ratingAverage": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "ratingCount": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" } } }, "ApiProviderSummary": { "type": "object", "properties": { "id": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "name": { "type": "string" }, "categoryPath": { "type": [ "null", "string" ] }, "address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApiAddress" } ] }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApiLocation" } ] }, "distanceKm": { "pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$", "type": [ "null", "number", "string" ], "format": "double" }, "switchboard": { "type": [ "null", "string" ] }, "languages": { "type": "array", "items": { "type": "string" } }, "accessMethods": { "type": "array", "items": { "type": "string" } }, "tier": { "type": [ "null", "string" ] }, "lastVerifiedUtc": { "type": [ "null", "string" ], "format": "date-time" }, "localTimeZone": { "type": [ "null", "string" ] }, "openingHoursText": { "type": [ "null", "string" ] }, "hasAlert": { "type": "boolean" } } }, "ApiSearchResponse": { "type": "object", "properties": { "total": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "page": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "pageSize": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "format": "int32" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ApiProviderSummary" } } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } } }, "securitySchemes": { "ApiKey": { "type": "http", "description": "Authorization: Bearer . Keys are issued by the N360 team on the Integrations screen and shown once. Server to server only - never put a key in browser code.", "scheme": "bearer", "bearerFormat": "n360_live_... or n360_test_..." } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "Providers" }, { "name": "Countries" }, { "name": "Lookups" } ] }