DISCLAIMER: Please note, this information is subject to change as content is still under development with MPI

Below is the technical information required for setting up the ERS Event APIs

29/08/2017: Changes have been made to the APIs to include a Signature in the request header instead of a Bearer Token.

21/08/2017: Changes have been made to the APIs and these changes are in our UAT environment only so that demo is unaffected for any current development work that may be occurring.

To access this environment you will need a UAT username and password. Please contact us for access.

For your reference, the url for the demo environment is: https://ers.demo.kupe.fishserve.co.nz/ . 

ERS Event APIs

ERS Non-Fishing Event APIs

ERS Find APIs

Trawl Event

The sections below describe the information necessary to create, get and update a trawl event.

Change history
Date Change
19/09/2017

Changed manual location details to only require a minimum of 3dp.

Removed all the fields for "Net at Depth Location" and "Net Leave Depth Location" from the body parameters.

Removed the NFPS Catch array and "Is Non Fish Or Protected Species Catch Present" field. NFPS catch will now be completed as a separate event only, and is not part of the Trawl event. 

Changed the validation on the Finish Location fields. This is now mandatory if the net is not lost, but optional if the net is lost. 

11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017

Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.

29/08/2017

Updated Request Header to Include Signature instead of Bearer token.

21/08/2017

Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 

31/07/2017 Updated validation for attribute Codend Mesh Size Mm to allow 0's.
14/07/2017 Attribute Headline Height Metres validation updated to include decimal.
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
15/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
18/05/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trawl/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trawl/5ba04c30-c81a-4618-898e-e832da93cf98

Create URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the BT method must be reported through the Trawl Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Number of Nets Mandatory Number Must be a whole number.

Must be greater than 0.

Vessel Pair Number Optional String If a pair method is used, this is the other vessel involved in the fishing.

If provided, must be a valid vessel number.

Wing Spread Metres Mandatory Number Must be a whole number.

Must be greater than 0.

Headline Height Metres Mandatory Number

Decimal to 2dp.

Must be greater than 0.

Codend Mesh Size Mm Mandatory Number Must be a whole number.

Must be 0 or greater.

Ground Rope Depth Metres Mandatory Number Must be a whole number.

Must be greater than 0.

Bottom Depth Metres Mandatory Number Must be a whole number.

Must be greater than 0.

Speed Knots Mandatory Number Decimal to 2dp.

Must be greater than 0.

Is Net Lost Conditional Boolean Records if the net has been lost and unable to be hauled.
Finish Location Conditional  Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Mandatory if net has not been lost - 'Is Net Lost' is false. 

Optional if net has been lost - 'Is Net Lost' is true.

Estimated Catch Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater.

If estimated catch > 0, then Catch must be provided (must have at least one catch record).

If estimated catch = 0 and Catch is provided, the ERS will still accept the event.

Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught

See Catches Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String

Must be a valid client number. 

Must be the same client number as specified in the URL.

Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset
Manual Date Time Optional String Date 24 hr + UTC Offset
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Longitude Mandatory decimal degrees 

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater

Trawl Create Request Body Example:

