Navbar
Logo
  • Overview
  • Products
  • Auth
  • Bill
  • Company
  • Payment
  • Client
  • Swap
  • Event
  • Overview

    Introduction

    API Host

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

    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

    Testing

    To quickly experiment with the API, you can use Postman. You'll need to set the apiHost and apiKey environment variables.

    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 bearer tokens. 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" \
      -H "Content-Type: application/json" \
      -d '{
        "clientId": "566595c8ce88ccec69328566",
        "companyId": "56e1dbb5443b10a3bd403fcf",
        "form": {
          "username": "Johnny",
          "password": "Appleseed"
        }
      }'
    

    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 respond with events.

    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.
    6. You can cancel a scheduled payment for a bill by using the /payment/cancel endpoint.

    Products

    Our white-label products are the fastest way to implement our API's functionality with a design that fits your branding. We've built a set of products that key in on common use cases of our API. These products include Connect, CardSwap and Biller Direct.

    WebView Integration

    Integration with our products is straightforward.

    1. Create a one-time use token by making a call to the /client/create-token endpoint.
    2. SSO into the white-label product by passing in the token as a URL parameter. An example URL would look like this: https://product.unbill.us?token=123.

    Connect

    Connect

    Connect is a drop-in module that provides a secure, elegant authentication flow for each company that the Q2 Biller Direct API supports. Connect makes it secure and easy for clients to link their accounts, while doing the heavy lifting for the authentication.

    Connect will emit events back to your app when a client successfully authenticates, exits, or times out.

    View demo

    CardSwap

    CardSwap

    Q2 CardSwap™ is the first switch kit for subscription and eCommerce merchants, allowing users to put your card top-of-wallet for their favorite services—all in one place.

    View demo

    Biller Direct

    Biller Direct

    Biller Direct is a card-enabled bill pay solution designed to dramatically improve the user experience and economic model of bill pay.

    View demo

    Auth

    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

    Authenticate a client's credentials. This process may take up to 30 seconds, but could extend if additional verification is required. The authentication process is event driven. The following events may be emitted during an authentication: auth.success, auth.mfa-required, and auth.failed.

    Example Request

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

    Example 200 Response

    {
      "success": true
    }
    

    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 an object with a success property if the auth request was created. Returns an error otherwise.

    Auth MFA

    Example Request (Question Based MFA)

    curl "https://api.unbill.co/v1/auth" \
      -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
      -H "Content-Type: application/json" \
      -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" \
      -H "Content-Type: application/json" \
      -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 by the auth.mfa-required event. For code (Code Based MFA) return the desired option by passing the identifier received by the auth.mfa-required event.

    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 an object with a success property if the mfa request was created. Returns an error otherwise.

    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."
      }
    }
    

    MFA Required Response

    {
      "status": {
        "type": "mfa-required"
      },
      "mfa": {
        "method": "questions",
        "mfa": [{
          "question": "What city did you grow up in?",
          "identifier": "1j5k2l1" 
        },
        {
          "answer": "What is your favorite food?",
          "identifier": "3buw78h3" 
        }]
      }
    }
    

    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 auth's credentials are no longer valid 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

    MFA Required

    When the link with a company requires additional MFA.

    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 client'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.

    Answer questions

    Example Request

    curl "https://api.unbill.co/v1/auth/{authId}/answer-questions" \
      -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
      -H "Content-Type: application/json" \
      -d '{
        "answers": [{
          "answer": "Seattle",
          "identifier": "1j5k2l1" 
        },
        {
          "answer": "Pickles",
          "identifier": "3buw78h3" 
        }]
      }'
    

    Accepts a list of answers to the questions presented when an auth has the mfa-required status.

    HTTP Request

    POST https://api.unbill.co/v1/auth/{authId}/answer-questions

    Arguments

    Parameter Description
    answers List of answered questions.

    Returns

    Returns an object with a success property indicating the answers were linked to the auth. Returns an error otherwise.

    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 client'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",
      "status": "operational",
      "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.
    status The operational status of the company at any given moment of time. Possible values are operational, maintenance.
    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",
      "status": "operational",
      "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" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "Netflix"
      }'
    
    curl "https://api.unbill.co/v1/company/search" \
      -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
      -H "Content-Type: application/json" \
      -d '{
        "category": "gas"
      }'
    
    curl "https://api.unbill.co/v1/company/search" \
      -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
      -H "Content-Type: application/json" \
      -d '{
        "geo": {
          "lat": 40.233845,
          "lng": -111.65852
        }
      }'
    

    Example Response

    {
      "data": [
        {
          "_id": "579b695decea110719b1874d",
          "name": "Netflix",
          "status": "operational",
          "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 and cancel a scheduled payment.

    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" \
      -H "Content-Type: application/json" \
      -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" \
      -H "Content-Type: application/json" \
      -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.

    Assign payment method

    Example Request

    curl "https://api.unbill.co/v1/payment/566595c8ce88ccec69328566/assign" \
      -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
      -H "Content-Type: application/json" \
      -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" \
      -H "Content-Type: application/json" \
      -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" \
      -H "Content-Type: application/json" \
      -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.

    Cancel payment

    Example Request

    curl "https://api.unbill.co/v1/payment/cancel" \
      -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
      -H "Content-Type: application/json" \
      -d '{
        "billId": "566595c8ce88ccec69328566",
      }'
    
    {
      "billId": "566595c8ce88ccec69328566",
    }
    

    Example Response

    {
      "success": true
    }
    

    Cancel a scheduled payment for a bill.

    HTTP Request

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

    Arguments

    Parameter Description
    billId ID of bill to cancel payment for.

    Returns

    Returns an object with a success property if the payment was canceled. 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" \
      -H "Content-Type: application/json" \
      -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" \
      -H "Content-Type: application/json" \
      -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.

    The swap object

    Example Response

    {
      "_id": "5b4cdadf8ea75a6602ff82bb",
      "status": {
        "type": "completed"
      },
      "auth": {
        "_id": "5b4cdade36c0c10108a57405",
        "status": {
          "type": "verified"
        }
      },
      "company": {
        "_id": "5522f59264f5785929aa1c42",
        "name": "Hulu",
        "status": "operational",
        "logo": {
          "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/a3c89f48378c84713fb31ce0e97bfa15.png",
          "background": false
        }
      },
      "paymentMethod": {
        "_id": "5b296e67a15d4e0001174fc2",
        "type": "card",
        "name": "Sean Hill",
        "status": "verified",
        "default": true,
        "card": {
          "number": "XXXX7989",
          "bin": "41474002",
          "brand": "visa",
          "type": "credit",
          "expDate": "2023-06-01T12:00:00.000Z"
        }
      }
    }
    
    
    Attribute Description
    _id ID of the swap. Unavailable when the status.type is pending.
    status Status of the swap.
    auth Auth Object
    company Company Object
    paymentMethod Payment method Object

    Swap status

    Pending Response

    {
      "status": {
        "type": "pending"
      }
    }
    

    Completed Response

    {
      "status": {
        "type": "completed"
      }
    }
    

    A swap status.type indicates the current state of a request to swap a payment method with a particular company.

    pending

    The swap of the payment method is currently in progress.

    completed

    The swap of the payment method has been completed successfully.

    Add a swap

    Example Request

    curl "https://api.unbill.co/v1/auth" \
      -H "Authorization: Bearer dc220490-e6ee-11e5-8a94-e7385a8d929e" \
      -H "Content-Type: application/json" \
      -d '{
        "authId": "566595c8ce88ccec69328566",
        "paymentMethodId": "5b4cdade36c0c10108a57405"
      }'
    

    HTTP Request

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

    Arguments

    Parameter Description
    authId ID of auth to create a swap for.
    paymentMethodId ID of payment method to link to the swap.

    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.

    List all swaps

    Example Request

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

    Example Response

    {
      "data": [
        {
          "_id": "5b4cdadf8ea75a6602ff82bb",
          "status": {
            "type": "completed"
          },
          "auth": {
            "_id": "5b4cdade36c0c10108a57405",
            "status": {
              "type": "verified"
            }
          },
          "company": {
            "_id": "5522f59264f5785929aa1c42",
            "name": "Hulu",
            "status": "operational",
            "logo": {
              "url": "https://s3-us-west-2.amazonaws.com/cdn.unbill.com/uploads/utility-provider-logos/a3c89f48378c84713fb31ce0e97bfa15.png",
              "background": false
            }
          },
          "paymentMethod": {
            "_id": "5b296e67a15d4e0001174fc2",
            "type": "card",
            "name": "Sean Hill",
            "status": "verified",
            "card": {
              "number": "XXXX7989",
              "bin": "41474002",
              "brand": "visa",
              "type": "credit",
              "expDate": "2023-06-01T12:00:00.000Z"
            }
          }
        }
      ]
    }
    

    Retrieves a list of client's swaps.

    HTTP Request

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

    Arguments

    Parameter Description
    clientId ID of client to retrieve swaps for.

    Returns

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

    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 a 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

    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.

    Auth success

    Example auth.success Event

    {
      "event": {
        "_id": "580e3e11dec21e861b5a3719",
        "type": "auth.success",
        "created": "2016-04-20T16:51:12Z",
        "payload": {
          "resource": {
            "type": "client",
            "id": "579b695decfa11012711875d"
          },
          "data": { 
            "auth" : {
              "_id" : "5b157888cb7e60000bfcaa41",
              "items" : [
                "bill"
              ], 
              "company" : {
                "_id" : "55942f330cfcfd6c4ed529d8",
                "name" : "Geico"
              }, 
              "status" : {
                "type" : "verified"
              }
            }
          }
        }
      }
    }
    

    When a client has successfully completed the authentication process.

    Attribute Description
    type auth.success
    payload.data.id The ID of the client who was authenticating.
    payload.data.auth The auth object linked to this resource.

    Auth MFA required

    Example auth.mfa-required Event (Question Based)

    {
      "event": {
        "_id": "580e3e11dec21e861b5a3719",
        "type": "auth.mfa-required",
        "created": "2016-04-20T16:51:12Z",
        "payload": {
          "resource": {
            "type": "client",
            "id": "579b695decfa11012711875d"
          },
          "data": { 
            "token": "566595c8ce88ccec69328566",
            "method": "questions",
            "mfa": [{ 
              "question": "What is the name of your first pet?",
              "identifier": "Bk0zwVx1Z"
            }],
            "company" : {
              "_id" : "55942f330cfcfd6c4ed529d8",
              "name" : "Geico"
            }
          }
        }
      }
    }
    

    Example auth.mfa-required Event (Code Based)

    {
      "event": {
        "_id": "580e3e11dec21e861b5a3719",
        "type": "auth.mfa-required",
        "created": "2016-04-20T16:51:12Z",
        "payload": {
          "resource": {
            "type": "client",
            "id": "579b695decfa11012711875d"
          },
          "data": { 
            "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" }
            ],
            "company" : {
              "_id" : "55942f330cfcfd6c4ed529d8",
              "name" : "Geico"
            }
          }
        }
      }
    }
    

    When additional authentication steps are required. Responses will be sent to the /auth/step endpoint.

    Attribute Description
    type auth.mfa-required
    payload.data.token The token to be sent in the request to the /auth/step endpoint.
    payload.data.method The type of MFA that is required.
    payload.data.mfa The requested MFA.
    payload.data.company The company object linked to this resource.

    Auth failed

    Example auth.failed Event

    {
      "event": {
        "_id": "580e3e11dec21e861b5a3719",
        "type": "auth.failed",
        "created": "2016-04-20T16:51:12Z",
        "payload": {
          "resource": {
            "type": "client",
            "id": "579b695decfa11012711875d"
          },
          "data": { 
            "reason": {
              "message": "You may want to double check your information."
            },
            "company" : {
              "_id" : "55942f330cfcfd6c4ed529d8",
              "name" : "Geico"
            }
          }
        }
      }
    }
    

    When a client fails the authentication process.

    Attribute Description
    type auth.failed
    payload.data.reason Why the authentication failed.
    payload.data.company The company object linked to this resource.

    Auth invalid

    Example auth.invalid Event

    {
      "event": {
        "_id": "580e3e11dec21e861b5a3719",
        "type": "auth.invalid",
        "created": "2016-04-20T16:51:12Z",
        "payload": {
          "resource": {
            "type": "auth",
            "id": "579b695decfa11012711875d"
          },
          "data": { 
            "company" : {
              "_id" : "55942f330cfcfd6c4ed529d8",
              "name" : "Geico"
            }
          }
        }
      }
    }
    

    When the auth's credentials are no longer valid and need to be reauthenticated.

    Attribute Description
    type auth.invalid
    payload.data.company The company object linked to this resource.

    Auth hold

    Example auth.hold Event

    {
      "event": {
        "_id": "580e3e11dec21e861b5a3719",
        "type": "auth.hold",
        "created": "2016-04-20T16:51:12Z",
        "payload": {
          "resource": {
            "type": "auth",
            "id": "579b695decfa11012711875d"
          },
          "data": { 
            "hold" : {
              "text" : "You need to login and activate your account."
            }, 
            "company" : {
              "_id" : "55942f330cfcfd6c4ed529d8",
              "name" : "Geico"
            }
          }
        }
      }
    }
    

    When an auth receives a hold that prevents access to the account data.

    Attribute Description
    type auth.hold
    payload.data.hold The hold placed on the account.
    payload.data.company The company object linked to this resource.

    Bill created

    Example bill.created Event

    {
      "event": {
        "_id": "580e3e11dec21e861b5a3719",
        "type": "bill.created",
        "created": "2016-04-20T16:51:12Z",
        "payload": {
          "resource": {
            "type": "bill",
            "id": "579b695decfa11012711875d"
          }
        }
      }
    }
    

    When a bill is found on an associated auth.

    Attribute Description
    type bill.created

    Bill update

    Example bill.update Event

    {
      "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"
            }
          }
        }
      }
    }
    

    When a bill's outstanding balance changes. Note that the payload.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 payload.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
    payload.data.company The company object linked to this resource.
    payload.data.previous Object containing the names of the attributes that have changed and their previous values.
    payload.data.current Object containing the names of the attributes that have changed and their current values.

    Bill payment sent

    Example bill.payment.sent Event

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

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

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

    Bill payment failed

    Example bill.payment.failed Event

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

    When a payment is unsuccessful.

    Attribute Description
    type bill.payment.failed
    payload.data.company The company object linked to this resource.
    payload.data.amount The amount of the unsuccesful payment.

    Swap success

    Example swap.success Event

    {
      "event": {
        "_id": "580e3e11dec21e861b5a3719",
        "type": "swap.success",
        "created": "2016-04-20T16:51:12Z",
        "payload": {
          "resource": {
            "type": "swap",
            "id": "579b695decfa11012711875d"
          },
          "data": {
            "clientId" : "5b157888cb7e60000bfcaa41"
          }
        }
      }
    }
    

    When a swap is successful.

    Attribute Description
    type swap.success
    payload.data.clientId The clientId linked to the swap.