Introduction

The Zego API presets a simple RESTful interface for interacting with Zego for Partners and on behalf of Zego Customers. By providing a Zego Customer ID, or Partner Customer ID, Users of the API can request the Zego insured status of a Customer, notify Zego of a Customer starting work, and perform other actions.

Authentication

[...]
import requests

response = requests.get(
    f'https://api.zego.com/v1/user/status/?workProviderUserId=1234',
    headers={'Authorization': AUTHORIZATION_CODE},  # header value set as token
)

Authenticating with the API requires a token to be set as the AUTHORIZATION header value. The token can requested from your Zego Partnerships Manager.

Making requests

Some of the API methods require identification of a particular Zego customer. This can be done in one of two ways:

• customerNumber is a unique identifier that Zego assigns to each of its customers.
• workProviderUserId is an identifier assigned by the work provider to uniquely identify its users.

Zego can obtain this identifier during customer signup, and use it to identify that customer during communication with the applicable work provider.

Errors

When the API encounters an error with your request, it will respond with a HTTP status code in the 5xx or 4xx range and a JSON body with an error code and detail (if applicable or available) of the error that occurred.

Example error response body

{
  "error":"INVALID_DATA", 
  "detail": "JSON decode error at line 1, column 2" 
}

Shifts

Creates a shift object for a registered Zego Customer. login and logout represent the start and the end of a given period of time for which the Customer should be insured.

shift/login

The request body should contain JSON data in one of the following formats:

{"workProviderUserId": <WORK_PROVIDER_USER_ID>, "timestamp": <TIMESTAMP>},

OR

{"customerNumber": <CUSTOMER_NUMBER>, "timestamp": <TIMESTAMP>}

>>> Script (using workProviderUserId)

[...]
import requests
import datetime
from pytz import UTC

response = requests.post(
    'https://api.zego.com/v1/shift/login/',
    headers={'Authorization': AUTHORIZATION_CODE},
    json={
        'workProviderUserId': '1686',
        'timestamp': UTC.localize(datetime.datetime.utcnow()).isoformat()
    })

print('Response status code:', response.status_code)
print('Response body:', response.text)

<<< Output

Response status code: 202
Response body: {"status": "PENDING"}

Make sure to replace '1686' with your user's id.

Start an individual Customers's shift for the given CustomerNumber or WorkProviderUserId and timestamp.

Request

Method	URL
POST	v1/shift/login/

Type	Params		Values
HEAD	Authorization		String
POST	body		JSON (Object)
		customerNumber	String (optional)
		workProviderUserId	String (optional)
		[Deprecated] policyId	String (optional)
		[Deprecated] driverId	String (optional)
		timestamp	String (ISO-8601 with timezone)

Response

Status	Response
202	{"status":"PENDING"}
401	{ "error":"MISSING_AUTH", "detail": "Authorization header missing" }
401	{ "error":"INVALID_KEY", "detail": "Authorization key is invalid" }
400	{ "error":"INVALID_DATA", "detail": "JSON decode error at line 1, column 2" }

shift/logout

The request body should contain JSON data in one of the following formats:

{"workProviderUserId": <WORK_PROVIDER_USER_ID>, "timestamp": <TIMESTAMP>}

OR

{"customerNumber": <CUSTOMER_NUMBER>, "timestamp": <TIMESTAMP>}

>>> Script (using customerNumber)

[...]
import requests
import datetime
from pytz import UTC

response = requests.post(
    'https://api.zego.com/v1/shift/logout/',
    headers={'Authorization': AUTHORIZATION_CODE},
    json={
        'customerNumber': '1686',
        'timestamp': UTC.localize(datetime.datetime.utcnow()).isoformat()
    })

print('Response status code:', response.status_code)
print('Response body:', response.text)

<<< Output

Response status code: 202
Response body: {"status": "PENDING"}

Make sure to replace '1686' with your user's work provider user id.

Logs the given user out at the given timestamp.

Request

Method	URL
POST	v1/shift/logout/

Type	Params		Values
HEAD	Authorization		String
POST	body		JSON (Object)
		customerNumber	String (optional)
		workProviderUserId	String (optional)
		[Deprecated] policyId	String (optional)
		[Deprecated] driverId	String (optional)
		timestamp	String (ISO-8601 with timezone)

Response

Status	Response
202	{ "status":"PENDING"}
401	{ "error":"MISSING_AUTH", "detail": "Authorization header missing" }
401	{ "error":"INVALID_KEY", "detail": "Authorization key is invalid" }
400	{ "error":"INVALID_DATA", "detail": "JSON decode error at line 1, column 2" }

