Overview

Introduction

API Host

https://sb.unbill.co/v1 (sandbox)
https://api.unbill.co/v1 (production)

Resource URL Patterns

/auth
/bill
/company
/payment
/client

Welcome! The Q2 Biller Direct API allows developers to receive user-authorized bill data and make payments on behalf of a user.

Here you will find information on how to integrate with and use the Q2 Biller Direct API. We’ve tried to make this documentation user-friendly and example-filled, but please drop us a line with any questions. If you’re planning to use our API in production, you should take a look at our privacy policy.

The Q2 Biller Direct API uses standard HTTP verbs to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Q2 Biller Direct API is served over HTTPS to ensure data privacy, HTTP is not supported.

Overview

Gaining Access

To gain access to the Q2 Biller Direct API, please contact us. After our review process is complete, you’ll be provided with an API key which you can use for your requests.

Authentication

Example Request

  curl "https://api.unbill.co/v1/auth"
    -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e"

Authenticate your account when using the API by including your secret API key in the request. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via the OAuth2 Protocol. Pass your API Key as a bearer token in the Authorization header.

Errors

The Q2 Biller Direct API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Q2’s servers (these are rare).

Code Description
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn’t exist.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on Q2’s end. (These are rare.)

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under request-id. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Getting Started

Example Request

curl "https://api.unbill.co/v1/auth" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "clientId": "566595c8ce88ccec69328566",
    "companyId": "56e1dbb5443b10a3bd403fcf",
    "form": {
      "username": "Johnny",
      "password": "Appleseed"
    }
  }'

Example Response

{
  "authId": "56e1dbb5443b10a3bd403fcf",
  "items": [{
    "_id": "56e1dbb5443b10a3bd403fcf",
    "type": "bill",
    "balance": "100",
    "dueDate": "2018-10-25T00:00:00.000Z"
  }]
}

To authenticate bills with your users, you may use the following flow.

User Creation

  1. User signs up in your app.
  2. Make a request to the /client endpoint to retrieve a clientId to store in your database for future requests.

Authentication

  1. Search for the company you’d like to add from the /company/search endpoint.
  2. Provide your user with a “bill authentication” view populated with the login fields retrieved from the desired company.
  3. Have your user fill out their credentials, and then send those credentials to the /auth endpoint.
  4. Q2 will begin the authentication process and if successful, will return available items.

Bills

  1. Requests can be made to the /bill/list/{clientId} endpoint to retrieve the list of authenticated bills and balance information.
  2. Requests can be made to the /bill/{billId} endpoint to retrieve details on a specific bill.

Payments

  1. Provide your user with a “link payment” view to choose a payment method.
  2. Link this payment method using the /payment endpoint.
  3. By default, bills will be paid automatically by using the payment method on file.
  4. To change this, you must make a request to the /payment/settings endpoint to disable recurring payments.
  5. When recurring payments are disabled, in order to make an on-demand payment, one must be scheduled via the /payment/schedule endpoint.

Auth

Authenticate a user’s bill credentials. This process may take anywhere from 5-30 seconds depending on the responsiveness of the company’s website. If a 200 status code is returned, no additional MFA is required. If a 201 status code is returned, additional MFA is required to authenticate with the company and must be submitted via the /auth/step endpoint.

Credentials View

The auth object

Example Response

{
  "_id": "579b695decea110719b1874d",
  "status": {
    "type": "verified"
  },
  "company": {
    "_id": "579b695decea110719b1874d",
    "name": "Netflix",
    "logo": {
      "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
      "background": false
    } 
  }
}
Attribute Description
_id ID of the auth.
status Status of the auth.
company Company Object

Add an auth

Example Request

curl "https://api.unbill.co/v1/auth" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "clientId": "566595c8ce88ccec69328566",
    "companyId": "56e1dbb5443b10a3bd403fcf",
    "items": ["bill"],
    "form": {
      "username": "Johnny",
      "password": "Appleseed"
    }
  }'

Example 200 Response (Authenticated)

{
  "authId": "56e1dbb5443b10a3bd403fcf",
  "items": [{
    "_id": "56e1dbb5443b10a3bd403fcf",
    "type": "bill",
    "balance": "100",
    "dueDate": "2018-10-25T00:00:00.000Z"
  }]
}

Example 201 Response (Question Based MFA)

{
  "token": "566595c8ce88ccec69328566",
  "method": "questions",
  "mfa": [{ 
    "question": "What is the name of your first pet?",
    "identifier": "Bk0zwVx1Z"
  }]
}

Example 201 Response (Code Based MFA)

{
  "token": "566595c8ce88ccec69328566",
  "method": "code",
  "mfa": [
    { "mask": "t...t@example.com", "type": "email", "identifier": "r1g0mvVg1Z", "label": "Email: t...t@example.com" },
    { "mask": "xxx-xxx-1234", "type": "phone", "identifier": "B1gyVvElJZ", "label": "Phone: xxx-xxx-1234" },
    { "mask": "xxx-xxx-1234", "type": "text", "identifier": "SkbkEP4ekW", "label": "Text: xxx-xxx-1234" }
  ]
}

HTTP Request

POST https://api.unbill.co/v1/auth

