v1Stable

Partner API Reference

Base URL: https://api.holidaynannies.com/v1

Holiday Nannies — Partner API v1

Base URL: https://api.holidaynannies.com/v1 Protocol: HTTPS (TLS 1.3) Format: JSON Authentication: Bearer token (API key issued per partner) Rate Limit: 1,000 requests/minute per partner key Environments: sandbox.api.holidaynannies.com (testing) · api.holidaynannies.com (production)

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer hn_live_k7x2m9p4...

Partner API keys are issued during onboarding. Each key is scoped to the partner's contracted destinations and rate card. Sandbox keys (hn_test_...) return mock data and never create real bookings.

Header	Required	Description
`Authorization`	Yes	`Bearer {api_key}`
`X-Partner-ID`	Yes	Your assigned partner identifier
`X-Idempotency-Key`	Conditional	Required on all `POST` requests to prevent duplicate operations
`Accept-Language`	No	`en` (default), `ko`, `ja`, `zh` — controls language of nanny bios and destination descriptions

Standard Response Envelope

All responses follow a consistent structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_8f3k2m1n",
    "timestamp": "2026-05-12T14:30:00Z"
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "NANNY_UNAVAILABLE",
    "message": "The requested nanny is not available for the specified dates.",
    "details": { ... }
  },
  "meta": {
    "request_id": "req_8f3k2m1n",
    "timestamp": "2026-05-12T14:30:00Z"
  }
}

1. Destinations

`GET /destinations`

Returns all destinations available under the partner's contract.

Query Parameters:

Param	Type	Description
`country`	string	Filter by ISO 3166-1 alpha-2 country code (e.g., `PH`, `ID`, `AU`)
`status`	string	`live` (default), `waitlist`

Response:

{
  "success": true,
  "data": [
    {
      "id": "c3a1f8e2-7b94-4d6e-a012-9f8c5d3b7e61",
      "slug": "boracay",
      "name": "Boracay",
      "country": "PH",
      "country_name": "Philippines",
      "timezone": "Asia/Manila",
      "status": "live",
      "nanny_count": 12,
      "currency": "PHP",
      "cover_image_url": "https://cdn.holidaynannies.com/destinations/boracay-cover.jpg",
      "description": "White Beach and surrounding resort areas",
      "supported_services": ["full_day", "half_day", "overtime_hourly", "nighttime"],
      "advance_booking_hours": 24
    }
  ]
}

`GET /destinations/{destination_id}`

Returns detail for a single destination including the partner-specific rate card.

Accepts either the destination UUID or slug (e.g., /destinations/boracay).

Response:

{
  "success": true,
  "data": {
    "id": "c3a1f8e2-7b94-4d6e-a012-9f8c5d3b7e61",
    "slug": "boracay",
    "name": "Boracay",
    "country": "PH",
    "timezone": "Asia/Manila",
    "status": "live",
    "nanny_count": 12,
    "description": "White Beach and surrounding resort areas",
    "rate_card": {
      "currency": "PHP",
      "full_day_8hr": 4500,
      "half_day_4hr": 2800,
      "overtime_per_hour": 650,
      "nighttime_4hr": 3200,
      "nighttime_per_extra_hour": 750
    },
    "operating_hours": {
      "earliest_start": "06:00",
      "latest_end": "00:00"
    },
    "cancellation_policy": {
      "free_cancellation_hours": 48,
      "late_cancellation_fee_percent": 50
    }
  }
}

2. Nanny Profiles

`GET /nannies`

Search and browse vetted nannies available in contracted destinations.

Query Parameters:

Param	Type	Description
`destination_id`	string	Required. Filter by destination UUID or slug
`date`	string	`YYYY-MM-DD` — only return nannies available on this date
`service_type`	string	`full_day`, `half_day`, `nighttime`
`languages`	string	Comma-separated. e.g., `en,ko`
`min_rating`	number	Minimum average rating (1.0–5.0)
`specializations`	string	Comma-separated. `infant`, `toddler`, `school_age`, `special_needs`, `first_aid_certified`, `swimming_certified`
`sort`	string	`rating_desc` (default), `experience_desc`, `bookings_desc`
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 20, max: 50)

Response:

