Fetch Documents

Overview

At this time, Deck must manually configure jobs to fetch documents and extract data.

Deck supports the fetching of raw documents from sources (PDF, Excel, CSV, etc.) In some cases, data extraction from those documents is also possible.
Once your fetching job is completed, the webhook will return with information to help you take action on said documents. Example of a successful webhook

{
  "job_guid": "b35aa2af-41e4-4833-95c9-9efd2069e70c",
  "output": {
     "success": true,
     "document_list_url": "https://live.deck.co/api/v1/jobs/b35aa2af-41e4-4833-95c9-9efd2069e70c/documents",
     "document_count": 12
  },
  "webhook_type": "Job",
  "webhook_code": "FetchBills",
  "environment": "Production"
}

Fetch a list of documents

You can get the list of all documents fetched during a session by calling the List documents endpoint.

curl --request GET \
  --url https://live.deck.co/api/v1/jobs/{jobGuid}/documents \
  --header 'x-deck-client-id: <api-key>' \
  --header 'x-deck-secret: <api-key>'

You will receive a response like this:

{
  "documents": [
    {
      "document_id": "<string>",
      "file_type": "<string>",
      "metadata": {},
      "file_name": "<string>",
      "file_size": 123,
      "fetch_date": "2023-11-07T05:31:56Z"
    }
  ]
}

Download documents

You can download the raw files fetched by a job by calling the Download a document endpoint. Note that you can only download one document at a time.

curl --request GET \
  --url https://live.deck.co/api/v1/jobs/documents/{documentId} \
  --header 'x-deck-client-id: <api-key>' \
  --header 'x-deck-secret: <api-key>'

The document will be automatically downloaded.

Data extraction from files

Extraction is currently limited to utility bills.

If your team has extraction enabled, jobs fetching documents will automatically parse the data and create a JSON file for every file found. Deck can easily turn this feature on or off for you. Once the extraction is complete, a DocumentExtractionSuccess webhook will be sent with a document_id and a document_extraction_id. Successful Document Extraction webhook:

{
  "webhook_type": "Document",
  "webhook_code": "DocumentExtractionSuccess",
  "environment": "Production",
  "job_guid": "65e038fd-3fdc-4f45-3029-08de33819524",
  "document_id": "15e038fd-3fdc-4f45-3029-08de33819525",
  "document_extraction_id": "65e038fd-3fdc-4f45-3029-08de33819524"
}

Failed Document Extraction webhook:
(Note how document_extraction_id is missing)

{
  "webhook_type": "Document",
  "webhook_code": "DocumentExtractionFailed",
  "environment": "Production",
  "job_guid": "65e038fd-3fdc-4f45-3029-08de33819524",
  "document_id": "15e038fd-3fdc-4f45-3029-08de33819525"
}

The document_id represents the original statement whereas the document_extraction_id denotes the extraction result of that document. Here are examples of extraction payloads:

Utility Bill
Detailed Interval Data

{
  "company_name": "energylink",
  "account_number": "58291-44720",
  "billing_date": "2025-01-22",
  "next_billing_date": "2025-02-22",
  "billing_period": {
    "start_date": "2024-12-18",
    "end_date": "2025-01-20",
    "total_days": 33
  },
  "balance_forward": 32.74,
  "previous_payments": 6892.44,
  "previous_amount_due": 6925.18,
  "new_charges": 8214.67,
  "amount_due": 8247.41,
  "payment_due_date": "2025-02-14",
  "auto_pay_date": "2025-02-07",
  "currency": "USD",
  "billing_address": {
    "name": "HARBORVIEW PROPERTIES LLP",
    "street": "217 MAPLE RIDGE AVE",
    "city": "BOSTON",
    "state": "MA",
    "postal_code": "02123-5521"
  },
  "service_locations": [
    {
      "service_type": "Fuel",
      "service_address": {
        "street": "4421 OAK VIEW LN UNIT 3A",
        "city": "CAMBRIDGE",
        "state": "MA",
        "postal_code": "02140"
      },
      "total_usage": 5348,
      "total_usage_unit": "Therms",
      "service_plan": "SC5 - Commercial Heating",
      "total_charges": 8214.67,
      "meters": [
        {
          "meter_number": "89314472",
          "usage_unit": "Therms",
          "reading_cycle": "14",
          "meter_reading": {
            "start_date": "2024-12-18",
            "end_date": "2025-01-20",
            "total_days": 33,
            "start_value": 38412,
            "end_value": 43716,
            "delta": 5304,
            "multiplier_conversion": 1.00829,
            "reading_type": "actual",
            "usage": 5348,
            "additional_data": [
              {
                "key": "Measured CCF",
                "value": "5304"
              },
              {
                "key": "Therm Factor",
                "value": "1.00829"
              }
            ]
          },
          "demand_meter_reading": {}
        }
      ],
      "charges": [
        {
          "group": "Delivery Services",
          "details": "Basic Service Charge (including first 3.3 therms)",
          "amount": 48.32
        },
        {
          "group": "Delivery Services",
          "details": "Next 1022.4 Therms",
          "amount": 678.11,
          "usage_unit": "therms",
          "usage": 1022.4,
          "usage_unit_rate": 0.663
        },
        {
          "group": "Delivery Services",
          "details": "Over/Last 4325 Therms",
          "amount": 2431.67,
          "usage_unit": "therms",
          "usage": 4325,
          "usage_unit_rate": 0.5623
        },
        {
          "group": "Delivery Services",
          "details": "delivery_rate_adj",
          "amount": 82.46,
          "usage_unit": "therms",
          "usage": 5348,
          "usage_unit_rate": 0.01542
        },
        {
          "group": "Delivery Services",
          "details": "billing_charge",
          "amount": 1.12
        },
        {
          "group": "Delivery Services",
          "details": "state_local_surcharges",
          "amount": 152.94
        },
        {
          "group": "Delivery Services",
          "details": "state_sales_tax_4_5_pct",
          "amount": 158.23
        },
        {
          "group": "Supply Services",
          "details": "gas_supply",
          "amount": 3497.28,
          "usage_unit": "therms",
          "usage": 5348,
          "usage_unit_rate": 0.65399
        },
        {
          "group": "Supply Services",
          "details": "state_local_surcharges",
          "amount": 91.77
        },
        {
          "group": "Supply Services",
          "details": "state_sales_tax_4_5_pct",
          "amount": 172.45
        }
      ]
    }
  ],
  "payments": [
    {
      "amount": 6892.44,
      "date": "2025-01-08",
      "details": "Payment Received on JAN 8 (Direct Deposit)"
    }
  ]
}

