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

ERS Event APIs

ERS Non-Fishing Event APIs

Trawl Event

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

Create

Request URL:

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

Example:

POST https://ers.demo.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

Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook)

Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)

Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)

Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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.
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 greater than 0.
Vessel Pair Number Optional String If a pair method is used, this is the other vessel involved in the fishing. Note - this vessel is not required to report.

If provided, must be a valid vessel number.

Wing Spread Metres Mandatory Number Must be greater than 0.
Headline Height Metres Mandatory Number Must be greater than 0.
Codend Mesh Size Mm Mandatory Number Must be greater than 0.
Ground Rope Depth Metres Mandatory Number Must be greater than 0.
Bottom Depth Metres Mandatory Number Must be greater than 0.
Speed Knots Mandatory Number Decimal (12,2)

Must be greater than 0.

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

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

Net Leave Depth Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) leave depth.

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

Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

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

Estimated Catch Kg Mandatory Number Decimal (12,2)

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.

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

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",
  },
  "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.5432,
             "latitude": -46.9878
                                }
                },

 
  "numberOfNets": 3,
  "vesselPairNumber": null,
  "wingSpreadMetres": 12,
  "headlineHeightMetres": 25,
  "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,

    "netAtDepthLocation": {
                                "systemDateTime": "2017-05-24T08:01:00+13:00",
                                "systemLocation": {
                                    "longitude": -175.5432,
                                    "latitude": -45.9878
                                },
                                "manualDateTime": "2017-05-24T09:15:00+13:00",
                },

  "netLeaveDepthLocation": {
                                "systemDateTime": "2017-05-24T12:30:00+13:00",
                                "manualLocation": {
                                    "longitude": -173.5432,
                                    "latitude": -43.9878
                                }
  },

  "estimatedCatchKg": 90,
  "catches": [
    {
      "speciesCode": "SNA",
      "greenWeightEstimateKg": 50.25,
    },
    {
      "speciesCode": "HOK",
      "greenWeightEstimateKg": 23.75,
    }
  ],
   "isNonFishOrProtectedSpeciesCatchPresent": false,
  "nonFishOrProtectedSpeciesCatches": [
    {
      "speciesCode": "XAF",
      "seabirdCaptureCode": "W",
      "estimatedWeightKg": null,
      "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 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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trawl/{eventID}

Example:

GET https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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
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
Net at Depth Location See Geolocation Set Parameters below. Geolocation Set
Net Leave Depth Location See Geolocation Set Parameters below. Geolocation Set
Finish Location See Geolocation Set Parameters below. Geolocation
Completed Date Time String
Estimated Catch Kg Number
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, 4dp
Longitude decimal degrees, 4dp

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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

Example:

 
{
  "event": {
    "numberOfNets": 3,
    "vesselPairNumber": null,
    "wingSpreadMetres": 12,
    "headlineHeightMetres": 25,
    "codendMeshSizeMm": 5,
    "groundRopeDepthMetres": 11,
    "bottomDepthMetres": 150,
    "speedKnots": 7,
    "isNetLost": false,
    "estimatedCatchKg": 90,
    "netAtDepthLocation": {
      "systemDateTime": "2017-05-24T08:01:00+13:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.9878
      },
      "manualDateTime": "2017-05-24T09:15:00+13:00",
      "manualLocation": null
    },
    "netLeaveDepthLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": null,
      "manualDateTime": null,
      "manualLocation": {
        "longitude": -173.5432,
        "latitude": -43.9878
      }
    },
    "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.5432,
        "latitude": -46.9878
      }
    },
    "finishLocation": {
      "systemDateTime": "2017-05-24T12:30:00+13:00",
      "systemLocation": {
        "longitude": -174.5432,
        "latitude": -44.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "isNonFishOrProtectedSpeciesCatchPresent": false,
    "catches": [
      {
        "speciesCode": "SNA",
        "greenWeightEstimateKg": 50.25,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      }
    ],
    "nonFishOrProtectedSpeciesCatches": [
      {
        "speciesCode": "XAF",
        "seabirdCaptureCode": "W",
        "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": "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
  },
  "errors": []
}

Back to top

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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

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.

Example:

 
{
  "eventHeader": {
    "tripid": "Trawltripid1",
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf9290",
    "eventVersion": "2",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Fishing conditions were poor",
    "completedDateTime": null,
    "amendmentReason": "Test Amendment Reason"
  },
  "FishingMethodCode": "BT",
  "targetSpeciesCode": "SNA",
  "MitigationDeviceCodes": ["BIB"],
  "startLocation": {
    "systemDateTime": null,
       "systemLocation": null,
    "manualDateTime": null,
        "manualLocation": null
  },
  "numberOfNets": 3,
  "vesselPairNumber": null,
  "wingSpreadMetres": 12,
  "headlineHeightMetres": 25,
  "codendMeshSizeMm": 5,
  "groundRopeDepthMetres": 11,
  "bottomDepthMetres": 150,
  "speedKnots": 7.5,
  "finishLocation": {
    "systemDateTime": null,
        "systemLocation": null,
    "manualDateTime": null,
        "manualLocation": null
  },

    "netatdepthlocation": {
                                "systemDateTime": null,
                                "systemLocation": null,
                                "manualDateTime": null,
                                "manualLocation": null
                },

  "netleavedepthLocation": {
                                "systemDateTime": null,
                                "systemLocation": null,
                                "manualDateTime": null,
                                "manualLocation": null
  },
  "estimatedCatchKg": 90,
  "catches": [
    {
      "speciesCode": "SNA",
      "greenWeightEstimateKg": 50.25
    },
    {
      "speciesCode": "HOK",
      "greenWeightEstimateKg": 23.75
    }
  ],
   "isNonFishOrProtectedSpeciesCatchPresent": false,
  "nonFishOrProtectedSpeciesCatches": [
    {
      "speciesCode": "XAF",
      "seabirdCaptureCode": "W",
      "estimatedWeightKg": null,
      "numberUninjured": 1,
      "numberInjured": null,
      "numberDead": null,
      "tags": null
    },
    {
      "speciesCode": "DEN",
      "estimatedWeightKg": 5.5,
      "numberUninjured": null,
      "numberInjured": null,
      "numberDead": null,
      "tags": ["SG101", "SG105", "SG305", "SG501", "SG111"]
    }
  ]
}
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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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

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

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Request Body: Example:

{
  "eventHeader": {
    "eventId":"5ba04c30-c81a-4618-898e-e832da93cf1532",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "2017-04-10T09:15:00+11:00",
    "tripID": "589"
  },

  "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": 8,
      "numberInjured": 8,
      "numberDead": 8,
      "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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/potting/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/potting/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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, 4dp
Longitude decimal degrees, 4dp

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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

Response 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,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      },
      {
        "speciesCode": "YBF",
        "greenWeightEstimateKg": 88.88,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      }
    ],
    "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
  },
  "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/potting/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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