batch/login

The request body should contain JSON data in the following formats:

[
    {"workProviderUserId": <WORK_PROVIDER_USER_ID>, "timestamp": <TIMESTAMP>},
    {"workProviderUserId": <WORK_PROVIDER_USER_ID>, "timestamp": <TIMESTAMP>},
    ...
]

OR

[
    {"customerNumber": <CUSTOMER_NUMBER>, "timestamp": <TIMESTAMP>},
    {"customerNumber": <CUSTOMER_NUMBER>, "timestamp": <TIMESTAMP>},
    ...
]

>>> Script (using customerNumber)

[...]
import requests
import datetime
from pytz import UTC

now = UTC.localize(datetime.datetime.utcnow())

response = requests.post(
    'https://api.zego.com/v1/batch/login/',
    headers={'Authorization': AUTHORIZATION_CODE},
    json=[
        {
            'customerNumber': '1686',
            'timestamp': now.isoformat()
        },
        {
            'customerNumber': '8545',
            'timestamp': now.isoformat()
        },
        # [...]
    ])

print('Response status code:', response.status_code)
print('Response body:', response.text)

<<< Output

Response status code: 202
Response body: {"status": "PENDING"}

Make sure to replace '1686' and '8545' with your user's work provider user id.

Supply a list of customerIds or workProviderUserIds and timestamps to start shifts for multiple users with one request.

Request

Method	URL
POST	v1/batch/login/

Type	Params		Values
HEAD	Authorization		String
POST	body		JSON (Array:[Object])
		customerNumber	String (optional)
		workProviderUserId	String (optional)
		[Deprecated] policyId	String (optional)
		[Deprecated] driverId	String (optional)
		timestamp	String (ISO-8601 with timezone)

Response

Status	Response
202	{ "status":"PENDING" }
401	{ "error":"MISSING_AUTH", "detail": "Authorization header missing" }
401	{ "error":"INVALID_KEY", "detail": "Authorization key is invalid" }
400	{ "error":"INVALID_DATA", "detail": "JSON decode error at line 1, column 2" }

batch/logout

The request body should contain JSON data in the following formats:

[
    {"workProviderUserId": <WORK_PROVIDER_USER_ID>, "timestamp": <TIMESTAMP>},
    {"workProviderUserId": <WORK_PROVIDER_USER_ID>, "timestamp": <TIMESTAMP>},
    ...
]

OR

[
    {"customerNumber": <CUSTOMER_NUMBER>, "timestamp": <TIMESTAMP>},
    {"customerNumber": <CUSTOMER_NUMBER>, "timestamp": <TIMESTAMP>},
    ...
]

>>> Script (using workProviderUserId)

[...]
import requests
import datetime
from pytz import UTC

now = UTC.localize(datetime.datetime.utcnow())

response = requests.post(
    'https://api.zego.com/v1/batch/logout/',
    headers={'Authorization': AUTHORIZATION_CODE},
    data=[
        {
            'workProviderUserId': '1686',
            'timestamp': now.isoformat()
        },
        {
            'workProviderUserId': '8545',
            'timestamp': now.isoformat()
        },
        # [...]
    ])

print('Response status code:', response.status_code)
print('Response body:', response.text)

<<< Output

Response status code: 202
Response body: {"status": "PENDING"}

Make sure to replace '1686' and '8545' with your user's work provider user id.

Supply a list of customerNumbers or workProviderUserIds and timestamps to start shifts for multiple users with one request.

Request

Method	URL
POST	v1/batch/logout/

Type	Params		Values
HEAD	Authorization		String
POST	body		JSON (Array:[Object])
		customerNumber	String (optional)
		workProviderUserId	String (optional)
		[Deprecated] policyId	String (optional)
		[Deprecated] driverId	String (optional)
		timestamp	String (ISO-8601 with timezone).

Response

Status	Response
202	{ "status":"PENDING" }
401	{ "error":"MISSING_AUTH", "detail": "Authorization header missing" }
401	{ "error":"INVALID_KEY", "detail": "Authorization key is invalid" }
400	{ "error":"INVALID_DATA", "detail": "JSON decode error at line 1, column 2" }

/v2/shift/

Creates a shift for the user with a matching customer number or work provider user id. The created shift will either be open if endTime is null or finished if an endTime is provided.