{
  "eventHeader": {
    "tripId": "Trawltripid121",
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf9290",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Fishing conditions were poor",
    "completedDateTime": "2017-05-04T10:00:00+13:00",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "12345" }, "fishingMethodCode": "MW", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["BIB"], "startLocation": { "systemDateTime": "2017-05-24T08:01:00+13:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 }, "manualDateTime": "2017-05-24T09:15:00+13:00", "manualLocation": { "longitude": -176.543, "latitude": -46.987 } }, "numberOfNets": 3, "vesselPairNumber": null, "wingSpreadMetres": 12, "headlineHeightMetres": 25.5, "codendMeshSizeMm": 5, "groundRopeDepthMetres": 11, "bottomDepthMetres": 150, "speedKnots": 7, "finishLocation": { "systemDateTime": "2017-05-24T12:30:00+13:00", "systemLocation": { "longitude": -174.5432, "latitude": -44.9878 } }, "isNetLost": false, }, "estimatedCatchKg": 90, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 23.75 } ] }
Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Body Parameters:

Parameter Data Type Validation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

 { 
  "errors": []
 }

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

 { 
  "errors": [ 
	 { 
		"propertyName": "EventId", 
		"attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91", 
		"errorCode": "DuplicateValue", 
		"errorMessage": "EventId already exists." 
	 } 
  ]
 }
 

Back to top

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trawl/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trawl/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

Content-Type: application/json
Signature: signature generated from the digital signature algorithm using the request body and private key.
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 Type
Event ID String
Trip ID String
Client Number String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Number of Nets Number
Vessel Pair Number String
Wing Spread Metres Number
Headline Height Metres Number
Codend Mesh Size Mm Number
Ground Rope Depth Metres Number
Bottom Depth Metres Number
Speed Knots Number
Is Net Lost Boolean
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Estimated Catch Kg Number
Catches See Catches Parameters below. Array of Catches
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Trawl Get Request Body Example:

 
{
  "event": {
    "numberOfNets": 3,
    "vesselPairNumber": null,
    "wingSpreadMetres": 12,
    "headlineHeightMetres": 25.5,
    "codendMeshSizeMm": 5,
    "groundRopeDepthMetres": 11,
    "bottomDepthMetres": 150,
    "speedKnots": 7,
    "isNetLost": false,
    "estimatedCatchKg": 90,
    },
    "fishingMethodCode": "MW",
    "targetSpeciesCode": "SNA",
    "mitigationDeviceCodes": [
      "BIB"
    ],
    "startLocation": {
      "systemDateTime": "2017-05-24T08:01:00+13:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.9878
      },
      "manualDateTime": "2017-05-24T09:15:00+13:00",
      "manualLocation": {
        "longitude": -176.543,
        "latitude": -46.987
      }
    },
    "finishLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5432,
        "latitude": -44.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "catches": [
      {
        "speciesCode": "SNA",
        "greenWeightEstimateKg": 50.25,
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
      }
    ],
    "tripId": "Trawltripid121",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf9290",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8462926",
    "completedDateTime": "2017-05-04T10:00:00+13:00",
    "notes": "Fishing conditions were poor",
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Back to top

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trawl/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trawl/5ba04c30-c81a-4618-898e-e832da93cf98

Update URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will need to be passed in the request body.

ParameterRequiredData TypeDescription
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Trawl Update Request Body Example:

 
{
  "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" }, "fishingMethodCode": "BT", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["BIB"], "startLocation": { "systemDateTime": "2017-05-24T08:01:00+13:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 }, "manualDateTime": "2017-05-24T09:15:00+13:00", "manualLocation": { "longitude": -176.543, "latitude": -46.987 } }, "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": -174.5432, "latitude": -44.9878 } }, "isNetLost": false, "estimatedCatchKg": 90, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "GSH", "greenWeightEstimateKg": 23.75 } ] }
Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Body Parameters:

ParameterData TypeDescription
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeDescription
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{ 
"errors": []
}

Example 2:

{ 
	"errors": [ 
	{ 
	 "propertyName": "EventVersion", 
	 "attemptedValue": "2", 
	 "errorCode": "InvalidValue", 
	 "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again." 
	 } 
	]
}

Back to top

Potting Event

The sections below describe the information necessary to create, get and update a Potting event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017

Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.

29/08/2017

Updated Request Header to include Signature instead of Bearer Token.

21/08/2017

Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here.

05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
15/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
18/05/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/potting/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/potting/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the CP method must be reported through the potting Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Number of Lifts Mandatory Number Must be a whole number.

Records the number of pots or nets lifted.

Must be 0 or greater.

Soak Time Mandatory Number Whole hours only. Round up. Must be 0 or greater.
Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught.

See Catches Parameters below.

Non Fish or Protected Species Catches Conditional Array of NFPS records Can have zero or many NFPS records.

Must have at least one if 'Is Non Fish Or Protected Species Catch Present' is True.

If 'Is Non Fish Or Protected Species Catch Present' is False and NFPS catch provided, ERS will accept the event.

See Non Fish or Protected Species Catches Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset
Manual Date Time Optional String Date 24 hr + UTC Offset
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against NFPS master data.

Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Potting Create Request Body Example:

{
  "eventHeader": {
    "eventId":"5ba04c30-c81a-4618-898e-e832da93cf1532",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "2017-04-10T09:15:00+11:00",
    "tripId": "589",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "RLP", "targetSpeciesCode": "ZAS", "mitigationDeviceCodes": ["SLE"], "startLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": -175.5432, "latitude": -88.9878 } }, "isNonFishOrProtectedSpeciesCatchPresent": true, "numberOfLifts": 8, "soakTimeHours": 8, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": "174.6799", "latitude": "-41.4289" } }, "catches": [ { "speciesCode": "ZAS", "greenWeightEstimateKg": 88.88 }, { "speciesCode": "YBF", "greenWeightEstimateKg": 88.88 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "FUG", "estimatedWeightKg": 88.88, "numberUninjured": null, "numberInjured": null, "numberDead": null, "tags": null } ] }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/potting/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/potting/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish Or Protected Species Catch Present Boolean
Number of Lifts Number
Soak Time Hours Number
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Catches See Catches Parameters below. Array of Catches
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Potting Get Request Body Example:

{
  "event": {
    "numberOfLifts": 8,
    "soakTimeHours": 8,
    "fishingMethodCode": "RLP",
    "targetSpeciesCode": "ZAS",
    "mitigationDeviceCodes": [
      "SLE"
    ],
    "startLocation": {
      "systemDateTime": "2017-04-10T09:15:00+11:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -88.987799999999993
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "finishLocation": {
      "systemDateTime": "2017-04-10T09:15:00+11:00",
      "systemLocation": {
        "longitude": 174.6799,
        "latitude": -41.4289
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "isNonFishOrProtectedSpeciesCatchPresent": true,
    "catches": [
      {
        "speciesCode": "ZAS",
        "greenWeightEstimateKg": 88.88,
      },
      {
        "speciesCode": "YBF",
        "greenWeightEstimateKg": 88.88,
      }
    ],
    "nonFishOrProtectedSpeciesCatches": [
      {
        "speciesCode": "FUG",
        "seabirdCaptureCode": null,
        "estimatedWeightKg": 88.88,
        "numberUninjured": 8,
        "numberInjured": 8,
        "numberDead": 8,
        "tags": null
      }
    ],
    "tripId": "589",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf1532",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8462926",
    "completedDateTime": "2017-04-10T09:15:00+11:00",
    "notes": null,
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/potting/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/potting/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Potting Update Request Body Example:

{
  "eventHeader": {
    "eventId":"5ba04c30-c81a-4618-898e-e832da93cf1532",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "",
    "amendmentReason": "Typo mistake for YBF estimated catch",
    "tripId": "589",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "RLP", "targetSpeciesCode": "ZAS", "mitigationDeviceCodes": ["SLE"], "startLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": -175.5432, "latitude": -88.9878 } }, "isNonFishOrProtectedSpeciesCatchPresent": true, "numberOfLifts": 11, "soakTimeHours": 11, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": "174.6799", "latitude": "-41.4289" } },
"catches": [ { "speciesCode": "ZAS", "greenWeightEstimateKg": 88.88 }, { "speciesCode": "YBF", "greenWeightEstimateKg": 42.52 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "FUG", "estimatedWeightKg": 88.88, "numberUninjured": null, "numberInjured": null, "numberDead": null, "tags": null } ] }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeDescription
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeDescription
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Netting Event

The sections below describe the information necessary to create, get and update a Netting event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
16/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
18/05/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/netting/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/netting/5ba04c30-c81a-4618-898e-e832da93cf99

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the DN method must be reported through the netting Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Number of Nets Mandatory Number Must be a whole number.

Must be greater than 0.

Total Length of Nets Metres Mandatory Number Decimal to 2dp. Must be greater than 0.
Min Mesh Size Mm Mandatory Number Must be a whole number.

Must be greater than 0.

Net Height Mandatory Number Must be a whole number.

Must be greater than 0.

Number of meshes

Is Net Lost Conditional Boolean Records if the net has been lost and unable to be hauled.
End of Set Location Mandatory Geolocation Set See Geolocation Set Parameters below.

If not provided, ‘Is Net Lost’ must be true.

Start of Haul Location Mandatory Geolocation Set See Geolocation Set Parameters below.

If not provided, ‘Is Net Lost’ must be true.

Estimated Green Weight for all other Species Kg Optional Number Decimal to 2dp. Must be 0 or greater.
Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught.

See Catches Parameters below.

Non Fish or Protected Species Catches Conditional Array of NFPS records Can have zero or many NFPS records.

Must have at least one if 'Is Non Fish Or Protected Species Catch Present' is True.

If 'Is Non Fish Or Protected Species Catch Present' is False and NFPS catch provided, ERS will accept the event.

See Non Fish or Protected Species Catches Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater.

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against NFPS master data.

Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Netting Create Request Body Example:

{
  "eventHeader": {
    "eventId":"NET99",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "2017-04-10T09:18:00+11:00",
    "tripId": "567",
    "notes": "Golden path - TEST",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "dn", "targetSpeciesCode": "KIN", "mitigationDeviceCodes": ["STR"], "isNonFishOrProtectedSpeciesCatchPresent": true, "totalLengthOfNetsMetres": 1, "minMeshSizeMm": 8, "netHeight": 8, "isNetLost": false, "numberOfNets": 1, "estimatedGreenWeightForAllOtherSpeciesKg": 18.8, "startLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -88.9878 } }, "finishLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -88.9878 } }, "endOfSetLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -88.9878 } }, "startOfHaulLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "catches": [ { "speciesCode": "KIN", "greenWeightEstimateKg": 88.88 }, { "speciesCode": "DPO", "greenWeightEstimateKg": 88.88 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "XAF", "estimatedWeightKg": null, "numberUninjured": 1, "numberInjured": 0, "numberDead": 0, "tags": null } ] }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeDescription
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeDescription
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf99",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/netting/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/netting/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish Or Protected Species Catch Present Boolean
Number of Nets Number
Total Length of Nets Metres Number
Min Mesh Size Mm Number
Net Height Number
Is Net Lost Boolean
End of Set Location See Geolocation Set Parameters below. Geolocation Set
Start of Haul Location See Geolocation Set Parameters below. Geolocation Set
Estimated Green Weight for all other Species Kg Number
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Catches See Catches Parameters below. Array of Catches
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Netting Get Request Body Example:

{
  "event": {
    "totalLengthOfNetsMetres": 1,
    "minMeshSizeMm": 8,
    "netHeight": 8,
    "isNetLost": false,
    "startOfHaulLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "endOfSetLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -88.987799999999993
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "numberOfNets": 1,
    "estimatedGreenWeightForAllOtherSpeciesKg": 18.8,
    "fishingMethodCode": "dn",
    "targetSpeciesCode": "KIN",
    "mitigationDeviceCodes": [],
    "startLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -88.987799999999993
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "finishLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -88.987799999999993
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "isNonFishOrProtectedSpeciesCatchPresent": true,
    "catches": [
      {
        "speciesCode": "KIN",
        "greenWeightEstimateKg": 88.88,
      },
      {
        "speciesCode": "DPO",
        "greenWeightEstimateKg": 88.88,
      }
    ],
    "nonFishOrProtectedSpeciesCatches": [
      {
        "speciesCode": "XAF",
        "seabirdCaptureCode": null,
        "estimatedWeightKg": 8,
        "numberUninjured": 88,
        "numberInjured": 88,
        "numberDead": 888,
        "tags": null
      }
    ],
    "tripId": "567",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "NET99",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8422125",
    "completedDateTime": "2017-04-10T09:18:00+11:00",
    "notes": "Golden path - TEST",
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/netting/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/netting/5ba04c30-c81a-4618-898e-e832da93cf99

Update URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeDescription
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Netting Update Request Body Example:

{
  "eventHeader": {
    "eventId":"NET100",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "tripId": "567",
    "notes": "Golden path UPDATE - TEST",
    "amendmentReason": "Wrong weight recorded for KIN",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "dn", "targetSpeciesCode": "KIN", "mitigationDeviceCodes": ["STR"], "isNonFishOrProtectedSpeciesCatchPresent": true, "totalLengthOfNetsMetres": 1, "minMeshSizeMm": 8, "netHeight": 8, "isNetLost": false, "numberOfNets": 1, "estimatedGreenWeightForAllOtherSpeciesKg": 18.8, "startLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -77.9878 } }, "finishLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -77.9878 } }, "endOfSetLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -77.9878 } }, "StartOfHaulLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "catches": [ { "speciesCode": "KIN", "greenWeightEstimateKg": 101.29 }, { "speciesCode": "DPO", "greenWeightEstimateKg": 88.88 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "XAF", "estimatedWeightKg": 8, "numberUninjured": 88, "numberInjured": 88, "numberDead": 888, "tags": null } ] }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeDescription
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeDescription
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Lining Event

The sections below describe the information necessary to create, get and update a Lining event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
20/07/2017 Attribute Hook Space Metres validation changed to allow decimal.
14/07/2017 Attribute Hook Space Cm relabelled to Hook Space Metres.
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
16/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
29/05/2017 Initial publication.

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/lining/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/lining/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the CP method must be reported through the potting Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Hook Space Metres Mandatory Number Decimal to 2dp.

Must be greater than 0.

Number of Hooks Mandatory Number Must be a whole number.

Must be 0 or greater.

Bottom Depth Metres Mandatory Number Must be a whole number.

Must be greater than 0.

Is Line Lost Optional Boolean Records if the line has been lost and unable to be hauled.
End of Set Location Mandatory Geolocation Set See Geolocation Set Parameters below.

If not provided, ‘Is Line Lost’ must be true (or) fishing method is 'DL'.

Start of Haul Location Mandatory Geolocation Set See Geolocation Set Parameters below.

If not provided, ‘Is Line Lost’ must be true (or) fishing method is 'DL'.

Number of Lines Hauled Conditional Number

Must be provided if 'Fishing Methods' master data property 'require_lines_hauled = true'.

Must be a whole number.

Must be greater than 0.

Can be provided for other Fishing Methods, ERS will not reject the event if provided.

Estimated Green Weight for all other Species Kg Optional Number

Decimal to 2dp.

Must be 0 or greater.

Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught

See Catches Parameters below.

Non Fish or Protected Species Catches Conditional Array of NFPS records Can have zero or many NFPS records.

Must have at least one if 'Is Non Fish Or Protected Species Catch Present' is True.

If 'Is Non Fish Or Protected Species Catch Present' is False and NFPS catch provided, ERS will accept the event.

See Non Fish or Protected Species Catches Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against NFPS master data.

Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Lining Create Request Body Example:

{
  "eventHeader": {
    "eventId": "LiningEvent1",
    "tripId": "tr1",
    "completedDateTime": "2017-04-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "BLL", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["BIB", "STR"], "startLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "finishLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "endOfSetLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "startOfHaulLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "isNonFishOrProtectedSpeciesCatchPresent": false, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "CRA", "greenWeightEstimateKg": 23.75 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 23.75 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "XAS", "seabirdCaptureCode": "H", "estimatedWeightKg": null, "numberUninjured": null, "numberInjured": null, "numberDead": 23, "tags": null } ], "hookSpaceMetres": 99, "numberOfHooks": 5, "bottomDepthMetres": 346, "estimatedGreenWeightForAllOtherSpeciesKg": 2, "numberOfLinesHauled": 8 }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/lining/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/lining/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

Response

Response Status:

Status Description
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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish Or Protected Species Catch Present Boolean
Hook Space Metres Number
Number of Hooks Number
Bottom Depth Metres Number
Is Line Lost Boolean
End of Set Location See Geolocation Set Parameters below. Geolocation Set
Start of Haul Location See Geolocation Set Parameters below. Geolocation Set
Number of Lines Hauled Number
Estimated Green Weight for all other Species Kg Number
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Catches See Catches Parameters below. Array of Catches
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Lining Get Request Body Example:

{
  "event": {
    "hookSpaceMetres": 99,
    "numberOfHooks": 5,
    "bottomDepthMetres": 346,
    "isLineLost": null,
    "numberOfLinesHauled": 8,
    "startOfHaulLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "endOfSetLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "estimatedGreenWeightForAllOtherSpeciesKg": 2,
    "fishingMethodCode": "BLL",
    "targetSpeciesCode": "SNA",
    "mitigationDeviceCodes": ["BIB", "STR"],
    "startLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "finishLocation": {
      "systemDateTime": "2017-04-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.1025,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "isNonFishOrProtectedSpeciesCatchPresent": false,
    "catches": [
      {
        "speciesCode": "SNA",
        "greenWeightEstimateKg": 50.25,
      },
      {
        "speciesCode": "CRA",
        "greenWeightEstimateKg": 23.75,
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
      }
    ],
    "nonFishOrProtectedSpeciesCatches": [
      {
        "speciesCode": "XAS",
        "seabirdCaptureCode": "H",
        "estimatedWeightKg": null,
        "numberUninjured": null,
        "numberInjured": null,
        "numberDead": 23,
        "tags": null
      }
    ],
    "tripId": "tr1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "LiningEvent1",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8462926",
    "completedDateTime": "2017-04-01T08:00:00+13:00",
    "notes": "Some notes",
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/lining/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/lining/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeDescription
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Lining Update Request Body Example:

{
  "eventHeader": {
    "eventId": "123qwert",
    "eventVersion": "1",
    "tripId": "tr1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Lining Update - TEST",
    "amendmentReason": "wrong catch recorded for Hoki",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "BLL", "targetSpeciesCode": "SNA", "mitigationDeviceCodes":["ACC"], "startLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "finishLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "endOfSetLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "startOfHaulLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "isNonFishOrProtectedSpeciesCatchPresent": false, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "CRA", "greenWeightEstimateKg": 23.75 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 24.25 } ], "nonFishOrProtectedSpeciesCatches": [{ "speciesCode": "XAS", "seabirdCaptureCode": "H", "estimatedWeightKg": 8, "numberUninjured": 88, "numberInjured": 888, "numberDead": 2, "tags": null
} ], "hookSpaceMetres": 2, "numberOfHooks": 2, "bottomDepthMetres": 2, "isLineLost": false, "estimatedGreenWeightForAllOtherSpeciesKg": 2, "numberOfLinesHauled": 2 }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeDescription
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeDescription
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Tuna Lining Event

The sections below describe the information necessary to create, get and update a Tuna Lining event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
09/06/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/tuna-lining/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/tuna-lining/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid Method for the Fishing Event Type. e.g a SLL code may be used for a Tuna Lining event.

Validated against the Fishing Methods master data.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Line Length Nm Mandatory Number

Decimal to 2dp.

Must be 0 or greater.

Number of Hooks Mandatory Number Must be a whole number.

Must be 0 or greater.

Number of Floats Mandatory Number Must be a whole number.

Must be 0 or greater.

Number of Lightsticks Mandatory Number Must be a whole number.

Must be 0 or greater.

Line Shooter Mandatory Boolean
Bait Type % - Fish Mandatory Number Decimal to 2dp.

Total Bait Type % must equal 100.

Must be 0 or greater.

Bait Type% - Other includes unbaited.

Bait Type % - Squid Mandatory Number
Bait Type % - Other Mandatory Number
Bait Type % - Artificial Mandatory Number
Is Line Lost Mandatory Boolean Records if the net has been lost and unable to be hauled.
Start of Haul Location Mandatory Geolocation Set See Geolocation Set Parameters below.
End of Set Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Catches Optional Array of catch Can be 0 or many Catch records. Records all species caught See Catches Parameters below.
Stocks Disposed Optional Array of stocks disposed Can be 0 or many stock disposed records.
Non Fish or Protected Species Catches Conditional Array of NFPS records See Non Fish or Protected Species Catches Parameters below. Mandatory if Is Non Fish Or Protected Species Catch Present is ‘Yes’

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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional Stirng Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided. See Geolocation parameters below.
Manual Location Conditional Geolocation


Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Product State Code Mandatory String

Must be a valid product state code.

Validated against Product States master data.

Processed Weight Kg Mandatory Number Must be a whole number.

Must be greater than 0.

Number of Fish Mandatory Number Must be a whole number.

Must be greater than 0.

Stocks Disposed Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Stock Code Mandatory String

Must be a valid ERS stock code.

Validated against Fish Stock master data.

Disposal Code Mandatory String

Must be a valid disposal code.

Validated against Disposal Codes master data.

Estimated Green Weight Kg Mandatory Number Decimal to 2dp.

Must be greater than 0.

Number of Fish Mandatory Number Must be a whole number.

Must be greater than 0.

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid NFPS species code. Validated against NFPS master data.
Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'. Validated against the Seabird Capture Codes master data.
Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Tuna Lining Create Request Body Example:

 {
  "eventHeader": {
    "eventId": "TL017",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",
    "completedDateTime": "2017-05-29T09:00:00+13:00",
    "tripId": "TL013",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "SLL", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["OTH", "LAS"], "startLocation": { "systemDateTime": "2017-05-24T08:01:00+13:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 }, "manualDateTime": "2017-05-24T09:15:00+13:00", "manualLocation": { "longitude": -176.5432, "latitude": -46.9878 } }, "finishLocation": { "systemDateTime": "2017-05-24T12:30:00+13:00", "systemLocation": { "longitude": -174.5432, "latitude": -44.9878 }, "manualDateTime": "2017-05-24T13:33:00+13:00", "manualLocation": { "longitude": -173.5432, "latitude": -43.9878 } }, "isNonFishOrProtectedSpeciesCatchPresent": true, "catches": [ { "speciesCode": "SNA", "processedWeightKg": 29, "productStateCode": "FIN", "numberOfFish": 3 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "XAF", "seabirdCaptureCode": "S", "estimatedWeightKg": 4, "numberUninjured": 4, "numberInjured": 1, "numberDead": 0, "tags": null } ], "lineLengthNm": 99.7, "numberOfHooks": 66, "numberOfFloats": 4, "numberOfLightsticks": 3, "lineShooter": true, "baitTypePercentFish": 25, "baitTypePercentSquid": 50, "baitTypePercentOther": 25, "baitTypePercentArtifical": 0, "endOfSetLocation": { "systemDateTime": "2017-05-24T12:30:00+13:00", "systemLocation": { "longitude": -174.5432, "latitude": -44.9878 } }, "isLineLost": false, "startOfHaulLocation": { "systemDateTime": "2017-05-24T12:30:00+13:00", "systemLocation": { "longitude": -174.5432, "latitude": -44.9878 } }, "stocksDisposed": [ { "numberOfFish": 5, "stockCode": "ANG13", "disposalCode": "E", "estimatedGreenWeightKg": 23 } ] }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/tuna-lining/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/tuna-lining/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

Response

Response Status:

Status Description
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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String

Start Location See Geolocation Set Parameters below.

Geolocation Set
Line Length Nm Number
Number of Hooks Number
Number of Floats Number
Number of Lightsticks Number
Line Shooter Boolean
Bait Type % - Fish Number
Bait Type % - Squid Number
Bait Type % - Other Number
Bait Type % - Artificial Number
Is Line Lost Boolean
Start of Haul Location See Geolocation Set Parameters below. Geolocation Set
End of Set Location See Geolocation Set Parameters below. Geolocation Set
Finish Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish Or Protected Species Catch Present Boolean
Completed Date Time String
Catches See Catches Parameters below. Array of catch
Stocks Disposed See Stocks Disposed Parameters below. Array of stocks disposed
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location See Geolocation Parameters below. Geolocation
Manual Location See Geolocation Parameters below. Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees


Catches Parameters:

ParameterData Type
Species Code String
Product State Code String
Processed Weight Kg Number
Number of Fish Number

Stocks Disposed Parameters:

ParameterData Type
Stock Code String
Disposal Code String
Estimated Green Weight Kg Number
Number of Fish Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Tuna Lining Get Request Body Example:

{
  "event": {
    "lineLengthNm": 99.7,
    "numberOfHooks": 66,
    "numberOfFloats": 4,
    "numberOfLightsticks": 3,
    "lineShooter": true,
    "baitTypePercentFish": 25,
    "baitTypePercentSquid": 50,
    "baitTypePercentOther": 25,
    "baitTypePercentArtifical": 0,
    "endOfSetLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5432,
        "latitude": -44.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "isLineLost": false,
    "startOfHaulLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5432,
        "latitude": -44.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "fishingMethodCode": "SLL",
    "targetSpeciesCode": "SNA",
    "mitigationDeviceCodes": [
      "OTH",
      "LAS"
    ],
    "startLocation": {
      "systemDateTime": "2017-05-24T08:01:00+13:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.9878
      },
      "manualDateTime": "2017-05-24T09:15:00+13:00",
      "manualLocation": {
        "longitude": -176.5432,
        "latitude": -46.9878
      }
    },
    "finishLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5432,
        "latitude": -44.9878
      },
      "manualDateTime": "2017-05-24T13:33:00+13:00",
      "manualLocation": {
        "longitude": -173.5432,
        "latitude": -43.9878
      }
    },
    "isNonFishOrProtectedSpeciesCatchPresent": true,
    "catches": [
      {
        "speciesCode": "SNA",
        "productStateCode": "FIN",
        "processedWeightKg": 29,
        "numberOfFish": 3
      }
    ],
    "nonFishOrProtectedSpeciesCatches": [
      {
        "speciesCode": "XAF",
        "seabirdCaptureCode": "S",
        "estimatedWeightKg": 4,
        "numberUninjured": 4,
        "numberInjured": 1,
        "numberDead": 0,
        "tags": null
      }
    ],
    "eventId": "TL017",
    "tripId": "TL013",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8491346",
    "completedDateTime": "2017-05-29T09:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Some notes",
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/tuna-lining/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/tuna-lining/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeDescription
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Tuna Lining Update Request Body Example:

  {
  "eventHeader": {
    "eventId": "TL017",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": null,
    "tripId": "TL013",
    "amendmentReason": "Audit error",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "SLL", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["OTH", "LAS"], "startLocation": { "systemDateTime": "2017-05-24T08:01:00+13:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 }, "manualDateTime": "2017-05-24T09:15:00+13:00", "manualLocation": { "longitude": -176.5432, "latitude": -46.9878 } }, "finishLocation": { "systemDateTime": "2017-05-24T12:30:00+13:00", "systemLocation": { "longitude": -174.5432, "latitude": -44.9878 }, "manualDateTime": "2017-05-24T13:33:00+13:00", "manualLocation": { "longitude": -173.5432, "latitude": -43.9878 } }, "isNonFishOrProtectedSpeciesCatchPresent": true, "catches": [ { "speciesCode": "SNA", "processedWeightKg": 29, "productStateCode": "FIN", "numberOfFish": 3 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "XAF", "seabirdCaptureCode": "S", "estimatedWeightKg": 4, "numberUninjured": 4, "numberInjured": 1, "numberDead": 0, "tags": null } ], "lineLengthNm": 99.7, "numberOfHooks": 66, "numberOfFloats": 4, "numberOfLightsticks": 3, "lineShooter": true, "baitTypePercentFish": 25, "baitTypePercentSquid": 50, "baitTypePercentOther": 25, "baitTypePercentArtifical": 0, "endOfSetLocation": { "systemDateTime": "2017-05-24T12:30:00+13:00", "systemLocation": { "longitude": -174.5432, "latitude": -44.9878 } }, "isLineLost": false, "startOfHaulLocation": { "systemDateTime": "2017-05-24T12:30:00+13:00", "systemLocation": { "longitude": -174.5432, "latitude": -44.9878 } }, "stocksDisposed": [ { "numberOfFish": 5, "stockCode": "ANG13", "disposalCode": "E", "estimatedGreenWeightKg": 23 } ] }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeDescription
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeDescription
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Other Lining Event

The sections below describe the information necessary to create, get and update an Other Lining event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
23/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
29/05/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/other-lining/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/other-lining/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the HL method must be reported through the lining Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Maximum Number of Lines Used Mandatory Number Must be a whole number.

Must be 0 or greater.

Maximum Number of Hooks Used Mandatory Number Must be a whole number.

Must be 0 or greater.

Finish Location Mandatory Geolocation Set See Finish Geolocation Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught.

See Catches Parameters below.

Non Fish or Protected Species Catches Conditional Array of NFPS records Can have zero or many NFPS records.

Must have at least one if 'Is Non Fish Or Protected Species Catch Present' is True.

If 'Is Non Fish Or Protected Species Catch Present' is False and NFPS catch provided, ERS will accept the event.

See Non Fish or Protected Species Catches Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against NFPS master data.

Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Other Lining Create Request Body Example:

{
  "eventHeader": {
    "eventId": "123",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "tripId": "999",
    "completedDateTime": "2017-01-01T08:00:00+13:00",
    "notes" : "Other Lining Create - TEST",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "T", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["DDD"], "startLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 } }, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": "174.6799", "latitude": "-41.4289" } }, "isNonFishOrProtectedSpeciesCatchPresent": false, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 23.75 } ], "nonFishOrProtectedSpeciesCatches": [], "maximumNumberOfLinesUsed": 3, "maximumNumberOfHooksUsed": 3 }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/other-lining/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/other-lining/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish Or Protected Species Catch Present Boolean
Maximum Number of Lines Hauled Number
Maximum Number of Hooks Used Number
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Catches See Catches Parameters below. Array of Catches
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Other Lining Get Request Body Example:

{
    "event": {
        "maximumNumberOfLinesUsed": 3,
        "maximumNumberOfHooksUsed": 3,
        "fishingMethodCode": "T",
        "targetSpeciesCode": "SNA",
        "mitigationDeviceCodes": [
        "DDD"
        ],
        "startLocation": {
            "systemDateTime": "2017-04-10T09:15:00+11:00",
            "systemLocation": {
                "longitude": -175.5432,
                "latitude": -45.9878
            },
            "manualDateTime": null,
            "manualLocation": null
        },
        "finishLocation": {
            "systemDateTime": "2017-04-10T09:15:00+11:00",
            "systemLocation": {
                "longitude": 174.6799,
                "latitude": -41.4289
            },
            "manualDateTime": null,
            "manualLocation": null
        },
        "isNonFishOrProtectedSpeciesCatchPresent": false,
        "catches": [
            {
                "speciesCode": "SNA",
                "greenWeightEstimateKg": 50.25,
            },
            {
                "speciesCode": "HOK",
                "greenWeightEstimateKg": 23.75,
            }
        ],
        "nonFishOrProtectedSpeciesCatches": [],
        "tripId": "999",
        "vesselNumber": "1",
        "isVesselUsed": true,
        "eventId": "123",
        "schemaEdition": 1,
        "eventVersion": 1,
        "clientNumber": "8462926",
        "completedDateTime": "2017-01-01T08:00:00+13:00",
        "eventDateTime": "2017-04-10T09:15:00+11:00",
        "notes": "Other Lining Create - TEST",
        "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/other-lining/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/other-lining/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Other Lining Update Request Body Example:

{
  "eventHeader": {
    "eventId": "123",
    "eventVersion": "1",
    "tripId": "999",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Comments",
    "amendmentReason": "wrong greenweight recorded for hoki",
    "softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "T", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["DDD"], "startLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 }, "manualDateTime": null, "manualLocation": null }, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": 174.6799, "latitude": -41.4289 }, "manualDateTime": null, "manualLocation": null }, "isNonFishOrProtectedSpeciesCatchPresent": false, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 24.75 } ], "nonFishOrProtectedSpeciesCatches": [], "maximumNumberOfLinesUsed": 3, "maximumNumberOfHooksUsed": 3 }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Hand Gathering Event

The sections below describe the information necessary to create, get and update a Hand Gathering event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
19/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
29/05/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/hand-gathering/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/hand-gathering/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the H method must be reported through the hand gathering Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Number of People Mandatory Number Must be a whole number.

Must be greater than 0.

Time Spent Hours Mandatory Number Must be a whole number.

Must be greater than 0.

Round up.

Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught.

See Catches Parameters below.

Non Fish or Protected Species Catches Conditional Array of NFPS records Can have zero or many NFPS records.

Must have at least one if 'Is Non Fish Or Protected Species Catch Present' is True.

If 'Is Non Fish Or Protected Species Catch Present' is False and NFPS catch provided, ERS will accept the event.

See Non Fish or Protected Species Catches Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against NFPS master data.

Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Hand Gathering Create Request Body Example:

{
  "eventHeader": {
  "eventId": "qweasd123",
  "isVesselUsed": false,
  "notes": "Hand gathering CREATE - TEST",
  "tripId": "111",
  "completedDateTime": "2017-01-01T08:00:00+13:00",
  "softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "numberOfPeople": 1, "timeSpentHours": 1, "isNonFishOrProtectedSpeciesCatchPresent": false, "fishingMethodCode": "H", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["STR"], "startLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 } }, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": "174.6799", "latitude": "-41.4289" } }, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 23.75 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "XAF", "estimatedWeightKg": null, "seabirdCaptureCode": "", "numberUninjured": 1, "numberInjured": null, "numberDead": null, "tags": null }, { "speciesCode": "DEN", "estimatedWeightKg": 5.5, "numberUninjured": null, "numberInjured": null, "numberDead": null, "tags": ["SG101", "SG105", "SG305", "SG501"] } ] }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/hand-gathering/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/hand-gathering/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish Or Protected Species Catch Present Boolean
Number of People Number
Time Spent Hours Number
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Catches See Catches Parameters below. Array of Catches
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Hand Gathering Get Request Body Example:

{
    "event": {
        "numberOfPeople": 1,
        "timeSpentHours": 1,
        "fishingMethodCode": "H",
        "targetSpeciesCode": "SNA",
        "mitigationDeviceCodes": [
            "STR"
        ],
        "startLocation": {
            "systemDateTime": "2017-04-10T09:15:00+11:00",
            "systemLocation": {
                "longitude": -175.5432,
                "latitude": -45.9878
            },
            "manualDateTime": null,
            "manualLocation": null
        },
        "finishLocation": {
            "systemDateTime": "2017-04-10T09:15:00+11:00",
            "systemLocation": {
                "longitude": 174.6799,
                "latitude": -41.4289
            },
            "manualDateTime": null,
            "manualLocation": null
        },
        "isNonFishOrProtectedSpeciesCatchPresent": false,
        "catches": [
            {
                "speciesCode": "SNA",
                "greenWeightEstimateKg": 50.25,
            },
            {
                "speciesCode": "HOK",
                "greenWeightEstimateKg": 23.75,
            }
        ],
        "nonFishOrProtectedSpeciesCatches": [
            {
                "speciesCode": "XAF",
                "seabirdCaptureCode": "",
                "estimatedWeightKg": null,
                "numberUninjured": 1,
                "numberInjured": null,
                "numberDead": null,
                "tags": null
            },
            {
                "speciesCode": "DEN",
                "seabirdCaptureCode": null,
                "estimatedWeightKg": 5.5,
                "numberUninjured": null,
                "numberInjured": null,
                "numberDead": null,
                "tags": [
                    "SG101",
                    "SG105",
                    "SG305",
                    "SG501"
                ]
            }
        ],
        "tripId": "111",
        "vesselNumber": null,
        "isVesselUsed": false,
        "eventId": "qweasd123",
        "schemaEdition": 1,
        "eventVersion": 1,
        "clientNumber": "8462926",
        "completedDateTime": "2017-01-01T08:00:00+13:00",
        "notes": "Hand gathering - TEST",
        "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/hand-gathering/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/hand-gathering/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Hand Gathering Update Request Body Example:

{
  "eventHeader": {
  "eventId": "qweasd123",
  "isVesselUsed": false,
  "notes": "Hand gathering UPDATE - TEST",
  "tripId": "111",
  "eventVersion": 1,
  "amendmentReason": "Wrong species code used ",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "numberOfPeople": 8, "timeSpentHours": 8, "isNonFishOrProtectedSpeciesCatchPresent": false, "fishingMethodCode": "H", "targetSpeciesCode": "HOK", "mitigationDeviceCodes": ["ACC"], "startLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": -175.5432, "latitude": -44.9878 } }, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": "174.6799", "latitude": "-44.4289" } }, "catches": [ { "speciesCode": "GSH", "greenWeightEstimateKg": 55.55 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 44.44 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "XAF", "estimatedWeightKg": 8, "seabirdCaptureCode": "", "numberUninjured": 8, "numberInjured": 8, "numberDead": 8, "tags": 8 }, { "speciesCode": "DEN", "estimatedWeightKg": 5.5, "numberUninjured": 8, "numberInjured": 8, "numberDead": 8, "tags": ["SG101", "SG105", "SG305", "SG501"] } ] }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Diving Event

The sections below describe the information necessary to create, get and update a Diving event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017

Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.

29/08/2017

Updated Request Header to include Signature instead of Bearer Token.

22/08/2017

Finish and Start location fields moved to the Divers Array. 

Removed the common catch collection, only the divers catch will be required.

New field, 'Total Diving Time Minutes', added to the divers array.

21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here.
14/07/2017 Attribute Diver Catch relabelled to Diver Catches and Diver Details relabelled to Divers.
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
22/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
29/05/2017 Initial publication.

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/diving/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/diving/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the DI method must be reported through the diving Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Swell Metres Mandatory Number Decimal to 2dp.

Must be 0 or greater.

Visibility Metres Mandatory Number Must be a whole number.

Must be 0 or greater.

Was Boat Person Used Conditional Boolean Must be provided if 'Fish Species' master data property 'require_boat_person_used = true'.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Non Fish or Protected Species Catches Conditional Array of NFPS records Can have zero or many NFPS records.

Must have at least one if 'Is Non Fish Or Protected Species Catch Present' is True.

If 'Is Non Fish Or Protected Species Catch Present' is False and NFPS catch provided, ERS will accept the event.

See Non Fish or Protected Species Catches Parameters below.

Divers Mandatory Array of Divers See Divers Parameters below.

Must have at least one diver record.

Can have many divers associated with the event.

Catch details are also recorded against each diver.

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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.


Divers Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Diver ID or Name Mandatory String Maximum of 50 characters. 
Total Diving Time Hours Mandatory Number Must be a whole number.

Must be greater than 0.

Total Diving Time Minutes Mandatory Number Must be a whole number.

Must be between 0 and 59, inclusive.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Diver Catches Optional Array of Diver Catches See Diver Catches Parameters below.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Diver Catches Parameters:

Note that, only the diver catches details are required. ERS will reject the event if the common catch block is provided for diving.

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.

Validated against Fish Species ERS master data.

Species code that is not allowed is defined in 'Fish Species' master data property 'not_allowed_for_diving = true'.

Estimated Catch Kg Mandatory Number Decimal to 2dp.

Must be greater than 0.

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against NFPS master data.

Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Diving Create Request Body Example:

{
"eventHeader": {
"eventId": "abcde",
"tripId": "tr1",
"vesselNumber": "92",
"isVesselUsed": true,
"completedDateTime": "2017-10-22T12:30:00+13:00",
"notes": "Single diver - TEST",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234"
},

"fishingMethodCode": "DI",
"targetSpeciesCode": "MRQ",
"mitigationDeviceCodes":["SBS"],

"swellMetres": 1.25,
"visibilityMetres": 10,
"wasBoatPersonUsed": false,

"isNonFishOrProtectedSpeciesCatchPresent": false,
"nonFishOrProtectedSpeciesCatches": [
{
"speciesCode": "ORT",
"estimatedWeightKg": 22024.35,
"numberUninjured": 18881,
"numberInjured": 13121,
"numberDead": 10966,
"tags": null
}
],

"divers": [
{
"diverIdOrName": "DiverAlex",
"totalDivingTimeHours": 8,
"totalDivingTimeMinutes": 56,

"startLocation": {
"systemDateTime": "2017-10-22T08:34:23+11:00",
"systemLocation": {
"longitude": "174.706405",
"latitude": "-41.357214"
}
},

"finishLocation": {
"systemDateTime": "2017-10-22T11:52:33+13:00",
"systemLocation": {
"longitude": "174.706519",
"latitude": "-41.357134"
}
},
"diverCatches": [
{"speciesCode": "PAA", "estimatedCatchKg": 187.75},
{"speciesCode": "PAI", "estimatedCatchKg": 66.75}
]
}
]
}

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/diving/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/diving/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Is Non Fish Or Protected Species Catch Present Boolean
Divers See Divers Parameters below. Array of Divers
Swell Metres Number
Visibility Metres Number
Was Boat Person Used Boolean
Completed Date Time String
Catches See Catches Parameters below. Array of Catches
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String


Divers Parameters:

ParameterData Type
Diver ID or Name String
Total Diving Time Hours Number
Total Diving Time Minutes Number
Start Location See Geolocation Set Parameters below. Geolocation Set
Finish Location See Geolocation Set Parameters below. Geolocation Set
Diver Catches See Diver Catches Parameters below. Array of Diver Catches

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Diver Catches Parameters:

ParameterData Type
Species Code String
Estimated Catch Kg Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Diving Get Request Body Example:

{
"event": {
"swellMetres": 1.25,
"visibilityMetres": 10,
"wasBoatPersonUsed": false,
"divers": [
{
"diverIdOrName": "DiverAlex",
"totalDivingTimeHours": 8,
"totalDivingTimeMinutes": 56,
"startLocation": {
"systemDateTime": "2017-10-22T08:34:23+11:00",
"systemLocation": {
"longitude": 174.706405,
"latitude": -41.357214
},
"manualDateTime": null,
"manualLocation": null
},
"finishLocation": {
"systemDateTime": "2017-10-22T11:52:33+13:00",
"systemLocation": {
"longitude": 174.706519,
"latitude": -41.357134
},
"manualDateTime": null,
"manualLocation": null
},
"diverCatches": [
{
"speciesCode": "PAA",
"estimatedCatchKg": 187.75
},
{
"speciesCode": "PAI",
"estimatedCatchKg": 66.75
}
]
}
],
"fishingMethodCode": "DI",
"targetSpeciesCode": "MRQ",
"mitigationDeviceCodes": [
"SBS"
],
"isNonFishOrProtectedSpeciesCatchPresent": false,
"nonFishOrProtectedSpeciesCatches": [
{
"speciesCode": "ORT",
"seabirdCaptureCode": null,
"estimatedWeightKg": 22024.35,
"numberUninjured": 18881,
"numberInjured": 13121,
"numberDead": 10966,
"tags": null
}
],
"tripId": "tr1",
"vesselNumber": "92",
"isVesselUsed": true,
"eventId": "abcde",
"schemaEdition": 1,
"eventVersion": 1,
"clientNumber": "1234567",
"completedDateTime": "2017-10-22T12:30:00+13:00",
"eventDateTime": "2017-10-22T08:34:23+11:00",
"notes": "Single diver - TEST",
"amendmentReason": null,
"completedByName": "Dirk Munroe"
},
"errors": []
}

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/diving/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/diving/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Diving Update Request Body Example:

 
{
"eventHeader": {
"eventId": "abcde",
"eventVersion": 1,
"vesselNumber": "92",
"isVesselUsed": true,
"completedDateTime": null,
"tripId": "hhh",
"amendmentReason": "Update species code to PAA",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234"
},

"fishingMethodCode": "DI",
"targetSpeciesCode": "PAA",
"mitigationDeviceCodes":["ACC"],

"swellMetres": 1.25,
"visibilityMetres": 10,
"wasBoatPersonUsed": true,

"isNonFishOrProtectedSpeciesCatchPresent": false,
"nonFishOrProtectedSpeciesCatches": [],

"divers": [
{
"diverIdOrName": "DiverAlex",
"totalDivingTimeHours": 8,
"totalDivingTimeMinutes": 56,

"startLocation": {
"systemDateTime": "2017-10-22T08:34:23+11:00",
"systemLocation": {
"longitude": "174.706405",
"latitude": "-41.357214"
}
},

"finishLocation": {
"systemDateTime": "2017-10-22T11:52:33+13:00",
"systemLocation": {
"longitude": "174.706519",
"latitude": "-41.357134"
}
},
"diverCatches": [
{"speciesCode": "PAA", "estimatedCatchKg": 187.75},
{"speciesCode": "PAI", "estimatedCatchKg": 66.75}
]
}
]
}

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Seining Event

The sections below describe the information necessary to create, get and update a Seining event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
19/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
29/05/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/seining/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/seining/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the PS method must be reported through the seining Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Total Net Length And Warps Metres Conditional Number Must be a whole number.

Must be provided if 'Fishing Method' master data property 'require_net_details = true'.

Reject if provided for other methods.

Must be greater than 0.

Ground Rope Length Metres Conditional Number Must be a whole number.

Must be provided if 'Fishing Method' master data property 'require_rope_details = true'.

Reject if provided for other methods.

Must be greater than 0.

Is Spotter Used Conditional Boolean Must be provided if 'Fishing Method' master data property 'require_spotter_used = true'.

Reject if provided for other methods.

Spotter Call Sign Conditional String Must be provided if 'Is Spotter Used' = True.

If 'Is Spotter Used' = False and fisher provides a call sign, ERS will accept the event.

Maximum of 100 characters allowed.

Number of Lifts Conditional Number Must be a whole number.

Must be provided if 'Fishing Method' master data property 'require_number_of_lifts = true'.

Reject if provided for other methods.

Must be greater than 0.

Estimated Catch Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater.

If estimated catch > 0, then Catch must be provided.

If estimated catch = 0 and Catch is provided, the ERS will still accept the event.

Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught

See Catches Parameters below.

Non Fish or Protected Species Catches Conditional Array of NFPS records Can have zero or many NFPS records.

Must have at least one if 'Is Non Fish Or Protected Species Catch Present' is True.

If 'Is Non Fish Or Protected Species Catch Present' is False and NFPS catch provided, ERS will accept the event.

See Non Fish or Protected Species Catches Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against NFPS master data.

Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Seining Create Request Body Example:

{
  "eventHeader": {
    "eventId": "S0111",
    "completedDateTime": "2017-04-30T08:00:00+13:00",
    "tripId": "seiningtrip1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "DPN", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["ACC", "BIB"], "startLocation": { "systemDateTime": "2017-05-24T08:01:00+13:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 }, "manualDateTime": "2017-05-24T09:15:00+13:00", "manualLocation": { "longitude": -176.5432, "latitude": -46.9878 } }, "finishLocation": { "systemDateTime": "2017-05-24T12:30:00+13:00", "systemLocation": { "longitude": -174.5432, "latitude": -44.9878 }, "manualDateTime": "2017-05-24T13:33:00+13:00", "manualLocation": { "longitude": -173.5432, "latitude": -43.9878 } }, "isNonFishOrProtectedSpeciesCatchPresent": false, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "CRA", "greenWeightEstimateKg": 23.75 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 23.75 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "XAF", "estimatedWeightKg": 4, "numberUninjured": 4, "numberInjured": 1, "numberDead": 0, "tags": null } ], "groundRopeLengthMetres": null, "spotterCallSign": null, "isSpotterUsed": null, "numberOfLifts": 6, "estimatedCatchKg": 87.5 }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/seining/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/seining/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish Or Protected Species Catch Present Boolean
Total Net Length And Warps Metres Number
Ground Rope Length Metres Number
Is Spotter Used Boolean
Spotter Call Sign String
Number of Lifts Number
Estimated Catch Kg Number
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Catches See Catches Parameters below. Array of Catches
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Seining Get Request Body Example:

{
    "event": {
        "totalNetLengthAndWarpsMetres": null,
        "groundRopeLengthMetres": null,
        "isSpotterUsed": null,
        "spotterCallSign": null,
        "numberOfLifts": 6,
        "estimatedCatchKg": 87.5,
        "fishingMethodCode": "DPN",
        "targetSpeciesCode": "SNA",
        "mitigationDeviceCodes": [
            "ACC",
            "BIB"
        ],
        "startLocation": {
            "systemDateTime": "2017-05-24T08:01:00+13:00",
            "systemLocation": {
                "longitude": -175.5432,
                "latitude": -45.9878
            },
            "manualDateTime": "2017-05-24T09:15:00+13:00",
            "manualLocation": {
                "longitude": -176.5432,
                "latitude": -46.9878
            }
        },
        "finishLocation": {
            "systemDateTime": "2017-05-24T12:30:00+13:00",
            "systemLocation": {
                "longitude": -174.5432,
                "latitude": -44.9878
            },
            "manualDateTime": "2017-05-24T13:33:00+13:00",
            "manualLocation": {
                "longitude": -173.5432,
                "latitude": -43.9878
            }
        },
        "isNonFishOrProtectedSpeciesCatchPresent": false,
        "catches": [
            {
                "speciesCode": "SNA",
                "greenWeightEstimateKg": 50.25,
            },
            {
                "speciesCode": "CRA",
                "greenWeightEstimateKg": 23.75,
            },
            {
                "speciesCode": "HOK",
                "greenWeightEstimateKg": 23.75,
            }
        ],
        "nonFishOrProtectedSpeciesCatches": [
            {
                "speciesCode": "XAF",
                "seabirdCaptureCode": null,
                "estimatedWeightKg": 4,
                "numberUninjured": 4,
                "numberInjured": 1,
                "numberDead": 0,
                "tags": null
            }
        ],
        "tripId": "seiningtrip1",
        "vesselNumber": "1",
        "isVesselUsed": true,
        "eventId": "S0111",
        "schemaEdition": 1,
        "eventVersion": 1,
        "clientNumber": "8491346",
        "completedDateTime": "2017-04-30T08:00:00+13:00",
        "notes": "Some notes",
        "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/seining/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/seining/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Seining Update Request Body Example:

{
  "eventHeader": {
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf91",
    "vesselNumber": "123",
    "isVesselUsed": true,
    "eventVersion": 1,
    "notes" : "Some notes",
    "completedDateTime" : null,
    "amendmentReason" : "Catch reported against incorrect stock.",
"tripId": "589",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "PS", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["SLE"], "startLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "isNonFishOrProtectedSpeciesCatchPresent": true, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": "174.6799", "latitude": "-41.4289" } }, "catches": [ { "speciesCode": "HOK", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "SNA", "greenWeightEstimateKg": 23.75 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "FUG", "estimatedWeightKg": 88.88, "numberUninjured": 8, "numberInjured": 8, "numberDead": 8, "tags": null }, ] "totalNetLengthAndWarpsMetres": 5, "groundRopeLengthMetres": null, "spotterCallSign": "CS1234", "isSpotterUsed": true, "numberOfLifts": null, "estimatedCatchKg": 87.5 }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Jigging Event

The sections below describe the information necessary to create, get and update a Jigging event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Reuqest Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here.
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
21/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
29/05/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/jigging/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/jigging/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the SJ method must be reported through the jigging Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Deepest Lure Depth Metres Mandatory Number Must be a whole number.

Must be greater than 0.

Bottom Depth Metres Mandatory Number Must be a whole number.

Must be greater than 0.

Number of Single Reels Mandatory Number Must be a whole number.

Must be 0 or greater.

Number of Double Reels Mandatory Number Must be a whole number.

Must be 0 or greater.

Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught

See Catches Parameters below.

Non Fish or Protected Species Catches Conditional Array of NFPS records Can have zero or many NFPS records.

Must have at least one if 'Is Non Fish Or Protected Species Catch Present' is True.

If 'Is Non Fish Or Protected Species Catch Present' is False and NFPS catch provided, ERS will accept the event.

See Non Fish or Protected Species Catches Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against NFPS master data.

Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Jigging Create Request Body Example:

{
  "eventHeader": {
    "eventId": "JE0111",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "2017-04-30T08:00:00+13:00",
    "tripId": "jiggingtrip1",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "SJ", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["SLE"], "startLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 } }, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": "174.6799", "latitude": "-41.4289" } }, "isNonFishOrProtectedSpeciesCatchPresent": false, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "CRA", "greenWeightEstimateKg": 23.75 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 23.75 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "XAF", "estimatedWeightKg": 4, "numberUninjured": 4, "numberInjured": 1, "numberDead": 0, "tags": null } ], "deepestLureDepthMetres": 55, "bottomDepthMetres": 44, "numberOfSingleReels": 677, "numberOfDoubleReels": 986 }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/jigging/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/jigging/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish Or Protected Species Catch Present Boolean
Deepest Lure Depth Metres Number
Bottom Depth Metres Number
Number of Single Reels Number
Number of Double Reels Number
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Catches See Catches Parameters below. Array of Catches
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Jigging Get Request Body Example:

{
  "event": {
    "deepestLureDepthMetres": 55,
    "bottomDepthMetres": 44,
    "numberOfSingleReels": 677,
    "numberOfDoubleReels": 986,
    "fishingMethodCode": "SJ",
    "targetSpeciesCode": "SNA",
    "mitigationDeviceCodes": [
      "SLE"
    ],
    "startLocation": {
      "systemDateTime": "2017-04-10T09:15:00+11:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "finishLocation": {
      "systemDateTime": "2017-04-10T09:15:00+11:00",
      "systemLocation": {
        "longitude": 174.6799,
        "latitude": -41.4289
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "isNonFishOrProtectedSpeciesCatchPresent": false,
    "catches": [
      {
        "speciesCode": "SNA",
        "greenWeightEstimateKg": 50.25,
      },
      {
        "speciesCode": "CRA",
        "greenWeightEstimateKg": 23.75,
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
      }
    ],
    "nonFishOrProtectedSpeciesCatches": [
      {
        "speciesCode": "XAF",
        "seabirdCaptureCode": null,
        "estimatedWeightKg": 4,
        "numberUninjured": 4,
        "numberInjured": 1,
        "numberDead": 0,
        "tags": null
      }
    ],
    "tripId": "jiggingtrip1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "JE0111",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8491346",
    "completedDateTime": "2017-04-30T08:00:00+13:00",
    "notes": null,
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/jigging/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/jigging/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Jigging Update Request Body Example:

{
  "eventHeader": {
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf91",
    "vesselNumber": "123",
    "isVesselUsed": true,
    "eventVersion": 1,
    "notes" : "Some notes",
    "completedDateTime" : null,
    "amendmentReason" : "Catch reported against incorrect stock.",
"tripId": "jiggingtrip1",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "SJ", "targetSpeciesCode": "SQU", "mitigationDeviceCodes": ["SLE"], "startLocation": { "systemDateTime": "2017-04-01T08:00:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 }, "manualDateTime": "2017-04-01T08:00:00+13:00", "manualLocation": { "longitude": -175.1025, "latitude": -45.9878 } },
"isNonFishOrProtectedSpeciesCatchPresent": true, "finishLocation": { "systemDateTime": "2017-01-011T12:30:00+13:00", "systemLocation": { "longitude": -175.1025, "latitude": -45.9878 }, "manualDateTime": "2017-01-01T12:30:00+13:00", "manualLocation": { "longitude": -175.1025, "latitude": -45.9878 } }, "catches": [ { "speciesCode": "HOK", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "SNA", "greenWeightEstimateKg": 23.75 } ], "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "FUG", "estimatedWeightKg": 88.88, "numberUninjured": 8, "numberInjured": 8, "numberDead": 8, "tags": null } ], "deepestLureDepthMetres": 55, "bottomDepthMetres": 44, "numberOfSingleReels": 677, "numberOfDoubleReels": 986 }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Dredging Event

The sections below describe the information necessary to create, get and update a Dredging event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here.
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
21/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
29/05/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/dredging/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/dredging/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Method Code Mandatory String

Must be a valid fishing method code for the Fishing Event Type.

Validated against Fishing Methods Master Data.

E.g. the D method must be reported through the dredging Fishing Event.

Mitigation Device Codes Optional Array of Strings Validated against the Mitigation Devices master data.
Target Species Code Mandatory String

Must be a valid species.

Validated against the Fish Species master data.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Is Non Fish Or Protected Species Catch Present Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.
Dredge Width Metres Conditional Number Decimal to 2dp.

Must be provided if 'Fishing Methods' master data property 'require_dredging_details = true'.

Must be greater than 0.

Fisher can provide for other Methods, ERS will not reject the event if provided.

Number of Tows Completed Conditional Number Must be a whole number.

Must be provided if 'Fishing Methods' master data property 'require_dredging_details = true'.

Must be greater than 0.

Fisher can provide for other Methods, ERS will not reject the event if provided.

Number of Devices Used Mandatory Number Must be a whole number.

Must be greater than 0.

Estimated Catch Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater.

If estimated catch > 0, then Catch must be provided.

If estimated catch = 0 and Catch is provided, ERS will still accept the event.

Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

Catches Optional Array of Catches Can be 0 or many Catch records.

Records all species caught

See Catches Parameters below.

Non Fish or Protected Species Catches Conditional Array of NFPS records Can have zero or many NFPS records.

Must have at least one if 'Is Non Fish Or Protected Species Catch Present' is True.

If 'Is Non Fish Or Protected Species Catch Present' is False and NFPS catch provided, ERS will accept the event.

See Non Fish or Protected Species Catches Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided.

See geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees, 4dp Minimum of 4dp required.
Longitude Mandatory decimal degrees, 4dp Minimum of 4dp required.

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String

Must be a valid ERS species code.

Validated against Fish Species master data.

Green Weight Estimate Kg Mandatory Number Decimal to 2dp.

Must be 0 or greater

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against NFPS master data.

Seabird Capture Code Conditional String Must be provided if 'NFPS' master data property 'is_seabird = true' & 'Fishing Methods' master data property 'require_seabird_capture_details = true'.

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Estimated Weight Kg Conditional Number Decimal to 2dp.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Must be greater than 0.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS Tag Number.

Dredging Create Request Body Example:

{
  "eventHeader": {
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf91",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "2017-01-01T12:30:00+13:00",
    "tripId": "123",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "D", "targetSpeciesCode": "SNA", "mitigationDeviceCodes": ["SLE"], "startLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 } }, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": "174.6799", "latitude": "-41.4289" } }, "isNonFishOrProtectedSpeciesCatchPresent": false, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "CRA", "greenWeightEstimateKg": 23.75 }, { "speciesCode": "HOK", "greenWeightEstimateKg": 23.75 } ], "dredgeWidthMetres": 55, "numberOfTowsCompleted": 44, "numberOfDevicesUsed": 677, "estimatedCatchKg": 986 }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/dredging/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/dredging/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Fishing Method Code String
Mitigation Device Codes Array of Strings
Target Species Code String
Start Location See Geolocation Set Parameters below. Geolocation Set
Is Non Fish Or Protected Species Catch Present Boolean
Dredge Width Metres Number
Number of Tows Completed Number
Number of Devices Used Number
Estimated Catch Kg Number
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Catches See Catches Parameters below. Array of Catches
Non Fish or Protected Species Catches See Non Fish or Protected Species Catches Parameters below. Array of NFPS records
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Location

See Geolocation Parameters below

Geolocation
Manual Location

See Geolocation Parameters below

Geolocation
System Date Time String
Manual Date Time String

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

Dredging Get Request Body Example:

{
  "event": {
    "dredgeWidthMetres": 55,
    "numberOfTowsCompleted": 44,
    "numberOfDevicesUsed": 677,
    "estimatedCatchKg": 986,
    "fishingMethodCode": "D",
    "targetSpeciesCode": "SNA",
    "mitigationDeviceCodes": [
      "SLE"
    ],
    "startLocation": {
      "systemDateTime": "2017-04-10T09:15:00+11:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "finishLocation": {
      "systemDateTime": "2017-04-10T09:15:00+11:00",
      "systemLocation": {
        "longitude": 174.6799,
        "latitude": -41.4289
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "isNonFishOrProtectedSpeciesCatchPresent": false,
    "catches": [
      {
        "speciesCode": "SNA",
        "greenWeightEstimateKg": 50.25,
      },
      {
        "speciesCode": "CRA",
        "greenWeightEstimateKg": 23.75,
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
      }
    ],
    "nonFishOrProtectedSpeciesCatches": [],
    "tripId": "123",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "f763a44e-101a-a997-6044-74928accf8f6",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8462926",
    "completedDateTime": "2017-01-01T12:30:00+13:00",
    "notes": null,
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/dredging/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/dredging/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Dredging Update Request Body Example:

  {
  "eventHeader": {
    "eventId": "f763a44e-101a-a997-6044-74928accf8f6",
    "eventVersion": 2,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "TEST UPDATE - Golden Path",
    "amendmentReason": "Incorrect species codes used.",
    "tripId": "123",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingMethodCode": "MH", "targetSpeciesCode": "HOK", "startLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": -175.5432, "latitude": -44.9878 } }, "finishLocation": { "systemDateTime": "2017-04-10T09:15:00+11:00", "systemLocation": { "longitude": "174.6799", "latitude": "-44.4289" } }, "isNonFishOrProtectedSpeciesCatchPresent": false, "catches": [ { "speciesCode": "SNA", "greenWeightEstimateKg": 50.25 }, { "speciesCode": "CRA", "greenWeightEstimateKg": 23.75 } ], "dredgeWidthMetres": 88, "numberOfTowsCompleted": 88, "numberOfDevicesUsed": 99, "estimatedCatchKg": 99 }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Trip Start Event

The sections below describe the information necessary to create, get and update a Trip Start event.

Change history
Date Change
19/09/2017

Changed manual location details to only require a minimum of 3dp.

11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
29/06/2017 Updated example message for CREATE and UPDATE.
22/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
09/06/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trip-start/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trip-start/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Person in Charge Mandatory String Must be at least 2 characters.

Maximum of 200 characters allowed.

Start Location Mandatory Geolocation Set See Geolocation Set Parameters 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.

Trip ID Mandatory String

Must not exist in any other trip start event for the vessel number.

If no vessel used, then must not exist in any other trip start event for the client number.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation

At least one group of system or manual location parameters must be provided.

See Geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Longitude Mandatory decimal degrees 

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Trip Start Create Request Body Example:

{
  "eventHeader": {
    "eventId": "TripStartEvent006",
    "tripId": "t1",
    "completedDateTime": "2017-05-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Some notes.",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "personInCharge": "Sam Mont", "startLocation": { "systemDateTime": "2017-05-01T08:00:00+13:00", "systemLocation": { "longitude": "-175.5423", "latitude": "-45.9880" },
"manualDateTime": null,
"manualLocation": null
}
}

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trip-start/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trip-start/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Person in Charge String

Start Location

See Geolocation Set Parameters below.

Geolocation Set
Completed Date Time String
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Date Time String
Manual Date Time String

System Location

See Geolocation Parameters below.

Geolocation

Manual Location

See Geolocation Parameters below.

Geolocation

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees


Trip Start Get Request Body Example:

{
  "event": {
    "personInCharge": "Sam Mont",
    "startLocation": {
      "systemDateTime": "2017-05-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.5423,
        "latitude": -45.988
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "eventId": "TripStartEvent006",
    "tripId": "t1",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8491346",
    "completedDateTime": "2017-05-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Some notes",
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trip-start/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trip-start/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Trip Start Update Request Body Example:

  {
  "eventHeader": {
    "eventId": "TripStartEvent006",
    "tripId": "t1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventVersion": 1,
    "notes" : "Some additional notes",
    "amendmentReason": "Fix error",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "personInCharge": "Alan Turing", "startLocation": { "systemDateTime": "2017-05-01T08:00:00+13:00", "systemLocation": { "longitude": -175.5423, "latitude": -45.9881 }, "manualDateTime": null, "manualLocation": null } }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Trip End Event

The sections below describe the information necessary to create, get and update a Trip End event.

Change history
Date Change
19/09/2017

Changed manual location details to only require a minimum of 3dp.

11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
29/06/2017 Updated example message for CREATE and UPDATE.
22/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
09/06/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trip-end/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trip-end/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Person in Charge Mandatory String Must be at least 2 characters.

Maximum of 200 characters allowed.

End Location Mandatory Geolocation Set See Geolocation Set Parameters 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.

Trip ID Mandatory String Must not exist in any other trip end event for the vessel number.

If no vessel used, then must not exist in any other trip end event for the client number.

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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided. See Geolocation parameters below.
Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Longitude Mandatory decimal degrees 

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Trip End Create Request Body Example:

{
  "eventHeader": {
    "eventId": "TripEndEvent006",
    "tripId": "t1",
    "completedDateTime": "2017-05-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Some notes.",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": 1234567,
"completerUserId": "1234" }, "personInCharge": "Sam Mont", "endLocation": { "systemDateTime": "2017-05-01T08:00:00+13:00", "systemLocation": { "longitude": "-175.5423", "latitude": "-45.9880" },
"manualDateTime": null,
"manualLocation": null }
}

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trip-end/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trip-end/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

Response

Response Status:

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

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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Person in Charge String

End Location

See Geolocation Set Parameters below.

Geolocation Set
Completed Date Time String
Errors Array
Amendment Reason String

Geolocation Set Parameters:

ParameterData Type
System Date Time String
Manual Date Time String
System Location

See Geolocation Parameters below.

Geolocation
Manual Location

See Geolocation Parameters below.

Geolocation

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Trip End Get Request Body Example:

{
  "event": {
    "personInCharge": "Sam Mont",
    "endLocation": {
      "systemDateTime": "2017-05-01T08:00:00+13:00",
      "systemLocation": {
        "longitude": -175.5423,
        "latitude": -45.988
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "eventId": "TripEndEvent006",
    "tripId": "t1",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8491346",
    "completedDateTime": "2017-05-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Some notes.",
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trip-end/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/trip-end/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Trip End Update Request Body Example:

{
  "eventHeader": {
    "eventId": "TripEndEvent006",
    "tripId": "t1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventVersion": 1,
    "notes" : "Some additional notes",
    "amendmentReason": "Fix error",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "personInCharge": "Alan Turing", "endLocation": { "systemDateTime": "2017-05-01T08:00:00+13:00", "systemLocation": { "longitude": -175.5423, "latitude": -45.9881 }, "manualDateTime": null, "manualLocation": null } }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Non Fish or Protected Species (NFPS) Event

The sections below describe the information necessary to create, get and update a NFPS event.

Change history
Date Change
19/09/2017

Changed manual location details to only require a minimum of 3dp.

Added a new field "Fishing Event ID" to the body parameters.

Added a new field "Seabird Capture Code" to the NFPS Catch parameters.

11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
28/06/2017 Updated NFPS parameter field names from 'Count Injured', 'Count Uninjured' and 'Count Dead' to ''Number Injured', 'Number Uninjured' and 'Number Dead'.
22/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
12/06/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/non-fish-or-protected-species/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/non-fish-or-protected-species/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Event ID Optional String The ID of the fishing event where the NFPS were caught.
NFPS Catch Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Non Fish or Protected Species Catches Mandatory Array of NFPS catches records See Non Fish or Protected Species Catches Parameters below.

Must provide at least one non fish or protected species catch.

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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Geolocation Set Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Date Time Mandatory String Date 24 hr + UTC Offset.
Manual Date Time Optional String Date 24 hr + UTC Offset.
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided. See Geolocation parameters below.
Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Longitude Mandatory decimal degrees 

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Non Fish or Protected Species Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid species NFPS species code.

Validated against the NFPS master data.

Seabird Capture Code Optional String

Validated againt Seabird Capture Codes master data property 'Seabird_Capture_Code'.

Must not be provided if NFPS master data property 'is_seabird' is not true.

Estimated Weight Kg Conditional Number

Decimal to 2dp.

Must be greater than 0.

Must be provided if 'NFPS' master data property 'measured_by = weight'.

Number Uninjured Conditional Number

Must be a whole number.

Must be provided if 'NFPS' master data property 'measured_by = count'.

At least one of Number Uninjured, Number Injured or Number Dead must be provided.
Number Injured Conditional Number
Number Dead Conditional Number
Tag Optional Array of Strings NFPS tag number.

NFPS Create Request Body Example:

{
  "eventHeader": {
    "eventId": "NFPS111",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "2017-03-28T09:15:00+11:00",
    "tripId": "123",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingEventId": "12345", "nfpsCatchLocation": { "systemDateTime": "2017-05-01T08:00:00+13:00", "systemLocation": { "longitude": "-175.5423", "latitude": "-45.9880" }, "manualDateTime": "2017-05-01T08:00:00+13:00", "manualLocation": { "longitude": "-175.542", "latitude": "-45.988" } }, "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "ACN", "estimatedWeightKg": 182.23, "numberUninjured": null, "numberInjured": null, "numberDead": null, "tags": null }, { "speciesCode": "XYP",
"seabirdCaptureCode": "W", "estimatedWeightKg": null, "numberUninjured": 0, "numberInjured": 0, "numberDead": 1, "tags": ["SG101"] } ] }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/non-fish-or-protected-species/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/non-fish-or-protected-species/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String

NFPS Catch Location

See Geolocation Set Parameters below.

Geolocation Set
Completed Date Time String
Errors Array
Amendment Reason String

Fishing Event ID

String

Non Fish or Protected Species Catches

See Non Fish or Protected Species Catches Parameters below.

Array of NFPS catches records

Geolocation Set Parameters:

ParameterData Type
System Date Time String
Manual Date Time String

System Location

See Geolocation Parameters below.

Geolocation

Manual Location

See Geolocation Parameters below.

Geolocation

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Non Fish or Protected Species Catches Parameters:

ParameterData Type
Species Code String
Seabird Capture Code String
Estimated Weight Kg Number
Number Uninjured Number
Number Injured Number
Number Dead Number
Tag Array of Strings

NFPS Get Request Body Example:

  {
    "event": {
"fishingEventID": "12345", "nfpsCatchLocation": { "systemDateTime": "2017-05-01T08:00:00+13:00", "systemLocation": { "longitude": -175.5423, "latitude": -45.9880 }, "manualDateTime": "2017-05-01T08:00:00+13:00", "manualLocation": { "longitude": -175.542, "latitude": -45.988 } }, "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "ACN", "seabirdCaptureCode": null, "estimatedWeightKg": 182.23, "numberUninjured": null, "numberInjured": null, "numberDead": null, "tags": null }, { "speciesCode": "atp", "seabirdCaptureCode": null, "estimatedWeightKg": 1.4, "numberUninjured": 2, "numberInjured": 3, "numberDead": 5, "tags": [ "SG101", "SG105", "SG305", "SG501", "SG111" ] } ], "tripId": "123", "vesselNumber": "1", "isVesselUsed": true, "eventId": "NFPS111", "schemaEdition": 1, "eventVersion": 1, "clientNumber": "8491346", "completedDateTime": "2017-03-28T09:15:00+11:00", "notes": null, "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/non-fish-or-protected-species/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/non-fish-or-protected-species/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

NFPS Update Request Body Example:

  
{
  "eventHeader": {
    "eventId": "NFPS1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventVersion": 1,
    "tripId": "TS1",
    "amendmentReason": "Estimated weight for ACN recorded incorrectly",
    "notes":"NFPS Update",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "fishingEventId": "12345", "nfpsCatchLocation": { "systemDateTime": "2017-05-01T08:00:00+13:00", "systemLocation": { "longitude": "-166.5423", "latitude": "-44.9880" }, "manualDateTime": "2017-05-01T08:00:00+13:00", "manualLocation": { "longitude": "-155.542", "latitude": "-44.988" } }, "nonFishOrProtectedSpeciesCatches": [ { "speciesCode": "ACN", "estimatedWeightKg": 187.23, "numberUninjured": null, "numberInjured": null, "numberDead": null, "tags": null }, { "speciesCode": "XYP",
"seabirdCaptureCode": "W", "estimatedWeightKg": null, "numberUninjured": 0, "numberInjured": 0, "numberDead": 1, "tags": ["SG101"] } ] }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Processing Event

The sections below describe the information necessary to create, get and update a Processing event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
22/06/2017 Trip ID field added to the API actions CREATE, GET and UPDATE. Schema Edition and Event Version fields added to the API action GET. Some field name changes. Grouping of locations and dates into Geolocation Set Parameters and Geolocation Parameters.
12/06/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/processing/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/processing/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Processing Date Time Mandatory String Date 24hr + UTC offset.
Oil Litres Optional Number Must be a whole number.

Must be 0 or greater.

Products Mandatory Array of Products Must have at least one product record.

Can have many products associated with a processing event.

Species details are also recorded against each product.

See Products Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Products Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Product State Code Mandatory String

Must be a valid ERS product state code.

Validated against product-states master data.

Must have at least one Product State for a Processing event.

Species Conditional Array of species If Product States master data property 'allow_multiple_fish_codes' = 'True' then one or more species codes may be supplied within the species array.

Else, only one species code may be supplied within the species array.

See Species Parameters Array below.

Container Type Code Mandatory String Must be a valid ERS container type code.

Validated against containers master data.

Estimated Container Weight Kg Mandatory Number Decimal to 2dp.

Must be greater than 0.

Per container.

Container Count Mandatory Number Must be a whole number.

Must be greater than 0.

Total number of containers associated with the container type code.

Conversion Factor Conditional Number Decimal to 2dp.

Must be provided if 'Product States' master data property 'require_conversion_factor' = 'True' and must equal (in hierarchical order) one of the following:

  • Species-specific CF; else,
  • Species Category-specific CF

NOTE: If a Species/Product State combination supplied has a NULL CF in the Species-specific CF table, then combination of Species and Product State is an invalid one.

Species Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Conditional String Must be a valid ERS species code.

Validated against Fish Species Master Data.

Green Weight Kg Conditional Number Decimal to 2dp.

Must be provided and greater than '0' if 'Product States' master data property 'require_greenweight' = 'True'.

Otherwise, must not be provided.

Processing Create Request Body Example:

{
  "eventHeader": {
    "eventId": "256",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",  
    "completedDateTime": "2017-05-17T15:34:12+13:00",
    "tripId": "123",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "processingDateTime": "2017-05-17T15:34:12+13:00", "oilLitres": 98, "products": [ { "productStateCode": "DRE", "species": [ {"speciesCode":"KIN", "greenWeightKg":25.5} ], "containerTypeCode": "BAG", "containerCount": 2, "estimatedContainerWeightKg": 12.3, "conversionFactor": 1.6 }, { "productStateCode": "FIT", "species": [ { "speciesCode": "KIN", "greenWeightKg": null } ], "containerTypeCode": "SAC", "containerCount": 14, "estimatedContainerWeightKg": 99.9, "conversionFactor": null } ] }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/processing/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/processing/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Processing Date Time String
Completed Date Time String
Errors Array
Amendment Reason String
Oil Litres Number

Products

See Products Parameters below.

Array of Products

Products Parameters Array:

ParameterData Type
Product State Code String
Species

See Products Parameters below.

Array of Species
Container Type Code String
Estimated Container Weight Kg Number
Container Count Number
Conversion Factor Number

Species Parameters Array:

ParameterData Type
Species Code String
Green Weight Kg Number

Processing Get Request Body Example:

{
  "event": {
    "processingDateTime": "2017-05-17T15:34:12+13:00",
    "oilLitres": 98,
    "products": [
      {
        "productStateCode": "DRE",
        "species": [
          {
            "speciesCode": "KIN",
            "greenWeightKg": 25.5
          }
        ],
        "containerTypeCode": "BAG",
        "estimatedContainerWeightKg": 12.3,
        "containerCount": 2,
        "conversionFactor": 1.6
      },
      {
        "productStateCode": "FIT",
        "species": [
          {
            "speciesCode": "KIN",
            "greenWeightKg": null
          }
        ],
        "containerTypeCode": "SAC",
        "estimatedContainerWeightKg": 99.9,
        "containerCount": 14,
        "conversionFactor": null
      }
    ],
    "tripId": "123",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "256abc",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8462926",
    "completedDateTime": "2017-05-17T15:34:12+13:00",
    "notes": "Some notes",
    "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/processing/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/processing/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number The version of the event that the fisher is wanting to update.

Processing Update Request Body Example:

 
{
  "eventHeader": {
    "eventId": "256abc",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",  
    "amendmentReason": "mistake in original",
    "tripId": "123",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "processingDateTime": "2017-06-17T15:34:12+13:00", "oilLitres": 98, "products": [ { "productStateCode": "DRE", "species": [ {"SpeciesCode":"KIN", "greenWeightKg":25.5} ], "containerTypeCode": "BAG", "containerCount": 2, "unitWeightKg": 4.5, "estimatedContainerWeightKg": 12.3, "conversionFactor": 1.6 }, { "productStateCode": "FIT", "species": [ { "speciesCode": "KIN", "greenWeightKg": null } ], "containerTypeCode": "SAC", "containerCount": 14, "estimatedContainerWeightKg": 99.9, "conversionFactor": null } ] }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Disposal Event

The sections below describe the information necessary to create, get and update a Disposal event.

Change history
Date Change
19/09/2017

Changed manual location details to only require a minimum of 3dp.

Added a new field "Fishing Event ID" to the body parameters.

11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
29/06/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/disposal/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/disposal/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Fishing Event ID Optional String The ID of the fishing event that stocks were disposed for. 
Disposal Date Time Mandatory String Date 24hr + UTC offset.
At Sea Holding Receptacle Location Conditional Basic GeoLocation Set

Must be provided if 'Disposal Codes' master data property 'require_holding_location = yes'.

At least one group of system or manual location parameters must be provided.

See At Sea Holding Receptacle Location Parameters below.

Stocks Disposed Mandatory Array of Stocks Disposed Must provide at least one disposal stock.

See Stocks Disposed Parameters 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.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Mandatory String

Must be a valid Vessel number.

Must be provided if 'Is Vessel Used' = True.

Must be provided if 'Fishing Methods' master data property 'require_vessel_number = true'.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

At Sea Holding Receptacle Location Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Location Conditional Geolocation At least one group of system or manual location parameters must be provided. See Geolocation parameters below.
Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Longitude Mandatory decimal degrees 

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Stocks Disposed Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Stock Code Mandatory String Must be a valid Stock code.

Validated against Fish Stock Master Data.

Disposal Code Mandatory String Must be a valid Disposal code.

Validated against Disposal Codes Master Data.

Estimated Green Weight Kg Mandatory Number Decimal to 2dp.

Must be be greater than 0.

Disposal Create Request Body Example:

{
  "eventHeader": {
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf91",
    "tripId": "DE-1",
    "completedDateTime": "2017-03-28T09:15:00+11:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Disposal Golden Path - TEST",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" },
"fishingEventId": "12345", "disposalDateTime": "2017-03-28T09:15:00+11:00", "atSeaHoldingReceptacleLocation": { "manualLocation": { "longitude": "-175.111", "latitude": "-44.222" }, "systemLocation": { "longitude": "-175.3333", "latitude": "-45.4444" } }, "stocksDisposed": [ { "stockCode" : "HOK1", "disposalCode": "H", "estimatedGreenWeightKg" : 2 }, { "stockCode" : "CAR1", "disposalCode": "d", "estimatedGreenWeightKg" : 1 } ] }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/disposal/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/disposal/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Completed Date Time String
Fishing Event ID String
Disposal Date Time String
At Sea Holding Receptacle Location

See At Sea Holding Receptacle Location Parameters below.

Basic Geolocation Set
Errors Array
Amendment Reason String

Stocks Disposed

See Stocks Disposed Parameters below.

Array of Stocks Disposed

At Sea Holding Receptacle Location Parameters:

ParameterData Type

System Location

See Geolocation Parameters below.

Geolocation

Manual Location

See Geolocation Parameters below.

Geolocation

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees

Stocks Disposed Parameters:

ParameterData Type
Stock Code String
Disposal Code String
Estimated Green Weight Kg Number

Disposal Get Request Body Example:

{
    "event": {
"fishingEventID": "12345", "disposalDateTime": "2017-03-28T09:15:00+11:00", "atSeaHoldingReceptacleLocation": { "systemLocation": { "longitude": -175.3333, "latitude": -45.4444 }, "manualLocation": { "longitude": -175.111, "latitude": -44.222 } }, "stocksDisposed": [ { "stockCode": "HOK1", "disposalCode": "H", "estimatedGreenWeightKg": 2 }, { "stockCode": "CAR1", "disposalCode": "d", "estimatedGreenWeightKg": 1 } ], "tripId": "DE-1", "vesselNumber": "1", "isVesselUsed": true, "eventId": "12345", "schemaEdition": 1, "eventVersion": 1, "clientNumber": "8462926", "completedDateTime": "2017-03-28T09:15:00+11:00", "notes": "Disposal Golden Path - TEST", "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/disposal/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/disposal/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number The version of the event that the fisher is wanting to update.

Disposal Update Request Body Example:

{
  "eventHeader": {
    "eventId": "12345",
    "eventVersion": 1,
    "tripId": "DE-2",
    "amendmentReason": "estimated green weight for CAR1 was wrong",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Disposal Update - TEST",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" },
"fishingEventId": "12345", "disposalDateTime": "2017-03-28T09:15:00+11:00", "atSeaHoldingReceptacleLocation":{ "manualLocation": { "longitude": "-175.444", "latitude": "-45.111" }, "systemLocation": { "longitude": "-175.33333", "latitude": "-45.2222" } }, "stocksDisposed": [ { "stockCode" : "HOK1", "disposalCode": "d", "estimatedGreenWeightKg" : 11 }, { "stockCode" : "CAR1", "disposalCode": "d", "estimatedGreenWeightKg" : 17 } ] }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

Landing Event

The sections below describe the information necessary to create, get and update a Landing event.

Change history
Date Change
19/0/2017

Changed manual location details to only require a minimum of 3dp.

11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

Removed attributes Is Green Weight Details Complete and Green Weight Details Completed Date Time.

Added new attribute LFR Details Received Date Time.

Updated validation for attributes LFR Client Number, Purchase Order Number, Tranship Vessel Number, Green Weight Kg, Shark Fins Weight Kg.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
28/07/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/landing/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/landing/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Landing Date Time Mandatory String Date 24hr + UTC offset.
Landings Mandatory Array of landings Must have at least one landing record.

Can have many landings associated with the event.

Product details are also recorded against each landing.

See Landings Parameters below.

Event Header Properties:

ParameterRequiredData TypeValidation and Additional Notes
Event ID Mandatory String Must be unique for the event.

Log book generated unique identifier.

Trip ID Mandatory String
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not.
Vessel Number Conditional String Mandatory if 'Is Vessel Used' = True.

Must be a valid Vessel number.

If 'Is Vessel Used' = False and Vessel Number provided, ERS will not accept the event.

Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Mandatory String

Date 24hr + UTC offset.

Must be provided for Create.

Must be null for Update. ERS will not accept the event if provided for update.

The date and time when the event data was completed in the Logbook. That is, when the status was set to “Complete”.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

Landings Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Landing Code Mandatory String

Must be a valid ERS landing code.

Validated against Landing Codes master data.

LFR Details Received Date Time Optional String

Date 24hr + UTC offset.

LFR Client Number Conditional String

Must be a valid Client number.

Must be provided if 'Landing Codes' master data property 'require_LFR_number = true' & 'LFR Details Received Date Time' has been provided.

Must not be provided for other landing codes.

Holding Receptable Location Conditional< Basic GeoLocation Set

Must be provided if 'Landing Codes' master data property 'require_holding_location = true'.

At least one group of system or manual location parameters must be provided if 'Address' is not provided.

Must not be provided for other landing codes.

See Holding Receptacle Location Parameters below.

Holding Receptacle Address Conditional String

Must be provided if one group of system or manual location parameters are not provided.

Maximum of 500 characters allowed.

Tranship Vessel Number Conditional String

Must be provided if 'Landing Codes' master data property 'require_vessel_number = true'.

Must not be provided for other landing codes.

Customary Fishing Document Reference Conditional String

Must be provided if 'Landing Codes' master data property 'require_customary_reference = true'.

Must not be provided for other landing codes.

Is Offal Mealed Optional Boolean Indicates if the offal has been processed as fish meal.
Oil Litres Optional Number

Must be a whole number.

Must be greater than 0.

Landing Products Mandatory Array of landing products Must have at least one product record.

See Landing Products Parameters below.

Holding Receptacle Location Parameters:

ParameterRequiredData TypeValidation and Additional Notes
System Location Conditional Geolocation

At least one group of system or manual location parameters must be provided.

See Geolocation parameters below.

Manual Location Conditional Geolocation

Geolocation Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Latitude Mandatory decimal degrees

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Longitude Mandatory decimal degrees 

System Location: Minimum of 4dp required.

Manual Location: Minimum of 3dp required.

Landing Products Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Product State Code Mandatory String

Must be a valid ERS product state code.

Validated against Product States master data.

Container Type Code Mandatory String

Must be a valid ERS container type code.

Validated against Containers master data.

Estimated Container Weight Mandatory Number

Decimal to 2dp.

Must be greater than 0.

Container Count Mandatory Number

Must be a whole number.

Must be greater than 0.

Total number of containers associated with the container type code.

Purchase Order Number Conditional String

Must be provided if 'Landing Codes' master data property 'require_purchase_order = true' and 'LFR Details Received Date Time' is provided.

Must not be provided for other landing codes.

Maximum of 50 characters allowed.

Stocks Conditional Array of stocks

Must have at least one stock record.

Multiple stocks allowed if 'Product States' master data property 'allow_multiple_fish_codes' = true.

>See Stocks Parameters Array below.

Stocks Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Stock Code Conditional String

Must be a valid ERS stock code.

Validated against Fish Stock master data.

Green Weight Kg Conditional Number

Decimal to 2dp.

Must be provided and greater than '0' if 'Product States' master data property 'require_greenweight' = true, except when landing code is L, LP, LR, Q, T, EOY and 'LFR Details Received Date Time' is not provided.

Must not be provided if 'Product States' master data property 'require_greenweight' is not true.

Optional if 'Product States' master data property 'require_greenweight' = true, Landing code is L, LP, LR, Q, T, EOY and 'LFR Details Received Date Time' is not provided.

Shark Fins Weight Kg Conditional Number

Decimal to 2dp.

Must be provided and greater than 0 if 'Product States' master data property 'require_shark_fin_weight' = true, except when landing code is L, LP, LR, Q, T, EOY and 'LFR Details Received Date Time' is not provided.

Must not be provided if 'Product States' master data property 'require_shark_fin_weight' is not true.

Optional if 'Product States' master data property 'require_shark_fin_weight' = true, Landing code is L, LP, LR, Q, T, EOY and 'LFR Details Received Date Time' is not provided.

Landing Create Request Body Example:

 {
  "eventHeader": 
  {
    "eventId": "abcdef",
    "tripId": "TR1",
    "completedDateTime": "2017-07-27T09:15:00+11:00",
    "vesselNumber": "15527",
    "isVesselUsed": true,
    "notes": "Test notes",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "landingDateTime": "2017-10-28T09:15:00+11:00", "landings": [ { "landingCode": "Q",
"lfrDetailsReceivedDateTime": null, "lfrClientNumber": null, "holdingReceptacleAddress": null, "holdingReceptacleLocation": { "manualLocation": { "longitude": "-175.543", "latitude": "-45.987" }, "systemLocation": { "longitude": "-175.5432", "latitude": "-45.9878" } }, "transhipVesselNumber": null, "customaryFishingDocumentReference": null, "isOffalMealed": true, "oilLitres": 143, "landingProducts": [ { "productStateCode": "DSC", "containerTypeCode": "BIN", "estimatedContainerWeightKg": 22.22, "containerCount": 7, "purchaseOrderNumber": null, "stocks": [ { "stockCode" : "HOK1", "greenWeightKg" : 20.12 } ] } ] } ] }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/landing/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/landing/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String
Completed By Name String
Completed Date Time String
Landing Date Time String
Landings Array of landings
Errors Array
Amendment Reason String

Landings Parameters Array:

ParameterData Type
Landing Code String
LFR Details Received Date Time String
LFR Client Number String

Holding Receptacle Location

See Holding Receptacle Location Parameters below.

Basic GeoLocation Set
Holding Receptacle Address String
Tranship Vessel Number String
Customary Fishing Document Reference String
Is Offal Mealed Boolean
Oil Litres Number
Landing Products Array of landing products

Holding Receptacle Location Parameters:

ParameterData Type

System Location

See Geolocation Parameters below.

Geolocation

Manual Location

See Geolocation Parameters below.

Geolocation

Geolocation Parameters:

ParameterData Type
Latitude decimal degrees
Longitude decimal degrees


Landing Products Parameters Array:

ParameterData Type
Product State Code String
Container Type Code String
Estimated Container Weight Number
Container Count Number
Purchase Order Number String
Stocks Array of stocks

Stocks Parameters Array:

ParameterData Type
Stock Code String
Green Weight Kg Number
Shark Fins Weight Kg Number

Landing Get Request Body Example:

{
    "event": {
        "landingDateTime": "2017-10-28T09:15:00+11:00",
        "landings": [
            {
                "landingCode": "Q",
"lfrDetailsReceivedDateTime": null, "oilLitres": 143, "lfrClientNumber": null, "holdingReceptacleLocation": { "systemLocation": { "longitude": -175.5432, "latitude": -45.9878 }, "manualLocation": { "longitude": -175.543, "latitude": -45.987 } }, "holdingReceptacleAddress": null, "transhipVesselNumber": null, "landingProducts": [ { "productStateCode": "DSC", "stocks": [ { "stockCode": "HOK1", "greenWeightKg": 99.54, "sharkFinsWeightKg": null } ], "containerTypeCode": "BIN", "estimatedContainerWeightKg": 22.22, "containerCount": 7, "purchaseOrderNumber": null } ] } ], "tripId": "TR1", "vesselNumber": "15527", "isVesselUsed": true, "eventId": "abcdef", "schemaEdition": 1, "eventVersion": 2, "clientNumber": "8462926", "completedDateTime": "2017-07-27T09:15:00+11:00", "eventDateTime": "0001-01-01T00:00:00+00:00", "notes": "Test notes", "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/landing/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/landing/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeDescription
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameters.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeDescription
Event Version Mandatory Number

The version of the event that the fisher is wanting to update.

Can only update the latest version of an event.

Landing Update Request Body Example:

{
  "eventHeader": 
  {
    "eventId": "abcdef",
    "tripId": "TR1",
    "eventVersion": 1,
    "completedDateTime": null,
    "vesselNumber": "15527",
    "isVesselUsed": true,
    "notes": "Test notes",
    "amendmentReason": "updating greenweight details",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "landingDateTime": "2017-10-28T09:15:00+11:00", "landings": [ { "landingCode": "Q",
"lfrDetailsReceivedDateTime": null, "lfrClientNumber": null, "holdingReceptacleAddress": null, "holdingReceptacleLocation": { "manualLocation": { "longitude": "-175.543", "latitude": "-45.987" }, "systemLocation": { "longitude": "-175.5432", "latitude": "-45.9878" } }, "transhipVesselNumber": null, "customaryFishingDocumentReference": null, "isOffalMealed": true, "oilLitres": 143, "landingProducts": [ { "productStateCode": "DSC", "containerTypeCode": "BIN", "estimatedContainerWeightKg": 22.22, "containerCount": 7, "purchaseOrderNumber": null, "stocks": [ { "stockCode" : "HOK1", "greenWeightKg" : 99.54 } ] } ] } ] }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeDescription
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeDescription
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

Back to top

No Activity Event

The sections below describe the information necessary to create, get and update a No Activity event.

Change history
Date Change
11/09/2017

Updated the GET URL to include the Software Installation Id and Completer User Id parameters.

Added Completed by Name to the Get request body.

31/08/2017 Included Completer User Id in the event header section of the payload and updated validation for attribute Software Installation Id.
29/08/2017 Updated Request Header to include Signature instead of Bearer Token.
21/08/2017 Three fields (software vendor, software version, software installation ID) have been moved from the request header to the event header parameters and a new field (client number) has also been added here. 
05/07/2017 Changed the way we display the event header parameters in this API documentation. All parameters that are used in the event header array were moved from the Request Body Parameters table to a new Event Header Parameters table. This better reflects their use as displayed in the Request Body Example. No parameter names were changed and the current API format was not changed.
29/06/2017 Initial publication

Create

Request URL:

POST https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/no-activity/{eventID}

Example:

POST https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/no-activity/5ba04c30-c81a-4618-898e-e832da93cf91

Create URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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.
Operator of Vessel Mandatory Boolean If 'No', Vessel Number must be NULL, otherwise invalid 'Operator of Vessel'.

Yes / No.

Vessel Numbers Conditional Array of vessel numbers Mandatory if 'Operator of Vessel' = Yes.

Must be a valid Vessel Number.

If Vessel Number is provided with no Operator of Vessel, invalid 'Operator of vessel is false and vessel number is provided'.

Multiple vessel numbers can be provided.

No Activity Date Time Mandatory String Date 24hr + UTC offset.

Must be the 1st of the month.

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.

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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.
Client Number Mandatory String Must be a valid client number. Must be the same client number as specified in the URL.
Notes Optional String The Fisher may record additional information relating to the event.
Completed Date Time Conditional String Must be provided for Create. Must be null for Update. ERS will not accept the event if provided for update.

Date 24hr + UTC offset.

Amendment Reason Conditional String Must be provided for Update.

Must be null for Create. ERS will not accept the event if provided for create.

No Activity Create Request Body Example:

{
  "eventHeader": {
    "eventId": "no21",
    "completedDateTime": "2017-04-01T12:30:00+13:00",
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "operatorOfVessel": true, "vesselNumbers": ["1","100"], "noActivityDateTime": "2017-03-01T09:15:00+11:00" }

Response

Response Status:

StatusDescription
201 Created Status when event has been accepted successfully.
400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{
 "errors": []
}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{
  "errors": [
    {
      "propertyName": "EventId",
      "attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf91",
      "errorCode": "DuplicateValue",
      "errorMessage": "EventId already exists."
    }
  ]
}

Get

Request URL:

GET https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/no-activity/{eventID}?softwareInstallationId={softwareInstallationId}&CompleterUserId={completerUserId}

Example:

GET https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/no-activity/EventId099?softwareInstallationId=74be4716-cd8f-4264-83e4-5b1249082900&CompleterUserId=8979

Get URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String Unique logbook generated ID for an event.
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.

Completer User Id Mandatory String The user ID retrieved from registering the logbook.

Request Header:

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

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 Type
Event ID String
Schema Edition Number
Event Version Number
Operator of Vessel Boolean
Vessel Number Array of vessel numbers
Notes String
Completed By Name String
Completed Date Time String
No Activity Date Time String
Errors Array
Amendment Reason String

No Activity Get Request Body Example:

{
    "event": {
        "noActivityDateTime": "2017-03-01T09:15:00+11:00",
        "operatorOfVessel": true,
        "vesselNumbers": [
            "1",
            "100"
        ],
        "eventId": "no21",
        "schemaEdition": 1,
        "eventVersion": 1,
        "clientNumber": "8462926",
        "completedDateTime": "2017-04-01T12:30:00+13:00",
        "notes": null,
        "amendmentReason": null,
"completedByName": "Dirk Munroe" }, "errors": [] }

Update

Request URL:

PUT https://ers.uat.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/no-activity/{eventID}

Example:

PUT https://ers.uat.kupe.fishserve.co.nz/api/1234567/event/v1/no-activity/5ba04c30-c81a-4618-898e-e832da93cf91

Update URL Parameters:

ParameterRequiredData typeValidation and Additional Notes
Client Number Mandatory String The main permit holder client number that the event is submitted against.
Event ID Mandatory String 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:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameter.

This parameter is a property of the Event Header Set.

The amended value of the fields that need to be updated will be passed in the request body.

ParameterRequiredData TypeValidation and Additional Notes
Event Version Mandatory Number The version of the event that the fisher is wanting to update.

No Activity Update Request Body Example:

{
  "eventHeader": {
    "eventId": "no21",
    "eventVersion": 1,
    "notes": "these are the notes",
    "amendmentReason": "to add notes",
    "completedDateTime": null,
"softwareVendor": "ERS-FishServe",
"softwareVersion": "1.1.2",
"softwareInstallationId": "a13afab2-c409-4622-b8f8-146996587809",
"clientNumber": "1234567",
"completerUserId": "1234" }, "operatorOfVessel": true, "vesselNumbers": ["1"], "noActivityDateTime": "2017-03-01T09:15:00+11:00" }

Response

Response Status:

StatusDescription
200 Ok Status when event has been updated successfully.
400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

ParameterData TypeValidation and Additional Notes
Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:

ParameterData TypeValidation and Additional Notes
Property Name String The name of the property that has an error.
Attempted Value String The attempted value used.
Error Code String The type of error.
Error Message String The description of the error.

Example 1:

{
 "errors": []
}

Example 2:

{
  "errors": [
  {
   "propertyName": "EventVersion",
   "attemptedValue": "2",
   "errorCode": "InvalidValue",
   "errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."
  }
 ]
}

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 or 'no-activity' events will be returned. 
  • Only the latest version of each event is returned. 
Change history
Date Change
13/09/2017 Initial publication

Get

Request URL:

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

Example:

GET https://ers.uat.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