{
 "openapi": "3.0.3",
 "info": {
  "title": "SUURA partner API (test mode)",
  "version": "1.0.0-test",
  "description": "Test mode only. No real insurer is contacted and records are invented and deleted after 30 days. Not for real customer data."
 },
 "servers": [
  {
   "url": "https://www.suura.co.uk/api/v1"
  }
 ],
 "security": [
  {
   "bearer": []
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "Test secret key starting sk_embed_test_. Server-side only."
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       },
       "details": {
        "type": "array",
        "items": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "Status": {
    "type": "string",
    "enum": [
     "received",
     "searching",
     "records_ready",
     "cannot_find"
    ]
   },
   "Request": {
    "type": "object",
    "properties": {
     "ref": {
      "type": "string",
      "example": "EMB-3F9A1C07BD"
     },
     "object": {
      "type": "string",
      "example": "request"
     },
     "status": {
      "$ref": "#/components/schemas/Status"
     },
     "status_label": {
      "type": "string"
     },
     "kind": {
      "type": "string",
      "nullable": true,
      "enum": [
       "ncd",
       "claims",
       "policy",
       "sar",
       "find"
      ]
     },
     "insurer": {
      "type": "string",
      "nullable": true
     },
     "partner_reference": {
      "type": "string",
      "nullable": true
     },
     "customer": {
      "type": "object",
      "properties": {
       "name": {
        "type": "string"
       },
       "email": {
        "type": "string"
       }
      }
     },
     "consent": {
      "type": "object",
      "properties": {
       "given": {
        "type": "boolean"
       },
       "captured_at": {
        "type": "string",
        "format": "date-time"
       },
       "wording_version": {
        "type": "string"
       }
      }
     },
     "created": {
      "type": "string",
      "format": "date-time"
     },
     "updated": {
      "type": "string",
      "format": "date-time"
     },
     "events": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "at": {
         "type": "string",
         "format": "date-time"
        },
        "status": {
         "$ref": "#/components/schemas/Status"
        },
        "text": {
         "type": "string"
        }
       }
      }
     },
     "result": {
      "type": "object",
      "nullable": true
     },
     "test": {
      "type": "boolean"
     }
    }
   },
   "CreateRequest": {
    "type": "object",
    "required": [
     "customer",
     "kind",
     "consent"
    ],
    "properties": {
     "customer": {
      "type": "object",
      "required": [
       "name",
       "email"
      ],
      "properties": {
       "name": {
        "type": "string",
        "minLength": 2,
        "maxLength": 80
       },
       "email": {
        "type": "string",
        "format": "email"
       }
      }
     },
     "kind": {
      "type": "string",
      "enum": [
       "ncd",
       "claims",
       "policy",
       "sar",
       "find"
      ]
     },
     "insurer": {
      "type": "string",
      "maxLength": 80
     },
     "partner_reference": {
      "type": "string",
      "maxLength": 64
     },
     "consent": {
      "type": "object",
      "required": [
       "given",
       "captured_at",
       "wording_version"
      ],
      "properties": {
       "given": {
        "type": "boolean",
        "enum": [
         true
        ]
       },
       "captured_at": {
        "type": "string",
        "format": "date-time"
       },
       "wording_version": {
        "type": "string",
        "maxLength": 40
       }
      }
     }
    }
   }
  }
 },
 "paths": {
  "/me": {
   "get": {
    "summary": "Check your key",
    "responses": {
     "200": {
      "description": "Partner, allowed kinds and statuses"
     },
     "401": {
      "description": "Invalid key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/requests": {
   "post": {
    "summary": "Create a test request",
    "parameters": [
     {
      "name": "Idempotency-Key",
      "in": "header",
      "schema": {
       "type": "string",
       "minLength": 8,
       "maxLength": 64
      }
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CreateRequest"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Created",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Request"
        }
       }
      }
     },
     "200": {
      "description": "Idempotent replay"
     },
     "409": {
      "description": "Idempotency conflict",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "Validation failed",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   },
   "get": {
    "summary": "List requests, newest first",
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 20
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "A page of requests"
     }
    }
   }
  },
  "/requests/{ref}": {
   "get": {
    "summary": "Retrieve a request",
    "parameters": [
     {
      "name": "ref",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^EMB-[A-F0-9]{10}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The request",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Request"
        }
       }
      }
     },
     "404": {
      "description": "Not found",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/sandbox/requests/{ref}/advance": {
   "post": {
    "summary": "Move a test request on (test mode only)",
    "parameters": [
     {
      "name": "ref",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "status": {
          "$ref": "#/components/schemas/Status"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Updated request"
     },
     "409": {
      "description": "Already final",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/webhook": {
   "get": {
    "summary": "Show the webhook address",
    "responses": {
     "200": {
      "description": "Webhook settings"
     }
    }
   },
   "post": {
    "summary": "Register or replace the webhook (returns a new signing secret once)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "url"
        ],
        "properties": {
         "url": {
          "type": "string",
          "format": "uri"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Registered, with signing_secret"
     },
     "422": {
      "description": "Invalid url",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   },
   "delete": {
    "summary": "Remove the webhook",
    "responses": {
     "200": {
      "description": "Removed"
     }
    }
   }
  },
  "/webhook/test": {
   "post": {
    "summary": "Send a test event",
    "responses": {
     "200": {
      "description": "Delivery result"
     },
     "409": {
      "description": "No webhook registered",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/webhook/deliveries": {
   "get": {
    "summary": "Last 10 delivery attempts",
    "responses": {
     "200": {
      "description": "List"
     }
    }
   }
  }
 },
 "x-webhooks": {
  "request.created": {
   "description": "Fired when a request is created"
  },
  "request.status_changed": {
   "description": "Fired when status changes"
  },
  "webhook.test": {
   "description": "Fired by POST /webhook/test"
  }
 }
}