Insurer API documentationv1 · draft

API reference

Packages

Packages (your products) are authored by your staff in the Wathiqaty portal, because benefits, wordings and documents need a human. Through the API your core system keeps the pricing and the on-sale state in sync. Price changes apply to quotes from the next request. Policies already sold keep the price they were sold at.

Base URL https://sandbox-api.wathiqaty.com/api/v1 (sandbox) · https://api.wathiqaty.com/api/v1 (production)

List packages

GET/partner/packages

Scope: packages:read

Query parameters

Name	Description
`insuranceType` string	Line of business. One of: `individual_medical`, `new_cars`
`status` string	Only `active` packages are sold. One of: `draft`, `active`, `inactive`
`updatedSince` date-time	Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed).
`page` integer	Page number, from 1. Default 1.
`size` integer	Items per page, 1–100. Default 20.
`sortOrder` string	Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed. One of: `asc`, `desc`

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/packages" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · A page of packages.

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13",
        "insuranceType": "individual_medical",
        "status": "active",
        "name": {
          "en": "Gold Care",
          "ar": "جولد كير"
        },
        "externalReference": "PRD-GOLD-2026",
        "sumInsured": "250000.00",
        "readiness": {
          "sellable": true,
          "missing": []
        },
        "version": 7,
        "createdAt": "2026-09-01T08:00:00.000Z",
        "updatedAt": "2026-11-02T10:20:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "size": 20,
      "totalItems": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/packages",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Get a package

GET/partner/packages/{id}

Scope: packages:read

readiness.missing lists what blocks activation. The ETag header (and version) is what to send as If-Match on writes.

Path parameters

Name	Description
`id` uuidrequired	The package's Wathiqaty id.

Errors

Status	Code	When
404	`not_found`	Package doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/packages/{id}" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · The package.