{
  "success": true,
  "data": [
    {
      "id": "f7e2a9d1-3c84-4b5f-9012-6d8e4a2c1b73",
      "display_name": "Maria G.",
      "profile_photo_url": "https://cdn.holidaynannies.com/nannies/f7e2a9d1/profile.jpg",
      "destination": {
        "id": "c3a1f8e2-7b94-4d6e-a012-9f8c5d3b7e61",
        "name": "Boracay"
      },
      "languages": ["en", "tl"],
      "years_experience": 6,
      "specializations": ["infant", "toddler", "first_aid_certified"],
      "bio_short": "Experienced childcare professional with 6 years working with resort families. First aid and CPR certified.",
      "rating": {
        "average": 4.8,
        "total_reviews": 34
      },
      "total_bookings": 87,
      "verification_status": "fully_verified",
      "available_on_requested_date": true
    }
  ],
  "meta": {
    "request_id": "req_9x2k3m",
    "timestamp": "2026-05-12T14:30:00Z",
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_results": 8,
      "total_pages": 1
    }
  }
}

`GET /nannies/{nanny_id}`

Full profile for a specific nanny.

Response:

{
  "success": true,
  "data": {
    "id": "f7e2a9d1-3c84-4b5f-9012-6d8e4a2c1b73",
    "display_name": "Maria G.",
    "profile_photo_url": "https://cdn.holidaynannies.com/nannies/f7e2a9d1/profile.jpg",
    "gallery": [
      "https://cdn.holidaynannies.com/nannies/f7e2a9d1/gallery-1.jpg",
      "https://cdn.holidaynannies.com/nannies/f7e2a9d1/gallery-2.jpg"
    ],
    "video_intro_url": "https://cdn.holidaynannies.com/nannies/f7e2a9d1/intro.mp4",
    "destination": {
      "id": "c3a1f8e2-7b94-4d6e-a012-9f8c5d3b7e61",
      "name": "Boracay"
    },
    "languages": ["en", "tl"],
    "years_experience": 6,
    "age_range": "25-30",
    "specializations": ["infant", "toddler", "first_aid_certified"],
    "bio": "Maria has been providing professional childcare services in Boracay for 6 years, primarily working with international resort families. She holds current first aid and CPR certifications and has experience caring for children aged 0-8. Known for her patience, creativity, and strong communication skills with both children and parents.",
    "certifications": [
      {
        "name": "First Aid & CPR",
        "issuer": "Philippine Red Cross",
        "valid_until": "2027-03-15"
      }
    ],
    "verification": {
      "status": "fully_verified",
      "identity_verified": true,
      "background_check": true,
      "references_verified": true,
      "verified_at": "2025-11-20T00:00:00Z"
    },
    "rating": {
      "average": 4.8,
      "total_reviews": 34,
      "breakdown": {
        "5": 28,
        "4": 4,
        "3": 2,
        "2": 0,
        "1": 0
      }
    },
    "total_bookings": 87,
    "member_since": "2024-06-10"
  }
}

`GET /nannies/{nanny_id}/reviews`

Paginated reviews for a specific nanny.

Query Parameters:

Param	Type	Description
`sort`	string	`recent` (default), `highest`, `lowest`
`page`	integer	Page number
`per_page`	integer	Default: 10, max: 50

Response:

{
  "success": true,
  "data": [
    {
      "id": "a4b8c2d1-9e73-4f5a-b612-3c7d8e9f0a12",
      "rating": 5,
      "comment": "Maria was wonderful with our two kids. She was punctual, attentive, and the children loved her. Would book again without hesitation.",
      "guest_display_name": "The K. Family",
      "guest_country": "KR",
      "service_type": "full_day",
      "booking_date": "2026-04-18",
      "created_at": "2026-04-20T08:00:00Z"
    }
  ]
}

3. Availability

`GET /availability`

Check nanny availability across a date range. Use this to power calendar displays or pre-filter before booking.

Query Parameters:

Param	Type	Description
`destination_id`	string	Required. UUID or slug
`start_date`	string	Required. `YYYY-MM-DD`
`end_date`	string	Required. `YYYY-MM-DD` (max 30-day range)
`nanny_id`	string	Optional. Check specific nanny; omit for all nannies in destination
`service_type`	string	`full_day`, `half_day`, `nighttime`

Response:

{
  "success": true,
  "data": {
    "destination_id": "c3a1f8e2-7b94-4d6e-a012-9f8c5d3b7e61",
    "date_range": {
      "start": "2026-06-01",
      "end": "2026-06-07"
    },
    "availability": [
      {
        "date": "2026-06-01",
        "available_nannies": 8,
        "nannies": [
          {
            "id": "f7e2a9d1-3c84-4b5f-9012-6d8e4a2c1b73",
            "display_name": "Maria G.",
            "available_services": ["full_day", "half_day", "nighttime"]
          },
          {
            "id": "b2d4e6f8-1a3c-5b7d-9e2f-4a6c8d0e2f4a",
            "display_name": "Anna R.",
            "available_services": ["full_day", "half_day"]
          }
        ]
      }
    ]
  }
}

