API Quickstart

In this section, you'll find a step-by-step guide to quickly start using the Core API.

Overview TL;DR

Content Management

Content built using global and/or client-specific blocks.
Permissions at page and block levels.
In-page real-time analytics.
Page categorisation, publishing dates, and templating for easy page creation.
ElasticSearch indexing for pages, posts, and PDFs.
Embedded YouTube, Vimeo, Wistia, and Brightcove videos using custom video widget.
Typeform surveys easily embedded.

Authentication & Permissions

Site authentication: Public, single login, individual user registration, SAML2.0 SSO.
User permissions using key->value operations, applied manually or automatically.
Zones to segment pages, file libraries, and users (e.g., global sites with country-specific content).
Multilingual support with in-page and global translation capabilities.
Outgoing SAML2.0 SSO connections to third-party vendors.

User Management & Engagement

Email campaigns segmented by user permission groups.
Automated email campaigns with real-time dispatch metrics.
User notifications displayed based on permissions.
Contact forms with automated user data prefill.
Dashboard with monthly reports on usage, users, and site activity.

File & Data Handling

File library with permissions at folder/file levels.
Decision manager for transaction records, feedback forms, and email confirmations.
User management including admin tools, audit trails, and analytics.
User onboarding surveys to personalise content based on user preferences.
Admin user segmentation for delegated access levels.
User collections for structured data uploads and automated processing.
Automation of demographic data feeds via SFTP.
API integrations with third-party providers.

Prerequisites

API access with a consumer-specific tenant-id, consumer-id, and x-service-provider. Contact matt_dixon@ajg.com if these are not known.
A mechanism for generating x-service-request-hash. For Angular projects utilising core-frontend, the API interceptor will auto-generate this hash on each API request.
A tool such as Postman, or a programming environment (e.g., Angular) to send API requests.

Versioning & Deprecation

Versioning: Managed at a global release level only.

Authentication

Where non-public requests are to be consumed, the Core API supports multiple authentication methods for individual or segmented audiences. Where a tenant is configured to have private access, a common approach is via username-password authentication.

To authenticate, make a POST request to the authentication endpoint:

curl -X POST "https://dev.servicegateway.io/auth" \
     -H "Content-Type: application/json" \
     -H "tenant-id: your-tenant-id" \
     -H "consumer-id: your-consumer-id" \
     -H "x-service-provider: your-service-provider" \
     -H "x-service-request-hash: your-service-request-hash" \
     -d '{
           "username": "your-username",
           "password": "your-password"
         }'

Response:

{
  "id": "your-user-id",
  "username": "your-username",
  "status": "your-status",
  "zone": "your-zone-id"
}

Response Headers:

x-service-user-name: your-tokenised-username
x-service-user-token: your-user-token

Use x-service-user-name and x-service-user-token from the response headers in subsequent requests by including them in the headers:

x-service-user-name: your-tokenised-username
x-service-user-token: your-user-token

Making Your First Request

Below is an example of making a GET request to retrieve a list of pages from the API.

Generate x-service-request-hash

generateRequestHashExample(req: HttpRequest<any>): string {
  const requestUrl = `${req.urlWithParams}`;
  let hashArgs: string[];
  if (req.method.substring(0, 3) === 'GET') {
      hashArgs = [requestUrl, String(this.getCookie('x-service-user-token'))];
  } else {
      hashArgs = [requestUrl, (req.body ? JSON.stringify(req.body) : ''), String(this.getCookie('x-service-user-token'))];
  }
  return SHA1(hashArgs.join('')).toString();
}

GET /pages HTTP/1.1
Host: dev.servicegateway.io
x-service-user-name: your-tokenised-username
x-service-user-token: your-user-token
x-service-provider: your-service-provider
x-service-request-hash: your-service-request-hash
tenant-id: your-tenant-id
consumer-id: your-consumer-id

Response:

{
  "pages": [
    {
      "id": 1,
      "title": "Welcome Page",
      "url": "welcome"
    },
    {
      "id": 2,
      "title": "About Us",
      "url": "about"
    }
  ]
}

Response Handling

The API returns standard HTTP response codes. Some common ones include:

200 OK – Successful request.
400 Bad Request – Invalid request parameters.
401 Unauthorized – Missing or incorrect authentication.
404 Not Found – Resource not found.
418 Multi-factor Authentication Required – User needs to complete MFA.

API Usage Tips

Always include the required headers (tenant-id, consumer-id, x-service-provider, and x-service-request-hash).
Implement error handling to manage different response statuses effectively.
Paginate results when retrieving large datasets.

Refer to the API Reference for in-depth API details.

01 September 2026