Arguments

Parameter Description
clientId ID of user being authenticated.
companyId ID of company being authenticated.
items
(optional)
The list of items you’d like attached to this auth. If not specified, all available items will be returned. If you’re only interested in verifying credentials, set this parameter as an empty array [], otherwise specify which items you’d like.
form Credentials to authenticate.

Returns

Returns a list of available items linked to an auth, or the MFA to be submitted to the /auth/step endpoint.

Auth flow

The authentication flow may vary depending on the company. Below you’ll find approaches to test the possible flows within your app. For each flow set form.password to test.

Basic Auth

The most common approach used by companies is a simple username & password combination. To test this set form.username to test.

Multi-factor Authentication

Some companies require multi-factor authentication (MFA). To test this set form.username to testmfaquestions for a question based response or testmfacode for a code based response. In this response will be provided the token which you can then submit to the /auth/step endpoint to complete the authentication.

Example Auth Items

An Auth may have various items linked to it. To test bill items you may set form.username to testsyncing, testupcoming, or testpaid.

Auth items

Example Bill Item

{
  "type": "bill",
  "balance": "100",
  "dueDate": "2018-10-25T00:00:00.000Z"
}

After a successful authentication is made, a list of available items attached to an auth will be returned for convience. For more details about each of these items, access the items endpoints. Currently only bill items are supported, but additional items like usage and transactions are coming soon!

Auth MFA

Example Request (Question Based MFA)

curl "https://api.unbill.co/v1/auth" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "mfa": [{
      "answer": "Secret Answer",
      "identifier": "Bk0zwVx1Z"
    }],
    "token": "56e1dbb5443b10a3bd403fcf"
  }'

Example Request (Code Based MFA)

curl "https://api.unbill.co/v1/auth" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "mfa": { 
      "identifier": "ByDXD4eJW" 
    },
    "token": "56e1dbb5443b10a3bd403fcf"
  }'

Some companies require multi-factor authentication (MFA) and the /auth/step route is built to submit the additional information needed. Users are first submitted via the standard authenticate process via the /auth endpoint, and the MFA data is sent through an additional request to the /auth/step route.

For questions (Question Based MFA) return the answers formatted as an array of objects, where each object includes the answer of the question and the identifier received from the previous auth response. For code (Code Based MFA) return the desired option by passing the identifier field given to you from the previous auth response. Continue to POST to the /auth/step with the required answers until a 200 status code is returned. At that point the user will be authenticated and you’ll have access to available items.

Credentials MFA View

HTTP Request

POST https://api.unbill.co/v1/auth/step

Arguments

Parameter Description
token Token provided to you from the /auth response.
mfa The extra information needed for MFA authentication.

Returns

Returns a list of available items linked to an auth, or any additional MFA to be submitted to the /auth/step endpoint.

Auth status

Verified Response

{
  "status": {
    "type": "verified"
  }
}

Authenticate Response

{
  "status": {
    "type": "authenticate"
  }
}

Hold Response

{
  "status": {
    "type": "hold"
  },
  "reason": {
    "userMessage": "You need to login and verify your account information.",
    "debugMessage": "The user has not verified their online account."
  }
}

An auth status.type can be a variety of types. Each type is documented below with a description of the status and a typical use case.

verified

The user’s auth has been verified. No actions are required.

authenticate

The user’s credentials no longer work with the company’s website and need to be reauthenticated. Make a request to the /auth endpoint with updated credentials to remove this status.

Bill Authenticate

hold

For a number of reasons an auth can have the status of hold. When an auth is on hold we’ll present you with a reason that you in turn can present to your users. To remove this status, the user must take the appropriate action as described in the reason. This usually involves them needing to login into their online account. Once the user has completed the action, make a request to the /auth/{authId}/fix-hold endpoint to resume their services.

Display hold reason

Bill Hold

Displayed after user returns to app

Bill Hold Confirm

List all auths

Example Request

curl "https://api.unbill.co/v1/auth/list/566595c8ce88ccec69328566" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -G

Example Response

{
  "data": [
    {
      "_id": "579b695decfa11012711875d",
      "status": {
        "type": "verified"
      },
      "company": {
        "_id": "579b695decea110719b1874d",
        "name": "Time Warner Cable",
        "logo": {
          "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/4c805851c738c006546b234e3c3c793d.png",
          "background": false
        } 
      }
    }, 
    {
      "_id": "579b695decfa11012711875d",
      "status": {
        "type": "authenticate"
      },
      "company": {
        "_id": "579b695decea110719b1874d",
        "name": "The Grove at Auburn",
        "logo": {
          "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/0e9a971a96646da46f5faa68862d0f2d.jpg",
          "background": true
        } 
      }
    }
  ]
}

Retrieves a list of user’s auths.

HTTP Request

GET https://api.unbill.co/v1/auth/list/{clientId}

Arguments

Parameter Description
clientId ID of client to retrieve auths for.

Returns

A dictionary with a data property that contains an array of auth objects.

Fix auth hold

Example Request

curl "https://api.unbill.co/v1/auth/566595c8ce88ccec69328566/fix-hold" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -X POST

Example Response

{
  "success": true
}

HTTP Request