4. Bookings

`POST /bookings`

Create a new booking. Supports both nanny-specific and "Best Available" matching.

Bookings are confirmed upon successful payment. Partners using prepaid credit have bookings debited from their balance at confirmation. Partners on invoiced billing are charged to their account.

Request Body:

{
  "destination_id": "c3a1f8e2-7b94-4d6e-a012-9f8c5d3b7e61",
  "nanny_id": "f7e2a9d1-3c84-4b5f-9012-6d8e4a2c1b73",
  "matching_preference": "specific",
  "service_type": "full_day",
  "date": "2026-06-15",
  "care_start_time": "08:00",
  "care_end_time": "16:00",
  "location": {
    "type": "hotel",
    "name": "Shangri-La Boracay Resort & Spa",
    "address": "Barangay Yapak, Boracay Island",
    "room_number": "412"
  },
  "children": [
    {
      "first_name": "Jiwon",
      "age_years": 3,
      "special_needs": null,
      "notes": "Shy initially but warms up quickly. Peanut allergy — please avoid."
    }
  ],
  "guest": {
    "first_name": "Hyunwoo",
    "last_name": "Park",
    "email": "h.park@example.com",
    "phone": "+821012345678",
    "preferred_language": "ko",
    "nationality": "KR"
  },
  "partner_reference": "PARTNER-REF-20260615-0042",
  "special_requests": "Please bring age-appropriate beach toys if possible.",
  "notify_guest_via": ["email", "whatsapp"]
}

Field	Required	Notes
`destination_id`	Yes	UUID or slug
`nanny_id`	No	Omit for "Best Available" matching
`matching_preference`	Yes	`specific` or `best_available`
`service_type`	Yes	`full_day`, `half_day`, `nighttime`
`date`	Yes	`YYYY-MM-DD`
`care_start_time`	Yes	`HH:MM` in destination local time
`care_end_time`	Yes	`HH:MM` in destination local time
`children`	Yes	Array, min 1
`guest`	Yes	Parent/guardian contact details
`partner_reference`	No	Your internal booking reference for reconciliation

Response:

{
  "success": true,
  "data": {
    "id": "bk_7k3m9x2p-a1b2-4c5d-e6f7-8g9h0i1j2k3l",
    "status": "confirmed",
    "destination": {
      "id": "c3a1f8e2-7b94-4d6e-a012-9f8c5d3b7e61",
      "name": "Boracay"
    },
    "nanny": {
      "id": "f7e2a9d1-3c84-4b5f-9012-6d8e4a2c1b73",
      "display_name": "Maria G.",
      "profile_photo_url": "https://cdn.holidaynannies.com/nannies/f7e2a9d1/profile.jpg",
      "phone": "+639171234567"
    },
    "service_type": "full_day",
    "date": "2026-06-15",
    "care_start_time": "08:00",
    "care_end_time": "16:00",
    "pricing": {
      "currency": "PHP",
      "base_rate": 4500,
      "overtime_hours": 0,
      "overtime_charge": 0,
      "total": 4500
    },
    "partner_reference": "PARTNER-REF-20260615-0042",
    "confirmation_code": "HN-7K3M9X",
    "cancellation_deadline": "2026-06-13T16:00:00+08:00",
    "created_at": "2026-05-12T14:35:00Z"
  }
}

Booking Statuses:

Status	Description
`pending_match`	"Best Available" booking awaiting nanny assignment
`confirmed`	Nanny assigned and booking confirmed
`in_progress`	Care session is currently active
`completed`	Care session finished
`cancelled`	Cancelled by guest or partner
`no_show`	Guest did not show for the booking

`GET /bookings/{booking_id}`

Retrieve current booking status and details.

`GET /bookings`

List bookings with filters.

Query Parameters:

Param	Type	Description
`status`	string	Filter by status
`destination_id`	string	Filter by destination
`date_from`	string	`YYYY-MM-DD`
`date_to`	string	`YYYY-MM-DD`
`partner_reference`	string	Look up by your internal reference
`guest_email`	string	Look up by guest email
`page`	integer	Page number
`per_page`	integer	Default: 20, max: 100

`PATCH /bookings/{booking_id}`

Modify a confirmed booking (before cancellation deadline).

