Utiliz API

Version 1.0 / 3 Nov 17
Contact: Kevin Manley (kevin@myutiliz.com)

Documentation

On any Utiliz server where the API is enabled, the server will respond with current API documentation in response to a GET request on the root directory.

Server names

Please contact Utiliz for the server names corresponding to the test and production environments.

Authentication

All API calls are done in the context of a user in the Utiliz system. The user must have the “api” role assigned to their account. Contact Utiliz to have this user account setup. Once it’s setup you can manage the password for the account (Utiliz only stores bcrypt hashes and has no way of knowing a user’s plaintext password)

Authentication to the API is performed via HTTP Basic Auth. Provide your account email and password's bcrypt hash (NOT the plaintext password) as the basic auth values.

Your account credentials carry many privileges, so be sure to keep them secret. Do not share your password or password hash in publicly accessible areas such GitHub, client-side code, and so forth.

All API requests must be made using HTTPS protocol. Calls made using HTTP will fail. API requests without authentication will also fail.

Return values

Response Content-Type should be assumed to be plain/text unless specified otherwise below. Generally responses that are not plain/text will be application/json.

`Ping`

Use Ping as a basic connectivity test. Ping will only succeed if you connect over TLS, pass valid user credentials via Basic Authentication, and the user has the 'api' role.

URL

/v1/ping
Method:

GET
URL Params

None
Data Params

None
Success Response:
- Code: 200
  Content: PONG
Error Response(s):
- Code: 426 Upgrade Required
  Content: tls required
- Code: 401 Unauthorized
  Content: missing basic auth credentials
- Code: 401 Unauthorized
  Content: user <email> not found
- Code: 401 Unauthorized
  Content: invalid password hash <hash>
- Code: 401 Unauthorized
  Content: user account is disabled
- Code: 401 Unauthorized
  Content: user does not have api role
- Code: 429 Too Many Requests
  Content: rate limit exceeded

Sample Request:

curl -i https://<servername>/v1/ping --user jdoe@wherever.com:JDJhJDEwJEtOQS9WLk12...

Sample Response:

HTTP/1.1 200 OK
Date: Thu, 12 Oct 2017 19:12:29 GMT
Content-Length: 4
Content-Type: text/plain; charset=utf-8

PONG

Rate Limit

5 req/sec per server
Notes:

None

`CreateSubscription`

Creates a new subscription for Utiliz service and kicks off the workflow to start auto-enrolling the customer on cheaper retail supply.

URL

/v1/create_subscription
Method:

POST
URL Params

None
Data Params

Required:

Label=[string] The white label partner identifier (contact Utiliz for this value)

PlanID=[string] The subscription plan ID (contact Utiliz for this value)

Quantity=[int] The number of subscriptions requested. Normally 1, but can be greater than 1 if customer has multiple meters. Normally 3rd party resellers are restricted to selling 1 meter at a time. Coordinate with your Utiliz contact for more info.

Firstname=[string] The customer's first name

Lastname=[string] The customer's last name

Company=[string] The customer's company name (only required if PlanID indicates a commercial subscription)

Email=[string] The customer's email address. Must not already be registered by an existing Utiliz customer. Note that Utiliz does not give out actual customer emails to suppliers. Each customer gets an internal Utiliz email address and only those are revealed to suppliers.

Address=[string] The customer's house number and street

City=[string] The customer's city

State=[string] The customer's state (2 letter abbreviation only). Must be one of the deregulated states currently served by Utiliz.

Zip=[string] The customer's zip code.

Phone=[string] The customer's phone number

Agree=[bool] Must be 'true' or 'false' indicating whether the customer agrees to e-sign the Utiliz Broker Agreement. The request will fail if Agree is not true. IMPORANT: when using a non-native Utiliz UI, you are responsible for ensuring the customer has a chance to review the broker agreement and that they take affirmative action to agree to it (i.e. manual opt-in)

Optional:

Address2=[string] Apartment number or other second line of address info

StripeToken=[string] Stripe single-use token representing the customer's credit card. For partners who bill on their side, this must not be passed. For partners who use Utiliz for recurring billing, this item must be passed. NOTE: when passed, Connecticut customers will be subject to state sales tax (currently 6.35%)