POST https://api.unbill.co/v1/auth/{authId}/fix-hold

Arguments

Parameter Description
authId ID of auth to fix.

Returns

Returns an object with a success property if the hold was fixed. If the authId does not exist, this call returns an error.

Delete auth

Example Request

curl "https://api.unbill.co/v1/auth/566595c8ce88ccec69328566" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -X DELETE

Example Response

{
  "success": true
}

Deletes an auth and all its items from the account.

HTTP Request

DELETE https://api.unbill.co/v1/auth/{authId}

Arguments

Parameter Description
authId ID of bill to delete.

Returns

Returns an object with a success property if the auth was deleted. If the authId does not exist, this call returns an error.

Bill

The bill object provides you with up-to-date balance, due date, and payment history for a bill. The API allows you to retrieve, list, and check the status of a user’s bills.

The bill object

Example Response

{
  "_id": "579b695decea110719b1874d",
  "balance": "100",
  "dueDate": "2018-10-25T00:00:00.000Z",
  "payDate": "2018-10-25T00:00:00.000Z",
  "status": {
    "type": "upcoming"
  },
  "settings": {
    "recurring": "enabled",
    "schedule": "on-due-date"
  },
  "company": {
    "_id": "579b695decea110719b1874d",
    "name": "Netflix",
    "logo": {
      "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
      "background": false
    },
    "schedule": "on-due-date"
  }
}
Attribute Description
_id ID of the bill.
balance Current bill balance.
dueDate Current bill due date.
lastPaidAmount Amount of last payment.
lastPaidOn The date when this bill was last paid.
payDate The date when the next bill will be paid.
status Status of the bill.
company Company Object
settings Settings for a bill.
settings.recurring Whether or not payments are scheduled automatically. Possible values are enabled, disabled.
settings.schedule The schedule for when a bill payment will be made.

Bill status

Syncing Response

{
  "status": {
    "type": "syncing"
  }, 
  "settings": {
    "recurring": "enabled",
    "schedule": "day-before"
  }
}

Nothing Due Response

{
  "status": {
    "type": "zero-balance"
  }, 
  "settings": {
    "recurring": "enabled",
    "schedule": "day-before"
  }
}

Overdue Response

{
  "balance": "100.00",
  "dueDate": "2016-03-25T00:00:00.000Z",
  "payDate": "2016-03-24T00:00:00.000Z",
  "status": {
    "type": "overdue"
  },
  "settings": {
    "recurring": "enabled",
    "schedule": "day-before"
  }
}

Payment Required Response

{
  "status": {
    "type": "payment-required"
  },
  "settings": {
    "recurring": "enabled",
    "schedule": "day-before"
  },
  "company": {
    "requiredPayment": "card"
  }
}

Payment Declined Response

{
  "status": {
    "type": "payment-declined"
  },
  "settings": {
    "recurring": "enabled",
    "schedule": "day-before"
  }
}

Upcoming Response

{
  "balance": "100.00",
  "dueDate": "2018-10-25T00:00:00.000Z",
  "payDate": "2018-10-24T00:00:00.000Z",
  "status": {
    "type": "upcoming"
  },
  "settings": {
    "recurring": "enabled",
    "schedule": "day-before"
  }
}

Pending Response

{
  "balance": "100.00",
  "dueDate": "2018-10-25T00:00:00.000Z",
  "payDate": "2018-10-24T00:00:00.000Z",
  "status": {
    "type": "pending"
  },
  "settings": {
    "recurring": "enabled",
    "schedule": "day-before"
  }
}

Paid Response

{
  "status": {
    "type": "paid"
  },
  "lastPaidAmount": "100.00",
  "lastPaidOn": "2016-01-01T00:00:00.000Z",
  "settings": {
    "recurring": "enabled",
    "schedule": "day-before"
  }
}

A bill’s status.type can be a variety of types. Each type is documented below with a description of the status and a typical use case.

syncing

Our system is currently retrieving data.

Bill Syncing

zero-balance

Bill data is not available yet. Most common reason is that the user hasn’t received a bill. (change image)

Bill Zero Balance

overdue

The due date for the bill has passed, and no payment has been made. Common reasons for an overdue bill are:

Bill Overdue

payment-required

The payment method specified by company.requiredPayment is required to pay this bill. A linked payment method must be assigned before bill payments will resume. This can be done via the /payment/{paymentMethodId}/assign endpoint.

Payment required

payment-declined

The payment method used to pay this bill was declined. To resume bill payments, have the user try their payment method again via the /payment/{paymentMethodId}/retry endpoint, or assign another one via the /payment/{paymentMethodId}/assign endpoint.

Payment declined

upcoming

The user has an outstanding balance on their account that will be paid in the future.

Bill Upcoming

pending

The user has an outstanding balance with a future due date.

Bill Pending

The user has no outstanding balance and has a last paid amount on their account.

Bill Paid

Bill payment schedule

A bill’s settings.schedule is the number of days before the due date when a bill will be paid. This schedule will be followed when settings.recurring is enabled and the company allows it.

The bill’s payDate is the date in which the next bill payment will be made. When recurring payments are enabled, the payDate is calculated by the assigned settings.schedule. When recurring payments are disabled, one-time payments may be scheduled on-demand via the /payment/schedule endpoint. Available settings.schedule options are documented below.

