Skip to main content

Access Synergy Citizen Api Guide

This guide explains how to use the Citizen API endpoint for creating or updating citizen records in Synergy.

Written by Asa MacLean

API Endpoint

Overview

This guide explains how to use the Citizen API endpoint for creating or updating citizen records in Synergy.

Licences

When calling this endpoint, the "(POR52) - Portal > Third Party API > Citizen" licence must be enabled.

Authentication

When calling this endpoint, a Synergy password user must be created and its credentials supplied.

Considerations:

  • The user should only have the permissions required to call the API endpoint. This approach follows security best practices by implementing the principle of least privilege.

  • A unique user should be created for each purpose or integration.

  • The user's password should be periodically rotated.

  • Use HTTPS to transmit the user's credentials securely.

For example:

  • Open the Synergy (Desktop) Client.

  • Navigate to Security Manager > Security Groups.

    • Create a new security group.

    • Grant the General > Shared Security > Application Programming Interface > Citizen Details > Full Access permission.

    • Save.

  • Navigate to Security Manager > Users.

    • Create a new user.

    • Add the previously created security group to the user.

    • Save.

Endpoint Details

URL: /Api/ThirdParty/v1/Citizen
Method: POST

Note: The full URL will depend on your environment. For example, "https://example.com/Synergy/Api/ThirdParty/v1/Citizen".

Request Header

Accept: application/json
Content-Type: application/json
Authorization: Basic username:password

Note: For Basic Authentication *1 *2, replace username:password with your actual credentials encoded in Base64.

*1 RFC 7617 - The 'Basic' HTTP Authentication Scheme *2 HTTP authentication - HTTP | MDN

Request Body

The request body should be a Citizen JSON object containing all required personal and address information.

Matching Logic

Synergy identifies existing citizens based on:

  • AuthenticationTypeName: Specifies the Citizen's authentication method (e.g., "Password").

  • ExternalId: A unique identifier from the system being integrated.

If a match is found using a combination of these pieces of information, the existing record will be updated.

If no match is found, a new citizen record will be created.

Data Completeness

When sending data to the Citizen API endpoint, every request is treated as the complete and current representation of the citizen record:

  • All fields you include will overwrite existing values in Synergy.

  • Any fields you omit will be interpreted as deliberately empty and will clear existing values in Synergy.

For example, if no middle name is supplied (either by omitting the field entirely or including it with an empty value), then the API will interpret this as the citizen not having a known middle name and will remove any middle name that currently exists in their record.

Considerations:

  • Include all information you wish to preserve in each API call.

  • If you only want to update specific fields, you must first retrieve the current record and include all unchanged values in your update request.

Response Body

The following response codes can be expected:

  • 200 OK - The request was successful and a create or update was actioned.

  • 400 Bad Request - An invalid Citizen JSON object was supplied.

  • 401 Unauthorized - An invalid username or password was supplied. Alternatively, the API is not licenced.

  • 403 Forbidden - The supplied username does not have permission to the API endpoint.

  • 500 Internal Server Error - An unexpected server-side error occurred. Further information may be available in the environment logs.

Validation Error Responses

When the API returns a 400 Bad Request response, it includes a JSON body that details specific validation errors.

We advise providing meaningful logging or auditing during integration to aid troubleshooting.

Internal Server Error Responses

When the API returns a 500 Internal Server Error response, this indicates an unexpected issue occurred on the server side. These errors are automatically logged in the Synergy environment for administrator review.

Administrators can find detailed error information in:

  • Synergy (Desktop) Client > Environment Manager > Central Services > Logs.

  • Synergy (Desktop) Client > Environment Manager > Synergy Web > Logs.

Schemas

Citizen

Field

Type

Constraints

Validation

Required

AuthenticationTypeName

String

Maximum Length: 128

Lookup (Authentication method name) *3

Yes

ExternalId

String

Maximum Length: 800

Yes

Title

String

Maximum Length: 30

Lookup (Title) *4

Forename

String

Maximum Length: 35

Yes

Middlename

String

Maximum Length: 35

Surname

String

Maximum Length: 35

Yes

Email

String

Maximum Length: 256