Request Body: Example:

{
  "eventHeader": {
    "eventId":"5ba04c30-c81a-4618-898e-e832da93cf1532",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "",
    "amendmentReason": "ALEX TEST",
    "tripID": "589"
  },

  "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": 88.88,
    }
  ],
  "nonFishOrProtectedSpeciesCatches": [
    {
      "speciesCode": "FUG",
      "estimatedWeightKg": 88.88,
      "numberUninjured": 8,
      "numberInjured": 8,
      "numberDead": 8,
      "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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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 greater than 0.
Total Length of Nets Metres Mandatory Number Decimal (12,2). Must be greater than 0.
Min Mesh Size Mm Mandatory Number Must be greater than 0.
Net Height Mandatory 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 (12,2). Must be 0 or greater.
Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

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

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Example:

{
  "eventHeader": {
    "eventId":"NET99",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "2017-04-10T09:18:00+11:00",
    "tripID": "567",
    "notes": "Golden path - TEST"
  },
  "fishingMethodCode": "dn",
  "targetSpeciesCode": "KIN",
  "mitigationDevicesUsed": ["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": 8,
      "numberUninjured": 88,
      "numberInjured": 88,
      "numberDead": 888,
      "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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/netting/{eventID}

Example:

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

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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, 4dp
Longitude decimal degrees, 4dp

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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

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,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      },
      {
        "speciesCode": "DPO",
        "greenWeightEstimateKg": 88.88,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      }
    ],
    "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
  },
  "errors": []
}

Update

Request URL:

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

Example:

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

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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.

Example:

{
  "eventHeader": {
    "eventId":"NET100",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "tripID": "567",
    "notes": "Golden path UPDATE - TEST",
    "amendmentReason": "Golden path UPDATE - TEST"
  },
  "fishingMethodCode": "dn",
  "targetSpeciesCode": "KIN",
  "mitigationDevicesUsed": ["STR"],

  "isNonFishOrProtectedSpeciesCatchPresent": true,
  
  "totalLengthOfNetsMetres": 9,
  "minMeshSizeMm": 9,
  "netHeight": 9,
  "isNetLost": false,
  "numberOfNets": 9,
  "estimatedGreenWeightForAllOtherSpeciesKg":  99.9,
  
  "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": 99.99
    },
    {
      "speciesCode": "DPO",
      "greenWeightEstimateKg": 99.99
    }
  ],
  "nonFishOrProtectedSpeciesCatches": [
    {
      "speciesCode": "XAF",
      "estimatedWeightKg": 9,
      "numberUninjured": 99,
      "numberInjured": 99,
      "numberDead": 999,
      "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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
    Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
    Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
    Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
    Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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 Cm Mandatory Number Must be greater than 0.
Number of Hooks Mandatory Number Must be 0 or greater.
Bottom Depth Metres Mandatory 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.

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

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

Number of Lines Hauled Conditional Number Must be provided if 'Fishing Methods' master data property 'require_lines_hauled = true'.

Must be greater than 0.

Required for DL (Dahn Lines).

Can be provided for Method = BLL (Bottom Long Line) & TL (Trot Line), ERS will not reject the event if provided.

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

Location when net(s) on deck.

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

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Request Body: Example

{
  "eventHeader": {
    "eventId": "LiningEvent1",
    "tripId": "tr1",
    "completedDateTime": "2017-04-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes"
  },
  "fishingMethodCode": "BLL",
  "targetSpeciesCode": "SNA",
  "mitigationDevicesUsed": ["Bird Baffler", "Shouting"],
  "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
   }
  ],
  
  "hookSpaceCm": 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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/lining/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/lining/5ba04c30-c81a-4618-898e-e832da93cf9

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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 Cm 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, 4dp
Longitude decimal degrees, 4dp

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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

Response Body: Example

{
  "event": {
    "hookSpaceCm": 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": [],
    "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,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      },
      {
        "speciesCode": "CRA",
        "greenWeightEstimateKg": 23.75,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      }
    ],
    "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
  },
  "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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.

Request Body: Example

{
  "eventHeader": {
    "eventId": "LiningEvent1",
    "eventVersion": "1",
    "tripId": "tr1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",
    "amendmentReason": "just because i can"
  },
  "fishingMethodCode": "BLL",
  "targetSpeciesCode": "SNA",
  "mitigationDevicesUsed": ["Bird Baffler", "Shouting"],
  "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}
  ],
  "HookSpaceCm": 99.7,
  "NumberOfHooks": 5,
  "BottomDepthMetres": 346,
  "IsLineLost": false,
  
  "StartOfHaulDateTime": "2017-04-03T08:37:00+13:00",
  "NumberOfLinesHauled": 8,
}

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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
    Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
    Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
    Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
    Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Conditional String If the fishing took place on a vessel, then the vessel must be identified. Must be a valid vessel number. Mandatory if 'Is Vessel Used' = True. If ‘Is Vessel Used’ = False and a Vessel Number is provided, ERS will not accept the event.
