Below is the technical information required for submitting ERS Event APIs in our production environment. 

Our production URL is: https://ers.kupe.fishserve.co.nz/

All of these APIs are available for testing and developing against in our UAT environment. Do not use the production environment for testing your applications.

Our UAT URL is: https://ers.uat.kupe.fishserve.co.nz/

Red text in the information below indicates changes that are in an upcoming new schema only and have yet to take effect in production. These changes are available in UAT.

Technical information on APIs still in the development phase are available on our ERS Event APIs in Development page here.

Available APIs in Production;

Fishing Event APIs

Non-Fishing Event APIs

Shared vs Restricted event API's

Managing Event APIs

Shared vs Restricted event API's

  • Restricting applies to the location (latitude and longitude) on catch reports and NFPS reports, (e.g. Start Location, Finish Location, End Of Set Location, Start Of Haul Location, and Diver-specific Start and Finish locations).
  • It applies equally to the system and manual latitudes/longitudes.
  • It does not apply to the location (latitude, longitude) on Trip Start, Trip End, Disposal or Landing reports.

Get restricted events

The section below describes the difference between a Get response for shared or restricted location sharing.

If a user who is not the original completer is viewing a report with a restricted location, the longitude and latitude will display with one decimal place (rounded).

Share - Trawl Get Request Location Body Example:

     "startLocation": {
      "systemDateTime": "2017-05-24T08:01:00+13:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.7878
      },
      "manualDateTime": "2017-05-24T09:15:00+13:00",
      "manualLocation": {
        "longitude": -176.543,
        "latitude": -46.787
      }
    },
    "finishLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5432,
        "latitude": -44.8878
      },
      "manualDateTime": null,
      "manualLocation": null
      },

Restrict - Trawl Get Request Location Body Example:

    "startLocation": {
      "systemDateTime": "2017-05-24T08:01:00+13:00",
      "systemLocation": {
        "longitude": -175.5,
        "latitude": -45.8
      },
      "manualDateTime": "2017-05-24T09:15:00+13:00",
      "manualLocation": {
        "longitude": -176.5,
        "latitude": -46.8
      }
    },
    "finishLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5,
        "latitude": -44.9
      },
      "manualDateTime": null,
      "manualLocation": null
      },

Amending restricted events

The section below describes amending a restricted location event.

If an ER Reporter has restricted their fishing location for a permit holder, other users besides the ER Reporter (original completer) will not be able to amend the fishing location or net/line lost of the reports for that permit holder.

Trawl Update Request for a Restricted event Body Example:

Note: The system/manual locations & isNetLost are set to null

{
  "eventHeader": {
    "tripId": "Trawltripid1",
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf9290",
    "eventVersion": "2",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Fishing conditions were poor",
    "completedDateTime": null,
    "amendmentReason": "Wrong species code used",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "FishingUnderHSP": "True",
"fishingMethodCode": "BT", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["BIB"], "startLocation": { "systemDateTime": "2017-05-24T08:01:00+13:00", "systemLocation": { "longitude": null, "latitude": null }, "manualDateTime": "2017-05-24T09:15:00+13:00", "manualLocation": { "longitude": null, "latitude": null } },
"IsNonFishOrProtectedSpeciesCatchPresent": "True",
"numberOfNets": 3, "vesselPairNumber": null, "wingSpreadMetres": 12, "headlineHeightMetres": 25.5, "codendMeshSizeMm": 5, "groundRopeDepthMetres": 11, "bottomDepthMetres": 150, "speedKnots": 7.5, "finishLocation": { "systemDateTime": "2017-05-24T12:30:00+13:00", "systemLocation": { "longitude": null, "latitude": null } }, "isNetLost": null, "estimatedCatchKg": 90, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "GSH", "greenWeightEstimateKg": 23.75 } ] }

Back to top

Find Events

The section below describes how to retrieve details of submitted events.

Please note:

  • Only accepted events will be returned.
  • No rejected events will be returned. 
  • Only the latest version of each event is returned. 

Get

Request URL:

GET https://ers.kupe.fishserve.co.nz/api/event/v1/event-find?ReceivedDateTimeFromDateRange=&ReceivedDateTimeToDateRange=&EventDateTimeFromDateRange=&EventDateTimeToDateRange=&VesselId=&TripId=&EventType=&clientNumber=&PageSize=&PageNumber=

Example:

GET https://ers.kupe.fishserve.co.nz/api/event/v1/event-find?ReceivedDateTimeFromDateRange=&ReceivedDateTimeToDateRange=&EventDateTimeFromDateRange=&EventDateTimeToDateRange=&VesselId=&TripId=&EventType=&clientNumber=7654321&PageSize=&PageNumber=

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Received Date Time From Date Range  Optional String

The beginning datetime to search from for the received date of an event. 

Searching by date can be done by providing either a From or To date parameter. It is not required to provide both a start and end date.

Received Date Time To Date Range Optional String

The end datetime to search up to for the received date of an event.