{
  "status": "success",
  "data": {
    "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13",
    "insuranceType": "individual_medical",
    "status": "active",
    "name": {
      "en": "Gold Care",
      "ar": "جولد كير"
    },
    "externalReference": "PRD-GOLD-2026",
    "sumInsured": "250000.00",
    "readiness": {
      "sellable": true,
      "missing": []
    },
    "version": 7,
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-11-02T10:20:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/packages/5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Get pricing rules

GET/partner/packages/{id}/rating-rules

Scope: packages:read

Each rule matches a customer profile (criteria) and sets a tax-inclusive price; loadings add a percentage for specific answers.

Path parameters

Name	Description
`id` uuidrequired	The package's Wathiqaty id.

Errors

Status	Code	When
404	`not_found`	Package doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X GET "https://sandbox-api.wathiqaty.com/api/v1/partner/packages/{id}/rating-rules" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · The package's rules.

{
  "status": "success",
  "data": {
    "version": 7,
    "rules": [
      {
        "id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "price": "9500.00",
        "criteria": [
          {
            "factor": "age",
            "min": 18,
            "max": 35
          },
          {
            "factor": "gender",
            "values": [
              "male",
              "female"
            ]
          }
        ],
        "loadings": [
          {
            "factor": "pre_existing_condition",
            "value": "diabetes",
            "percent": "15.00"
          }
        ]
      },
      {
        "id": "9b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e",
        "price": "12800.00",
        "criteria": [
          {
            "factor": "age",
            "min": 36,
            "max": 50
          }
        ],
        "loadings": []
      }
    ]
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Replace pricing rules

PUT/partner/packages/{id}/rating-rules

Scope: packages:writeIdempotency-Key optionalIf-Match

Replaces all rules of the package in one transaction. Rules not in the body are removed. Counts as 10 requests against your rate limit.

Path parameters

Name	Description
`id` uuidrequired	The package's Wathiqaty id.

Body (JSON)

Name	Description
`rules` object[]required	1–500 rules: `{ price (decimal string), criteria[{ factor, min?, max?, values? }], loadings[{ factor, value, percent }] }`.

Errors

Status	Code	When
404	`not_found`	Package doesn't exist or isn't your company's.
412	`version_conflict`	Changed since you read it (`If-Match` doesn't match). Reload and retry.
422	`validation_error`	A rule is invalid (`details.fields`, e.g. `rules.3.price`).
422	`unknown_rating_factor`	A factor or value isn't one your company has selected.

Plus the generic errors any route can return: Errors.

curl -X PUT "https://sandbox-api.wathiqaty.com/api/v1/partner/packages/{id}/rating-rules" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "If-Match: W/"7"" \
  -d '{"rules":[{"price":"9500.00","criteria":[{"factor":"age","min":18,"max":35},{"factor":"gender","values":["male","female"]}],"loadings":[{"factor":"pre_existing_condition","value":"diabetes","percent":"15.00"}]},{"price":"12800.00","criteria":[{"factor":"age","min":36,"max":50}],"loadings":[]}]}'

200 · The new rules and the package's new version.

{
  "status": "success",
  "data": {
    "version": 8,
    "rules": [
      {
        "id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "price": "9500.00",
        "criteria": [
          {
            "factor": "age",
            "min": 18,
            "max": 35
          },
          {
            "factor": "gender",
            "values": [
              "male",
              "female"
            ]
          }
        ],
        "loadings": [
          {
            "factor": "pre_existing_condition",
            "value": "diabetes",
            "percent": "15.00"
          }
        ]
      },
      {
        "id": "9b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e",
        "price": "12800.00",
        "criteria": [
          {
            "factor": "age",
            "min": 36,
            "max": 50
          }
        ],
        "loadings": []
      }
    ]
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "PUT",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Put a package on sale

POST/partner/packages/{id}/activate

Scope: packages:write

draft or inactive → active, only when the package is complete.

Path parameters

Name	Description
`id` uuidrequired	The package's Wathiqaty id.

Errors

Status	Code	When
404	`not_found`	Package doesn't exist or isn't your company's.
422	`package_incomplete`	Something is missing (`details.missing`, e.g. `rating_rules`, `terms_and_conditions`).
409	`package_duplicate`	Another active package has the same policy and name.

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/packages/{id}/activate" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · The package, now active.

{
  "status": "success",
  "data": {
    "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13",
    "insuranceType": "individual_medical",
    "status": "active",
    "name": {
      "en": "Gold Care",
      "ar": "جولد كير"
    },
    "externalReference": "PRD-GOLD-2026",
    "sumInsured": "250000.00",
    "readiness": {
      "sellable": true,
      "missing": []
    },
    "version": 7,
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-11-02T10:20:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Take a package off sale

POST/partner/packages/{id}/deactivate

Scope: packages:write

→ inactive. Sold policies are not affected.

Path parameters

Name	Description
`id` uuidrequired	The package's Wathiqaty id.

Errors

Status	Code	When
404	`not_found`	Package doesn't exist or isn't your company's.

Plus the generic errors any route can return: Errors.

curl -X POST "https://sandbox-api.wathiqaty.com/api/v1/partner/packages/{id}/deactivate" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 · The package, now inactive.

{
  "status": "success",
  "data": {
    "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13",
    "insuranceType": "individual_medical",
    "status": "inactive",
    "name": {
      "en": "Gold Care",
      "ar": "جولد كير"
    },
    "externalReference": "PRD-GOLD-2026",
    "sumInsured": "250000.00",
    "readiness": {
      "sellable": true,
      "missing": []
    },
    "version": 7,
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-11-02T10:20:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "POST",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

Set your product code

PUT/partner/packages/{id}/external-reference

Scope: packages:write

Echoed on every policy sold from the package as packageExternalReference.

Path parameters

Name	Description
`id` uuidrequired	The package's Wathiqaty id.

Body (JSON)

Name	Description
`externalReference` stringrequired	Your own reference, 1–100 characters, unique within your company.

Errors

Status	Code	When
404	`not_found`	Package doesn't exist or isn't your company's.
409	`conflict`	Another package of yours already has this reference.

Plus the generic errors any route can return: Errors.

curl -X PUT "https://sandbox-api.wathiqaty.com/api/v1/partner/packages/{id}/external-reference" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externalReference":"PRD-GOLD-2026"}'

200 · The package.

{
  "status": "success",
  "data": {
    "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13",
    "insuranceType": "individual_medical",
    "status": "active",
    "name": {
      "en": "Gold Care",
      "ar": "جولد كير"
    },
    "externalReference": "PRD-GOLD-2026",
    "sumInsured": "250000.00",
    "readiness": {
      "sellable": true,
      "missing": []
    },
    "version": 7,
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-11-02T10:20:00.000Z"
  },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/…",
    "method": "PUT",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}