ten-days-before

A payment will be made ten days before the due date.

five-days-before

A payment will be made five days before the due date.

day-before

A payment will be made the day before the due date.

on-due-date

A payment will be made on the due date.

immediately

A payment will be made as soon as a new bill is received.

Retrieve bill details

Example Request

curl "https://api.unbill.co/v1/bill/566595c8ce88ccec69328566" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -G

Example Upcoming Response

{
  "bill": {
    "_id": "579b695decfa11012711875d",
    "balance": "100",
    "dueDate": "2018-10-25T00:00:00.000Z",
    "payDate": "2018-10-25T00:00:00.000Z",
    "status": {
      "type": "upcoming"
    }, 
    "settings": {
      "recurring": "enabled",
      "schedule": "on-due-date"
    },
    "company": {
      "_id": "579b695decea110719b1874d",
      "name": "Netflix",
      "logo": {
        "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
        "background": false
      },
      "schedule": "on-due-date"
    }
  },
  "payments": []
}

Example Paid Response

{
  "bill": {
    "_id": "579b695decfa11012711875d",
    "status": {
      "type": "paid"
    },
    "lastPaidAmount": "100",
    "lastPaidOn": "2016-01-01T00:00:00.000Z",
    "settings": {
      "recurring": "enabled",
      "schedule": "on-due-date"
    },
    "company": {
      "_id": "579b695decea110719b1874d",
      "name": "Netflix",
      "logo": {
        "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
        "background": false
      },
      "schedule": "on-due-date"
    }
  },
  "payments": [{
    "amount": "123.12",
    "paidOn": "2016-01-01T00:00:00.000Z"
  },{
    "amount": "153.19",
    "paidOn": "2016-01-02T00:00:00.000Z"
  }]
}

Retrieve details about a bill including outstanding balance, due date, settings, status, and payment history.

Detail

HTTP Request

GET https://api.unbill.co/v1/bill/{billId}

Arguments

Parameter Description
billId ID of bill to retrieve.

Returns

Returns details for a bill if a valid billId was provided. Returns an error otherwise.

List all bills

Example Request

  curl https://api.unbill.co/v1/bill/list/579b695decfa11012711875d
    -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e"
    -G 

Example Response

{
  "data": [
    {
      "bill": {
        "_id": "579b695decfa11012711875d",
        "balance": "100",
        "dueDate": "2018-10-25T00:00:00.000Z",
        "payDate": "2018-10-25T00:00:00.000Z",
        "status": {
          "type": "upcoming"
        }, 
        "settings": {
          "recurring": "enabled",
          "schedule": "on-due-date"
        },
        "company": {
          "_id": "579b695decea110719b1874d",
          "name": "Netflix",
          "logo": {
            "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
            "background": false
          },
          "schedule": "on-due-date"
        }
      },
      "payments": []
    },
    {
      "bill": {
        "_id": "579b695decfa11012711875d",
        "status": {
          "type": "paid"
        },
        "lastPaidAmount": "100",
        "lastPaidOn": "2016-01-01T00:00:00.000Z",
        "settings": {
          "recurring": "enabled",
          "schedule": "day-before"
        },
        "company": {
          "_id": "579b695decea110719b1874d",
          "name": "Netflix",
          "logo": {
            "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
            "background": false
          }
        }
      },
      "payments": [{
        "amount": "123.12",
        "paidOn": "2016-01-01T00:00:00.000Z"
      },{
        "amount": "153.19",
        "paidOn": "2016-01-02T00:00:00.000Z"
      }]
    }
  ]
}

Retrieves a list of user’s bills.

Overview

HTTP Request

GET https://api.unbill.co/v1/bill/list/{clientId}

Arguments

Parameter Description
clientId ID of the client to retrieve bills for.

Returns

A dictionary with a data property that contains an array of bill details.

Company

Company objects allow you to authenticate bills with your users. The API allows you to retrieve and search for companies.

The company object

Sample Response

{
  "_id": "579b695decea110719b1874d",
  "name": "Netflix",
  "logo": {
    "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
    "background": false,
    "svg": {
      "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.svg",
      "color": "FF041F"
    }
  },
  "requiredPayment": "bank",
  "schedule": "on-due-date",
  "auth": {
    "urls": {
      "login": "https://www.netflix.com/Login",
      "signup": "https://www.netflix.com"
    },
    "loginFields": [{
      "placeholder": "Username",
      "formType": "text",
      "name": "username",
      "label": "Username"
    }, {
      "placeholder": "Password",
      "formType": "password",
      "name": "password",
      "label": "Password"
    }]
  },
  "geo": {
    "lat": 30.70,
    "lng": -95.53,
    "state_short": "TX",
    "state_long": "Texas",
    "zipcode": "77340"
  }
}
Attribute Description
_id ID of the company.
name Name of the company.
logo Company logo object.
logo.url URL of the company logo.
logo.background If this is true, then the logo looks best as a background image.
logo.svg Company logo svg object.
logo.svg.url URL of the company svg logo.
logo.svg.color Hex color of the company logo.
requiredPayment If a specific payment method type is required by this company, this will be defined. Possible values are bank, card.
schedule The bill payment schedule this company follows. If this parameter is set, the schedule for a bill linked to this company may not be changed. Typically subscription companies such as Netflix have this parameter set since payments must be made on a specific date.
auth Company auth fields.
auth.urls Company Auth Urls (login URL is always available, but the others can by null).
auth.urls.login Login URL.
auth.urls.signup Signup URL.
auth.urls.forgotPassword Forgot password URL.
auth.urls.forgotUsername Forgot username URL.
auth.loginFields Form fields for credentials.
auth.loginFields.placeholder Input placeholder field.
auth.loginFields.formType Input type field.
auth.loginFields.name Input name field.
auth.loginFields.label Label for input.
geo Geo based location (not available for regional or national company).
geo.lat Latitude coordinate.
geo.lng Longitude coordinate.
geo.stateShort Abbreviated state name.
geo.stateLong Full state name.
geo.zipcode Zipcode.
geo.address Formatted address.