Modifiable Fields: care_start_time, care_end_time, service_type, location, children, special_requests

Nanny changes require cancellation and rebooking.

`POST /bookings/{booking_id}/cancel`

Cancel a booking.

Request Body:

{
  "reason": "guest_itinerary_change",
  "notes": "Family rescheduled to a different island."
}

Response includes cancellation_fee (if applicable) and refund_amount. Refunds are credited back to the partner's prepaid balance or deducted from the next invoice.

`POST /bookings/{booking_id}/extend`

Extend an active or upcoming booking by adding overtime hours.

Request Body:

{
  "additional_hours": 2,
  "new_end_time": "18:00"
}

5. Care Sessions (Live Tracking)

`GET /bookings/{booking_id}/session`

Returns live data for an in-progress care session. Partners can surface this data directly to guests within their own app or platform.

Response:

{
  "success": true,
  "data": {
    "booking_id": "bk_7k3m9x2p-a1b2-4c5d-e6f7-8g9h0i1j2k3l",
    "status": "in_progress",
    "started_at": "2026-06-15T08:02:00+08:00",
    "nanny": {
      "id": "f7e2a9d1-3c84-4b5f-9012-6d8e4a2c1b73",
      "display_name": "Maria G."
    },
    "check_ins": [
      {
        "timestamp": "2026-06-15T08:02:00+08:00",
        "type": "session_start",
        "note": "Arrived at the resort. Met the family at the lobby.",
        "photo_urls": []
      },
      {
        "timestamp": "2026-06-15T10:15:00+08:00",
        "type": "activity_update",
        "note": "Kids are having a great time building sandcastles on the beach.",
        "photo_urls": [
          "https://cdn.holidaynannies.com/sessions/bk_7k3m9x2p/update-1a.jpg"
        ]
      }
    ],
    "location": {
      "last_updated": "2026-06-15T12:35:00+08:00",
      "latitude": 11.9674,
      "longitude": 121.9249,
      "accuracy_meters": 15
    }
  }
}

6. Webhooks

Partners register webhook endpoints to receive real-time event notifications. All webhooks are signed with HMAC-SHA256 using a shared secret for verification.

Verification

X-HN-Signature: sha256=a1b2c3d4e5...
X-HN-Timestamp: 1718460600

Verify by computing HMAC-SHA256(timestamp + "." + raw_body, webhook_secret).

Events

Event	Trigger
`booking.confirmed`	Nanny assigned, booking confirmed
`booking.nanny_matched`	"Best Available" nanny assigned
`booking.cancelled`	Booking cancelled (includes reason and any applicable fees)
`booking.reminder`	24hr and 2hr reminders before session start
`session.started`	Nanny checked in; care session began
`session.check_in`	Nanny posted a photo or activity update
`session.location_update`	GPS location update (configurable frequency)
`session.completed`	Care session ended
`session.overtime_started`	Session exceeded original end time; overtime billing in effect
`review.submitted`	Guest submitted a post-session review
`billing.credit_low`	Prepaid credit balance below configured threshold
`billing.invoice_generated`	Monthly invoice ready for download

Webhook Payload Example:

{
  "event": "session.check_in",
  "timestamp": "2026-06-15T10:15:00Z",
  "data": {
    "booking_id": "bk_7k3m9x2p-a1b2-4c5d-e6f7-8g9h0i1j2k3l",
    "partner_reference": "PARTNER-REF-20260615-0042",
    "check_in": {
      "type": "activity_update",
      "note": "Kids are having a great time building sandcastles on the beach.",
      "photo_urls": [
        "https://cdn.holidaynannies.com/sessions/bk_7k3m9x2p/update-1a.jpg"
      ]
    }
  }
}

7. Reviews

`POST /bookings/{booking_id}/review`

Submit a guest review after session completion.

Request Body:

{
  "rating": 5,
  "comment": "Fantastic experience. Very attentive nanny and the photo updates throughout the day gave us total peace of mind.",
  "guest_display_name": "The P. Family"
}

8. Billing

Holiday Nannies offers two billing models for partner accounts.

Prepaid Credit (Preferred)

Partners load credit to their account. Each booking is debited from the balance at confirmation. Partners on prepaid credit receive preferred rate card pricing and priority nanny matching.

`GET /billing/balance`

{
  "success": true,
  "data": {
    "currency": "USD",
    "available_balance": 5240.00,
    "reserved": 450.00,
    "low_balance_threshold": 1000.00,
    "auto_topup_enabled": false
  }
}