{
  "accounts": [
    {
      "account_number": "1",
      "interval_data": [
        {
          "start_date": "2024-10-01T00:00:00",
          "end_date": "2025-03-12T00:00:00",
          "duration_time_in_minutes": 15,
          "total_intervals": 4,
          "intervals": [
            {
              "start_time": "2024-10-01T00:00:00",
              "usage": null,
              "imported_usage": 1.25,
              "exported_usage": 1.25,
              "rate": null,
              "cost": 0,
              "usage_unit": "kWh",
              "meter_id": null
            },
            {
              "start_time": "2024-10-01T00:15:00",
              "usage": 0.020,
              "imported_usage": null,
              "exported_usage": null,
              "rate": null,
              "cost": null,
              "usage_unit": "kWh",
              "meter_id": null
            },
            {
              "start_time": "2024-10-01T00:30:00",
              "usage": 0.020,
              "imported_usage": null,
              "exported_usage": null,
              "rate": null,
              "cost": null,
              "usage_unit": "kWh",
              "meter_id": null
            },
            {
              "start_time": "2025-03-11T15:45:00",
              "usage": 0.000,
              "imported_usage": null,
              "exported_usage": null,
              "rate": null,
              "cost": null,
              "usage_unit": "kWh",
              "meter_id": null
            }
          ]
        }
      ]
    }
  ]
}

Extraction Data Dictionary

Top-level fields

Field name	Type	Description	Example
`company_name`	string	Name of the utility provider.	”energylink”
`account_number`	string	Unique identifier for the account.	”58291-44720”
`billing_date`	string	Date the bill was sent.	”2025-01-22”
`next_billing_date`	string	Date the next bill is stated to be sent.	”2025-02-22”
`billing_period`	object	Object containing details about the billing period.
`balance_forward`	number	Balance carried over from the previous billing period minus any payments or credits. This may have to be calculated based on previous balance plus payments made.When there is a previous balance and a payment but no balance forward provided, then it should be inferred on the basis of what was previously owed and what was paid. For example, if the previous balance was 52.96 and there is a payment of 52.96 (sometimes listed as a credit - CR), then the balance forward is 0, not 52.96.	32.74
`previous_payments`	number	Amount paid for last billing.	6892.44
`previous_amount_due`	number	Amount due at the time of last billing.	6925.18
`new_charges`	number	New charges for the current billing period.	8214.67
`amount_due`	number	Amount due for the current billing period.	8247.41
`payment_due_date`	string	Due date for the payment of this statement.	”2025-02-14”
`auto_pay_date`	string	Date on which automatic payment is set to trigger.	”2025-02-07”
`currency`	string	Currency used in the statement. (Enum: “USD”, “CAD”, “EUR”, “GBP”, “MXN”, “JPY”, “AUD”, “CNY”, “KRW”, “THB”, “INR”, “BRL”, “CHF”, “RUB”, “SGD”, “HKD”, “SEK”, “NZD”, “ZAR”, “AED”)	“USD”
`billing_address`	object	Object containing details about the billing address.
`service_locations`	array	Array containing details about the service locations.
`payments`	array	Array containing details about the payments.