Must be unique; Regular expression *1

Yes

Dob

DateTime

Date

(Must be between 01/01/1900 and Today)

DaytimeNumber

String

Maximum Length: 35

Regular expression *2

MobileNumber

String

Maximum Length: 35

Regular expression *2

EveningNumber

String

Maximum Length: 35

Regular expression *2

Address

Citizen Address

Yes

*1 Email regular expression pattern: ^[^\s@]+@[^\s@]+\.[^\s@]+$

*2 Phone number regular expression pattern: ^[0-9- +][0-9- ]{0,34}$

*3 Synergy Desktop Client > Security Manager > Authentication Methods.

*4 Synergy Desktop Client > System Manager > Lookup Editor > (search) Title. Note - Title is not required for the citizen account to be created. However, the Admissions application process does require this value, and users will be prompted to supply it when making an application. It is therefore recommended to always include Title.

Citizen Address

Field

Type

Constraints

Primary

String

Maximum Length: 100

Secondary

String

Maximum Length: 100

Street

String

Maximum Length: 100

Locality

String

Maximum Length: 100

Town

String

Maximum Length: 100

County

String

Maximum Length: 100

Postcode

String

Maximum Length: 8 Postcode (Regular Expression *1) Required

Northing *2

String

Maximum Length: 8 IsInteger (Must be a valid Int32, however can have proceeding zeros)

Easting *2

String

Maximum Length: 8 IsInteger (Must be a valid Int32, however can have proceeding zeros)

ManualAddress

Boolean

Uprn

Int64

Maximum Digits: 12

LEA

String / Int

Maximum Length: 3 Must be a 3 digit number Lookup value against LA lookup list *3

*1 Postcode regular expression pattern: ^(?:BFPO [1-3]{3}|(?:[A-Z]\d\d?|[A-Z][A-Z]\d\d?|[A-Z]?[A-Z]\d[A-Z])\s?\d[A-Z][A-Z])$

*2 Northing and Easting are required for distance based Citizen searching e.g. when searching and selecting schools during school admissions applications.

*3 The supplied value must be a valid LA code as per the lookup list managed in Synergy. The codes are expected to align with the CBDS list.

Supporting Configuration

System Options

When integrating Citizen information with another system, consider the following system options.

These can be configured in the Synergy (Desktop) Client under System Manager > Options.

Option

Description

Synergy Web > Allow Citizen Account Creation

When disabled, Citizens cannot create password-based accounts via the web client login screen. Note: This setting does not prevent single sign-on (SSO) authentication methods from creating a Citizen account if one does not already exist. Recommendation: Disable this option when using Citizen-based SSO, unless both SSO and password-based accounts are required.

Synergy Web > Prompt Citizen for Details on First Sign In

When disabled, Citizens are not prompted to provide additional details on their first sign-in to Synergy. Recommendation: Disable this option if "Make Core Citizen Details Read-Only" is enabled, as most details will be read-only.

Synergy Web > Make Core Citizen Details Read-Only

When enabled, information that can be provided to the Citizen API is read-only for the Citizen in Synergy. Recommendation: Enable this option to prevent Citizens from making changes that may be overwritten by the API.

Synergy Web > Allow Child to have different address to Citizen

When disabled, a child cannot have a different address from their parent. Recommendation: Disable this option if you require that Admissions or other child applications always use the Citizen's address.

Global Settings

When integrating Citizen information with another system, consider the following settings.

These can be configured in the Synergy Web (Client) under Administration > Global Settings.

Option

Description

Validate child addresses are in the home LA

When set to "Off", child applications will be allowed for any child address. Recommendation: Set this setting to "Round", and ensure that the Admissions round level option for Home LA validation is set to Error / Warn / Off accordingly.

System Lookups

When integrating Citizen information with Synergy, it is essential to ensure that any lookup values are synchronized between the integrating system and Synergy. Synergy enforces validation on reference information, and any values provided by the integrating system must match the valid options configured within Synergy.

These can be configured in the Synergy (Desktop) Client under System Manager > Lookup Editor.

Lookup name

Title

Local Authority

Related Articles
Did this answer your question?