The request body should contain JSON data in the following format

{
  "user": {
    "customerNumber": "IT15K",
  },
  "startTime": "2018-12-15T14:00:00+00:00",
  "endTime": null
}

Request

Method	URL
POST	/v2/policy/

Type	Params		Values
HEAD	Authorization		String
POST	user		JSON (Object)
		customerNumber	String; Not required if workProviderUserId is sent.
		workProviderUserId	String; Not required if customerNumber is sent.
	startTime		String (ISO-8601 formatted date)
	endTime		Optional string (ISO-8601 formatted date). Must be null if not being set.

Response

Status	Response
201	{ "id": "1", "user": {"customerNumber": "IT15K"}, "startTime": "2018-12-14T14:00:00+00:00", "endTime": null}
400	{ "status": "NOK", "error":"INVALID_DATA", "message": "Invalid data format", "detail": { "startTime ": "`startTime` must be within 30 minutes from now."} }
401	{ "status": "NOK", "error":"INVALID_KEY", "detail": "Invalid API key" }

/v2/shift/<id>

Updates a created shift with an end time.

The request body should contain JSON data in the following format

{
  "endTime": "2018-12-15T14:00:00+00:00",
}

Request

Method	URL
PUT	/v2/policy/<id>

Type	Params		Values
HEAD	Authorization		String
PUT	endTime		string (ISO-8601 formatted date).

Response

Status	Response
201	{"endTime": "2018-12-14T14:00:00+00:00"}
400	{ "status": "NOK", "error":"INVALID_DATA", "message": "Invalid data format", "detail": { "endTime ": "The maximum allowable shifts length is 14:00:00."} }
401	{ "status": "NOK", "error":"INVALID_KEY", "detail": "Invalid API key" }

Customers

user/status

>>> Script

[...]
import requests

work_provider_user_id = "12345"

response = requests.get(
    f'https://api.zego.com/v1/user/status/?workProviderUserId={work_provider_user_id}',
    headers={'Authorization': AUTHORIZATION_CODE},
)

print(json.loads(response.content))

<<< Customer / User has a valid product output

{
  "status": "ENABLED",
  "detail": "Valid integrated insurance product found",
  "policyId": "ABC123",  # maintained for backwards compatibility
  "customerNumber": "ABC123",
  "cover_class_of_use": "Carriage of Goods for Hire & Reward",
  "cover_level": "Third Party (TPO)",
  "vehicle_registration": "VY7 JC3"
}

<<< Customer / User does not have a product linked

{
  "status": "DISABLED",
  "detail": "No integrated insurance product linked to <WORK_PROVIDER_NAME>",
  "policyId": "ABC123",  # maintained for backwards compatibility
  "customerNumber": "ABC123",
}

Supply a customerNumber OR workProviderUserId and receive status information about that particular Customer/User. If a Customer/User hasn't consented to sharing their information with the requester then the same error message will be received as when the Customer/User is not found.

Request

Method	URL
GET	v1/status/?customerNumber=
GET	v1/status/?workProviderUserId=
[Deprecated] GET	v1/status/?policyId=
[Deprecated] GET	v1/status/?driverId=

Response

Status	Response
200	{"status":"DISABLED", "policyId": , "customerNumber": , "detail": }
200	{"status":"ENABLED", "policyId": , "customerNumber": , "cover_class_of_use": , "cover_level": , "detail": }
200	{"status":"ENABLED", "policyId": , "customerNumber": , "cover_class_of_use": , "cover_level": , "detail": , "vehicle_registration": }
400	{"error":"INVALID_DATA"}
401	{"error":"MISSING_AUTH"}
401	{"error":"INVALID_KEY"}
404	{"error":"INVALID_CUSTOMER"}

validate/customer-number

>>> Script

[...]
import requests

customer_number = "ABC12"

response = requests.get(
    'https://api.zego.com/v1/validate/customer-number/{}'.format(customer_number),
    headers={'Authorization': AUTHORIZATION_CODE},
)

print('Response status code: ', response.status_code)

<<< Output

Response status code: 204

Validate a Zego customer number exists (additionally validate that it matches a given email address).

Request

Method	URL
GET	v1/validate/customer-number/<A-Z0-9: customerNumber>
GET	v1/validate/customer-number/<A-Z0-9: customerNumber>?email=<str: emailAddress>

Response

Status	Response
204
401	{"error":"MISSING_AUTH"}
401	{"error":"INVALID_KEY"}
404	{"error":"INVALID_CUSTOMER"}
404	{"error":"INVALID_CUSTOMER_EMAIL"}