Coupon=[string] Promotion/coupon code. May only be passed when StripeToken is also passed.

UtilityBill[string] If specified and starts with https://, it is interpreted as a \n-delimited set of URLs from
which the customer's initial utility bill page(s) will be downloaded and attached to the account as untranscribed bills. If UtilityBill is not passed, then the Utiliz system will email the customer asking them to send in a copy of their bill. The email will use the template defined for the specified white label partner. Downloads via http are not supported. Downloads greater than 10MB in size are not supported.

UserID=[string] User ID in your system. Utiliz doesn't do anything with this, except include it in calls returning customer data.
Success Response:
- Code: 200
  Content: <customer_id>
Error Response(s):
- Code: 426 Upgrade Required
  Content: tls required
- Code: 401 Unauthorized
  Content: missing basic auth credentials
- Code: 401 Unauthorized
  Content: user <email> not found
- Code: 401 Unauthorized
  Content: invalid password hash <hash>
- Code: 401 Unauthorized
  Content: user account is disabled
- Code: 401 Unauthorized
  Content: user does not have api role
- Code: 429 Too Many Requests
  Content: rate limit exceeded
- Code: 400 Bad Request
  Content: failed to parse form data
- Code: 400 Bad Request
  Content: schema decode error
- Code: 422 Unprocessable Entity
  Content Type: application/json
  Content: A map of semantic errors keyed by Data Param name
```
{"errors" : { "<param name>" : "<error msg>",
              "<param name>" : "<error msg>", }}
```
- Code: 500 Internal Server Error
  Content: <downstream subscription management or payment processing error>

Sample Request:

curl -i https://<servername>/v1/create_subscription --user jdoe@wherever.com:JDJhJDEOQS9WLk12...
-d Label=partner1
-d PlanID=partner1-resi-elec-monthly 
-d Quantity=1 
-d Firstname=Cranston 
-d Lastname=Snerd 
-d Address="100 Main St" 
-d City=Westport 
-d State=CT 
-d Zip=06880 
-d Email="csnerd@gmail.com"
-d Phone=2035002989 
-d Agree=true

Sample Response:

HTTP/1.1 200 OK
Content-Length: 37
Content-Type: application/json
Date: Tue, 17 Oct 2017 16:03:48 GMT
Server: Caddy

9a9ac789-ff7f-4f32-8f6f-287bb6b371ea

Rate Limit

1 req/sec per server + 100 req/hr per server. If you plan to send more volume than this please contact Utiliz to have the rate limit increased.
Notes:

Due to replication delays the returned Customer ID cannot immediately be used to request customer info. The replication delay can be several seconds.

This method succeeding does not guarantee Utiliz will be able to onboard the customer. There are some issues that are only revealed by looking at the customer's bill that could potentially prevent onboarding. For example, if the customer is already enrolled with a retail supplier and has a high early termination fee, or if the customer happens to be in one of the few small municipalities that does not allow supplier choice. In those cases we will contact you out of band to resolve.

Once a new subscription is created and the customer's bill information is transcribed into the Utiliz system, their first new enrollment submission will generally be done within 1-7 days. The range is due to the fact that sometimes batch up many customers in order to enroll in bulk at a negotiated supplier price.

For partners billing on their side, you may want to defer the first charge until the customer has seen some value from the service. First enrollments can take 30-60 days from the date of enrollment to take effect, depending on the customer's billing cycle.

`DisableSubscription`

Cancels a user's Utiliz subscription (e.g. for non-payment). The subscription must have previously been setup via CreateSubscription.

URL

/v1/disable_subscription
Method:

POST
URL Params

None
Data Params

Required:

Label=[string] The white label partner identifier (contact Utiliz for this value)

CustomerID=[string] The ID of the customer whose subscription should be disabled

Optional:

None
Success Response:
- Code: 200
  Content: OK
Error Response(s):
- Code: 426 Upgrade Required
  Content: tls required
- Code: 401 Unauthorized
  Content: missing basic auth credentials
- Code: 401 Unauthorized
  Content: user <email> not found
- Code: 401 Unauthorized
  Content: invalid password hash <hash>