Notes Optional String The Fisher may record additional information relating to the event.
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 Must be 0 or greater.
Number of Hooks Mandatory Number Must be 0 or greater.
Number of Floats Mandatory Number Must be 0 or greater.
Number of Lightsticks Mandatory Number Must be 0 or greater.
Line Shooter Mandatory Boolean
Bait Type % - Fish Mandatory Number Decimal (12,2)

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.
Completed Date Time Mandatory String Must be provided for Create Must be null for Update. ERS will reject the event if provided for update. Date 24hr + UTC offset
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 Parameters below. Mandatory if Is Non Fish Or Protected Species Catch Present is ‘Yes’
Amendment Reason Conditional String Must be provided for an Update. Must be null for Create. ERS will reject 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
Longitude Mandatory decimal degrees, 4dp

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 greater than 0.
Number of Fish Mandatory 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 Must be greater than 0.
Number of Fish Mandatory 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Request Body: Example

 {
  "eventHeader": {
    "eventId": "TL017",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",
    "completedDateTime": "2017-05-29T09:00:00+13:00",
    "tripId": "TL013"
  },
  "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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/tuna-lining/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/tuna-lining/5ba04c30-c81a-4618-898e-e832da93cf9

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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 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, 4dp
Longitude decimal degrees, 4dp


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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

Response 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",
        "greenWeightEstimateKg": null,
        "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
  },
  "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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.

Request Body: Example

  {
  "eventHeader": {
    "eventId": "TL017",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": null,
    "tripId": "TL013",
    "amendmentReason": "Audit error"
  },
  "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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
    Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
    Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
    Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
    Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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 Hauled Mandatory Number Must be 0 or greater
Maximum Number of Hooks Used Mandatory 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.

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

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Request Body: Example

{
  "eventHeader": {
    "eventId": "4003abcd",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "tripID": "125",
    "completedDateTime": "2017-01-01T08:00:00+13:00"
  },
  "fishingMethodCode": "T",
  "targetSpeciesCode": "SNA",
  "mitigationDevicesUsed": ["ACC"],
  "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": [],
  "nonFishOrProtectedSpeciesCatches": [],
  
  "MaximumNumberOfLinesUsed": 9,
  "MaximumNumberOfHooksUsed": 0,
}

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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/other-lining/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/other-lining/5ba04c30-c81a-4618-898e-e832da93cf9

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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, 4dp
Longitude decimal degrees, 4dp

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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

Response Body: Example

{
    "event": {
        "maximumNumberOfLinesUsed": 9,
        "maximumNumberOfHooksUsed": 0,
        "fishingMethodCode": "T",
        "targetSpeciesCode": "SNA",
        "mitigationDeviceCodes": [
            "ACC"
        ],
        "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": [],
        "nonFishOrProtectedSpeciesCatches": [],
        "tripId": "125",
        "vesselNumber": "1",
        "isVesselUsed": true,
        "eventId": "4003abcde",
        "schemaEdition": 1,
        "eventVersion": 1,
        "clientNumber": "8491346",
        "completedDateTime": "2017-01-01T08:00:00+13:00",
        "notes": null,
        "amendmentReason": null
    },
    "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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

Request Body: Example

{
  "eventHeader": {
    "eventId": "4002",
    "vesselNumber": "1",
    "isVesselUsed": true,
        "eventVersion": 1,
    "notes" : "Comments"
  },
  "startDateTime": "2016-01-01T08:00:00+13:00",
  "method": "bottom",
  "targetSpeciesCode": "SNA",
  "mitigationDeviceCodes": ["ACC"],
  "startLocation": {
    "longitude": -175.5432,
    "latitude": -45.9878,
    "isManual": true
  },
  "finishDateTime": "2017-01-01T12:30:00+13:00",
  "finishLocation": {
    "longitude": -175.1025,
    "latitude": -46.3256,
    "isManual": true
  },

  "isNonFishOrProtectedSpeciesCatchPresent": false,
  "catches": [],
  "nonFishOrProtectedSpeciesCatches": [],
  
  "MaximumNumberOfLinesUsed": 9,
  "MaximumNumberOfHooksUsed": 0,
}

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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
    Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
    Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
    Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
    Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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 greater than 0.
Time Spent Hours Mandatory Number Must be greater than 0.

Whole number only. Round up.

Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

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

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Request Body: Example

{
  "eventHeader": {
  "eventId": "HandGatheringCreate",
  "isVesselUsed": false,
  "notes": "Hand gathering CREATE - TEST",
  "tripID": "111",
  "completedDateTime": "2017-01-01T08:00:00+13:00"
  },
  "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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/hand-gathering/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/hand-gathering/5ba04c30-c81a-4618-898e-e832da93cf9

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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, 4dp
Longitude decimal degrees, 4dp

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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

Response 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,
                "productStateCode": null,
                "processedWeightKg": null,
                "numberOfFish": null
            },
            {
                "speciesCode": "HOK",
                "greenWeightEstimateKg": 23.75,
                "productStateCode": null,
                "processedWeightKg": null,
                "numberOfFish": null
            }
        ],
        "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": "HandGatheringCreate",
        "schemaEdition": 1,
        "eventVersion": 1,
        "clientNumber": "8462926",
        "completedDateTime": "2017-01-01T08:00:00+13:00",
        "notes": "Hand gathering - TEST",
        "amendmentReason": null
    },
    "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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

Request Body: Example

