Skip to main content
All Partner API responses use a consistent JSON envelope.

Success — Single Resource

{
  "success": true,
  "data": { }
}
FieldTypeDescription
successbooleanAlways true on success
dataobject | arrayResponse payload

Example — Booking Status

{
  "success": true,
  "data": {
    "bookingId": "11111111-0000-0000-0000-000000000001",
    "status": "in progress",
    "paymentStatus": "PENDING",
    "externalReference": "ORDER-20260615-001"
  }
}

Success — Paginated List

{
  "success": true,
  "data": [ ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}
FieldTypeDescription
dataarrayCurrent page items
meta.pagenumberCurrent page (1-based)
meta.limitnumberPage size
meta.totalnumberTotal matching records
meta.totalPagesnumberceil(total / limit)

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": { },
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
FieldTypeDescription
successbooleanAlways false on error
error.codestringMachine-readable error code (see Errors)
error.messagestringHuman-readable summary
error.detailsobjectOptional validation details or extra context
error.requestIdstringTrace ID — include when contacting support
The same requestId is returned in the X-Request-Id response header.

HTTP Status Codes

StatusMeaning
200Success (GET, PATCH, POST actions)
201Created (booking, webhook subscription)
400Validation error
401Missing or invalid API key
403Forbidden (permission or domain)
404Resource not found
409Conflict (e.g. duplicate externalReference)
422Business rule violation
429Rate limit exceeded
500Internal server error

Validation Errors

When error.code is VALIDATION_ERROR, error.details may contain field-level messages from class-validator:
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "message": [
        "contactId must be a UUID",
        "date must be a valid ISO 8601 date string"
      ]
    },
    "requestId": "..."
  }
}

Null & Omitted Fields

  • Optional fields may be omitted or null depending on the endpoint.
  • Empty arrays are returned as [], not null.
  • Monetary amounts are numbers in SAR with up to two decimal places in API output.