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

Change history
Date Change
21/12/2018

Released to production

10/12/2018

Added new field Breath Mode Code.

Removed field UBA Tank Type.

Moved Swell, Visability and Boat Person Used fields into the Divers Array.

04/07/2018 Removed all references to the Mitigation Device Codes field.
11/06/2018

Added a new field UBA Tank Type.

Removed reference to Non Fish Protected Species Catches - this is now a seperate event.

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.

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.
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.

UBA Tank Type Conditional String

Must be a valid tank type validated against the tank types master data

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

Must not be provided for any other fishing method.

Breath Mode Mandatory String Must be a valid breath mode validated against the breath mode codes 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'.
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.

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",
"isNonFishOrProtectedSpeciesCatchPresent": false,
"divers": [
{
"diverIdOrName": "DiverAlex",
"totalDivingTimeHours": 8,
"totalDivingTimeMinutes": 56,
"breathMode": "SN",
"swellMetres": 1.25,
"visibilityMetres": 10,
"wasBoatPersonUsed": false,

"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
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
Errors Array
Amendment Reason String


Divers Parameters:

ParameterData Type
Diver ID or Name String
Total Diving Time Hours Number
Total Diving Time Minutes Number
UBA Tank Type String
Breath Mode String
Swell Metres Number 
Visibility Metres Number
Was Boat Person Used Boolean
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

Diving Get Request Body Example:

{
"event": {
"divers": [
{
"diverIdOrName": "DiverAlex",
"totalDivingTimeHours": 8,
"totalDivingTimeMinutes": 56,
"breathMode": "SN",
"swellMetres": 1.25,
"visibilityMetres": 10,
"wasBoatPersonUsed": false,
"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",
"isNonFishOrProtectedSpeciesCatchPresent": false,
"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",
"isNonFishOrProtectedSpeciesCatchPresent": false,

"divers": [
{
"diverIdOrName": "DiverAlex",
"totalDivingTimeHours": 8,
"totalDivingTimeMinutes": 56,
"breathMode": "SN",
"swellMetres": 1.25,
"visibilityMetres": 10,
"wasBoatPersonUsed": false,
"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