Company logos

The Q2 Biller Direct API provides image URL’s for each company’s logo. For our most popular companies, we also provide a white svg logo, along with the hex color of the company’s brand. There are three ideal ways of presenting these logos in your apps.

  1. When the company.logo.svg is available, the svg logo looks best on the company.logo.svg.color background.

    Netflix

  2. When the company.logo.svg is not available and the company.logo.background field is set to false, the logo looks best on a white background.

    TWC

  3. When the company.logo.svg is not available and the company.logo.background field is set to true, the logo looks best as a background image with the company name overlaid on top.

    Varsity House

Company categories

Example Request

curl "https://api.unbill.co/v1/company/categories" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -G

Example Response

{
  "data": [{
    "name": "Electric",
    "type": "electric",
    "image": {
      "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/assets/mobile/billers/category_icons/electric.svg"
    }
  }]
}

Retrieve a list of company categories you can use to search for companies by category type.

HTTP Request

GET https://api.unbill.co/v1/company/categories

Returns

A dictionary with a data property that contains an array of company categories.

Retrieve a company

Example Request

curl "https://api.unbill.co/v1/company/566595c8ce88ccec69328566" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -G

Example Response

{
  "_id": "579b695decea110719b1874d",
  "name": "Netflix",
  "logo": {
    "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
    "background": false,
    "svg": {
      "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.svg",
      "color": "FF041F"
    }
  },
  "requiredPayment": "bank",
  "schedule": "on-due-date",
  "auth": {
    "urls": {
      "login": "https://www.netflix.com/Login",
      "signup": "https://www.netflix.com"
    },
    "loginFields": [{
      "placeholder": "Username",
      "formType": "text",
      "name": "username",
      "label": "Username"
    }, {
      "placeholder": "Password",
      "formType": "password",
      "name": "password",
      "label": "Password"
    }]
  },
  "geo": {
    "lat": 30.70,
    "lng": -95.53,
    "state_short": "TX",
    "state_long": "Texas",
    "zipcode": "77340"
  }
}

Retrieves the company with the given ID.

HTTP Request

GET https://api.unbill.co/v1/company/{companyId}

Arguments

Parameter Description
companyId ID of company to retrieve.

Returns

Returns a company object if a valid companyId was provided. Returns an error otherwise.

Search for companies

Example Requests

curl "https://api.unbill.co/v1/company/search" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "query": "Netflix"
  }'
curl "https://api.unbill.co/v1/company/search" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "category": "gas"
  }'
curl "https://api.unbill.co/v1/company/search" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "geo": {
      "lat": 40.233845,
      "lng": -111.65852
    }
  }'

Example Response

{
  "data": [
    {
      "_id": "579b695decea110719b1874d",
      "name": "Netflix",
      "logo": {
        "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
        "background": false,
        "svg": {
          "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.svg",
          "color": "FF041F"
        }
      },
      "requiredPayment": "bank",
      "schedule": "on-due-date",
      "auth": {
        "urls": {
          "login": "https://www.netflix.com/Login",
          "signup": "https://www.netflix.com"
        },
        "loginFields": [{
          "placeholder": "Username",
          "formType": "text",
          "name": "username",
          "label": "Username"
        }, {
          "placeholder": "Password",
          "formType": "password",
          "name": "password",
          "label": "Password"
        }]
      },
      "geo": {
        "lat": 30.70,
        "lng": -95.53,
        "state_short": "TX",
        "state_long": "Texas",
        "zipcode": "77340"
      }
    }
  ]
}

Search for companies by name, category, or nearby a geo coordinate.

Company Categories

HTTP Request

POST https://api.unbill.co/v1/company/search

Arguments

Parameter Description
query The text string on which to search companies by name.
category Category type retrieved from the /company/categories endpoint.
geo Geo coordinates to search companies by location.
geo.lat Latitude coordinate.
geo.lng Longitude coordinate.

Returns

A dictionary with a data property that contains an array of company objects that match the provided search filters.

Payment

In order to make payments towards a user’s bill, they must first link a payment method using the /payment endpoint. By default, after a payment method is linked, payments will be made towards a user’s bills on time. The API allows you to add and retrieve a user’s payment method, as well as make payments towards a bill’s outstanding balance.