{
  "eventHeader": {
  "eventId": "HandGatheringCreate",
  "isVesselUsed": false,
  "notes": "Hand gathering UPDATE - TEST",
  "tripID": "111",
  "eventVersion": 1,
  "AmendmentReason": "Amendment reason - TEST"
  },
  "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": "SNA",
      "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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
    Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
    Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
    Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
    Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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.
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.
Diver Details Mandatory Array of Diver Details See Diver 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.

Swell Metres Mandatory Number Decimal (12,2).

Must be 0 or greater

Visibility Metres Mandatory 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'.
Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

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

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Diver Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Diver ID or Name Mandatory String Diver's ID is expected when TargetSpecies is Paua. Otherwise the diver's name is expected.
Total Diving Time Hours Mandatory Number Must be greater than 0.
Diver Catch Optional Array of Diver Catch See Diver Catch Parameters below.

Need not provide diver catch.

Diver Catch Parameters:

Note that, in addition to the diver catch details, we also get the standard catch details. ERS will not validate that the two datasets are consistent.

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

Validated against Fish Species ERS master data.

Must not be provided if 'Fish Species' master data property 'not_allowed_for_diving = true'.

PAU should not reported in the diver catch. ERS will reject the event if provided.

Estimated Catch Kg Mandatory Number Decimal (12,2).

Must be greater than 0.

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Request Body: Example

{
  "eventHeader": {
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf91",
    "tripId": "tr1",
    "vesselNumber": "1",
    "isVesselUsed": true,
	"notes" : "Fishing conditions were poor",
    "completedDateTime": "2017-04-01T12:30:00+13:00"
  },

  "fishingMethodCode": "di",
  "targetSpeciesCode": "pau",
  "MitigationDeviceCodes":["ACC"],
  "startLocation": {
      "systemDateTime": "2017-03-28T09:15:00+11:00",
      "systemLocation": {
    "longitude": "-175.5432",
      "latitude": "-45.9878"
      }
  },
  "isNonFishOrProtectedSpeciesCatchPresent": false,
  "nonFishOrProtectedSpeciesCatches": [],
  "finishDateTime": "2017-04-01T12:30:00+13:00",
  "finishLocation": {
      "systemDateTime": "2017-03-28T09:15:00+11:00",
      "systemLocation": {
    "longitude": "-175.5432",
      "latitude": "-45.9878"
      }
  },
  "catches": [{
    "speciesCode": "PAU",
    "greenWeightEstimateKg": 50.25
  }],
  "swellMetres": 1.25,
  "visibilityMetres": 10,
  "wasBoatPersonUsed": true,
  "divers": [
    {  
      "diverIdOrName": "DiverDave",
      "totalDivingTimeHours": 8,
      "diverCatches": [
        {"speciesCode": "PAA",   "estimatedCatchKg": 27.75},
        {"speciesCode": "PAI",   "estimatedCatchKg": 5.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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/diving/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/diving/5ba04c30-c81a-4618-898e-e832da93cf9

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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
Diver Details See Diver Parameters below. Array of Diver Details
Swell Metres Number
Visibility Metres Number
Was Boat Person Used Boolean
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, 4dp
Longitude decimal degrees, 4dp

Catches Parameters:

ParameterData Type
Species Code String
Green Weight Estimate Kg Number

Diver Parameters:

ParameterData Type
Diver ID or Name String
Total Diving Time Hours Number
Diver Catch See Diver Catch Parameters below. Array of Diver Catch

Diver Catch Parameters:

ParameterData Type
Species Code String
Estimated Catch Kg Number

Non Fish or Protected Species Catches Parameters:

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

Response Body: Example

{
  "event": {
    "swellMetres": 1.25,
    "visibilityMetres": 10,
    "wasBoatPersonUsed": true,
    "divers": [
      {
        "diverIdOrName": "DiverDave",
        "totalDivingTimeHours": 8,
        "diverCatches": [
          {
            "speciesCode": "PAA",
            "estimatedCatchKg": 27.75
          },
          {
            "speciesCode": "PAI",
            "estimatedCatchKg": 5.75
          }
        ]
      }
    ],
    "fishingMethodCode": "di",
    "targetSpeciesCode": "pau",
    "mitigationDeviceCodes": [
      "ACC"
    ],
    "startLocation": {
      "systemDateTime": "2017-03-28T09:15:00+11:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "finishLocation": {
      "systemDateTime": "2017-03-28T09:15:00+11:00",
      "systemLocation": {
        "longitude": -175.5432,
        "latitude": -45.9878
      },
      "manualDateTime": null,
      "manualLocation": null
    },
    "isNonFishOrProtectedSpeciesCatchPresent": false,
    "catches": [
      {
        "speciesCode": "PAU",
        "greenWeightEstimateKg": 50.25,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      }
    ],
    "nonFishOrProtectedSpeciesCatches": [],
    "tripId": "tr1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventId": "0ae7d65a-d651-1f46-289e-eefb2299a183",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "8491346",
    "completedDateTime": "2017-04-01T12:30:00+13:00",
    "notes": null,
    "amendmentReason": null
  },
  "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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

Request Body: Example

{
  "eventHeader": {
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf91",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": null,
    "tripID": "hhh",
    "amendmentReason": "error found during internal audit"
  },

  "fishingMethodCode": "di",
  "targetSpeciesCode": "CRA",
  "mitigationDeviceCodes": ["ACC"],

  "startLocation": {
      "systemDateTime": "2017-03-28T09:15:00+11:00",
      "systemLocation": {
    "longitude": "-175.5432",
      "latitude": "-45.9878"
      }
  },
  "isNonFishOrProtectedSpeciesCatchPresent": true,
  "nonFishOrProtectedSpeciesCatches": [
        {
      "speciesCode": "XAF",
      "estimatedWeightKg": 8,
      "numberUninjured": 8,
      "numberInjured": 8,
      "numberDead": 8,
      "tags": null
    }
    ],
  "finishLocation": {
      "systemDateTime": "2017-03-28T09:15:00+11:00",
      "systemLocation": {
    "longitude": "-175.5432",
      "latitude": "-45.9878"
      }
  },
    "catches": [
    {
      "speciesCode": "HOK",
      "greenWeightEstimateKg": 50.25,
    },
    {
      "speciesCode": "SNA",
      "greenWeightEstimateKg": 23.75,
    } 
  ],
  "swellMetres": 1.25,
  "visibilityMetres": 10,
  "wasBoatPersonUsed": true,
  "divers": [
    {  
      "diverIdOrName": "DiverDave",
      "totalDivingTimeHours": 8,
	  "diverCatches": [
        {"speciesCode": "CRA",   "estimatedCatchKg": 27.75},
        {"speciesCode": "SNA",   "estimatedCatchKg": 5.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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
    Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
    Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
    Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
    Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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 provided if 'Fishing Method' master data property 'require_net_details = true'.

 Reject if provided for other methods.

 Must be greater than 0.

 Required for BS, DPS, DS, L, PS

Ground Rope Length Metres Conditional 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.

Required for DS (Danish Seine).

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

Reject if provided for other methods.

Required for PS (Purse Seine).

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.

Number of Lifts Conditional 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.

Required for DPN (Dip Net) and SCN (Scoop Net).

Estimated Catch Kg Mandatory Number Decimal (12,2)

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.

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

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Request Body: Example

{
  "eventHeader": {
    "eventId": "S0111",
    "completeddatetime": "2017-04-30T08:00:00+13:00",
    "tripid": "seiningtrip1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes"
  },
  "startDateTime": "2017-04-30T08:00:00+13:00",
  "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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/seining/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/seining/5ba04c30-c81a-4618-898e-e832da93cf9

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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, 4dp
Longitude decimal degrees, 4dp

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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

Response 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,
                "productStateCode": null,
                "processedWeightKg": null,
                "numberOfFish": null
            },
            {
                "speciesCode": "CRA",
                "greenWeightEstimateKg": 23.75,
                "productStateCode": null,
                "processedWeightKg": null,
                "numberOfFish": null
            },
            {
                "speciesCode": "HOK",
                "greenWeightEstimateKg": 23.75,
                "productStateCode": null,
                "processedWeightKg": null,
                "numberOfFish": null
            }
        ],
        "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
    },
    "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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

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"
  },
  "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": 12345,
  "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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
    Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
    Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
    Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
    Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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 greater than 0.
Bottom Depth Metres Mandatory Number Must be greater than 0. Depth at Start
Number of Single Reels Mandatory Number Must be 0 or greater.
Number of Double Reels Mandatory Number Must be 0 or greater.
Finish Location Mandatory Geolocation Set See Geolocation Set Parameters below.

Location when net(s) on deck.

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

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Request Body: Example

{
  "eventHeader": {
    "eventId": "JE0111",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completeddatetime": "2017-04-30T08:00:00+13:00",
    "tripid": "jiggingtrip1"
  },

  "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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/jigging/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/jigging/5ba04c30-c81a-4618-898e-e832da93cf9

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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, 4dp
Longitude decimal degrees, 4dp

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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

Response 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,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      },
      {
        "speciesCode": "CRA",
        "greenWeightEstimateKg": 23.75,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      }
    ],
    "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
  },
  "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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

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",
  },
  "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.

Create

Request URL:

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

Example:

POST https://ers.demo.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
    Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
    Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
    Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
    Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Mandatory String Must be provided if 'Is Vessel Used' = True.

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

Must be a valid Vessel number.

If the fishing took place on a vessel, then the vessel must be identified.

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.
Fishing Method Code Mandatory String Must be a valid fishing method code. Validated against Fishing Methods Master Data.

Must be a valid Method Code for the Fishing Event Type.

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 (12,2)

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

Must be greater than 0.

Required for D (Dredging).

Fisher can provide for Method = MH (Mechanical Beach Harvester), ERS will not reject the event if provided.
Number of Tows Completed Conditional Number Must be provided if 'Fishing Methods' master data property 'require_dredging_details = true'.

Must be greater than 0.

Required for D (Dredging).

Fisher can provide for Method = MH (Mechanical Beach Harvester), ERS will not reject the event if provided.

Number of Devices Used Mandatory Number Must be greater than 0.
Estimated Catch Kg Mandatory Number Decimal (12,2)

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.

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

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.

Records details of non-fish or protected species that have been caught while fishing.

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.

Amendment Reason Conditional String Must be provided for Update.

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

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

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
Longitude Mandatory decimal degrees, 4dp

Catches Parameters:

ParameterRequiredData TypeValidation and Additional Notes
Species Code Mandatory String Must be a valid ERS species code.
Green Weight Estimate Kg Mandatory Number Decimal (12,2)

Must be 0 or greater

Non Fish or Protected Species 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 Details 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 Must be provided if 'NFPS' master data property 'measured_by = weight'
Count Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Count Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS Tag Number.

Request Body: Example

{
  "eventHeader": {
    "eventId": "5ba04c30-c81a-4618-898e-e832da93cf91",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "2017-01-01T12:30:00+13:00",
    "tripID": "123"
   },

  "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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/dredging/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/dredging/5ba04c30-c81a-4618-898e-e832da93cf9

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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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, 4dp
Longitude decimal degrees, 4dp

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 Details String
Estimated Weight Kg Number
Count Uninjured Number
Count Injured Number
Count Dead Number
Tag Array of Strings

Response 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,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      },
      {
        "speciesCode": "CRA",
        "greenWeightEstimateKg": 23.75,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      },
      {
        "speciesCode": "HOK",
        "greenWeightEstimateKg": 23.75,
        "productStateCode": null,
        "processedWeightKg": null,
        "numberOfFish": null
      }
    ],
    "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
  },
  "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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

Request Body: Example

{
  "eventHeader": {
    "eventId": "f763a44e-101a-a997-6044-74928accf8f6",
    "eventVersion": 1,
    "vesselNumber": "",
    "isVesselUsed": false,
    "notes": "TEST UPDATE - Golden Path",
    "amendmentReason": "Dredging UPDATE - TEST",
    "tripID": "123"
   },

  "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
    },
    {
      "speciesCode": "HOK",
      "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.

Create

Request URL:

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

Example:

POST https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/trip-start/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Conditional String If the fishing took place on a vessel, then the vessel must be identified. Must be a valid vessel number. Mandatory if 'Is Vessel Used' = True. If ‘Is Vessel Used’ = False and a Vessel Number is provided, ERS will not accept the event.
Notes Optional String The Fisher may record additional information relating to the event.
Person in Charge Mandatory String

Must be at least 2 characters.

Individual in charge of the fishing event, to allow for non-vessel fishing events
Start Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Completed Date Time Mandatory String Must be provided for Create Must be null for Update. ERS will reject the event if provided for update. Date 24hr + UTC offset
Amendment Reason Conditional String Must be provided for an Update. Must be null for Create. ERS will reject the event if provided for create.


Geolcation 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
Longitude Mandatory decimal degrees, 4dp

Request Body: Example

{
  "eventHeader": {
    "eventId": "TripStartEvent006",
    "tripId": "t1",
    "completedDateTime": "2017-05-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes."
  },
  "startDateTime": "2017-05-01T08:00:00+13:00",
  "personInCharge": "Samuel Montague",
  "startLocation": {
    "systemDateTime": "2017-05-01T08:00:00+13:00",
    "systemLocation": {
      "longitude": "-175.5423",
      "latitude": "-45.9880"
    }
  }

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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trip-start/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/trip-start/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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, 4dp
Longitude decimal degrees, 4dp


Response Body: Example

{
  "event": {
    "personInCharge": "Samuel Montague",
    "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
  },
  "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/trip-start/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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.

Request Body: Example

  {
  "eventHeader": {
    "eventId": "TripStartEvent006",
    "tripId": "t1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventVersion": 1,
    "notes" : "Some additional notes",
    "amendmentReason": "Fix error"
  },

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

Trip End Event

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

Create

Request URL:

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

Example:

POST https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/trip-end/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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.
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Conditional String If the fishing took place on a vessel, then the vessel must be identified. Must be a valid vessel number. Mandatory if 'Is Vessel Used' = True. If ‘Is Vessel Used’ = False and a Vessel Number is provided, ERS will not accept the event.
Notes Optional String The Fisher may record additional information relating to the event.
Person in Charge Mandatory String

Must be at least 2 characters.

Individual in charge of the fishing event, to allow for non-vessel fishing events
End Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Completed Date Time Mandatory String Must be provided for Create Must be null for Update. ERS will reject the event if provided for update. Date 24hr + UTC offset
Amendment Reason Conditional String Must be provided for an Update. Must be null for Create. ERS will reject the event if provided for create.


Geolcation 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
Longitude Mandatory decimal degrees, 4dp

Request Body: Example

{
  "eventHeader": {
    "eventId": "TripEndEvent006",
    "tripId": "t1",
    "completedDateTime": "2017-05-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes."
  },
  "endDateTime": "2017-05-01T08:00:00+13:00",
  "personInCharge": "Samuel Montague",
  "endLocation": {
    "systemDateTime": "2017-05-01T08:00:00+13:00",
    "systemLocation": {
      "longitude": "-175.5423",
      "latitude": "-45.9880"
    }
  }

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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/trip-end/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/trip-end/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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, 4dp
Longitude decimal degrees, 4dp


Response Body: Example

{
  "event": {
    "personInCharge": "Samuel Montague",
    "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
  },
  "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/trip-end/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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.

Request Body: Example

  {
  "eventHeader": {
    "eventId": "TripEndEvent006",
    "tripId": "t1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "eventVersion": 1,
    "notes" : "Some additional notes",
    "amendmentReason": "Fix error"
  },

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

Non Fish or Protected Species (NFPS) Event

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

Create

Request URL:

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

Example:

POST https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/non-fish-or-protected-species/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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

Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Conditional String If the fishing took place on a vessel, then the vessel must be identified. Must be a valid vessel number. Mandatory if 'Is Vessel Used' = True. If ‘Is Vessel Used’ = False and a Vessel Number is provided, ERS will not accept the event.
Notes Optional String The Fisher may record additional information relating to the event.
NFPS Catch Location Mandatory Geolocation Set See Geolocation Set Parameters below.
Completed Date Time Mandatory String Must be provided for Create Must be null for Update. ERS will reject the event if provided for update. Date 24hr + UTC offset
Amendment Reason Conditional String Must be provided for an Update. Must be null for Create. ERS will reject the event if provided for create.
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.


Geolcation 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
Longitude Mandatory decimal degrees, 4dp

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.

Estimated Weight Kg Conditional Number Must be provided if 'NFPS' master data property 'measured_by = weight'
Number Uninjured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Number Injured Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Number Dead Conditional Number Must be provided if 'NFPS' master data property 'measured_by = count'
Tag Optional Array of Strings NFPS tag number.

Request Body: Example

{
  "eventHeader": {
    "eventId": "NFPS111",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "completedDateTime": "2017-03-28T09:15:00+11:00",
    "tripID": "123"
  },

  "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.5423",
      "latitude": "-45.9880"
    }
 },
  "nonFishOrProtectedSpeciesCatches": [
    {
      "speciesCode": "ACN",
      "estimatedWeightKg": 182.23,
      "numberUninjured": null,
      "numberInjured": null,
      "numberDead": null,
      "tags": null
    },
    {
      "speciesCode": "atp",
      "estimatedWeightKg": 1.4,
      "numberUninjured": 2,
      "numberInjured": 3,
      "numberDead": 5,
      "tags": ["SG101", "SG105", "SG305", "SG501", "SG111"]
    }
  ]

}

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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/non-fish-or-protected-species/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/non-fish-or-protected-species/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes String

NFPS Catches Location

See Geolocation Set Parameters below.

Geolocation Set
Completed Date Time String
Errors Array
Amendment Reason 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, 4dp
Longitude decimal degrees, 4dp

Non Fish or Protected Species Catches Parameters:

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


Response Body: Example

  {
    "event": {
        "nfpsCatchLocation": {
            "systemDateTime": "2017-05-01T08:00:00+13:00",
            "systemLocation": {
                "longitude": -175.5423,
                "latitude": -45.988
            },
            "manualDateTime": "2017-05-01T08:00:00+13:00",
            "manualLocation": {
                "longitude": -175.5423,
                "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
    },
    "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/non-fish-or-protected-species/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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.

Request Body: Example

  
{
  "eventHeader": {
    "eventId": "NFPS1",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Test notes"
    "completedDateTime": "2017-03-28T09:15:00+11:00",
    "tripID": "123"
    "amendmentReason": "update notes"
  },
  "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.5423",
      "latitude": "-45.9880"
    }
 },
  "nonFishOrProtectedSpeciesCatches": [
    {
      "speciesCode": "ACN",
      "estimatedWeightKg": 182.23,
      "numberUninjured": null,
      "numberInjured": null,
      "numberDead": null,
      "tags": null
    },
    {
      "speciesCode": "atp",
      "estimatedWeightKg": 1.4,
      "numberUninjured": 2,
      "numberInjured": 3,
      "numberDead": 5,
      "tags": ["SG101", "SG105", "SG305", "SG501", "SG111"]
    }
  ]
}

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

Processing Event

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

Create

Request URL:

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

Example:

POST https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/processing/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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

Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Conditional String If the fishing took place on a vessel, then the vessel must be identified. Must be a valid vessel number. Mandatory if 'Is Vessel Used' = True. If ‘Is Vessel Used’ = False and a Vessel Number is provided, ERS will not accept the event.
Notes Optional String The Fisher may record additional information relating to the event.
Processing Date Time Mandatory String

Date 24hr + UTC offset

Completed Date Time Mandatory String Must be provided for Create. Must be null for Update. ERS will reject the event if provided for update. Date 24hr + UTC offset
Amendment Reason Conditional String Must be provided for an Update. Must be null for Create. ERS will reject the event if provided for create.
Oil Litres Optional 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.


Products Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Product State Mandatory String

Must have at least one Product State for a Processing event.

Sourced from Master Data

Species Conditional Array of species

If Product States master data property 'allow_multiple_fish_codes' = 'Yes' then one or more species codes may be supplied within the species array.

Else, if Product States master data property 'allow_multiple_fish_codes' = 'No' then only one species code may be supplied within the species array.

See Species Parameters Array below.
Container Type Mandatory String

Must be a valid ERS container type code.

Sourced from Master Data.
Estimated Container Weight Kg Mandatory Number

Decimal (12,2)

Must be greater than 0.

Per container.
Container Count Mandatory Number

Must be greater than 0.

Total number of containers associated with the container type code.
Conversion Factor Conditional Number

Decimal (12,2)

Must be provided if 'Product States' master data property 'require_conversion_factor' = Yes 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.

Sourced from Master Data.
Green Weight Kg Conditional Number

Decimal (12,2)

Must be provided and greater than '0' if 'Product States' master data property 'require_greenweight' = 'Yes'.

Must not be provided if 'Product States' master data property 'require_greenweight' = 'No'.

Request Body: Example

{
  "eventHeader": {
    "eventId": "256",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes" : "Some notes",  
    "completedDateTime": "2017-05-17T15:34:12+13:00",
    "tripID": "123"
  },
  "processingDateTime": "2017-05-17T15:34:12+13:00",
  "oilLitres": 98,
  "products": [
    {
                "productState": "MEB",
                "species": [ 
               
                                ],
                "containerType": "BAG",
                "containerCount": 2,
                "estimatedContainerWeightKg": 12.3,
                "conversionFactor": 0
    },
    {
                "productState": "FIT",
                                "species": [ 
                                  {
                                "speciesCode": "KIN",
                                "greenWeightKg": 0
                  }
                                ],
                "containerType": "SAC",
                "containerCount": 14,
                "estimatedContainerWeightKg": 99.9,
                "conversionFactor": 0
    }

  ]
}

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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/processing/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/processing/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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 String
Species Array of Species

Container Type

String

Estimated Container Weight Kg

Number

Container Count

Number
Conversion Factor Number

Species Parameters Array:

ParameterData Type
Species Code String
Green Weight Kg Number


Response Body: Example

{
  "event": {
"processingDateTime": "2017-05-17T15:34:12+13:00",
  "oilLitres": 98,
  "products": [
    {
                "productState": "MEB",
                "species": [ 
               
                                ],
                "containerType": "BAG",
                "containerCount": 2,
                "estimatedContainerWeightKg": 12.3,
                "conversionFactor": 0
    },
    {
                "productState": "FIT",
                                "species": [ 
                                  {
                                "speciesCode": "KIN",
                                "greenWeightKg": 0
                  }
                                ],
                "containerType": "SAC",
                "containerCount": 14,
                "estimatedContainerWeightKg": 99.9,
                "conversionFactor": 0
    }
    "tripId": "123",
    "vesselNumber": "1",
    "isVesselUsed": true,
"eventId": "256"
"schemaEdition": 1,
"eventVersion": 1,
"clientNumber": "8491346",
"completedDateTime": "2017-05-17T15:34:12+13:00"' "notes" : "Some notes", "amendmentReason": null }, "errors": [] }

Update

Request URL:

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

Example:

PUT https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/processing/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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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.

Request Body: Example

 
{
  "eventHeader": {
    "eventId": "PR027z11",
    "vesselNumber": "1",
        "eventVersion": 1,
    "isVesselUsed": true,
    "notes" : "Some notes",
    "amendmentReason": "Forgot to add oil"
  },
  "processingDateTime": "2017-05-17T15:34:12+13:00",
  "oilLitres": 8,
  "products": [
    {
                "productState": "MEB",
                "species": [ 
               
                                ],
                "containerType": "BAG",
                "containerCount": 2,
                "estimatedContainerWeightKg": 12.3,
                "conversionFactor": 0
    },
    {
                "productState": "FIT",
                                "species": [ 
                                  {
                                "speciesCode": "KIN",
                                "greenWeightKg": 0
                  }
                                ],
                "containerType": "SAC",
                "containerCount": 14,
                "estimatedContainerWeightKg": 99.9,
                "conversionFactor": 0
    }

  ]
}

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

Landing Event

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

Create

Request URL:

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

Example:

POST https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

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 Unique logbook generated ID for the trip
Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not
Vessel Number Conditional String If the fishing took place on a vessel, then the vessel must be identified. Must be a valid vessel number. Mandatory if 'Is Vessel Used' = True. If ‘Is Vessel Used’ = False and a Vessel Number is 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 Must be provided for Create Must be null for Update. ERS will reject the event if provided for update. Date 24hr + UTC offset
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
Amendment Reason Conditional String Must be provided for an Update. Must be null for Create. ERS will reject 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. Sourced from Master Data.
Oil Litres Optional Number Must be 0 or greater than 0.
LFR Client Number Conditional String Must be a valid Client number. Must be provided if 'Landing Codes' master data property 'require_LFR_number = true'. Must not be provided for any other 'Landing Code'.
Holding Receptacle Address Conditional String Must be provided if one group of system or manual location parameters are not provided.
Holding Receptable Location Conditional Basic GeoLocation Set

Must be provided if 'Landing Codes' master data property 'require_holding_location = true'. Must not be provided for any other 'Landing Code'. At least one group of system or manual location parameters must be provided if 'Holding Receptacle Address' is not provided.

See Holding Receptacle Location Parameters below.

Tranship Vessel Number Conditional String Must be provided if 'Landing Codes' master data property 'require_vessel_number = true'. Must not be provided for any other 'Landing Code'.
Landing Products Mandatory Array of landing products Must have at least one product record. Can have many products associated with a landing. Stock details are also recorded against each product. 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, 4dp
Longitude Mandatory decimal degrees, 4dp


Landing Products Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Product State Code Mandatory String Must be a valid ERS product state code. Sourced from Master Data
Stocks Conditional Array of stocks

Not required if 'Product States' master data property 'fish_code_requirement = Optional'.

Multiple stocks allowed if 'Product States' master data property 'fish_code_requirement = Multiple.

Multiple stocks not allowed if 'Product States' master data property 'fish_code_requirement = Single'.Green weight kg is also recorded against each stock.

See Stocks Parameters Array below.
Container Type Code Mandatory String Must be a valid ERS container type code. Sourced from Master Data.
Estimated Container Weight Kg Mandatory Number Decimal (12,2) Must be greater than 0. Per container.
Container Count Mandatory 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'. Must not be provided for any other 'Landing Code'.

Stocks Parameters Array:

ParameterRequiredData TypeValidation and Additional Notes
Stock Code Conditional String Must be a valid ERS stock code. Sourced from Master Data.
Green Weight Kg Conditional Number

Decimal (12,2)

Must be provided and greater than '0' if 'Product States' master data property 'greenweight_requirement = Must'.

Must not be provided if 'Product States' master data property 'greenweight_requirement= Must Not'.

Request Body: Example

{
  "eventHeader": {
    "eventId": "LandingSuccess13",
    "tripId": "LandingTrip1",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Test notes",
    "CompletedDateTime": "2017-03-28T09:15:00+11:00"
  },
  "LandingDateTime": "2017-03-28T09:15:00+11:00",
  "landings": [
    {  
      "landingCode": "Q",
      "lfrClientNumber": null,
      "holdingReceptacleLocation":{
        "longitude": "-175.5432",
        "latitude": "-45.9878",
        "isManual": true
      },
      "holdingReceptacleAddress": "165 Victoria Street",
      "transhipVesselNumber": null,
      "landingProducts": [
        {
          "productStateCode": "LIB",   
          "Stocks": [
            { 
              "StockCode" : "HOK1",
              "greenWeightKg" : 0
            },
                        { 
              "StockCode" : "BAR1",
              "greenWeightKg" : 0
            }
          ],
          "containerTypeCode": "BIN",
          "estimatedContainerWeightKg": 22.22,
          "containerCount": 7,
          "purchaseOrderNumber": 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.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/landing/{eventID}

Example:

GET https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: 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:

ParameterData Type
Event ID String
Trip ID String
Schema Edition Number
Event Version Number
Is Vessel Used Boolean
Vessel Number String
Notes 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
Oil Litres Number
LFR Client Number String
Holding Receptacle Address String

Holding Receptacle Location

See Holding Receptacle Location Parameters below.

Basic GeoLocation Set
Tranship Vessel Number String
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, 4dp
Longitude decimal degrees, 4dp


Landing Products Parameters Array:

ParameterData Type
Product State Code String
Stocks Array of stocks
Container Type Code String
Estimated Container Weight Kg Number
Container Count Number
Purchase Order Number String

Stocks Parameters Array:

ParameterData Type
Stock Code String
Green Weight Kg Number

Response Body: Example

{
  "event": {
  "LandingDateTime": "2017-03-28T09:15:00+11:00",
  "landings": [
    {  
      "landingCode": "Q",
      "lfrClientNumber": null,
      "holdingReceptacleLocation":{
        "longitude": "-175.5432",
        "latitude": "-45.9878",
        "isManual": true
      },
      "holdingReceptacleAddress": "165 Victoria Street",
      "transhipVesselNumber": null,
      "landingProducts": [
        {
          "productStateCode": "LIB",   
          "Stocks": [
            { 
              "StockCode" : "HOK1",
              "greenWeightKg" : 0
            },
                        { 
              "StockCode" : "BAR1",
              "greenWeightKg" : 0
            }
          ],
          "containerTypeCode": "BIN",
          "estimatedContainerWeightKg": 22.22,
          "containerCount": 7,
          "purchaseOrderNumber": null
        }
      ]
    }
  ]
}
  {
    "eventId": "LandingEvent0111e",
    "tripId": "LandingTrip1",
    "schemaEdition": 1,
    "eventVersion": 1,
    "clientNumber": "9791515",
    "landingDateTime": "2017-04-01T08:00:00+13:00",
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Some notes",
    "completedDateTime" : "2017-01-01T12:30:00+13:00",
    "amendmentReason" : null
  },
  "errors": []
}

Update

Request URL:

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

Example:

PUT https://ers.demo.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
Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook) 
Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)
Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)
Authorization: Bearer YOUR_USER_TOKEN

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.

Request Body: Example

{
  "eventHeader": {
    "eventId": "LandingSuccess13",
    "tripId": "LandingTrip1",
    "eventVersion": 1,
    "vesselNumber": "1",
    "isVesselUsed": true,
    "notes": "Test notes",
    "CompletedDateTime": null,
    "amendmentReason": "Test amendment reason"
  },
  "LandingDateTime": "2017-04-28T09:15:00+11:00",
  "landings": [{
      "landingCode": "L",
      "lfrClientNumber": "8422125",
      "holdingReceptacleAddress": null,
      "transhipVesselNumber": null,
      "landingProducts": [{
        "productStateCode": "SKF",
        "Stocks": [{
          "StockCode": "PAD6",
          "greenweightkg": 1
        }],
        "containerTypeCode": "SAC",
        "estimatedContainerWeightKg": 27.56,
        "containerCount": 7,
        "purchaseOrderNumber": "12345"
      }]
    },
    {
      "landingCode": "L",
      "lfrClientNumber": "8422125",
      "holdingReceptacleAddress": null,
      "transhipVesselNumber": null,
      "landingProducts": [{
        "productStateCode": "MGU",
        "Stocks": [{
          "StockCode": "ANG13",
          "GreenweightKg": 1
        }],
        "containerTypeCode": "T2",
        "estimatedContainerWeightKg": 27.22,
        "containerCount": 77,
        "greenWeightKg": 11.33,
        "purchaseOrderNumber": "PO1"
      },
      {
        "productStateCode": "GRE",
        "Stocks": [{
          "StockCode": "BAR1",
          "Greenweightkg": 2
        }],
        "containerTypeCode": "T15",
        "estimatedContainerWeightKg": 77.22,
        "containerCount": 11,
        "greenWeightKg": 112.33,
        "purchaseOrderNumber": "PO2"
      }]
    }
  ]
}

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