WatchEye · Entities

Create an entity in a program

Creating an entity adds a person, business, vessel or property to a program as the record that screening checks, ID checks and monitor runs read from. The fields required depend on the entity type, and the call returns 201 with the entity, its short entity number and the risk level it was given.

Four entity types, each with its own required fields and up to four phones and four emails
A customer reference of your own, unique within the program, for matching records back to your system

Request access Talk to sales

For developers

After the technical detail?

For the technical detail, go to the API documentation. It holds the request and response schema, the integration guides and the error codes for this endpoint.

Request and response schema
Fields by entity type and idempotency

Go to the API docs

New accounts begin with sandbox access.

ISO 27001 certified Handled under Australian privacy law Every API call written to the audit log

What the check gives you

Putting a customer on the books so screening can find them

Every entity check and monitor run reads its subject from the entity record, so the details entered here are the details screened. A reference number of your own ties the entity back to your customer record, and flags and a risk level carry your own assessment alongside the screening results.

A record shaped by its type

An individual carries names and a date of birth. A business carries its name and an ABN, ACN, UK company registration number or other identifier. A vessel carries its name. A property carries its name and address. Address, phone and email fields sit alongside where they apply.

Your reference on the record

A reference number of your choosing, unique within the program, is stored on the entity and can be filtered on when listing.

Your own assessment

Manual flags such as PEP, sanction or deceased, and a risk level of low, medium or high, are stored on the entity. Omit the risk level to take the program's default, or send null to leave it unassigned.

That a retry will not create a duplicate

An optional Idempotency-Key header returns the original response on a retry with the same key and body. A key reused with a different body is rejected with 422.

How a check runs

Where entities sit in the WatchEye model

An entity belongs to a program. Screening checks and monitors run against it, its matches become events in the triage queue, and every call is written to the audit log.

The date of birth on an individual is locked once it has been used in an identification check.

What it costs

Charged when screening runs, not when records are managed

Charges arise when screening runs against the entities in a program: each check type launched against an entity is charged at launch, and a monitor run is charged for each entity eligible for its operation. Rates are set for your account and communicated by your Global Data account manager, and statements with a per-call breakdown are in the WatchEye portal.

Billed per screening operation
Refunded if the provider fails

How billing works

Credits drawn down against your account balance

A screening check is charged per check type when it is launched, and refunded if the provider fails.
A monitor run bills only for the entities eligible for its operation; a UK check skips businesses outside the UK, for example.
A run that would exceed the account's credit is refused with 402 and a billing breakdown, before anything is queued.
Reads, lists and PDF downloads are not billed.

Talk to us about rates

Related checks

Others in WatchEye Entities

Show an entity reads it back. Update an entity changes it. Launch screening checks against an entity and Launch an ID check against an entity run the checks that read from it.

Archive an entity Delete an entity List entities in a program Show an entity Unarchive an entity Update an entity

All WatchEye entities endpoints

Questions

Questions we get asked about creating an entity

Do we need a developer to implement this?

Yes. This is a single REST call that returns the created entity, so a developer wires it to the point where a customer is onboarded in your system. A sandbox account is available for development at no charge. It is a separate account with its own API keys, it returns test data in the same response shapes as live, and the same base URL serves both environments.

What does our system need to send?

The program UUID in the path, the entity type, and the fields that type requires. Optionally a reference number, address lines with suburb, state, postcode and a two-letter country code, up to four phones and four emails, flags and a risk level.

Which entity types are there, and what does each need?

An individual needs at least a first or last name and may carry a date of birth. A business needs a business name and may carry a business number with its type: Australian ABN, Australian ACN, UK company registration number or other. A vessel needs a vessel name. A property needs a property name, with address fields optional. Fields that belong to another type are ignored.

What are flags and risk levels?

Flags are manual markers on the entity: sanction, PEP, adverse media, fraud, hardship, bankruptcy, deceased, court actions, deregistered and external administration. The risk level is low, medium or high, or null when no risk has been assigned; when omitted on creation, the program's default risk level applies, falling back to low.

What comes back?

A 201 with the entity: its UUID, a short entity number, your reference number, the type, a display name computed from the type-specific fields, every stored field, the flags, the risk level, the program UUID and the created and updated timestamps.

What if the connection drops after we send the request?

Send an Idempotency-Key header, typically a fresh UUID per logical request. A retry with the same key and body returns the original response verbatim, marked with an Idempotent-Replay header, and the entity is not created twice. A successful response is remembered for 24 hours, and the same key with a different body is rejected with 422.

What happens to the personal information in the response?

Personal information stored in WatchEye is covered by Global Data's security policies for the platform. Once your integration copies it into your own applications, databases, logs or backups, protecting it becomes your responsibility. Retrieve only the fields you need and treat any logs that capture API payloads as sensitive.

Getting started

The first step to access is a conversation

Sandbox accounts are provisioned by your Global Data account manager. API keys are created and managed in the WatchEye portal, and the same endpoints serve sandbox and live; the account behind the key decides which environment you are in.

Request access Talk to sales

Call 03 9948 4089, 9am–5pm AEST Monday to Friday

ISO 27001 certified

Handled under Australian privacy law

Every API call written to the audit log