Create and Enrol a customer on a Public Liability product

customer/enrol/public-liability/

The request body should contain JSON data in the following format

{
"customer": {
    "address": "25 Luke Street",
    "city": "London",
    "dob": "2000-04-15",
    "email": "raekwon@wutangforever.wu",
    "givenNames": "Reakwon The",
    "lastName": "Chef",
    "phoneNumber": "+4412314323423",
    "postCode": "EC2A 4DS",
    "workProviderUserId": "596e34ee2346c78cc8cf7c4"},
    "product": {
      "occupations": ["childminders"]}
}

>>> Example Request

import requests

response = requests.post(
    'https://api.zego.com/v2/customer/enrol/public-liability/',
    headers={'Authorization': AUTHORIZATION_CODE},
    json={
        'customer': {...},
        'product': {...}
    })

print('Response status code:', response.status_code)
print(response.json())

<<< Response

> "Response status code: 200"

{
    "customerNumber": "SE33S",
    "message": "Customer has been enrolled on <PUBLIC_LIABILITY_PRODUCT_NAME",
    "workProviderUserId": "212312qd2131",  # Your internal ID for easier matching
    "status": "ENROLLED",
}

Creates a new Customer on the Zego platform and enrols them onto a public liability product.

Request

Method	URL
POST	v2/customer/enrol/public-liability/

Type	Params		Values
HEAD	Authorization		String
POST	customer		JSON (Object)
		givenNames	String
		lastName	String
		dob	String (ISO-8601)
		address	String (first line only)
		city	String
		postCode	String
		email	String
		phoneNumber	String (including dialing country)
		workProviderUserId	String
	product		JSON (Object)
		occupations	JSON(List) ["occupation_1", "occupation_2"] (optional)

Response