`billing_period` object

Field name	Type	Description	Example
`start_date`	string	Start date of the billing period.	”2024-12-18”
`end_date`	string	End date of the billing period.	”2025-01-20”
`total_days`	number	Total number of days elapsed during the billing period.	33

`billing_address` object

Field name	Type	Description	Example
`name`	string	Name of the paying entity.	”HARBORVIEW PROPERTIES LLP”
`street`	string	Street number of the paying entity.	”217 MAPLE RIDGE AVE”
`city`	string	City of the paying entity.	”BOSTON”
`state`	string	Abbreviation of the state or province of the paying entity.	”MA”
`postal_code`	string	Postal code of the paying entity.	”02123-5521”

`service_locations` array

Field name	Type	Description	Example
`service_type`	string	Type of service.	”Fuel”
`service_address`	object	Object containing details about the service location.
`total_usage`	number	Total usage of all meters for this service location.	5348
`total_usage_unit`	string	Total usage units of all meters for this service location.	”Therms”
`service_plan`	string	Name of the service plan.	”SC5 - Commercial Heating”
`total_charges`	number	Total dollar amount of all charges for this service location.	8214.67
`meters`	array	Array containing details about the meters of the service location.
`charges`	array	Array containing details about the charges for the service location.

`service_address` object

Field name	Type	Description	Example
`street`	string	Street number of the location using the service.	”4421 OAK VIEW LN UNIT 3A”
`city`	string	City of the location using the service.	”CAMBRIDGE”
`state`	string	Abbreviation of the state or province of the location using the service.	”MA”
`postal_code`	string	Postal code of the location using the service.	”02140”

`meters` array

Field name	Type	Description	Example
`meter_number`	string	Number for the meter, as registered on the statement.	”89314472”
`usage_unit`	string	Unit of measure for the utility used.	”Therms”
`reading_cycle`	string	Recurring timeframe during which the utility company reads the meter to measure consumption.	”14”
`meter_reading`	object	Object containing details about the meter readings.
`demand_meter_reading`	object	Object containing details about the peak rate of the meter.

`meter_reading` object

Field name	Type	Description	Example
`start_date`	string	The start date of the date range for the meter reading.	”2024-12-18”
`end_date`	string	The end date of the date range for the meter reading.	”2025-01-20”
`total_days`	number	Total number of days elapsed during the billing period.	33
`start_value`	number	The value of the meter at the start of the date range.	38412
`end_value`	number	The value of the meter at the end of the date range.	43716
`delta`	number	The difference between the end_value and the start_value.	5304
`multiplier_conversion`	number	This adjusts the raw reading from the meter to account for larger consumption units.	1.00829
`reading_type`	string	The type of reading for the meter (actual, estimate or null).	“actual”
`usage`	number	Total utility used for this meter reading. This is an amount based on the units of utility, not a dollar amount.	5348
`additional_data`	array	Array of additional data related to the location.

`additional_data` array

Field name	Type	Description	Example
`key`	string	Key of the additional data.	”Measured CCF”
`value`	string	Value of the additional data.	”5304”

`charges` array

Field name	Type	Description	Example
`group`	string	Category of the charge.	”Delivery Services”
`details`	string	Details about the charge.	”delivery_rate_adj”
`amount`	number	Specific dollar amount for the indicated line item.	82.46
`usage_unit`	string	Unit of measure for the utility used.	”therms”
`usage`	number	This is an amount based on the units of utility, not a dollar amount.	5348
`usage_unit_rate`	number	An amount in dollars indicating the price of how much each usage unit costs. Normally, the total utility used for this meter reading is multiplied by this rate for calculating the total consumption billed for the meter reading.	0.01542

`payments` array

Field name	Type	Description	Example
`amount`	number	Amount paid.	6892.44
`date`	string	Date of payment.	”2025-01-08”
`details`	string	Description of payment.	”Payment Received on JAN 8 (Direct Deposit)”

Get Started

Guides

Development

Overview

Fetch a list of documents

Download documents

Data extraction from files

Extraction Data Dictionary

Top-level fields

`billing_period` object

`billing_address` object

`service_locations` array

`service_address` object

`meters` array

`meter_reading` object

`additional_data` array

`charges` array

`payments` array

Get Started

Guides

Development

​Overview

​Fetch a list of documents

​Download documents

​Data extraction from files

​Extraction Data Dictionary

​Top-level fields

​billing_period object

​billing_address object

​service_locations array

​service_address object

​meters array

​meter_reading object

​additional_data array

​charges array

​payments array

Overview

Fetch a list of documents

Download documents

Data extraction from files

Extraction Data Dictionary

Top-level fields

`billing_period` object

`billing_address` object

`service_locations` array

`service_address` object

`meters` array

`meter_reading` object

`additional_data` array

`charges` array

`payments` array