`GET /billing/transactions`

Query Parameters:

Param	Type	Description
`type`	string	`credit`, `debit`, `refund`
`date_from`	string	`YYYY-MM-DD`
`date_to`	string	`YYYY-MM-DD`
`page`	integer	Page number
`per_page`	integer	Default: 20, max: 100

Invoice Billing

Partners on invoice billing are billed monthly. Volume discounts may apply based on partnership agreement terms.

`GET /billing/invoices`

List invoices.

Query Parameters:

Param	Type	Description
`status`	string	`draft`, `issued`, `paid`, `overdue`
`period`	string	`YYYY-MM`

`GET /billing/invoices/{invoice_id}`

Response:

{
  "success": true,
  "data": {
    "id": "inv_2026_06",
    "period": "2026-06",
    "status": "issued",
    "currency": "USD",
    "summary": {
      "total_bookings": 142,
      "total_care_hours": 1036,
      "subtotal_usd": 17040.00,
      "volume_discount_percent": 5,
      "volume_discount_usd": -852.00,
      "cancellation_fees_usd": 240.00,
      "total_due_usd": 16428.00
    },
    "issued_at": "2026-07-01T00:00:00Z",
    "due_date": "2026-07-31",
    "pdf_url": "https://api.holidaynannies.com/v1/billing/invoices/inv_2026_06/pdf"
  }
}

9. Partner Analytics

`GET /analytics/summary`

Aggregated performance metrics for the partner's account.

Query Parameters:

Param	Type	Description
`period`	string	`YYYY-MM` or `YYYY`
`destination_id`	string	Optional filter

Response:

{
  "success": true,
  "data": {
    "period": "2026-06",
    "total_bookings": 142,
    "bookings_by_status": {
      "completed": 130,
      "cancelled": 8,
      "no_show": 4
    },
    "average_rating": 4.7,
    "total_reviews": 98,
    "average_response_time_minutes": 12,
    "top_destinations": [
      { "destination": "Boracay", "bookings": 68 },
      { "destination": "Cebu", "bookings": 41 },
      { "destination": "Bohol", "bookings": 33 }
    ],
    "repeat_booking_rate_percent": 34,
    "total_care_hours": 1036
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key missing, expired, or invalid
`PARTNER_NOT_ACTIVE`	403	Partner account suspended or not yet activated
`DESTINATION_NOT_CONTRACTED`	403	Destination not included in partner agreement
`INSUFFICIENT_CREDIT`	402	Prepaid balance too low to confirm booking
`NANNY_UNAVAILABLE`	409	Nanny is already booked for requested date/time
`INSUFFICIENT_NOTICE`	422	Booking does not meet minimum advance notice requirement
`PAST_CANCELLATION_DEADLINE`	422	Cancellation deadline has passed
`INVALID_DATE_RANGE`	422	Date range exceeds maximum or is in the past
`CHILDREN_REQUIRED`	422	At least one child must be included in booking
`RATE_LIMIT_EXCEEDED`	429	Too many requests; retry after Retry-After header value
`INTERNAL_ERROR`	500	Unexpected server error; contact support

SDKs & Integration Support

Resource	Description
OpenAPI 3.1 Spec	`https://api.holidaynannies.com/v1/openapi.json`
Postman Collection	Available on request
JavaScript/TypeScript SDK	`npm install @holidaynannies/partner-sdk`
Python SDK	`pip install holidaynannies`
Webhook Testing Tool	Available in Partner Dashboard
Partner Dashboard	`https://dashboard.holidaynannies.com`
Integration Support	`partners@holidaynannies.com`
Status Page	`https://status.holidaynannies.com`

Rate Card

Partner-specific rate cards are configured during onboarding and returned dynamically via GET /destinations/{id}. Rates vary by destination, service type, and billing model.

Service	Description
Full Day	8-hour care session
Half Day	4-hour care session
Overtime	Per-hour charge beyond the booked service duration
Nighttime	Evening/night care, 4-hour minimum (after 8:00 PM)
Nighttime Overtime	Per-hour charge beyond the 4-hour nighttime minimum

Partners on prepaid credit billing receive preferred rates. Volume-based discounts are available and configured per partnership agreement.

*Holiday Nannies Partner API v1* *Appy Studios Pty Ltd (ABN 77 649 698 859) — trading as Holiday Nannies Intl.* *holidaynannies.com · partners@holidaynannies.com*

Ready to integrate?

API access requires an approved partner account. Contact us to get started.

Apply as a partner partners@holidaynannies.com