uDrew API Reference

This page documents the two Neptune endpoints used by the uDrew integration.

It is intended as a technical reference for implementation and troubleshooting.

Overview

Neptune currently exposes two separate uDrew endpoints:

• udrewIntake receives uDrew lead submissions and upserts them into Neptune.
• uDrewWidget receives generated planning images and saves them into a Neptune customer record.

These endpoints do different jobs and use different authentication rules.

Environment URLs

Production

• https://us-central1-netpune-220210.cloudfunctions.net/udrewIntake
• https://us-central1-netpune-220210.cloudfunctions.net/uDrewWidget

Staging

• https://us-central1-neptune-dev-753ab.cloudfunctions.net/udrewIntake
• https://us-central1-neptune-dev-753ab.cloudfunctions.net/uDrewWidget

1. udrewIntake

Use this endpoint for inbound lead submissions from the uDrew website lead generator.

Request

• Method: POST
• Headers:
  • Content-Type: application/json
  • x-api-key: <your-uDrew-api-key>

Authentication

The API key must be an active Neptune organisation API key for the uDrew integration.

You can generate this in Neptune under Admin → Integrations → uDrew.

Request body

All body fields are optional in the current implementation. However, for a useful lead record you should normally send at least one identifying field such as name, email, phone, address, or sessionId.

Example body

{
  "address": "12 Example Street, Bristol",
  "firstName": "Jamie",
  "lastName": "Taylor",
  "email": "jamie@example.com",
  "phone": "07700111222",
  "message": "Interested in a pool design",
  "sessionId": "udrew-session-12345",
  "latitude": 51.4545,
  "longitude": -2.5879,
  "featureId": "feature_456",
  "featureName": "Rectangle Pool",
  "featureType": "pool",
  "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Example request

curl -X POST "https://us-central1-netpune-220210.cloudfunctions.net/udrewIntake" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-uDrew-api-key>" \
  -d '{
    "address": "12 Example Street, Bristol",
    "firstName": "Jamie",
    "lastName": "Taylor",
    "email": "jamie@example.com",
    "phone": "07700111222",
    "message": "Interested in a pool design",
    "sessionId": "udrew-session-12345",
    "latitude": 51.4545,
    "longitude": -2.5879,
    "featureId": "feature_456",
    "featureName": "Rectangle Pool",
    "featureType": "pool",
    "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }'

What Neptune does

1. Validates the x-api-key.
2. Looks for an existing udrewLeads record with the same sessionId if one is provided.
3. Updates that record if found, or creates a new one if not found.
4. Saves feature metadata if featureId, featureID, featureName, or featureType are provided.
5. Converts latitude and longitude into a Neptune latLng value when both coordinates are present and valid numbers.
6. Uploads imageData to storage if it is present.
7. Returns the Neptune lead record ID.

If image upload fails, Neptune still continues processing the lead submission and returns success if the lead itself was saved.

If the organisation has Neptune sequencing enabled, Neptune may also create a Lead record automatically from the uDrew submission.

Field handling notes

• Neptune accepts either featureId or featureID. If both are present, featureId is used.
• Neptune only saves location data when both latitude and longitude are provided and can be parsed into valid numbers.
• When sequencing is enabled, the saved latLng value is also copied onto the auto-created Lead record.

Success response

{
  "ok": true,
  "leadId": "abc123",
  "isUpdate": false
}

Error responses

2. uDrewWidget

Use this endpoint when the uDrew planning widget built into Neptune sends a generated image back to Neptune for a specific customer.

Request

• Method: POST
• Headers:
  • Content-Type: application/json

Authentication

This endpoint does not use an API key.

Instead, Neptune validates the provided customerId by checking that the customer exists and has an organisationId.

Request body

Example body

{
  "customerId": "customer_123",
  "featureId": "feature_456",
  "featureName": "Rectangle Pool",
  "featureType": "pool",
  "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Example request

curl -X POST "https://us-central1-netpune-220210.cloudfunctions.net/uDrewWidget" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_123",
    "featureId": "feature_456",
    "featureName": "Rectangle Pool",
    "featureType": "pool",
    "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }'

What Neptune does

1. Confirms customerId, featureId, and imageData are present.
2. Loads the Neptune customer record.
3. Uses the customer’s organisationId to determine where to store the image.
4. Uploads the image to storage.
5. Creates a new record in customers/{customerId}/uploads.

The saved upload uses:

• featureName as the label if present
• otherwise featureType
• otherwise uDrew Generated

Success response

{
  "ok": true,
  "imageBucket": "org123/customerUploads/customer_123/udrew-1710000000000_Rectangle-Pool.png",
  "customerId": "customer_123",
  "featureId": "feature_456"
}

Error responses

Image format notes

Both endpoints accept imageData as either:

• a full data URL, for example data:image/png;base64,...
• a raw base64 string

Neptune currently recognises:

• image/jpeg
• image/jpg
• image/webp

If the image type cannot be recognised from the provided string, Neptune defaults to png.