Searching by date can be done by providing either a From or To date parameter. It is not required to provide both a start and end date.

Event Date Time From Date Range  Optional String

The beginning datetime to search from for the date of an event.

This is the date as entered on the event. For example, processed datetime, landing datetime, or start of haul datetime. 

Searching by date can be done by providing either a From or To date parameter. It is not required to provide both a start and end date.

Event Date Time To Date Range Optional String

The end datetime to search up to for the date of an event.

This is the date as entered on the event. For example, processed datetime, landing datetime, or start of haul datetime. 

Searching by date can be done by providing either a From or To date parameter. It is not required to provide both a start and end date.

Vessel Id Optional String The vessel number.
Trip Id Optional String The trip id for a set of events.
Event Type Optional String The event name.
Client Number Optional String

The permit holder client number that the event is submitted against.

Page Size Optional Number

The number of records returned on the page. 

For example, if you want 20 records per page to be returned, then set this parameter to 20.

Default size limit is 1000. 

Page Number Optional Number

The page number returned.

For example, if you want to view page 3 out of 4, then set this parameter to 3.

Default page number is 1.

Request Header:

Content-Type: application/json
Authorisation: Bearer YOUR_USER_TOKEN

Response

Response Status:

StatusDescription
200 Ok Status when event has been retrieved successfully.
404 Not Found Status when event cannot be found.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Body Parameters:

Properties are returned within an Event parameter. Please see the example provided.

ParameterData TypeValidation and Additional Notes 
Data See Data Parameters below. Array of Data records
Total Number of Records Number

The total number of events retrieved. 

Page Number Number The page number of the page returned.
Page Size Number

The total number of records per page.

Data Parameters:

ParameterData TypeValidation and Additional Notes
Event ID String Unique ID provided for each event.
Trip ID String Unique ID provided for each set of events which make up a single trip. 
Vessel ID String The vessel number.
Event Date String

The date of the event.

This is the date as entered on the event. For example, processed datetime, landing datetime, or start of haul datetime. 

Received Date String The date the event was submitted. 
Version Number The event version number. 
Event Type String

The name of the event. 

For example; Trawl, Disposal, Processing. 

Get URL String

The URL to retrieve details of the particular event. 

Client Number String

The permit holder client number that the event is submitted against. 

Find Events Get Request Body Example:

{
	"data": [
	{
	"eventId": "ee1b41cc-8dbd-18d1-7100-c25e0c093431",
	"tripId": "t122",
	"vesselId": "44453",
	"eventDate": "2017-07-01T08:00:00+13:00",
	"receivedDate": "2017-07-06T13:03:18+12:00",
	"version": 1,
	"eventType": "TripEnd",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/10323",
	"clientNumber": "7654321"
	},
	{
	"eventId": "c77d9922-0039-c0c2-8c90-7eb928526303",
	"tripId": "TS1",
	"vesselId": "2066",
	"eventDate": "2017-07-01T08:00:00+13:00",
	"receivedDate": "2017-07-06T13:02:37+12:00",
	"version": 1,
	"eventType": "NonFishOrProtectedSpecies",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/10320",
	"clientNumber": "7654321"
	},
	{
	"eventId": "254da76e-b7e6-be4e-6b81-42554adbe3de",
	"tripId": "jiggingtripId1",
	"vesselId": "15527",
	"eventDate": "2017-05-10T09:15:00+11:00",
	"receivedDate": "2017-07-04T10:38:50+12:00",
	"version": 1,
	"eventType": "Jigging",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/10123",
	"clientNumber": "7654321"
	},
	{
	"eventId": "835825ea-0689-315d-3d66-2593f1edeb1b",
	"tripId": "Trawltripid1",
	"vesselId": "15950",
	"eventDate": "2017-07-24T09:15:00+13:00",
	"receivedDate": "2017-06-30T16:45:26+12:00",
	"version": 1,
	"eventType": "Trawl",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/10042",
	"clientNumber": "7654321"
	},
	{
	"eventId": "26ef9c3e-5512-e2b0-4ce0-a8ac446507ed",
	"tripId": "15950",
	"vesselId": "1",
	"eventDate": "2017-03-28T09:15:00+11:00",
	"receivedDate": "2017-06-30T15:42:47+12:00",
	"version": 1,
	"eventType": "Disposal",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/10007",
	"clientNumber": "7654321"
	},
	{
	"eventId": "NET99",
	"tripId": "567",
	"vesselId": "1",
	"eventDate": "2017-04-01T08:00:00+13:00",
	"receivedDate": "2017-06-15T15:52:46+12:00",
	"version": 1,
	"eventType": "Netting",
	"getUrl": "https://ers.uat.kupe.fishserve.co.nz/clients/7654321/event-detail/7062",
	"clientNumber": "7654321"
	}
	],
	"totalNumberOfRecords": 6,
	"pageNumber": 1,
	"pageSize": 1000
	}

Back to top

Delete Events