The card object

Example Response

{
  "number": "XXXX0005",
  "brand": "american express",
  "type": "credit",
  "expDate": "2019-06-01T12:00:00.000Z"
}
Attribute Description
number Masked card number.
brand Card brand. Possible values are visa, mastercard, american express, etc.
type Card type. Possible values are credit, debit.
expDate Card expiration date.

The bank object

Example Response

{
  "routingNumber": "XXXX0002",
  "accountNumber": "XXXX0021",
  "type": "checking"
}
Attribute Description
routingNumber Masked routing number.
accountNumber Masked account number.
type Bank account type. Possible values are checking, savings.

The payment method object

Example Response

{
  "_id": "580e3e11dec21e861b5a3719",
  "type": "card",
  "status": "verified",
  "default": true,
  "card": {
    "number": "XXXX0005",
    "brand": "american express",
    "type": "credit",
    "expDate": "2019-06-01T12:00:00.000Z"
  },
  "assignedBills": [ "580e3e11dec21e861b5a3719" ]
}
Attribute Description
_id ID of the payment method.
type The type of the payment method on file. Possible values are card, bank.
status The status of the payment method on file. Possible values are verified, declined.
default If this is the default payment method. Default means that it will pay any bills not specifically assigned a payment method.
assignedBills A list of bill ID’s this payment method was specifically assigned to.
card Card object
bank Bank object

Payment status

A payment method can have one of three statuses. Each type is documented below with a description of the status and a typical use case.

verified

The payment method on file is verified and eligible to make payments.

declined

The payment method on file is not eligible to make payments. This may happen for a number of reasons including:

When a user’s payment method fails to pay a bill, we set their payment method status as declined. While their status is declined no bill payments will be made in behalf of the user. To address this issue, you may take one of the following courses of action:

  1. Link a new payment method via the /payment endpoint.
  2. Retry the payment method via the /payment/{paymentMethodId}/retry endpoint.

Declined payment prompt

Failed Payment

If their payment method continues to be declined, it will be removed from their account. If the removed payment method was the default, the user will need to link a new payment method or choose another payment method on file as their default before bill payment services resume.

Add a payment method

Example Card Request

curl "https://api.unbill.co/v1/auth" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "clientId": "56e1ddbd1a05319bc198d36f",
    "paymentType": "card",
    "cardNumber": "378282246310005",
    "cardCode": "218",
    "expMonth": "10",
    "expYear": "2017",
    "zipcode": "12345",
    "name": "Sean Hill",
    "setAsDefault": true
  }'

Example Bank Request

curl "https://api.unbill.co/v1/auth" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "clientId": "56e1ddbd1a05319bc198d36f",
    "paymentType": "bank",
    "routingNumber": "021000021",
    "accountNumber": "9900000002",
    "accountType": "checking",
    "name": "Sean Hill"
  }'

Example Response

{
  "paymentMethodId": "56e1ddbd1a05319bc198d36f"
}

Add a payment method to a user.

HTTP Request

POST https://api.unbill.co/v1/payment

Arguments

Parameter Description
clientId ID of the client to add a payment method to.
paymentType Type of payment. Possible values are card, bank.
cardNumber Credit card number.
cardCode Credit card CVV.
expMonth Credit card expiration month formatted as XX.
expYear Credit card expiration year formatted as XXXX.
zipcode Credit card zipcode.
name The name as it appears on the payment account.
routingNumber Bank routing number.
accountNumber Bank account number.
accountType Type of bank account. Possible values are checking, savings.
setAsDefault Set this payment method as the default.

Returns

Returns an object with a paymentMethodId property if the payment method was successfully added. Returns an error otherwise.

List all payment methods

Example Request

curl "https://api.unbill.co/v1/payment/list/566595c8ce88ccec69328566" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -G

Example Response

{
  "data": [
    {
      "_id": "580e3754dec21e861b5a3718",
      "type": "card",
      "status": "verified",
      "default": true,
      "name": "Sean Hill",
      "card": {
        "number": "XXXX4242",
        "brand": "visa",
        "type": "credit",
        "expDate": "2016-12-01T12:00:00.000Z"
      }
    },
    {
      "_id": "580e3e11dec21e861b5a3719",
      "type": "bank",
      "status": "declined",
      "name": "Sean Hill",
      "bank": {
        "routing": "XXXX2531",
        "account": "XXXX4124",
        "type": "checking"
      }
    }
  ]
}

Retrieve a list of payment methods on file for a client.

HTTP Request

GET https://api.unbill.co/v1/payment/list/{clientId}

Arguments

Parameter Description
clientId ID of client to retrieve payment methods for.

Returns

A dictionary with a data property that contains an array of payment method objects.

Delete payment method

Example Request

curl "https://api.unbill.co/v1/payment/566595c8ce88ccec69328566" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -X DELETE

Example Response

{
  "success": true
}

Delete a payment method on file for bill payments. If a payment was made within the last 24 hours with this payment method, an error will be returned. Q2 requires a 24 hour time span after a payment has been made before a payment method can be deleted.

HTTP Request

