> ## Documentation Index > Fetch the complete documentation index at: https://docs.pingintel.com/llms.txt > Use this file to discover all available pages before exploring further. # List Historical SOVs > List completed and failed SOVs and SOV Update Data (SUD) in chronological order. Supply `start` to begin at a specific timestamp. Pass the returned `cursor_id` in each subsequent request to page through results. Intended for periodic polling to stay current with all processed submissions. ## OpenAPI ````yaml https://api-staging.sovfixer.com/api/schema/?format=json get /api/v1/sov/history openapi: 3.0.3 info: title: Ping.Extraction API version: v1.0 description: >- ### Ping.Extraction API This API provides an asynchronous method for parsing Excel SOV documents using the Ping Intel SOV Fixer platform. The typical SOV Fixer usage flow is: * POST to `/api/v1/sov` * Poll GET `/api/v1/sov/{id}`, passing the `id` given by the previous response until `response.request.status` is `COMPLETE` or `FAILED`. Depending on load, number of buildings in the SOV, and 3rd party integrations, it may take anywhere from a few seconds to many minutes. * Download the parsed SOV data as JSON from `/api/v1/sov/{id}/output/{filename}`. The exact url comes from the response to the above query, in `response.result.outputs[].url`. API Usage Examples: [Python](/api/v1/sov-api-usage-example.py) | [.NET](/api/v1/sov-api-usage-example.cs) Client Libraries: [Python](https://pypi.org/project/pingintel-api/) #### Authorization Most endpoints are protected by Bearer authentication. Under each endpoint listed below, click into the `authorizations` section to see what is required for that endpoint. #### Output JSON Example: ```json { "id": "s-e-xxxxxxx", "source_filename": "My Example SOV.xls", "num_buildings": 26, "extra_data": { "insured_name": "Joe Insured", "... custom document-level data fields ...": "" }, "buildings": [ { "item_key": "i-s-e-xxxxxxx!Original SOV Sheet!7", "building_counter": 1, "sheet_name": "Original SOV Sheet", "sheet_row_number": 7, "parsing_sheet_name": "Original SOV Sheet", "location_code": { "value": "A-1", "confidence": 0.5, "comment": "Adjusted." }, "bldg_name": { "value": "Elementary School", "confidence": 0.7 }, "street": { "value": "1212 Mockingbird Lane", "confidence": 0.7 }, "city": { "value": "Tewksbury", "confidence": 0.5 }, "state": { "original": "Mass", "value": "MA", "confidence": 0.9 }, "zip": { "value": "01876", "original": 1876, "confidence": 0, "comment": "Please check." }, "... more building attributes ...": "", "external_data": { "PG": { "latitude": 42.6109, "longitude": -71.2342, "confidence": 0.9, "street": "1212 Mockingbird Ln", "city": "Tewksbury", "... rest of the data from the Ping Geocoding (PG) external data source ...": "" }, "... any other requested third party data sources ...": "" }, "extra": { "... columns that were not identified as a standard SOV field ...": "", "Unidentified Column": "123213", "Another Unidentified Column": "abc" } }, "... additional buildings ...": "" ] } ``` Complete JSON reference documentation can be found for each output type: [SOV](/docs/data/SOV/) | [Premium BDX](/docs/data/PREM_BDX/) | [Claim BDX](/docs/data/CLAIM_BDX/). Some notes about specific JSON output fields: * `limits__total_limit`: Contains the TIV if explicitly specified in the SOV. If not, it is summed from the fields `limits__building_limit` + `limits__bpp_limit` + `limits__bi_limit` + `limits__signs_and_other_limit`. * `limits__building_limit`: Building Limit is an aggregate of: * `limits__building_value` * `limits__location_limit` * `limits__blanket_limit` * `limits__building_only_limit` * `limits__real_property_limit` * `limits__structure_limit` * `limits__bpp_limit`: Business Personal Property (Contents) Limit is an aggregate of: * `limits__contents_value` * `limits__contents_limit` * `limits__bpp_value` * `limits__equip_limit` * `limits__personal_property_limit` * Any field identified as a limit field but not otherwise categorized. * `limits__bi_limit`: Business Interruption Limit is an aggregate of: * `limits__bi_value` * `limits__bi_income_limit` * `limits__business_interruption_limit` * `limits__time_element_limit` * `limits__signs_and_other_limit`: Signs and Other Structures Limit is an aggregate of: * `limits__signs_limit` * `limits__other_structures_limit` ### Ping Intel SOV History API This API provides a method for accessing historical SOV submissions including their revisions (SOV Updates) and the raw parsed output. The typical usage workflow is: * GET to `api/v1/sov/history?start={start_timestamp}` for a list of SOVIDs submitted between `start_timestamp` and now. * For each sovid: * GET to `api/v1/sov/history/{id}` to get information about the SOV or SOV Update. This includes any output we produced in servicing the request * GET to the the URL in the outputs dict to download the resource you need. contact: email: support@pingintel.com name: Ping Intel url: https://www.pingintel.com servers: - url: https://api.sovfixer.com description: Ping.Extraction API - url: https://api-staging.sovfixer.com description: Ping.Extraction API (staging) security: [] paths: /api/v1/sov/history: get: tags: - Get SOV Data summary: List Historical SOVs description: >- List completed and failed SOVs and SOV Update Data (SUD) in chronological order. Supply `start` to begin at a specific timestamp. Pass the returned `cursor_id` in each subsequent request to page through results. Intended for periodic polling to stay current with all processed submissions. operationId: sov_history_retrieve parameters: - in: query name: cursor_id schema: type: string minLength: 1 description: >- Optional. The last received SOV or SOV Update Data (SUD) id. When this parameter is set, the page of results will start on the next record after this id. Defaults to the first result on or after the start timestamp. - in: query name: page_size schema: type: integer maximum: 250 minimum: 1 default: 50 description: Optional. The maximum number of results returned in a page. - in: query name: start schema: type: string format: date-time description: >- Optional. Start timestamp for which results will be returned. All timestamps are UTC. It should be formatted like `%Y%m%d%H%M%S`. E.g. `Jan 1 2023 1:00 PM` would be given as `20230101130000`. responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListHistory' description: Successful response with a list of historical SOVs. '400': content: application/json: schema: $ref: '#/components/schemas/SOVHistoryError400' description: '' '401': content: application/json: schema: $ref: '#/components/schemas/SOVHistoryError401' description: '' security: - tokenAuth: [] - cookieAuth: [] components: schemas: ListHistory: type: object properties: results: type: array items: $ref: '#/components/schemas/ListHistoryResult' description: >- SOV and SUD records sorted in ascending order by completion time. Contains up to `page_size` items. cursor_id: type: string description: >- The last SOV or SUD id returned in a set of results. Pass this value as `cursor_id` in the next request to retrieve the following page of results. required: - results SOVHistoryError400: type: object properties: error: type: string description: Server error message detail. required: - error SOVHistoryError401: type: object properties: detail: type: string description: Authorization error message. required: - detail ListHistoryResult: type: object properties: completed_time: type: string format: date-time description: Time this SOV or SUD reached a terminal status (COMPLETE or FAILED). id: type: string description: >- SOV ID or SOV Update Data ID (SUDID) for this record. Pass this value as `id` to Get Historical SOV to retrieve outputs. pingid: type: string nullable: true description: Ping ID associated with this SOV or SUD, if any. record_type: enum: - ORIG - SCRUB - AIR - RMS - RMS_ANALYSIS - API - COMPLETE - PINGREADY - READY_FOR_REVIEW - PRECERTIFIED - MODELING_FILES_CREATED type: string x-spec-enum-id: cf66b32ef5fb8a64 description: |- The type of record. * `ORIG` - Original SOV * `SCRUB` - Scrubber Reoutput * `AIR` - AIR Exports * `RMS` - RMS Exports * `RMS_ANALYSIS` - RMS Analysis * `API` - API Reoutput * `COMPLETE` - Scrubbing Complete * `PINGREADY` - Ping Ready * `READY_FOR_REVIEW` - Ready for Review * `PRECERTIFIED` - Clone Pre-Certified * `MODELING_FILES_CREATED` - Modeling Files Created sovid: type: string description: >- The originating SOV ID. Identical to `id` when this record is an original SOV; differs when this record is a SUD. client_ref: type: string nullable: true description: Client reference supplied when this SOV was submitted, if any. incremental: type: boolean default: false description: Reserved for future use. is_data_ready: type: boolean nullable: true description: >- Whether the enriched building data for this SOV or SUD is ready to download. revision: type: integer description: >- Revision number for this record. `0` identifies the original SOV; values greater than 0 identify subsequent SUDs. status: enum: - P - I - E - R - C - F type: string x-spec-enum-id: c6faa696db72d849 description: |- Processing status of this SOV or SUD. * `P` - Pending * `I` - In Progress * `E` - Enriching * `R` - Re-enriching * `C` - Complete * `F` - Failed required: - completed_time - id - pingid - record_type - sovid securitySchemes: tokenAuth: type: apiKey in: header name: Authorization description: Token-based authentication with required prefix "Token" cookieAuth: type: apiKey in: cookie name: sessionid ````