The section below describes how to delete an event.

Please note:

  • Events can only be deleted if transmitted unintentionally and no event actually occurred, or where a single event is reported twice.
  • Events should never be deleted where incorrect details can be corrected using an amendment.
  • Only events that have been accepted by the FishServe APIs can be deleted. Rejected events cannot be deleted.
  • Once deleted, an event cannot be amended or retrieved using the GET or UPDATE APIs.
  • Delete information will be transmitted to MPI.

Delete

Request URL:

DEL https://ers.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/{eventtype}/{eventID}

Example:

DEL https://ers.kupe.fishserve.co.nz/api/8765432/event/v1/trawl/abc123456789-01

Delete URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Event Type Mandatory String The event name.
Client Number Mandatory String The permit holder client number that the event is submitted against.
Event ID Mandatory Number Unique logbook generated ID for an event.

Request Header:

Content-Type: application/json 
Signature: signature generated from the digital signature algorithm using the request body and private key.

Request Body Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Event Header Mandatory Event Header Set See Event Header Properties below.

Event Header Properties:

ParameterRequiredData TypeValidation and Additional Notes
Event ID Mandatory String Unique logbook generated ID for an event.

The same event ID as defined in the URL.

Notes Mandatory String Reason for deletion of event.
Software Vendor Mandatory String Your software vendor name. For example, e-logbook.
Software Version Mandatory String Your software version number. For example, 1.0.0.0
Software Installation Id Mandatory String

Your software installation ID. For example, a13afab2-c409-4622-b8f8-146996587809

Must be the Software Installation Id that was registered with the user and public key.

Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Delete Events DEL Request Body Example:

{
 "eventId": "abc123456789-01",
"Notes": "Delete of a duplicate event",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "8765432",
"completerUserId": "123456"
}

Response

Response Status:

StatusDescription
200 Ok Status when event has been deleted successfully.
404 Not Found Status when event cannot be found.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Back to top

Event Schema Editions

The section below describes how to retrieve details of event schema editions

The results are sorted alphabetically by event type

Get

Request URL:

GET https://ers.kupe.fishserve.co.nz/api/event-schema-editions

Response

Response Status:

StatusDescription
200 Ok Status when event has been retrieved successfully.
404 Not Found Status when event cannot be found.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Body Parameters:

Properties are returned within an Event parameter. Please see the example provided.

ParameterData TypeValidation and Additional Notes 
Data See Data Parameters below. Array of Data records
Event Type String

Event schema event type

Schema Edition Number Event schema version number
Start Date String

Date when schema edition begins

Finish Date String

Date when schema edition ends

URL String

An example of the submit URL used for that event. Note: the only change between event schema versions for an event is the version e.g. 'v1' changed to 'v2'.

Find Events Get Request Body Example:

[
{
"eventType": "Disposal",
"schemaEdition": 1,
"startDate": "2017-10-01T00:00:00",
"finishDate": null,
"url": "https://ers.test.kupe.fishserve.co.nz/api/[ClientNumber]/event/v1/disposal/[EventId]"
},
{
"eventType": "Diving",
"schemaEdition": 1,
"startDate": "2018-07-01T00:00:00",
"finishDate": null,
"url": "https://ers.test.kupe.fishserve.co.nz/api/[ClientNumber]/event/v1/diving/[EventId]"
},
{
"eventType": "Dredging",
"schemaEdition": 1,
"startDate": "2018-07-01T00:00:00",
"finishDate": null,
"url": "https://ers.test.kupe.fishserve.co.nz/api/[ClientNumber]/event/v1/dredging/[EventId]"
},
{
"eventType": "Non Fish or Protected Species",
"schemaEdition": 1,
"startDate": "2017-10-01T00:00:00",
"finishDate": "2018-09-30T23:59:59",
"url": "https://ers.test.kupe.fishserve.co.nz/api/[ClientNumber]/event/v1/non-fish-or-protected-species/[EventId]"
},
]

Back to top

Event Error Id's

The section below describes how to retrieve details of the event error id's.

The results are sorted by ID descending.

Get

Request URL:

GET https://ers.kupe.fishserve.co.nz/api/event-error-ids

Response

Response Status:

StatusDescription
200 Ok Status when event has been retrieved successfully.
404 Not Found Status when event cannot be found.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Body Parameters:

Properties are returned within an Event parameter. Please see the example provided.

ParameterData TypeValidation and Additional Notes 
Data See Data Parameters below. Array of Data records
Id Number

Event error id. This will be provided with every error message.

Description String Event error message, e.g. "The request body is missing or could not be bound."

Find Events Get Request Body Example:

[
{
"id": 1,
"description": "The request body is missing or could not be bound."
},
{
"id": 2,
"description": "Event id must be provided."
},
{
"id": 3,
"description": "Event id already exists."
},
{
"id": 4,
"description": "The event id specified in the url does not match the event id in the request body."
},
{
"id": 5,
"description": "The event id does not exist."
}
]