- Code: 401 Unauthorized
  Content: user account is disabled
- Code: 401 Unauthorized
  Content: user does not have api role
- Code: 429 Too Many Requests
  Content: rate limit exceeded
- Code: 400 Bad Request
  Content: failed to parse form data
- Code: 422 Unprocessable Entity
  Content Type: application/json
  Content: A map of semantic errors keyed by Data Param name
```
{"errors" : { "<param name>" : "<error msg>",
              "<param name>" : "<error msg>", }}
```
- Code: 500 Internal Server Error
  Content: <downstream subscription management error>

Sample Request:

curl -i https://<servername>/v1/disable_subscription --user jdoe@wherever.com:JDJhJDEOQS9WLk12...
  -d Label=partner1
  -d CustomerID=9a9ac789-ff7f-4f32-8f6f-287bb6b371ea

Sample Response:

HTTP/1.1 200 OK
Content-Length: 37
Content-Type: application/json
Date: Tue, 17 Oct 2017 16:03:48 GMT
Server: Caddy

OK

Rate Limit

1 req/sec per server + 10 req/hr per server.
Notes:

Only partners who handle billing on their side are able to use the disable_subscription API. This API should be called when a customer is no longer paying for the Utiliz service.

Upon successful completion of this API, the customer's electricity subscription will be cancelled and they will receive a white-labeled cancellation email.

`EnableSubscription`

Re-enables a user's Utiliz subscription that was previously disabled. The subscription must have previously been setup via CreateSubscription.

URL

/v1/enable_subscription
Method:

POST
URL Params

None
Data Params

Required:

CustomerID=[string] The ID of the customer whose subscription should be re-enabled

Optional:

None
Success Response:
- Code: 200
  Content: OK
Error Response(s):
- Code: 426 Upgrade Required
  Content: tls required
- Code: 401 Unauthorized
  Content: missing basic auth credentials
- Code: 401 Unauthorized
  Content: user <email> not found
- Code: 401 Unauthorized
  Content: invalid password hash <hash>
- Code: 401 Unauthorized
  Content: user account is disabled
- Code: 401 Unauthorized
  Content: user does not have api role
- Code: 429 Too Many Requests
  Content: rate limit exceeded
- Code: 400 Bad Request
  Content: failed to parse form data
- Code: 422 Unprocessable Entity
  Content Type: application/json
  Content: A map of semantic errors keyed by Data Param name
```
{"errors" : { "<param name>" : "<error msg>",
              "<param name>" : "<error msg>", }}
```
- Code: 500 Internal Server Error
  Content: <downstream subscription management error>

Sample Request:

curl -i https://<servername>/v1/enable_subscription --user jdoe@wherever.com:JDJhJDEOQS9WLk12...
  -d Label=partner1  
  -d CustomerID=9a9ac789-ff7f-4f32-8f6f-287bb6b371ea

Sample Response:

HTTP/1.1 200 OK
Content-Length: 37
Content-Type: application/json
Date: Tue, 17 Oct 2017 16:03:48 GMT
Server: Caddy

OK

Rate Limit

1 req/sec per server + 10 req/hr per server.
Notes:

Only partners who handle billing on their side are able to use the enable_subscription API. This API should be called when a customer chooses to reactive a previously created subscription for the Utiliz service.

Upon successful completion of this API, the customer's electricity subscription will be re-enabled and they will receive a white-labeled reactivation email.

`GetCustomer`

URL

/v1/customer/<id>
Method:

GET

TBD

`GetCustomerCurrentEnrollment`

URL

/v1/customer/<id>/current_enrollment
Method:

GET

TBD

`GetAllCustomerEnrollments`

URL

/v1/customer/<id>/enrollments
Method:

GET

TBD

Utiliz API Documentation

Utiliz API

Documentation

Server names

Authentication

Return values

Ping

CreateSubscription

DisableSubscription

EnableSubscription

GetCustomer

GetCustomerCurrentEnrollment

GetAllCustomerEnrollments

`Ping`

`CreateSubscription`

`DisableSubscription`

`EnableSubscription`

`GetCustomer`

`GetCustomerCurrentEnrollment`

`GetAllCustomerEnrollments`