DELETE https://api.unbill.co/v1/payment/{paymentMethodId}

Arguments

Parameter Description
paymentMethodId ID of payment method to delete.

Returns

Returns an object with a success property if the payment method was deleted. Returns an error otherwise.

Retry payment method

Sample Request

curl "https://api.unbill.co/v1/payment/566595c8ce88ccec69328566/retry" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -X POST

Example Response

{
  "success": true
}

Retry a declined payment method on file for bill payments.

HTTP Request

POST https://api.unbill.co/v1/payment/{paymentMethodId}/retry

Arguments

Parameter Description
paymentMethodId ID of payment method to retry.

Returns

Returns an object with a success property if the payment method will be retried. Returns an error otherwise.

Default payment method

Example Request

curl "https://api.unbill.co/v1/payment/566595c8ce88ccec69328566/set-default" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -X POST

Example Response

{
  "success": true
}

Set a payment method as the default for bill payments.

HTTP Request

POST https://api.unbill.co/v1/payment/{paymentMethodId}/set-default

Arguments

Parameter Description
paymentMethodId ID of payment method to set as default.

Returns

Returns an object with a success property if the payment method was set as default. Returns an error otherwise.

Assign payment method

Example Request

curl "https://api.unbill.co/v1/payment/566595c8ce88ccec69328566/assign" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "billId": "566595c8ce88ccec69328566",
  }'
  -X POST

Example Response

{
  "success": true
}

Assign a linked payment method to pay a specific bill. This is required when a company’s requiredPayment is defined as card or bank.

HTTP Request

POST https://api.unbill.co/v1/payment/{paymentMethodId}/assign

Arguments

Parameter Description
paymentMethodId ID of payment method to assign.
billId ID of bill to assign payment method to.

Returns

Returns an object with a success property if the payment method was assigned. Returns an error otherwise.

Update payment settings

Example Request

curl "https://api.unbill.co/v1/payment/settings" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "billId": "566595c8ce88ccec69328566",
    "recurring": "enabled",
    "schedule": "five-days-before"
  }'
  -X POST

Example Response

Update payment settings for a bill.

Some subscription companies, such as Netflix, Hulu, and Spotify require recurring payments to be enabled. If a request to the /payment/settings endpoint is made for one of these companies, an error will be returned and recurring payments will not be disabled.

HTTP Request

POST https://api.unbill.co/v1/payment/settings

Arguments

Parameter Description
billId ID of bill to update payment settings for.
recurring Whether recurring payments should be enabled or disabled.
schedule The bill payment schedule for payments

Returns

Returns an object with a success property if payment settings were successfully updated. Returns an error otherwise.

Schedule payment

Example Request

curl "https://api.unbill.co/v1/payment/schedule" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "billId": "566595c8ce88ccec69328566",
    "payDate": "2018-10-25T00:00:00.000Z"
  }'
{
  "apiKey": "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e",
  "billId": "566595c8ce88ccec69328566",
  "payDate": "2018-10-25T00:00:00.000Z"
}

Example Response

{
  "success": true
}

Schedule an on-demand payment towards a bill’s outstanding balance.

HTTP Request

POST https://api.unbill.co/v1/payment/schedule

Arguments

Parameter Description
billId ID of bill to schedule payment for.
date
(optional)
An ISO 8601 formatted date that sets what day this bill will be paid. If no date is specified, the bill is scheduled to be paid immediately.

Returns

Returns an object with a success property if a payment was scheduled. Returns an error otherwise.

Client

To authenticate and interact with the endpoints on behalf of a given user, a clientId is required.

Create Client

Example Request

curl "https://api.unbill.co/v1/client" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "identifier": "Bk0zwVx1Z",
    "meta": {
      "firstName": "Sean",
      "lastName": "Hill",
      "email": "sean@hill.com",
      "phone": "4801428531",
      "address1": "123 Api St.",
      "address2": "P.O. Box 283",
      "city": "Mesa",
      "state": "AZ",
      "zipcode": "12345"
    }
  }'

Example Response

{
  "clientId": "579b695decfa11012711875d"
}

Creates or returns an existing client to be used with requests.

HTTP Request

POST https://api.unbill.co/v1/client

Arguments

Parameter Description
identifier A unique identifier that represents a user in your system.
meta Additional information about the user in your system.

Returns

Returns an object with a clientId property that can be used for requests.

Create Token

Example Request

curl "https://api.unbill.co/v1/client/create-token" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "identifier": "Bk0zwVx1Z",
    "nonce": false,
    "meta": {
      "firstName": "Sean",
      "lastName": "Hill",
      "email": "sean@hill.com",
      "phone": "4801428531",
      "address1": "123 Api St.",
      "address2": "P.O. Box 283",
      "city": "Mesa",
      "state": "AZ",
      "zipcode": "12345"
    }
  }'

Example Response

{
  "token": "566595c8ce88ccec69328566c8ce8595c8"
}

Create a token to be used for SSO into applications.

HTTP Request

POST https://api.unbill.co/v1/client/create-token

Arguments

Parameter Description
identifier A unique identifier that represents a user in your system.
nonce Tokens are instantly consumed upon use. If you would like to make a re-useable token, you may set nonce to false.
meta Additional information about the user in your system.

