---
title: US Utility Bill Extraction
slug: us-apis/us-utility-bill-extraction
createdAt: 2024-09-17T07:50:24.974Z
---

### Overview

This API is designed to extract detailed addresses and basic account information associated with the bill from different utility and telecom bills in the United States. Utility bills are a common and reliable source for address verification, making this API help businesses requiring proof of residence for customer verification purposes.

### Usecase

This API is primarily used for customer onboarding in sectors where proof of residence is required, such as banking, telecommunications, and rental services. By automating the extraction of address data from utility and telecom bills, the API facilitates quicker customer verification processes and improves the accuracy of data capture.

### API Details

### Request Body

:::CodeblockTabs
Production

```curl
curl --location 'https://api-preproduction.signzy.app/api/v3/us-api/utility-bill-extraction' \
--header 'Content-Type: application/json' \
--header 'Authorization: <-----Auth Token----->' \
--data '{
  "fileUrl": "https://persist.signzy.tech/api/files/992527839/download/68148f24ch38bf74v7329bfe5e21deb3b22cdd141b29bc317239874b.pdf"
}'
```

Preproduction

```curl
curl --location 'https://api.signzy.app/api/v3/us-api/utility-bill-extraction' \
--header 'Content-Type: application/json' \
--header 'Authorization: <-----Auth Token----->' \
--data '{
  "fileUrl": "https://persist.signzy.tech/api/files/992527839/download/68148f24ch38bf74v7329bfe5e21deb3b22cdd141b29bc317239874b.pdf"
}'
```
:::

### Request Body Parameters

| Input Parameter | Data Type | Description                                                           |
| --------------- | --------- | --------------------------------------------------------------------- |
| `fileUrl`       | String    | The URL where the utility or telecom bill PDF is stored for download. |

### Response Body

```json
{
    "result": {
        "name": "NAME_STRING",
        "address": {
            "streetAddress": "STREET_ADDRESS_STRING",
            "city": "CITY_STRING",
            "state": "STATE_STRING",
            "zipCode": "ZIP_CODE_STRING",
            "country": "COUNTRY_STRING"
        },
        "billDate": "DATE_STRING",
        "accountNumber": "ACCOUNT_NUMBER_STRING",
        "companyName": "COMPANY_NAME_STRING"
    }
}
```

### Response Body Parameters

| Output Parameter        | Data Type | Description                                                 |
| ----------------------- | --------- | ----------------------------------------------------------- |
| `name`                  | String    | The name of the individual or entity the bill is issued to. |
| `address.streetAddress` | String    | The street address as listed on the bill.                   |
| `address.city`          | String    | The city as listed on the bill.                             |
| `address.state`         | String    | The state as listed on the bill.                            |
| `address.zipCode`       | String    | The postal zip code as listed on the bill.                  |
| `address.country`       | String    | The country as listed on the bill.                          |
| `billDate`              | String    | The date the bill was issued.                               |
| `accountNumber`         | String    | The account number associated with the bill.                |
| `companyName`           | String    | The name of the company issuing the bill.                   |

### Error Cases

The API can encounter the following error cases:

- Invalid URL: If the `fileUrl` provided does not link to a valid or accessible PDF document.
- Unsupported Document Type: If the document at the `fileUrl` is not a utility or telecom bill.
- Parsing Error: If the document's structure prevents data extraction.
- Service Unavailability: When the service is temporarily unavailable due to maintenance or unexpected outages.

### Error Codes Description

| HTTP Status Code | Description                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------- |
| 400              | Invalid URL: The URL provided is malformed or inaccessible.                                 |
| 400              | Unsupported Document Type: The document is not a recognized utility or telecom bill format. |
| 401              | Invalid authentication credentials                                                          |
| 503              | Service Unavailability: The extraction service is temporarily unavailable.                  |

***

### Error Code Response & Mapping

:::CodeblockTabs
400(Bad Request)

```json
{
  "error": {
     "name": "error",
     "message": "Password protected PDF files are not allowed",
     "status": 400,
     "reason": "VALIDATION_ERROR",
     "type": "Bad Request",
     "statusCode": 400
  }
}
```

400(Bad Request)

```json
{
  "error": {
     "name": "error",
     "message": "PDF of more than 10 pages are not allowed",
     "status": 400,
     "reason": "VALIDATION_ERROR",
     "type": "Bad Request",
     "statusCode": 400
  }
}
```

409(Upstream Down)

```json
{
  "error": {
     "name": "error",
     "message": "Upstream Down",
     "status": 409,
     "reason": "ERROR",
     "type": "Bad Request",
     "statusCode": 409
  }
}
```
:::