Status	Response
202	{ "customerNumber": "SE33S", "workProviderUserId": "212312qd2131", "status": "ENROLLED", "detail": "Customer has been enrolled on <PUBLIC_LIABILITY_PRODUCT>}
401	{ "error":"MISSING_AUTH", "detail": "Authorization header missing" }
401	{ "error":"INVALID_KEY", "detail": "Authorization key is invalid" }
400	{ "error":"INVALID_DATA", "detail": "JSON decode error at line 1, column 2" }

customer/register/

Creates a user in our system, and registers that user as working for the owner of the API key that made the request.

The request body should contain JSON data in the following format

{
"customer": {
    "address": "25 Luke Street",
    "city": "London",
    "dob": "2000-04-15",
    "email": "raekwon@wutangforever.wu",
    "givenNames": "Reakwon The",
    "lastName": "Chef",
    "phoneNumber": "+4412314323423",
    "postCode": "EC2A 4DS",
    "workProviderUserId": "596e34ee2346c78cc8cf7c4"},
}

Request

Method	URL
POST	/v2/customer/register/

Type	Params		Values
HEAD	Authorization		String
POST	customer		JSON (Object)
		givenNames	String
		lastName	String
		dob	String (ISO-8601)
		address	String (first line only)
		city	String
		postCode	String
		email	String
		phoneNumber	String (including dialing country)
		workProviderUserId	String

Response

Status	Response
200	{ "customerNumber": "SE33S", "workProviderUserId": "212312qd2131", "status": "CUSTOMER_CREATED", "message": "Customer has been created"}
401	{ "error":"MISSING_AUTH", "detail": "Authorization header missing" }
401	{ "error":"INVALID_KEY", "detail": "Authorization key is invalid" }
400	{ "error":"INVALID_DATA", "detail": "JSON decode error at line 1, column 2" }

Policies

/v2/policy/

Note: this endpoint is currently in beta. The format of the request and the response may change without notice.

Creates a one-day fixed term Public Liability policy for the subject, the premium of which will be paid for by the work provider creating the policy. This policy can be created for the user and can cover one or several occupations.

The request body should contain JSON data in the following format

{
  "subject": {
    "customerNumber": "IT15K"
  },
  "policyOptions": {
    "occupations": ["accountants_or_bookkeepers"],
    "coverAmount": "pl_1000000",
    "startDate": "2018-12-15T14:00:00+00:00"
  }
}

Request

Method	URL
POST	/v2/policy/

Type	Params		Values
HEAD	Authorization		String
POST	subject		JSON (Object)
		customerNumber	String
	policyOptions		JSON (Object)
		occupations	JSON (List) (eg. ["occupation_1", "occupation_2"])
		coverAmount	String (eg. pl_1000000 for 1 million pounds of cover)
		startDate	String (ISO-8601 formatted date)

Response

Status	Response
202	{ "policyId": "1", "customerNumber": "IT15K", "product": "Public Liability", "startDate": "2018-12-14T14:00:00+00:0"}
401	{ "error":"MISSING_AUTH", "detail": "Authorization header missing" }
401	{ "error":"INVALID_KEY", "detail": "Authorization key is invalid" }
400	{ "error":"INVALID_DATA", "message": "Invalid data format", "detail": { "policyOptions": { "startDate": "\`startDate\` cannot be in the past."} } }

Public Liability Occupations

/v2/public-liability-occupations/

This endpoint returns the list of public liability occupations supported by our products.

When creating fixed term policies via the /v2/policy/ endpoint, you can use the value in the code field to create a policy with that occupation.

Request

Method	URL
GET	/v2/public-liability-occupations/

Response

Status	Response
200	{ "occupations": [{ "code": "actuary", "label": "Actuary" }, { "code": "advertising_agency", "label": "Advertising Agency" }]}
401	{ "error":"MISSING_AUTH", "detail": "Authorization header missing" }
401	{ "error":"INVALID_KEY", "detail": "Authorization key is invalid" }

)`

Customer Integration

Methods required to link and match external platform user accounts and Zego customers

/match

The request body should contain JSON data in the following formats:

{"customerNumber": <CUSTOMER_NUMBER>, "success": <SUCCESS>}

Supply a customer number to confirm that it has been matched to a user and you are ready to start sending shift data, or report that no match was possible and additional reconciliation will be required. When success is true, we will record that the given user has been matched by the authenticated work provider and that they are ready to start sending shifts.

Request

Method	URL
POST	v1/match/

Type	Params		Values
HEAD	Authorization		String
POST	body		JSON (Object)
		customerNumber	String
		[Deprecated] policyId	String
		success	Boolean

Response

Status	Response
202	{"status":"PENDING"}
401	{"error":"MISSING_AUTH"}
401	{"error":"INVALID_KEY"}
400	{"error":"INVALID_DATA"}

Web hooks

Customer sign up integration

We support a webhook integration flow to link Zego customers to their work provider. Once a user has successfully registered through our app, we will issue the following POST request to a url configurable by the work provider.

You should use the email and phoneNumber to try and match the user that has signed up to a user in your system. If there is a match, you may respond in one of the following ways:

• with a 204 response indicating you have successfully found a match. You should then record the customerNumber, and use the customerNumber when logging shifts.

If you don't have a match, you should respond with a 404 response. This will allow us to feed back to the user that we failed to find a match in your system.

{
    "customerNumber": <CUSTOMER_NUMBER>,
    "email": <USER_EMAIL>,
    "phoneNumber": <USER_PHONE_NUMBER>,
}

Type	Params		Values
HEAD	X-ZEGO-SIGNATURE		String
POST	body		JSON (Array:[Object])
		customerNumber	String
		email	String
		phoneNumber	String (optional)

Documentation versions

Version	Date	Author	Description
1.0	30-Mar-2017	Stuart Kelly	Initial draft.
1.1	08-Apr-2017	Stuart Kelly	Removed /register. Edited error responses.
1.2	22-Jun-2017	Tony Bajan	Document driver id. Added /link-work-provider
1.3	12-Sept-2017	Luis Visintini	Adaptation to Slate
1.4	27-Sept-2017	Stuart Kelly	Added /validate/customer-number
1.5	19-Oct-2017	Luis Visintini	Fixed mistakes in examples that did not include timezone data
1.6	12-Jan-2018	Tony Bajan	Added /match
1.7	05-Feb-2018	Stuart Kelly	Added /user/status
1.8	03-April-2018	Luis Visintini	Added timezone clarifications related to timestamps required for some methods
1.9	13-Aug-2018	Cedric Cordenier	Deprecate policyId and driverId fields. These are replaced by customerNumber and workProviderUserId respectively.
1.10	13-Aug-2018	Cedric Cordenier	Add information on webhook integration with Zego.
1.11	30-Sep-2018	Daniel Inniss	Reorganise documentation into smaller sections. Add /customer/enrol
1.12	17-Dec-2018	Cedric Cordenier	Add customer/register, v2/policy, and v2/public-liability-occupations