Returns

Returns an object with a token property that can be used to SSO into applications.

Swap

Enables account holders to automatically apply new debit or credit card information across their favorite subscription and digital point-of-sale services.

Add a swap

Example Request

curl "https://api.unbill.co/v1/auth" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -d '{
    "authId": "566595c8ce88ccec69328566"
  }'

HTTP Request

POST https://api.unbill.co/v1/swap

Arguments

Parameter Description
authId ID of auth to create a swap for.

Returns

Returns an object with a success property if the swap was created. Returns an error otherwise.

Company list

Example Request

curl "https://api.unbill.co/v1/swap/companies" \
  -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
  -G

Example Response

{
  "data": [
    {
      "_id": "579b695decea110719b1874d",
      "name": "Netflix",
      "logo": {
        "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.png",
        "background": false,
        "svg": {
          "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/7242937ba29042cce61a8e4745269fce.svg",
          "color": "FF041F"
        }
      },
      "requiredPayment": "bank",
      "schedule": "on-due-date",
      "auth": {
        "urls": {
          "login": "https://www.netflix.com/Login",
          "signup": "https://www.netflix.com"
        },
        "loginFields": [{
          "placeholder": "Username",
          "formType": "text",
          "name": "username",
          "label": "Username"
        }, {
          "placeholder": "Password",
          "formType": "password",
          "name": "password",
          "label": "Password"
        }]
      },
      "geo": {
        "lat": 30.70,
        "lng": -95.53,
        "state_short": "TX",
        "state_long": "Texas",
        "zipcode": "77340"
      }
    }
  ]
}

Retrieve a list of companies that support swaps.

HTTP Request

GET https://api.unbill.co/v1/swap/companies

Returns

A dictionary with a data property that contains an array of company objects that support swaps.

Event

Events are our way of letting you know when something interesting happens on behalf of your users. When an interesting event occurs, we create a new Event object. For example, when a new bill is received, we create a bill.update event; when a bill payment is sent, we create a bill.payment event.

We have system for sending the event objects directly to an endpoint on your server, called webhooks. Webhooks are managed by our team, and our customer support team will help you get set up.

The event object

Example Response

{
  "_id": "580e3e11dec21e861b5a3719",
  "type": "bill.update",
  "created": "2016-04-20T16:51:12Z",
  "payload": {
    "resource": {
      "id": "579b695decfa11012711875d",
      "type": "bill"
    },
    "data": {
      "previous": {
        "balance": "25.21"
      },
      "current": {
        "balance": "52.11"
      }
    }
  }
}
Attribute Description
_id ID of the event.
type Description of the event: e.g. bill.issued, bill.updated, etc.
created An ISO 8601 formatted date of when this event was created.
payload Object containing data associated with the event..
payload.resource Object containing data associated with the resource of the event.
payload.resource.id ID of the resource associated with the event.
payload.resource.type The type of resource associated with the event. Possible values are bill.
payload.data Object containing unique attributes per type as described in types of events.

Types of events

Example bill.update Event

{
  "_id": "580e3e11dec21e861b5a3719",
  "type": "bill.update",
  "created": "2016-04-20T16:51:12Z",
  "payload": {
    "resource": {
      "type": "bill",
      "id": "579b695decfa11012711875d"
    },
    "data": {
      "company": {
        "name": "Netflix"
      },
      "previous": {
        "balance": "25.21"
      },
      "current": {
        "balance": "52.11"
      }
    }
  }
}

Example bill.payment Event

{
  "_id": "580e3e11dec21e861b5a3719",
  "type": "bill.payment",
  "created": "2016-04-20T16:51:12Z",
  "payload": {
    "resource": {
      "type": "bill",
      "id": "579b695decfa11012711875d"
    },
    "data": {
      "company": {
        "name": "Netflix"
      },
      "amount": "25.21",
      "surcharge": {
        "type": "debit card",
        "rate": "2.50"
      }
    }
  }
}

This is a list of all the types of events we currently send. We may add more at any time, so you shouldn’t rely on only these types existing in your code.

You’ll notice that these events follow a pattern: resource.event. Our goal is to design a consistent system that makes things easier to anticipate and code against.

Each event object includes a payload.data property which contains unique values for each type of event. Each event type below describes these unique values.

Bill update

When a bill’s outstanding balance changes. Note that the data.previous value may not always be available. For instance, when the system first aggregates bill data, the previous bill balance may not have been known. Also note that when the data.previous.balance is 0.00 and there is a new current balance, this means that a new bill was issued by the company’s system.

Attribute Description
type bill.update
data.company The company object linked to this resource.
data.previous Object containing the names of the attributes that have changed and their previous values.
data.current Object containing the names of the attributes that have changed and their current values.

Bill payment

When a payment is made towards a bill’s outstanding balance. Note that the data.surcharge may not be available when a company does not require it.

Attribute Description
type bill.payment
data.company The company object linked to this resource.
data.amount The amount sent to the company.
data.surcharge The surcharge required by the company to process the payment.
data.surcharge.type The type of surcharge required. Possible values are credit card, debit card, or ACH.
data.surcharge.rate The fee amount the company requires to process the payment.