Overview
Getting Started
Welcome to the official Griddy API Documentation. We are currently under construction, but feel free to browse around.
This will be the definitive resource for API information.
You’ll succeed if you do this.
Here’s some useful information.
Something may not happen if you try and do this.
Something bad will happen if you do this.
Authentication
You need to be authenticated for most API requests.
Errors
| Code | Name | Description |
|---|---|---|
| 200 | OK | Success |
| 201 | Created | Creation Successful |
| 400 | Bad Request | We could not process that action |
| 403 | Forbidden | We couldn’t authenticate you |
| 500 | Server Error | Something comletely unexpected happened |
{
"InvalidFields": [
"email"
]
}
{
"MissingItemType": "meter"
}
Enrollment
The enrollment process consists of the following steps:
Create the User and Member Data
/users/signupto create the user/members/createto setup the member
Setup Payments and Add Money
- Stripe.js to get a Stripe token
/payment/enrollto setup payments/payment/add_cardto add the card using the Stripe token/billing/addfundsto add money to the user’s account
Find and Register a Meter
/meterLookup/searchto find a meter/meter/metersto register a meter
Analytics
/analytics/costs
Get cost data regarding specific meters in loadzones. [NOT USED]
Request
The request asks for cost metrics for a specific load zone and meter.
Parameters
- load_zone required
- the meter’s load zone
- meterID required
- the meter ESI ID
- start optional
- the start date for the time period of cost data needed
- end optional
- the end date for the time period of cost data needed
- interval optional
- the inteval at which the cost data is needed; e.g. 5, 15, or 45 minutes
Response
The response will contain the electricity total, average and interval costs for the meter requested
Parameters
- load_zone
- the meter’s load zone
- meterID
- the meter’s ESI ID
- costs
- a nested object containing the
time,amount, andactualbool stating… WHAT DOES THE BOOL STATE? - average
- the average cost of energy for the selected time period
- total
- the total cost of energy for the selected time period
{
"load_zone": "LZ_HOUSTON",
"meterID": "0123456789123456",
"start": "2017-01-03T01:30:00Z",
"end": "2017-01-03T01:30:00Z",
"interval": [
{
"value": 3,
"interval_type": "1.2",
}...],
}
{
"load_zone": "LZ_HOUSTON",
"meterID": "0123456789123456",
"costs": [
{
"time": "2017-01-03T01:30:00Z",
"amount": "1.2",
"actual": true,
}
]
"average": "3.4",
"total": "8.2",
}
/analytics/get_edf_trades
Get EDF Trade value for range of operating dates.
Request
The request asks for cost metrics for a specific load zone and meter.
Parameters
- page optional
- the offset of the number of records from the most recent entry (default 1)
- limit required if page is set
- the number of records to return in the response (default 25)
Response
The response will contain the electricity total, average and interval costs for the meter requested
Parameters
- trades
- a list of trade objects containing each trade (operating_date, amount_dollars)
- operating_date
- the operating date for a given trade
- amount_dollars
- the amount of the trade total in dollars
Errors
Parameters
- 500 - Internal Server Error
- If there is some problem obtaining the trades given the parameters
{
"page": "1",
"limit": "3"
}
{
"trades": [
{
"operating_date": "2018-12-25",
"amount_dollars": "11027.77000000"
},
{
"operating_date": "2018-12-24",
"amount_dollars": "10770.31000000"
},
{
"operating_date": "2018-12-23",
"amount_dollars": "11426.68000000"
}
]
}
/analytics/history
Get historical price, usage, and cost data for a member.
Request
Parameters
- meterID required
- the ID of the meter to retrieve the history data (not esi)
- iana_timezone optional
- The time zone the result should be returned in (Default:
America/Chicago) - meter deprecated
- The esi id. Do not use this field as it can lead to ambiguous results.
Response
The response contains an object with data hourly, daily, and monthly keys.
Each of those is an array of price, usage, and cost objects that have the following:
Parameters
- time
- a RFC3339-compliant timestamp for the data retrieved
- price_ckwh
- the price in cents per kWh or ¢/kWh
- usage_kwh
- the usage in kWh
- cost_dollars
- the electricity cost in dollars
{
"meterID": "35001"
}
{
"hourly": [{
"time": "2017-01-03T01:30:00Z",
"price_ckwh": "1.2",
"usage_kwh": "3.8",
"cost_dollars": "1.23"
}...],
"daily": [{
"time": "2017-01-03T01:30:00Z",
"price_ckwh": "1.2",
"usage_kwh": "3.8",
"cost_dollars": "1.23"
}...],
"monthly": [{
"time": "2017-01-03T01:30:00Z",
"price_ckwh": "1.2",
"usage_kwh": "3.8",
"cost_dollars": "1.23"
}...],
}
/analytics/now
Get the real time price of energy for a specific settlement point or loadzone. [NOT USED]
Request
Parameters
- settlement_point required
- the sub-region within a load zone, but also refers to the load zone
Response
The response will return the real time price of energy for the specified load zone/settlement point
Parameters
- settlement_point
- the requested settlement point or load zone
- price_now
- the real time price of energy in cents per kWh or ¢/kWh
- forecast
- the forecast of electricity costs for the specified load zone or settlement point
{
"settlement_point": "2",
}
{
"settlement_point": 3,
"price_now": [{
"time": "2017-01-03T01:30:00Z",
"amount": "1.2",
"rate_ckwh": "3.8",
"value_score": 1,
}...],
"forecast": [{
"time": "2017-01-03T01:30:00Z",
"amount": "1.2",
"rate_ckwh": "3.8",
"value_score": 1,
}...],
}
/analytics/range
Get the price for energy in a specific range[NOT USED]
Request
Parameters
- load_zone required
- the meter’s load zone
- start optional
- the start date for the time period of cost data needed
- end optional
- the end date for the time period of cost data needed
- interval optional
- the inteval at which the cost data is needed; e.g. 5, 15, or 45 minutes
Response
The response has lots of information, here is what it shares…
Parameters
- load_zone
- the meter’s load zone
- prices
- a nested object that give us the
time- timestamp,amount- amount of energy,rate_ckwh- the rate in cents per kWh or ¢/kWh, and avalue_score… WHAT IS A VALUE SCORE? - average
- the average price of energy based on the reques parameters
- settlement_point
- the requested settlement point or load zone
{
"load_zone": "lZ_HOUSTON"
"start": "2017-01-03T01:30:00Z",
"end": "2017-01-03T01:30:00Z",
"interval": [{
"value": 2,
"interval_type": "45" ,
}...],
}
{
"load_zone": "LZ_HOSUTON"
"prices": [{
"time": "2017-01-03T01:30:00Z",
"amount": "1.23",
"rate_ckwh": "1.23",
"value_score": 4,
}...],
"average": "1.2",
"settlement_point": "3",
}
/analytics/savings
Get historical price, usage, and cost data for a member.
Request
Parameters
- memberID required
- the member’s ID
Response
The response contains an object with three keys monthly, totals, and hide_savings.
The hide_savings value is a boolean which indicates whether or not the front end should display the savings numbers. The totals value is an object with keys as described below. Finally the monthly value is an array of objects with the same keys below:
Parameters
- period
- The time period for the savings data.
- griddy_costs
- The amount the member paid during the period (excluding taxes)
- griddy_taxes
- The amount in taxes the member paid during the period
- usage
- The amount of usage in kwh the member consumed during the period
- eia_rate
- The EIA rate for that period
- is_rolling_avg
- Set to true if the EIA rate for this period is a rolling avg of the previous 12 months. True for recent months when the eia rates have not yet been published.
- eia_costs
- Deprecated
- eia_taxes
- Estimated taxes the member would have paid on the EIA costs
- savings
- Estimated savings compared to EIA:
eia_costs+eia_taxes-griddy_costs-griddy_taxes - griddy_allin_rate
- Costs plus taxes divided by usage
- eia_allin_rate
- EIA rate plus estimated rate for taxes.
- griddy_all_in_costs
- Griddy costs plus taxes (griddy_costs+griddy_taxes)
- eia_tax_cpkwh
- Estimated taxes per kwh based on the EIA costs (eia_taxes/usge)
- eia_allin_costs
- Estimated EIA costs plus estimated taxes
- eia_costs_wo_taxes
- Usage multiplied by the EIA rate
{
"memberID": "21527b3d0-3585-428a-8fbc-5bc730a35001"
}
{
"monthly": [
{
"period": "2018-06-01",
"griddy_costs": "4.03",
"griddy_taxes": "0.02",
"usage": "32",
"eia_rate": "11.4",
"is_rolling_avg": false,
"eia_costs": "3.61",
"eia_taxes": "0.02",
"savings": "-0.42",
"griddy_allin_rate": "12.7",
"eia_allin_rate": "11.4",
"griddy_all_in_costs": "4.05",
"eia_tax_cpkwh": "0.0",
"eia_allin_costs": "102.55",
"eia_costs_wo_taxes": "102.44"
},
{
"period": "2018-07-01",
"griddy_costs": "73.42",
"griddy_taxes": "2.12",
"usage": "988",
"eia_rate": "11.2",
"is_rolling_avg": true,
"eia_costs": "110.62",
"eia_taxes": "3.19",
"savings": "38.28",
"griddy_allin_rate": "7.6",
"eia_allin_rate": "11.5",
"griddy_all_in_costs": "75.54",
"eia_tax_cpkwh": "0.0",
"eia_allin_costs": "102.55",
"eia_costs_wo_taxes": "102.44"
}
],
"totals": {
"period": "total",
"griddy_costs": "77.45",
"griddy_taxes": "2.14",
"usage": "1020",
"eia_rate": "11.2",
"is_rolling_avg": true,
"eia_costs": "114.23",
"eia_taxes": "3.16",
"savings": "37.80",
"griddy_allin_rate": "7.8",
"eia_allin_rate": "11.5",
"griddy_all_in_costs": "79.59",
"eia_tax_cpkwh": "0.0",
"eia_allin_costs": "102.55",
"eia_costs_wo_taxes": "102.44"
},
"hide_savings": true
}
/analytics/set_edf_trade
Set EDF Trade value for an operating dates.
Request
The request sets cost metrics for a specific load zone and meter.
Parameters
- operating_date required
- the operating date in
YYYY-MM-DDformat for the given EDF trade to be set (must be unique) - amount_dollars required
- the amount in dollars of the EDF trade to be set
Response
If successfully set, the response will contain the trade set by the request body, plus the next 24 trades by operating date.
Parameters
- trades
- a list of trade objects containing each trade (operating_date, amount_dollars)
- operating_date
- the operating date for a given trade
- amount_dollars
- the amount of the trade total in dollars
Errors
Parameters
- 400 - Bad Request
- If operating date or amount dollars are not set
- 409 - Conflict
- If a trade already exists for the given operating date
- 500 - Internal Server Error
- If there is some other problem setting the trade information
{
"operating_date": "2018-12-28",
"amount_dollars": "11144.8"
}
{
"trades": [
{
"operating_date": "2018-12-28",
"amount_dollars": "11144.77000000"
},
{
"operating_date": "2018-12-24",
"amount_dollars": "10770.31000000"
},
{
"operating_date": "2018-12-23",
"amount_dollars": "11426.68000000"
}
]
}
/analytics/totalsavings
Get total amount saved by all member over all time.
Request
No Field values. Only a valid token is needed.
Response
The response contains an object with two fields residential and commercial.
Each of those is an object with rate and savings keys:
Parameters
- rate
- The weighted average all in rate of all our members (for that class).
- savings
- An estimated savings compared to the EIA for all our members.
{}
{
"residential": {
"rate": "7.96",
"savings": "469"
},
"commercial": {
"rate": "8.18",
"savings": "5"
}
}
/analytics/usage
Get usage data for a specific meter.
Request
Parameters
- meterID required
- the Griddy internal meter ID (not the esi)
- period required
- The starting timestamp of the usage that is requested. (format:
YYYY-MM-DD) - aggregation required
- The interval that the usage should be aggregated for. Must be either “yearly”, “monthly”, or “daily”
Response
Parameters
- aggregation
- The top level aggregation
- period
- The start of the usage interval
- usage_kwh
- Total usage for this period
- price_ckwh
- The average price per kwh during this period
- cost_dollars
- Total cost of electricity for this period
- high_spike
- This period contains a high price spike
- low_spike
- This period contains a low price spike
- pending
- This usage data is still pending and subject to change
- missing
- This usage data was never received
- children
- Child aggregations with the same shape as the top level object (with the expection that children will not have additional children). If the top level aggregation is “yearly”, then the children will be aggregated by month (“monthly”). If the top level is “monthly” the children will be “daily”. And finally if the top level is “daily” the children will be “hourly”. The top level cannot be “hourly”.
- avg_kwh
- The average kwh of the child units. This field is not used in the children.
- avg_cost
- The average cost of the child units. This field is not used in the children.
{
"meterID": "20007",
"period": "2018-09-01",
"aggregation": "yearly"
}
{
"aggregation": "yearly",
"period": "2018-09-01T00:00:00-05:00",
"usage_kwh": "691.9",
"price_ckwh": "2.5",
"cost_dollars": "17.50",
"high_spike": false,
"low_spike": false,
"pending": false,
"missing": false,
"children": [
{
"aggregation": "monthly",
"period": "2019-02-01T00:00:00-06:00",
"usage_kwh": "657.6",
"price_ckwh": "2.5",
"cost_dollars": "16.56",
"high_spike": false,
"low_spike": false,
"pending": false,
"missing": false,
"children": [],
"avg_kwh": "",
"avg_cost": ""
},
...
{
"aggregation": "monthly",
"period": "2019-03-01T00:00:00-06:00",
"usage_kwh": "34.4",
"price_ckwh": "2.7",
"cost_dollars": "0.93",
"high_spike": false,
"low_spike": false,
"pending": false,
"missing": false,
"children": [],
"avg_kwh": "",
"avg_cost": ""
}
],
"avg_kwh": "71.0",
"avg_cost": "2.28"
}
Billing
/billing/account
Get billing information for a specific member's account.
Request
Parameters
- memberID required
- the member’s ID
Response
The response contains basic account balance and pending account balance information for the specified member.
Parameters
- memberID
- the member’s ID for the data returned
- account_balance
- the member’s account balance in dollars
- account_pending_balance
- the pending account balance if there are any pending credits or debits to the member’s account
- est_top_off_date
- the estimated date the member’s account will be topped off
- top_off
- the top off amount in dollars
{
"memberID": "0c3...d64",
}
{
"memberID": "0c3...d64",
"account_balance": "30.56",
"account_pending_balance": "49.00",
"est_top_off_date": "2017-01-03T01:30:00Z",
"top_off": "100",
"accountID": "35002"
"active": false
}
/billing/activate
Activate a specific member's billing account.[NOT USED]
Request
Activate an account
Parameters
- memberID required
- the member’s ID
Response
The respose returns a boolean depending on the success or failure of your request to activate a member’s billing account.
Parameters
- success
- returns the success to activate the account as
trueorfalse
{
"memberID": "0c3...d64",
}
{
"success": true,
}
/billing/addfunds
A member manually adds more money or funds to their account.
Request
After adding a card, you may add funds to your account.
Parameters
- memberID required
- your member’s ID
- new_payment_amount required
- the total amount of funds to be added
- payment_methodID
- the method of payment to add funds to an account
- initial_payment optional
- this is set to
trueduring enrollment to signify this is the first payment - hashID required
- a unique ID used to prevent processing the same payment multiple times
- promo_id optional
- ID of the specific promotion
Response
The response confirms the request
Parameters
- memberID
- the member’s ID
- account_balance
- the member’s current account balance
- inital_payment
- if this was set to
trueit will return true that this payment was made during enrollment - account_pending_balance
- the future account balance when the new funds are added to the member’s account
- promo_allocated
- a
truevalue states promotional offer was allocated to the member’s account and afalsevalue states that no promotional offer was allocated to the member’s account. Promo can be in the form of free months membership or dollar credit applied to the member’s accounts
{
"memberID": "0c3...d64",
"new_payment_amount": "49",
"payment_methodID": "456"
"initial_payment": true,
"hashID": "757...125"
"promo_id": "1"
}
{
"memberID": "0c3...d64",
"account_balance": "30.56",
"initial_payment": true,
"account_pending_balance": "49.00",
"promo_allocated": true
}
/billing/capturepayments
This endpoint is for internal use only and not public facing.
Request
This is a placeholder
Parameters
- placeholder required
- holding that place
Response
This is a placeholder
Parameters
- placeholder
- holding that place
{
"placeholder": "holdMyPlace",
}
{
"placeholder": "holdMyPlace",
}
/billing/charge
This endpoint is for internal use only and not public facing.
Request
This is a placeholder
Parameters
- placeholder required
- holding that place
Response
This is a placeholder
Parameters
- placeholder
- holding that place
{
"placeholder": "holdMyPlace",
}
{
"placeholder": "holdMyPlace",
}
/billing/create
Create a billing account for which to pay for Griddy's services.
Request
This requests creates an account in billing for member’s to add funds and get recharged
Parameters
- memberID required
- the member’s ID
Response
The response serves as a reciept that the account in billing has been made. It will return the following information when successful…
Parameters
- memberID
- the member’s ID
- account_balance
- the total amount of money in the member’s account
- account_pending_balance
- the future account balance when the new funds are added to the member’s account
- est_top_off_date
- the estimated date the member’s account will get recharged
- top_off
- the member’s recharge amount
{
"memberID": "0c3...d64",
}
{
"memberID": "0c3...d64",
"account_balance": "30.56",
"account_pending_balance": "49.00",
"est_top_off_date": "2017-01-03T01:30:00Z"
"top_off": "60.89",
}
/billing/credit
Credit money back to a member's account
Request
Provide the member and some additiona; information to apply a credit to a member account
Parameters
- memberID required
- the member ID to apply the credit
- amount required
- the amount in dollars to be credited to the member’s account
- credit_type required
- the type of credit
- credit_subtype required
- the reason code for the application of credit
- date required
- the date the credit was applied to the member’s account
- meta_data optional
- just another fun nested JSON object with limitless possibilities
- hashID required
- a unique ID used to prevent processing the same payment multiple times
Response
The respose returns a bool stating if the credit application was successful
Parameters
- success
- returns the success of the CreditRequest as
trueif the credit was successful orfalseif the credit failed - transaction_id
- a unique id assigned to the processed transaction
{
"memberID": "0c3...d64",
"amount": "49",
"credit_type": "membership_fee",
"credit_subtype": "day_credit",
"date": "2019-03-01T00:00:00+07:00",
"meta_data": {
"somekey": "somevalue",
"anotherkey": "anothervalue"
},
"hashID": "757...125"
}
{
"success": true,
"transaction_id": "0"
}
/billing/deactivate
Deactivate an specific member's billing account
Request
Deactivate an account and set active column to false
Parameters
- memberID required
- the member ID whose account is to be deactivated
Response
The respose tells you if your request was or was not successful
Parameters
- success
- returns the success to deactivate the account as
truedeactivation was successful orfalseif deactivation failed
{
"memberID": "0c3...d64",
}
{
"success": true,
}
/billing/debit
Charge a member's account.
Request
Charge a member’s account.
Parameters
- memberID required
- the member’s ID
- debit_type required
- the type of debit being performed
- amount required
- the total amount in dollars to charge a member’s account
- start required
- the start date for the charge
- end required
- the end date for the charge
- debit_subtype required
- the reason or reason code for the debit
- meta_data optional
- just another fun nested JSON object with limitless possibilities
- hashID required
- a unique ID used to prevent processing the same payment multiple times
Response
The respose returns a bool stating if the credit application was successful.
Parameters
- success
- returns the success of the DebitRequest as
trueif the charge was successful orfalseif the charge failed
{
"memberID": "0c3...d64",
"debit_type": "49",
"amount": "456",
"start": "2017-01-03T01:30:00Z",
"end": "2017-01-03T01:30:00Z",
"debit_subtype": "manual_deposit",
"meta_data": {
"somekey": "somevalue",
"anotherkey": "anothervalue",
},
"hashID": "757...125",
}
{
"success": true,
}
/billing/ercot_invoices_report
Request an ERCOT invoice report
Request
Request a report of ERCOT invoices between a specified time frame
Parameters
- start_date required
- the beginning date for the report data
- end_date required
- the end date for the report data
Response
The ERCOT Invoice Report returns rows of data including…
Parameters
- operating_date
- the operating date for the ERCOT invoice
- total_ercot
- Total ERCOT invoice amount
- energy_shadow
- shandow energy amount
- rtm_amount
- real time market amount
- rtm_final
- the final amount for the real time market
- rtm_trueup
- the true up for the real time market amount
- rtm_resettlement
- the resettlement amount for the cost from the real time market
- dam
- day ahead market amount
- dam_resettlement
- resettlement amount for the day ahead market
- invoice_amounts
- a nested object providing detailed the
amountsfor the ERCOT invoices
{
"start_date": "2017-01-03T01:30:00Z",
"end_date": "2017-01-03T01:30:00Z",
}
{
"rows": [{
"operating_date": "2017-01-03T01:30:00Z",
"total_ercot": "10.2",
"energy_shadow": "3.8",
"rtm_amount": "1.23",
"rtm_final": "4.5",
"rtm_trueup": "2.1",
"rtm_resettlement": "1.5",
"dam": "4.1",
"dam_resettlement": "1.4",
"invoice_amounts": {
"amount": "somevalue",
"anotherAmount": "anothervalue"
},
}...],
}
/billing/get_account_deposits
Get a list of all transactions.
Request
Request a member’s transaction data
Parameters
- memberID required
- the member’s ID
- page optional
- the page from which the transactions are to be returned
- month optional
- the month from which the transactions are to be returned
Response
Transaction data per the request parameters and filters. It will return a list of default: 25 transactions per page with the following data…
Parameters
- amount
- the amount of transactions for the period requested
- type_name
- the transaction type name
- type_description
- a description of the transaction type
- subtype_name
- the name of the transaction subtype
- subtypeID
- the ID number for the transaction subtype
- subtype_description
- a description of the subtype transaction
- created_date
- the date the transaction was created
More from the transaction response….
Parameters
- page
- number of pages in the report
- has_next
- responds with
trueif the report has a next page orfalseif the report does not have a next page - next
- number of pages after the current page
- total
- total number of transactions returned
{
"memberID": "4jf..23f"
"page": "1",
"month": "1"
}
{
"deposits": [
{
"amount": "50.99",
"type_id": "5",
"type_name": "deposit",
"type_description": "someDescription",
"subtype_id": "6789",
"subtype_name": "manual_deposit",
"subtype_description": "someDescription",
"created_date": "2019-02-19T20:00:00:00Z",
"pending": false,
}
{
"amount": "150.00",
"type_id": "2",
"type_name": "promo",
"type_description": "someDescription",
"subtype_id": "13",
"subtype_name": "dollar_credit",
"subtype_description": "someDescription",
"created_date": "2019-02-19T20:00:00:00Z",
"pending": false,
}...],
"page": "1",
"has_next": false,
"next": "0",
"total": "2"
}
/billing/ledgers
Get a ledger for a specific member's billing account.
Request
Request the ledger for a specific member for a specific month and year.
Parameters
- memberID required
- the member ID
- month
- the requested month of ledger data
- year
- the requested year of ledger data
Response
The response returns a nested object with details about the ledger for the month and year requested
Parameters
- time
- the time period for the ledger data
- beginning_balance
- the balance at the beginning of the time period of the ledger data
- ending_balance
- the balance at the end of the time period of the the ledger data
- reason
- the transaction type ie Taxes, Fees
{
"memberID": "0c3...d64",
"month": "January",
"year": "2016"
}
{
"ledgers": [{
"time": "2017-01-03T01:30:00Z",
"beginning_balance": "49.00",
"ending_balance": "24.9",
"reason": "someReason"
}...],
}
/billing/list_payments
Get a list of a speficic member's payments.
Request
Parameters
- memberID required
- the member’s ID
- status
- the payment status list to filter by;
- valid choices include:
authorized,captured,declinedandpending
Response
The response provides a list of a member’s payments and data specific to each payment.
Parameters
- ID
- the payment ID
- amount
- the amount of the payment
- status
- the status of the payment; can be
pending,captured - created
- the date the payment was created
- charge_id
- the stripe
charge_idof the payment
{
"memberID": "0c3...d64",
"status": ["authorized", "captured"]
}
{
"payments":[
{
"ID": 1234,
"amount": "10.2",
"status": "captured",
"created": "2017-01-03T01:30:00Z",
"charge_id": "ch_1A9bblCsz..."
}...],
/billing/promo
Get details about promos applied to a member's account.[NOT USED]
Request
Promo details for a member’s account.
Parameters
- memberID required
- the member’s ID
Response
Information about the promo applied to a member’s account.
Parameters
- credit
- the credit applied to the member’s account based on the promo
- percent_discount
- the percentage discount applied to the member’s account by the promo
- membership_fee
- the amount of money the member is charged for each month of membership
- duration
- the duration of time the promo is to be applied WHAT IS THE DURATION IN? MONTHS? DAYS?
{
"memberID": "0c3...d64"
}
{
"credit": "9.99",
"percent_discount": "30",
"membership_fee": "9.99",
"duration": "30"
}
/billing/promo/apply
Apply a promo to a memnber's account.[NOT USED]
Request
Promo details for a member’s account.
Parameters
- memberID required
- the member’s ID
- code required
- the promo code entered
Response
The response confirms the member’s account, their balance and the discount applied by the promo.
Parameters
- memberID
- the memberID for the account the promo was applied
- account_balance
- the member’s account balance IS THIS AFTER THE PROMO?
- discount
- the discount applied to the account WHAT IS THE DISCOUNT APPLIED IN? PERCENTAGE?
{
"memberID": "0c3...d64",
"code": "member30"
}
{
"memberID": "0c3...d64",
"account_balance": "30.59",
"discount": "9.99",
}
/billing/refund
Refund a member's payment
Request
Refund a member’s account
Parameters
- memberID required
- the member’s ID
- amount_dollars required
- the amount for the refund in dollars
- deactivate_account required
- set
trueto deactivate the account with the refund or set asfalseto keep the account active with the refund
Response
The respose confirms your refund request
Parameters
- success
- returns the success to refund the account as
trueorfalse - message
- a message is returned with the response
- new_balance
- the new balance of the member’s account with the refund
{
"memberID": "0c3...d64",
"amount_dollars": "40.45",
"deactivate_account": false,
}
{
"success": true,
"message": "some Message",
"new_balance": "new_balance",
}
/billing/subtypetotals
Get totals for subtypes
Request
Request subtype totals
Parameters
- start required
- start date for subtype totals requesting
- end required
- end date for subtype totals requesting
Response
Data points for the subtype totals request.
Parameters
- subtypeID
- the ID for the subtype total
- name
- the name of the subtype
- description
- the description for the subtype total
- subtype_total
- the total amount for the subtype
{
"start": "2017-01-03T01:30:00Z",
"end": "2017-01-03T01:30:00Z",
}
{
"transations": [
{
"subtypeID": 12345,
"name": "someName",
"description": "someDescription",
"subtype_total": "15.23",
}...],
}
/billing/summary
Get a billing summary for a member's account.
Request
Provide the member and the date range for the account summary
Parameters
- memberID required
- the member’s ID
- month required
- the requested month for summary data
- year required
- the requested year for summary data
Response
The response provides a summary of billing data for a specific member.
Parameters
- month
- the month for the summary data
- year
- the year for the summary data
- total_amount
- total amount paid
- beginning_account_balance
- the account balance at the beginning of the summary period
- ending_account_balance
- the ending account balance at the end of the summary period
- group_items
- A nested object in the response that provides:
ID, type, title, description, amount_dollars, line items, name - line_items
- A nested object in the
group_itemsresponse that provides: ID, type, description, item type, subID, title, sub_discription, amount_dollars, date, meta_data, name - allin_rate_ckwh
- the member’s all in rate - the total bottom line cost for energy with taxes
- rate_to_compare
- the rate of electricity cost for that summary period
- cost_to_compare
- the cost of electricity for that summary period
- kwh_used
- the total kWh of electricity used for the summary period
- projected_annual_savings_dollars
- the projected savings for the year for that member
- free_membership_expiration
- a nested object in the response that provides
has_free_monthsanddate - has_free_months
truevalue states member has free months andfalsevalue states, the member does not have free months- date
- populates end date of the free month if the boolean value above is
trueand returns a null of the above boolean is set tofalse
{
"memberID": "0c3...d64",
"month": "April",
"year": "2017"
}
{
"month": "4",
"year": "2017",
"total_amount": "234.98",
"beginning_account_balance": "200.89",
"ending_account_balance": "34.98",
"group_items": [
{
"ID": "1",
"type": "tdsp_cost",
"title": "TDU Delivery Charges",
"descriptoion": "someDescription",
"amount_dollars": "45.60",
"line_items": [
{
"ID": "0",
"type": "TDU Delivery Charges",
"description": "TDU Delivery Charges",
"item_type": "",
"subID": "0",
"title": "TDU Delivery Charges",
"sub_description": "",
"amount_dollars": "25.79",
"date": "2017-01-03T01:30:00Z",
"meta_data":
{
"somekey": "somevalue",
"anotherkey": "anothervalue"
},
"name": "TDU Delivery Charges",
}...],
"name": "someName",
"display_rank": "2"
}...],
"allin_rate_ckwh": "65.98",
"rate_to_compare_ckwh": "68.54",
"cost_to_compare": "66.75",
"kwh_used": "5.4",
"projected_annual_savings_dollars": "305.5"
"free_membership_expiration":
{
"has_free_months": true,
"date": "2019-03-19T21:41:28Z"
}
}
/billing/tdsp_invoices_report
Request a report of TDSP invoices.
Request
Request an TDSP invoice report.
Parameters
- start_date required
- the beginning date for which you require ERCOT invoices
- end_date required
- the end date for which you require ERCOT invoices
- memberID
- the member’s ID
Response
The TDSP Invoice Report returns returns rows of data including…
Parameters
- memberID
- member’s ID
- invoiceID
- the TDSP invoice ID
- invoice_date
- the TDSP invoice date
- start_date
- the start date for the invoice
- end_date
- the end date for the invoice
- invoice_amount_dollars
- the total amount in the TDSP invoice in dollars
- tdsp_shadow_amount_dollars
- the amount to shadow for TDSP charges in dollars
- tdsp_credit
- credits from TDSP
- tdsp_invoice
- the total amount in the TDSP invoice in dollars (same as invoice_amount_dollars)
- ESID
- the meter’s ESI ID
- created
- the creation date for the TDSP invoice
{
"start_date": "2017-01-03T01:30:00Z",
"end_date": "2017-01-03T01:30:00Z",
"memberID": "0c3...d64",
}
{
"rows": [{
"memberID": "0c3...d64",
"invoiceID": "1234",
"invoice_date": "2017-01-03T01:30:00Z",
"start_date": "2017-01-03T01:30:00Z",
"end_date": "2017-01-03T01:30:00Z",
"invoice_amount_dollars": "4.5",
"tdsp_shadow_amount_dollars": "2.1",
"tdsp_credit": "1.5",
"tdsp_invoice": "4.1",
"ESID": "1.4",
"created": "2017-01-03T01:30:00Z",
}...],
}
/billing/topoff
Automatically recharge a member's account when their account balances drops below the threshold - default $25.
Request
Parameters
- memberID required
- the member’s ID
- new_top_off required
- the recharge amount to be applied to the member’s account balance
Response
The response confirms the memberID and the new_top_off amount has been updated to a member’s account
Parameters
- memberID
- the member’s ID
- new_top_off
- the amount in dollars recharged to the member’s account
- account_pending_balance
- the pending account balance if there are any pending credits or debits to the member’s account
{
"memberID": "0c3...d64",
"new_top_off": "49",
}
{
"memberID": "0c3...d64",
"new_top_off": "49"
"account_pending_balance": "49.00"
}
/billing/totalusagecharged
This endpoint is for internal use only. This is not public facing.
Request
This is a placeholder
Parameters
- placeholder required
- holding that place
Response
This is a placeholder
Parameters
- placeholder
- holding that place
{
"placeholder": "holdMyPlace",
}
{
"placeholder": "holdMyPlace",
}
/billing/transactions
Get a list of transations.[NOT USED]
Request
Request transaction data by indicating a time frame and filters.
Parameters
- start required
- the start date for the transaction data requested
- end required
- the end date for the transaction data requested
- filter optional
- filter the transaction data by applying
nameandvalues - limit optional
- the maximum number of transactions to be returned
- page optional
- the page from which the transactions are to be returned
Response
Transaction data per the request parameters and filters. It will return a list of transactions with the following data…
Parameters
- transactions
- a nested object that returns the following data points
- amount
- the amount of transactions for the period requested
- operating_date
- the operating date for the transaction
- created_date
- the date the transaction was created
- memberID
- the member’s ID for the transaction
- accountID
- the account Id for the transaction
- type_name
- the transaction type name
- type_description
- a description of the transaction type
- subtype_name
- the name of the transaction subtype
- subtypeID
- the ID number for the transaction subtype
- subtype_description
- a description of the subtype transaction
- hashID
- the hash ID for the trasaction
- ID
- THE TRANSACTION ID?
- meta_data
- many strings of data
- modified_date
- the date the transaction was modified
More from the transaction response….
Parameters
- total
- total number of transactions returned
- has_next
- responds with
trueorfalseif the report has a next page? - page
- number of pages in the report
- limit
- limit of transactions returned in the report
{
"start": "2017-01-03T01:30:00Z",
"end": "2017-01-03T01:30:00Z",
"filters": [{
"name": "someName",
"values": "someValues",
}...],
"limit": 50,
"page": 4,
}
{
"transations": [{
"amount": "50.99",
"operating_date": "10.2",
"created_date": "3.8",
"memberID": "1.23",
"accountID": 10111213,
"typeID": 12345,
"type_name": "1.5",
"type_description": "someDescription",
"subtypeID": 6789,
"subtype_name": "someName",
"subtype_description": "someDescription",
"hashID": "757...125",
"ID": 1234,
"meta_data": {
"somekey": "somevalue",
"anotherkey": "anothervalue"
},
"modified_date": "2017-01-03T01:30:00Z",
}...],
"total": 240,
"has_next": true,
"page": 3,
"limit": 100,
}
/billing/usage_and_cost_report
Get a report of usage and cost.
Request
Request a report looking at usage and costs.
Parameters
- start required
- start date for usage and cost totals to request
- end required
- end date for usage and cost totals to request
Response
Data points for the usage and cost report.
Parameters
- total_amount_dollars
- total cost in dollar amounts for the date range requested
- total_usage
- total usage amoutn for the date range requested
- average_rate_cent
- average rate for the date rage requested in cents
{
"start": "2017-01-03T01:30:00Z",
"end": "2017-01-03T01:30:00Z",
}
{
"total_amount_dollars": "350.99",
"total_usage": "4.7",
"average_rate_cent": "0.75",
}
GriddyGuest
/griddyguest/analytics/history
Get usage history for a Griddy Guest member.
Request
Parameters
- iana_timezone
- the time zone to use for aggregating data; will default to ‘America/Chicago’ if left blank
- meterID
- the ID of the Griddy Guest member
Response
The response will contain hourly, daily, and monthly usage data.
Parameters
- time
- the time the usage interval was for
- price_kwh
- the price per kWh of usage
- usage_kwh
- the total usage consumed during that interval
- cost_dollars
- the total cost for the listed usage
{
"iana_timezone": "America/Chicago",
"meterID": "12345"
}
{
"hourly": [
{
"time": "2019-02-17T06:00:00Z",
"price_ckwh": "1.87",
"usage_kwh": "0.7000637338345986",
"cost_dollars": "0.01"
},
{
"time": "2019-02-17T07:00:00Z",
"price_ckwh": "1.96",
"usage_kwh": "0.5911514848369948",
"cost_dollars": "0.01"
}...],
"daily": [
{
"time": "2018-09-20T05:00:00Z",
"price_ckwh": "2.45",
"usage_kwh": "28.96581768896275",
"cost_dollars": "0.71"
},
{
"time": "2018-09-21T05:00:00Z",
"price_ckwh": "2.41",
"usage_kwh": "29.39057546005341",
"cost_dollars": "0.71"
}...],
"monthly": [
{
"time": "2018-02-01T06:00:00Z",
"price_ckwh": "2.31",
"usage_kwh": "183.94492267230322",
"cost_dollars": "4.26"
},
{
"time": "2018-03-01T06:00:00Z",
"price_ckwh": "2.04",
"usage_kwh": "526.0116737795778",
"cost_dollars": "10.71"
}...],
}
/griddyguest/analytics/savings
Get savings data for a Griddy Guest member.
Request
Parameters
- memberID required
- the ID for the Griddy Guest member (not the same as the
userIDor thememberIDof an actual member)
Response
The response will contain hourly, daily, and monthly usage data.
Parameters
- period
- the time interval the data is for
- griddy_costs not in use
- the total cost paid with Griddy before taxes
- griddy_taxes not in use
- the total taxes associated with the
griddy_costsamount - usage not in use
- the total kWh usage for the period
- eia_rate not in use
- the Texas average EIA rate for that operating month
- is_rolling_avg
- returns
trueif the calculation is a rolling average andfalseif it is not a rolling average - eia_costs not in use
- the total estimated cost using the
eia_ratefor that operating month - eia_taxes not in use
- the total taxes associated with the
eia_costsamount - savings
- the total savings estimated with Griddy as your electricity provider compared to the average Texan
- griddy_allin_rate
- the c/kWh rate for your usage calculated with Griddy’s wholesale rate and including delivery charges, membership, taxes & fees
- eia_allin_rate not in use
- the c/kWh rate for your usage calculated with the EIA rate and including delivery charges, taxes & fees
- griddy_all_in_costs not in use
- the total cost paid with Griddy after taxes (
griddy_costs+griddy_taxes) - eia_tax_cpkwh not in use
- the calculation used to estimate the total tax rate
- eia_allin_costs not in use
- the total cost paid by the average Texan after taxes (
eia_costs+eia_taxes) - eia_costs_wo_taxes not in use
- the total cost calculated with the
eia_ratebefore taxes
{
"memberID": "1234"
}
{
"monthly": [
{
"period": "2018-02-01",
"griddy_costs": "0.0",
"griddy_taxes": "0.0",
"usage": "0.0",
"eia_rate": "11.1",
"is_rolling_avg": false,
"eia_costs": "21.56",
"eia_taxes": "0.0",
"savings": "4.43",
"griddy_allin_rate": "9.32",
"eia_allin_rate": "11.7",
"griddy_all_in_costs": "17.14",
"eia_tax_cpkwh": "0.6",
"eia_allin_costs": "21.56",
"eia_costs_wo_taxes": "0.0"
},
{
"period": "2018-03-01",
"griddy_costs": "0.0",
"griddy_taxes": "0.0",
"usage": "0.0",
"eia_rate": "11.6",
"is_rolling_avg": false,
"eia_costs": "64.45",
"eia_taxes": "0.0",
"savings": "17.44",
"griddy_allin_rate": "8.94",
"eia_allin_rate": "12.3",
"griddy_all_in_costs": "47.00",
"eia_tax_cpkwh": "0.7",
"eia_allin_costs": "64.45",
"eia_costs_wo_taxes": "0.0"
}...],
"totals": {
"period": "total",
"griddy_costs": "0.0",
"griddy_taxes": "0.0",
"usage": "0.0",
"eia_rate": "0.0",
"is_rolling_avg": false,
"eia_costs": "0.0",
"eia_taxes": "0.0",
"savings": "167.76",
"griddy_allin_rate": "10.0",
"eia_allin_rate": "0.0",
"griddy_all_in_costs": "0.0",
"eia_tax_cpkwh": "0.0",
"eia_allin_costs": "0.0",
"eia_costs_wo_taxes": "0.0"
},
"hide_savings": false
}
/griddyguest/analytics/usage
Get usage data for a specific Griddy Guest.
Request
Parameters
- meterID required
- the Griddy Guest meter ID
- period required
- The starting timestamp of the usage that is requested. (format:
YYYY-MM-DD) - aggregation required
- The interval that the usage should be aggregated for. Must be either “yearly”, “monthly”, or “daily”
Response
Parameters
- aggregation
- The top level aggregation
- period
- The start of the usage interval
- usage_kwh
- Total usage for this period
- price_ckwh
- The average price per kwh during this period
- cost_dollars
- Total cost of electricity for this period
- high_spike
- This period contains a high price spike
- low_spike
- This period contains a low price spike
- pending
- This usage data is still pending and subject to change
- missing
- This usage data was never received
- children
- Child aggregations with the same shape as the top level object (with the expection that children will not have additional children). If the top level aggregation is “yearly”, then the children will be aggregated by month (“monthly”). If the top level is “monthly” the children will be “daily”. And finally if the top level is “daily” the children will be “hourly”. The top level cannot be “hourly”.
- avg_kwh
- The average kwh of the child units. This field is not used in the children.
- avg_cost
- The average cost of the child units. This field is not used in the children.
{
"meterID": "20007",
"period": "2018-09-01",
"aggregation": "yearly"
}
{
"aggregation": "yearly",
"period": "2018-09-01T00:00:00-05:00",
"usage_kwh": "691.9",
"price_ckwh": "2.5",
"cost_dollars": "17.50",
"high_spike": false,
"low_spike": false,
"pending": false,
"missing": false,
"children": [
{
"aggregation": "monthly",
"period": "2019-02-01T00:00:00-06:00",
"usage_kwh": "657.6",
"price_ckwh": "2.5",
"cost_dollars": "16.56",
"high_spike": false,
"low_spike": false,
"pending": false,
"missing": false,
"children": [],
"avg_kwh": "",
"avg_cost": ""
},
...
{
"aggregation": "monthly",
"period": "2019-03-01T00:00:00-06:00",
"usage_kwh": "34.4",
"price_ckwh": "2.7",
"cost_dollars": "0.93",
"high_spike": false,
"low_spike": false,
"pending": false,
"missing": false,
"children": [],
"avg_kwh": "",
"avg_cost": ""
}
],
"avg_kwh": "71.0",
"avg_cost": "2.28"
}
/griddyguest/billing/summary
Get a billing summary for a Griddy Guest member.
Request
Parameters
- memberID
- the ID for the Griddy Guest member (not the same as the
userIDor thememberIDof an actual member) - month required
- the operating month to view
- year required
- the operating year to view
Response
The response will contain a breakdown of all costs.
Parameters
- month
- the operating month to view
- year
- the operating year to view
- total_amount
- the total cost paid for the period
- begining_account_balance
- the account balance before a transaction was applied
- ending_account_balance
- the account balance after a transaction was applied
- ID
- the internal ID used to label each charge type
- type
- the database name for each charge type
- title
- the name of the charge type as displayed on the statement
- description
- an explanation of the charge type
- amount_dollars
- the total cost accrued for each charge type
- subID
- the internal ID used to label each charge subtype
- meta_data
- many strings of data
- display_rank
- the position of where each charge type appears on the statement
- allin_rate_ckwh
- the all in rate in c/kWh calculated from the total cost and total usage for the period including taxes
- rate_to_compare_ckwh
- the rate to compare in c/Kwh calculated from the total cost and total usage for the period before taxes
- cost_to_compare
- the total dollar amount paid for the period before taxes
- kwh_used
- the usage consumed during the period
- projected_annual_savings_dollars
- how much the average Griddy member is expected to save each year
{
"memberID": "1234",
"month": "8",
"year": "2018"
}
{
"month": "8",
"year": "2018",
"total_amount": "211.14",
"begining_account_balance": "",
"ending_account_balance": "",
"group_items": [
{
"ID": "7",
"type": "membership_fee",
"title": "Griddy Membership",
"description": "",
"amount_dollars": "9.99",
"line_items": [
{
"ID": "7",
"type": "membership_fee",
"description": "",
"item_type": "",
"subID": "",
"title": "Griddy Membership",
"sub_discription": "",
"amount_dollars": "9.99",
"date": "",
"meta_data": {},
"name": "Griddy Membership"
}
],
"name": "Griddy Membership",
"display_rank": "4"
},
{
"ID": "8",
"type": "wholesale_energy_cost",
"title": "Wholesale Electricity",
"description": "",
"amount_dollars": "100.87",
"line_items": [
{
"ID": "0",
"type": "Ancillary Services",
"description": "",
"item_type": "",
"subID": "",
"title": "Ancillary Services",
"sub_discription": "",
"amount_dollars": "13.33",
"date": "",
"meta_data": {},
"name": "Ancillary Services"
},
{
"ID": "0",
"type": "Electricity Usage",
"description": "",
"item_type": "",
"subID": "",
"title": "Electricity Usage",
"sub_discription": "",
"amount_dollars": "87.53",
"date": "",
"meta_data": {},
"name": "Electricity Usage"
}
],
"name": "Wholesale Electricity",
"display_rank": "1"
}...],
"allin_rate_ckwh": "10.00",
"rate_to_compare_ckwh": "",
"cost_to_compare": "",
"kwh_used": "2112",
"projected_annual_savings_dollars": ""
}
/griddyguest/create
Create a Griddy Guest member from an existing user id that has not completed enrollment (abandoned).
Request
The request simply requires a valid user_id (gg_status = available) from the users/signup/users/signin endpoint.
Parameters
- userID required
- the user ID of a member that has not registered a meter or completed enrollment
Response
The response will contain a simple empty Griddy Guest member definition.
Parameters
- memberID
- the ID for the Griddy Guest member (not the same as the
user_id) - zip_code
- the zip code for the Griddy Guest member - this will always be empty on create
- home_size
- the home size for the Griddy Guest member - this will always be empty on create
- contract_end_date
- the Griddy Guest member’s contract end date from their current energy provider (so we can remind them to switch at contract end)
Response Error Codes
Parameters
- 409 Conflict
- account already exists for this user - this userID has already been submitted to griddyguest/create and a Griddy Guest account already exists
{
"userID": "1234"
}
{
"Members": [
{
"memberID": "1234",
"zip_code": "",
"home_size": "",
"contract_end_date": "",
"profileID": "",
"settlement_point": "",
"provided_zip_code": ""
}
]
}
/griddyguest/get_all
Get information for a Griddy Guest member with their user ID.
Request
The request simply requires a valid user_id (gg_status = available) from the users/signup/users/signin endpoint.
Parameters
- userID required
- the user ID of a member that has not registered a meter or completed enrollment
Response
The response will contain a simple empty Griddy Guest member definition.
Parameters
- memberID
- the ID for the Griddy Guest member (not the same as the
userIDor thememberIDof an actual member) - zip_code
- the zip code for the Griddy Guest member - this will always be empty on create
- home_size
- the home size for the Griddy Guest member - this will always be empty on create
- contract_end_date
- the Griddy Guest member’s contract end date from their current energy provider (so we can remind them to switch at contract end)
- profileID
- the ID assigned to a Griddy Guest member for a specific weather zone and home size to display sample data
- settlement_point
- the sub-region within a load zone, but also refers to the load zone; must be in all caps
- provided_zip_code
- the zip code entered during Griddy Guest sign up and used to display sample data
{
"userID": "12345"
}
{
"Members": [
{
"memberID": "1234",
"zip_code": "77064",
"home_size": "small",
"contract_end_date": "2019-01-01",
"profileID": "27",
"settlement_point": "LZ_HOUSTON",
"provided_zip_code": "77002"
}
]
}
/griddyguest/get_meter
Get meter information for a Griddy Guest member.
Request
Parameters
- memberID required
- the ID for the Griddy Guest member (not the same as the
userIDor thememberIDof an actual member)
Response
Parameters
- meterID
- the ID for the meter (this is not the ESI)
- memberID
- the ID for the Griddy Guest member
- settlement_point
- the sub-region within a load zone, but also refers to the load zone
- status
- status of the meter is returned with an
effective_dateand thestatusofconnected,disconnected,pending_connectionorpending_disconnection - service_address
- the service address for the meter
- enrollment_date
- the date the enrollment was completed; this is different from
start_datewhen the meter service begins or is on flow - start_date
- the date service started
- end_date
- the date service ended
- ID
- the Griddy Guest profile ID used to display sample usage and savings data
- meta_data
- more strings of data
- duns_number
- the DUNS number of the corresponding TDSP
- griddy_rate_class
- states whether the meter is classified as commercial/business or residential/home
- esg_meter_token
- the meter token assigned by ESG during the enrollment process
- enrollMode
- states whether the enrollment was a “switch” or a “movein”
- requested_start_date
- the date the member requested to be on flow with Griddy
- rate_class
- declares the POLR rate class of residential, small non-residential, medium non-residential, etc.
- tier_name
- indicates which tier the meter falls into based on average monthly usage for business - residential has only one tier
- membership_rate
- the monthly rate the member pays for their Griddy membership
- utility_rates
- the flat rate per month and volumetric rate per kWh that the TDSP charges for delivery
- polr_customer_class
- declares the POLR rate class of residential, small non-residential, medium non-residential, etc.
{
"memberID": "1234"
}
{
"meters": [
{
"meterID": "",
"memberID": "",
"settlement_point": "LZ_HOUSTON",
"status": {
"status": "connected",
"effective_date": "2019-03-19T22:05:59Z"
},
"service_address": null,
"enrollment_date": "",
"start_date": "2018-03-19",
"end_date": "",
"ID": "26",
"meta_data": {},
"duns_number": "",
"griddy_rate_class": "residential",
"esg_meter_token": "",
"enrollMode": "",
"requested_start_date": "",
"rate_class": "",
"tier_name": "",
"membership_rate": "",
"utility_rates": null,
"polr_customer_class": "",
"load_profile": "",
"tier_pending": false
}
]
}
/griddyguest/update
Update a Griddy Guest member's parameters
Request
The request simply requires a valid user_id (gg_status = available) from the users/signup/users/signin endpoint.
Once a value is set, there currently is no way to unset a value (return it to NULL in the database)
Parameters
- memberID required
- the ID for the Griddy Guest member (not the same as the
userIDor thememberIDof an actual member) - zip_code
- the
provided_zip_codefor the Griddy Guest member used to display sample data - home_size
- the home size for the Griddy Guest member
There are 3 accepted values at this time -
small,medium,large. Thezip_codemust either be set in the request or previously set on the Griddy Guest member in order for this parameter to be accepted. - contract_end_date
- Format - “YYYY-MM-DD” - the Griddy Guest member’s contract end date from their current energy provider (so we can remind them to switch at contract end)
Response
The response is confirmation that the changes from the request were made, and should mirror the values in the request. The only time this will not be the case is if a zip code is provided that is not in the supported region (ERCOT), in which case a default Houston zip code will be used.
Parameters
- memberID
- the ID for the Griddy Guest member (not the same as the
userIDor thememberIDof an actual member) - zip_code
- the zip code for the Griddy Guest member - this will always be empty on create
- home_size
- the home size for the Griddy Guest member - this will always be empty on create
- contract_end_date
- the Griddy Guest member’s contract end date from their current energy provider (so we can remind them to switch at contract end)
- profileID
- the ID assigned to a Griddy Guest member for a specific weather zone and home size to display sample data
- settlement_point
- the sub-region within a load zone, but also refers to the load zone; must be in all caps
- provided_zip_code
- the zip code entered during Griddy Guest sign up and used to display sample data
{
"memberID": "1234"
"zip_code": "77064",
"home_size": "small",
"contract_end_date": "2019-01-01"
}
{
"Members": [
{
"memberID": "1234",
"zip_code": "77064",
"home_size": "small",
"contract_end_date": "2019-01-01",
"profileID": "27",
"settlement_point": "LZ_HOUSTON",
"provided_zip_code": "77002"
}
]
}
Insights
/insights/getnow
Get insights NOW!
Request
Parameters
- settlement_point
- the load zone, or the region within a load zone
Response
Response returns data for now and forcast data including…
Parameters
- date
- the date
- hour_num
- WHAT IS THIS?
- min_num
- WHAT IS THIS?
- settlement_point
- the settlement point for the data
- price_type
- WHAT IS THIS?
- price_ckwh
- the real time price of electricity in cents per kWh
- value_score
- WHAT IS THIS?
- mean_price_ckwh
- the mean price of electricity in cents per kWh
- diff_mean_ckwh
- WHAT IS THIS?
- high_ckwh
- the highest cost of electricity in cents per kWh
- low_ckwh
- the lowest cost of electricity in cents per kWh
- std_dev_ckwh
- WHAT IS THIS?
- price_display
- WHAT IS THIS?
- price_display_sign
- WHAT IS THIS?
- date_local_tz
- the date in the local time zone of the member
{
"settlement_point": "someSettlementPoint",
}
{
"now": [{
"date": "2018-05-02",
"hour_num": 16,
"min_num": 8,
"settlement_point": "someSettlementPoint",
"price_type": "someType",
"price_ckwh": "0.45",
"value_score": 1,
"mean_price_ckwh": "0.70",
"diff_mean_ckwh": "0.56",
"high_ckwh": "2.50",
"low_ckwh": "0.01",
"std_dev_ckwh": "0.67",
"price_display": "0.45",
"price_display_sign": "cents",
"date_local_tz": "cst",
}...]
"forecast": [{
"date": "2018-05-02",
"hour_num": 16,
"min_num": 8,
"settlement_point": "someSettlementPoint",
"price_type": "someType",
"price_ckwh": "0.45",
"value_score": 1,
"mean_price_ckwh": "0.70",
"diff_mean_ckwh": "0.56",
"high_ckwh": "2.50",
"low_ckwh": "0.01",
"std_dev_ckwh": "0.67",
"price_display": "0.45",
"price_display_sign": "cents",
"date_local_tz": "cst",
}...]
"seconds_until_refresh": 5,
}
Members
/members/create
Add the member information for a user.
Request
Each user must have an associated member. This API call creates the member.
member_agreement must be true or the request will be denied.
Calling members/create without providing a password simply validates that the email has not been taken. It does not reserve the email address in any way, and it does not prevent a different client, session, or person from creating a User with that email.
Parameters
- userID required
- ID of the user which must match the userID of the access token
- member_agreement required
- set to
truewhen the member has acknowledged the member agreemend in enrollment - this is the default setting and a member cannot continue unless this is true - first_name required
- the member’s first name, or forename
- last_name required
- the member’s last name, or surname
- birthday required
- the member’s birthday
- address optional
- the desired service address
- recharge_dollars optional
- the amount of dollars the member’s account will be recharged when their account balance falls below the threshold
- language optional
- the language of the all
- critical_care optional
- the acknowledgment of the critical care statement
Response
A successful response will return a member object with a memberID and a list of member data.
Parameters
- userID
- the member’s user ID - each member has a single unique user ID
- memberID:
- the member’s ID - has a one-to-one ratio with the member’s ESI ID or meter ID; one userID can have multiple memberIDs associated with it
- first_name
- the member’s first name - as provided in the request
- last_name
- the member’s last name - as provided in the request
- address
- the member’s address - will only be returned if provided in the request
- profile_pic_url
- the image url where the member’s profile pic is located
- current_bal_dollars
- the member’s current account balance in dollars - Key returned with a null value
- est_top_off_date
- the stimated date when the member’s account is perceived to be automatically recharged for the recharge amount - Key returned with a null value
- recharge_dollars
- the amount of dollars the member’s account will be recharged when their account balance falls below the threshold - (default:
$49) - notify_price_alert
- will show
trueif the member has opt’d in for price alert push notifications orfalseif the member has opt’d out of price alert push notifications - notify_refill
- will show
trueif the member has opt’d in for refill alert push notifications orfalseif the member has opt’d out of refill alert push notifications - create_date
- the date and time member was created - Auto generated based on local time format (
YYYY-MM-DDT00:00:00Z) - fee
- the daily portion of monthly membership rate - (default:
0.49) - language
- the language preference of the member - (default:
en) - critical_care
- set to
falsewhen the member has acknowledged the critical care statement in enrollment - confirming that no one at the residence is designated as a Critical Care or Chronic Condition customer (default:false) - birthday
- the member’s birthday - for residential members, this is their security question returned in the format (
YYYY-MM-DDT00:00:00Z) - esg_customer_token
- the customer token for ESG reference - Key returned with a null value
- secondary_acc_holder
- the secondary contact person on the member’s account - Key returned with a null value
{
"userID": "0a6...f0x",
"member_agreement": true,
"first_name": "Jane",
"last_name": "Smith",
"address":
{
"street_address" "10206 Tallowbend Court",
"city": "Houston",
"state": "TX",
"country": "USA",
"postal_code": "77064"
},
"recharge_dollars": "49.00",
"language": "en",
"critical_care": false,
"birthday": "1980-12-31"
}
{
"userID": "33443",
"memberID": "0c3...d64",
"first_name": "Jane",
"last_name": "Smith",
"address":
{
"street_address" "10206 Tallowbend Court",
"city": "Houston",
"state": "TX",
"country": "USA",
"postal_code": "77064"
},
"profile_pic_url": "https://s3-us-west-2.amazonaws.com/member-profile-pics/Greg_GriddyMan_mod.png",
"current_balance_dollars": "",
"est_top_off_date": "",
"recharge_dillars": "49",
"notify_price_alert": true,
"notify_refill": true,
"created_date": "2019-03-14-T19:02:22Z",
"fee": "0.49",
"language": "en",
"critical_care": false,
"birthday": "1980-01-01T00:00:00Z",
"esg_customer_token": "",
"secondary_account_holder": null
}
/members/get
Get data on a specific userID and memberID.
Request
The request will return data on a specified memberID or userID. Only provide either memberID or userID in the request.
Parameters
- memberID required
- the member’s ID
- userID required
- the member’s user ID
Response
A successful response will return a huge list of member data.
Parameters
- userID
- the member’s user ID
- memberID:
- the member’s ID
- first_name
- the member’s first name, or forename
- last_name
- the member’s last name, or surname
- address
- the member’s service address
- profile_pic_url
- the image url where the member’s profile pic is located
- current_bal_dollars
- the member’s current account balance in dollars - Key returned with a null value
- est_top_off_date
- the estimated day the member’s account will be recharged - Key returned with a null value
- recharge_dollars
- the amount of dollars the member’s account will be recharged when their account balance falls below the threshold - (default:
$49) - notify_price_alert
- will show
trueif the member has opt’d in for price alert push notifications orfalseif the member has opt’d out of price alert push notifications - (default:true) - notify_refill
- will show
trueif the member has opt’d in for refill alert push notifications orfalseif the member has opt’d out of refill alert push notifications - (default:false) - created_date
- the date the member’s account has been created Auto generated based on local time format (
YYYY-MM-DDT00:00:00Z) - fee
- the daily portion of monthly membership rate - (default:
0.49) - language
- the language preference of the member - (default:
en) - critical_care
- set to
falsewhen the member has acknowledged the critical care statement in enrollment - confirming that no one at the residence is designated as a Critical Care or Chronic Condition customer (default:false) - birthday
- the member’s birthday - for residential members, this is their security question returned in the format (
YYYY-MM-DDT00:00:00Z) - esg_customer_token
- the customer token for ESG reference - Key returned with a null value
- secondary_acct_holder
- the secondary contact person on the member’s account - Key returned with a null value
{
"memberID": "69a...12b"
}
{
"userID": "970",
"memberID": "69a...12b",
"first_name": "Jason",
"last_name": "Rudder",
"address":
{
"street_address": "123 Moorefield Rd",
"city": "Palmview",
"state": "TX",
"country": "usa",
"postal_code": "78572"
},
"profile_pic_url": "https: //profilepicurl.com",
"current_balance_dollars": "",
"est_top_off_date": "",
"recharge_dollars": "75",
"notify_price_alert": true,
"notify_refill": true,
"created_date": "2017-01-27T21:09:44Z",
"fee": "0.49",
"language": "en",
"critical_care": false,
"birthday": "1976-06-14T00:00:00Z",
"esg_customer_token": ""
"secondary_account_holder": null
}
/members/get_active_by_day
Get the total number of active members on flow on a operating day. This requires an admin access token
Request
Call this to get meters that went on flow on a operating day
Parameters
- days required
- operating day on which user wants on flow meters to be returned ie to see all meters that went on flow 1 day ago enter
1
Response
A successful response will return all members on flow on a operating day.
Parameters
- userID
- the member’s user ID
- memberID:
- the member’s ID
- first_name
- the member’s first name, or forename
- last_name
- the member’s last name, or surname
- address
- the member’s service address
- profile_pic_url
- the image url where the member’s profile pic is located
- current_bal_dollars
- the member’s current account balance in dollars - Key returned with a null value
- est_top_off_date
- the estimated day the member’s account will be recharged - Key returned with a null value
- recharge_dollars
- the amount of dollars the member’s account will be recharged when their account balance falls below the threshold - (default:
$49) - notify_price_alert
- will show
trueif the member has opt’d in for price alert push notifications orfalseif the member has opt’d out of price alert push notifications - (default:true) - notify_refill
- will show
trueif the member has opt’d in for refill alert push notifications orfalseif the member has opt’d out of refill alert push notifications - (default:false) - created_date
- the date the member’s account has been created
- fee
- the daily portion of monthly membership rate - (default:
0.49) - language
- the language preference of the member - (default:
en) - critical_care
- set to
falsewhen the member has acknowledged the critical care statement in enrollment - confirming that no one at the residence is designated as a Critical Care or Chronic Condition customer (default:false) - birthday
- the member’s birthday - for residential members, this is their security question returned in the format (
YYYY-MM-DDT00:00:00Z) - esg_customer_token
- the customer token for ESG reference - Key returned with a null value
- secondary_acct_holder
- the secondary contact person on the member’s account - Key returned with a null value
{
"days": ""
}
{
"Members": [
{
"userID": "970",
"memberID": "69a...12b",
"first_name": "Jason",
"last_name": "Rudder",
"address":
{
"street_address": "123 Moorefield Rd",
"city": "Palmview",
"state": "TX",
"country": "usa",
"postal_code": "78572"
},
"profile_pic_url": "https: //profilepicurl.com",
"current_balance_dollars": "",
"est_top_off_date": "",
"recharge_dollars": "49",
"notify_price_alert": true,
"notify_refill": true,
"created_date": "2017-01-27T21:09:44Z",
"fee": "0.49",
"language": "en",
"critical_care": false,
"birthday": "1976-06-14T00:00:00Z",
"esg_customer_token": ""
"secondary_account_holder": null
}...],
}
/members/get_all
Get member data on a specific userID.
Request
The request will return data on a specified userID or memberID.
Parameters
- userID required
- the user’s ID
Response
A successful response will return all member data for a specific userID. Some userIDs are associated with multiple memberIDs if they have more than one meter registered with Griddy.
Parameters
- userID
- the member’s user ID
- memberID:
- the member’s ID
- first_name
- the member’s first name, or forename
- last_name
- the member’s last name, or surname
- address
- the member’s service address
- profile_pic_url
- the image url where the member’s profile pic is located
- current_bal_dollars
- the member’s current account balance in dollars - Key returned with a null value
- est_top_off_date
- the estimated day the member’s account will be recharged - Key returned with a null value
- recharge_dollars
- the amount of dollars the member’s account will be recharged when their account balance falls below the threshold - (default:
$49) - notify_price_alert
- will show
trueif the member has opt’d in for price alert push notifications orfalseif the member has opt’d out of price alert push notifications - (default:true) - notify_refill
- will show
trueif the member has opt’d in for refill alert push notifications orfalseif the member has opt’d out of refill alert push notifications - (default:false) - created_date
- the date the member’s account has been created
- fee
- the daily portion of monthly membership rate - (default:
0.49) - language
- the language preference of the member - (default:
en) - critical_care
- set to
falsewhen the member has acknowledged the critical care statement in enrollment - confirming that no one at the residence is designated as a Critical Care or Chronic Condition customer (default:false) - birthday
- the member’s birthday - for residential members, this is their security question returned in the format (
YYYY-MM-DDT00:00:00Z) - esg_customer_token
- the customer token for ESG reference - Key returned with a null value
- secondary_acct_holder
- the secondary contact person on the member’s account - Key returned with a null value
{
"userID": "06...90",
}
{
"Members": [
{
"userID": "970",
"memberID": "69a...12b",
"first_name": "Jason",
"last_name": "Rudder",
"address":
{
"street_address": "123 Moorefield Rd",
"city": "Palmview",
"state": "TX",
"country": "usa",
"postal_code": "78572"
},
"profile_pic_url": "https: //profilepicurl.com",
"current_balance_dollars": "",
"est_top_off_date": "",
"recharge_dollars": "49",
"notify_price_alert": true,
"notify_refill": true,
"created_date": "2017-01-27T21:09:44Z",
"fee": "0.49",
"language": "en",
"critical_care": false,
"birthday": "1976-06-14T00:00:00Z",
"esg_customer_token": ""
"secondary_account_holder": null
}...],
}
/members/list
Get a list of members and member data.[NOT USED]
Request
The ListRequest message is empty. Will return all the members and all the data.
Response
A successful response will return a huge list of member data.
Parameters
- userID
- the member’s user ID
- memberID:
- the member’s ID
- first_name
- the member’s first name, or forename
- last_name
- the member’s last name, or surname
- address
- the member’s service address
- profile_pic_url
- the image url where the member’s profile pic is located
- current_bal_dollars
- the member’s current account balance in dollars - Key returned with a null value
- est_top_off_date
- the estimated day the member’s account will be recharged - Key returned with a null value
- recharge_dollars
- the amount of dollars the member’s account will be recharged when their account balance falls below the threshold - (default:
$49) - notify_price_alert
- will show
trueif the member has opt’d in for price alert push notifications orfalseif the member has opt’d out of price alert push notifications - (default:true) - notify_refill
- will show
trueif the member has opt’d in for refill alert push notifications orfalseif the member has opt’d out of refill alert push notifications - (default:false) - created_date
- the date the member’s account has been created
- fee
- the daily portion of monthly membership rate - (default:
0.49) - language
- the language preference of the member - (default:
en) - critical_care
- set to
falsewhen the member has acknowledged the critical care statement in enrollment - confirming that no one at the residence is designated as a Critical Care or Chronic Condition customer (default:false) - birthday
- the member’s birthday - for residential members, this is their security question returned in the format (
YYYY-MM-DDT00:00:00Z) - esg_customer_token
- the customer token for ESG reference - Key returned with a null value
- secondary_acct_holder
- the secondary contact person on the member’s account - Key returned with a null value
{
//the proto shows there is nothing in this message
ListRequest {}
}
{
"Members": [
{
"userID": "970",
"memberID": "69a...12b",
"first_name": "Jason",
"last_name": "Rudder",
"address":
{
"street_address": "123 Moorefield Rd",
"city": "Palmview",
"state": "TX",
"country": "usa",
"postal_code": "78572"
},
"profile_pic_url": "https: //profilepicurl.com",
"current_balance_dollars": "",
"est_top_off_date": "",
"recharge_dollars": "49",
"notify_price_alert": true,
"notify_refill": true,
"created_date": "2017-01-27T21:09:44Z",
"fee": "0.49",
"language": "en",
"critical_care": false,
"birthday": "1976-06-14T00:00:00Z",
"esg_customer_token": ""
"secondary_account_holder": null
}...],
}
/members/get_me
Get a member's data to display in their client instance.[NOT USED]
Request
The request will return data on a specified userID or memberID. The request is to populate a member’s client with their memberID data.
to get member data, use memberID or userID - but not both.
Parameters
- memberID required
- the member ID
- userID required
- the user’s ID
Response
A successful response will return all member data for a specific userID or memberID.
Parameters
- userID
- the member’s user ID
- memberID:
- the member’s ID
- first_name
- the member’s first name, or forename
- last_name
- the member’s last name, or surname
- address
- the member’s service address
- profile_pic_url
- the image url where the member’s profile pic is located
- current_bal_dollars
- the member’s current account balance in dollars - Key returned with a null value
- est_top_off_date
- the estimated day the member’s account will be recharged - Key returned with a null value
- recharge_dollars
- the amount of dollars the member’s account will be recharged when their account balance falls below the threshold - (default:
$49) - notify_price_alert
- will show
trueif the member has opt’d in for price alert push notifications orfalseif the member has opt’d out of price alert push notifications - (default:true) - notify_refill
- will show
trueif the member has opt’d in for refill alert push notifications orfalseif the member has opt’d out of refill alert push notifications - (default:false) - created_date
- the date the member’s account has been created Auto generated based on local time format
(
YYYY-MM-DDT00:00:00Z) - fee
- the daily portion of monthly membership rate - (default:
0.49) - language
- the language preference of the member - (default:
en) - critical_care
- set to
falsewhen the member has acknowledged the critical care statement in enrollment - confirming that no one at the residence is designated as a Critical Care or Chronic Condition customer (default:false) - birthday
- the member’s birthday - for residential members, this is their security question returned in the format
(
YYYY-MM-DDT00:00:00Z) - esg_customer_token
- the customer token for ESG reference - Key returned with a null value
- secondary_acct_holder
- the secondary contact person on the member’s account - Key returned with a null value
{
"userID": "970..8"
}
{
"Members": [
{
"userID": "970..8",
"memberID": "69a...12b",
"first_name": "Jason",
"last_name": "Rudder",
"address":
{
"street_address": "123 Moorefield Rd",
"city": "Palmview",
"state": "TX",
"country": "usa",
"postal_code": "78572"
},
"profile_pic_url": "https: //profilepicurl.com",
"current_balance_dollars": "",
"est_top_off_date": "",
"recharge_dollars": "49",
"notify_price_alert": true,
"notify_refill": true,
"created_date": "2017-01-27T21:09:44Z",
"fee": "0.49",
"language": "en",
"critical_care": false,
"birthday": "1976-06-14T00:00:00Z",
"esg_customer_token": ""
"secondary_account_holder": null
}...],
}
/members/search
Get all Members where the fields are matched
Request
Search for member data.
Parameters
- first_name required
- member’s first name, or forename
- last_name required
- member’s last name, or surname
- userID optional
- the member’s user ID
- memberID: optional
- the member’s ID
Response
A successful response will return all members where the fields matched
Parameters
- userID
- the member’s user ID
- memberID
- the member’s ID
- first_name
- the member’s first name, or forename
- last_name
- the member’s last name, or surname
- address
- the member’s service address
- profile_pic_url
- the image url where the member’s profile pic is located
- current_bal_dollars
- the member’s current account balance in dollars - Key returned with a null value
- est_top_off_date
- the estimated day the member’s account will be recharged - Key returned with a null value
- recharge_dollars
- the amount of dollars the member’s account will be recharged when their account balance falls below the threshold - (default:
$49) - notify_price_alert
- will show
trueif the member has opt’d in for price alert push notifications orfalseif the member has opt’d out of price alert push notifications - (default:true) - notify_refill
- will show
trueif the member has opt’d in for refill alert push notifications orfalseif the member has opt’d out of refill alert push notifications - (default:false) - created_date
- the date the member’s account has been created
- fee
- the daily portion of monthly membership rate - (default:
0.49) - language
- the language preference of the member - (default:
en) - critical_care
- set to
falsewhen the member has acknowledged the critical care statement in enrollment - confirming that no one at the residence is designated as a Critical Care or Chronic Condition customer (default:false) - birthday
- the member’s birthday - for residential members, this is their security question returned in the format (
YYYY-MM-DDT00:00:00Z) - esg_customer_token
- the customer token for ESG reference - Key returned with a null value
- secondary_acct_holder
- the secondary contact person on the member’s account - Key returned with a null value
{
"first_name": "Jane",
"last_name": "Doe"
}
{
"Members": [
{
"userID": "970",
"memberID": "69a...12b",
"first_name": "Jane",
"last_name": "Doe",
"address":
{
"street_address": "123 Moorefield Rd",
"city": "Palmview",
"state": "TX",
"country": "usa",
"postal_code": "78572"
},
"profile_pic_url": "https: //profilepicurl.com",
"current_balance_dollars": "",
"est_top_off_date": "",
"recharge_dollars": "49",
"notify_price_alert": true,
"notify_refill": true,
"created_date": "2017-01-27T21:09:44Z",
"fee": "0.49",
"language": "en",
"critical_care": false,
"birthday": "1976-06-14T00:00:00Z",
"esg_customer_token": ""
"secondary_account_holder": null
}...],
}
/members/status
Get status on member's data.
Request
Parameters
- userID required
- the user’s ID
Response
Responds in a series of bools either confirming or identifying the presence of that data - will respond true if data exists and false if data does not exist
Parameters
- name
- the member’s name
- address
- the member’s service address
- birthday
- the birthday or security question
- billing_enroll
- the member completed billing in enrollment
- recharge_settings
- the member updated their recharge settings
- agreement
- the member acknowledged the member agreement in enrollment
- payment_enroll
- the member completed payment in enrollment
- payment_card
- the member has a payment card on their account
- meter
- the member has an active meter on their account
- billng_has_funds
- the member has funds in their account
- billing_has_funds
- the member has funds in their account
{
"userID": "0a6...f0x",
}
{
"members": [{
"name": true,
"address": true,
"birthday": true,
"billing_enroll": true,
"recharge_settings": false,
"agreement": true,
"payment_enroll": true,
"payment_card": true,
"meter": true,
"billing_has_funds": true,
}...],
}
/members/update
Update a member's data.
Request
Update a member’s account with requested data.
Parameters
- userID required
- the member’s user ID
- memberID required
- the member’s ID
- first_name
- the member’s first name, or forename
- last_name
- the member’s last name, or surname
- address
- the member’s service address
- profile_pic_url
- the image url where the member’s profile pic is located
- recharge_dollars
- the amount of dollars the member’s account will be recharged when their account balance falls below the threshold
- notify_price_alert
- will show
trueif the member has opt’d in for price alert push notifications orfalseif the member has opt’d out of price alert push notifications - notify_refill
- will show
trueif the member has opt’d in for refill alert push notifications orfalseif the member has opt’d out of refill alert push notifications - created_date
- the date the member’s account has been created
- fee
- the daily portion of monthly membership rate
- language
- the language preference of the member
- critical_care
- set to
falsewhen the member has acknowledged the critical care statement in enrollment - confirming that no one at the residence is designated as a Critical Care or Chronic Condition customer - birthday
- the member’s birthday - for residential members, this is their security question
- esg_customer_token
- the customer token for ESG reference
- secondary_acct_holder
- the secondary contact person on the member’s account - Key returned with a null value
Response
A successful response will return all member data for a specific userID or memberID.
Parameters
- success
- responds if the update to members data was successful if
trueis returned or failed iffalseis returned
{
"userID": "970",
"memberID": "69a...12b",
"first_name": "Jason",
"last_name": "Rudder",
"address":
{
"street_address": "123 Moorefield Rd",
"city": "Palmview",
"state": "TX",
"country": "USA",
"postal_code": "78572"
},
"profile_pic_url": "https: //profilepicurl.com",
"current_balance_dollars": "",
"est_top_off_date": "",
"recharge_dollars": "49",
"notify_price_alert": true,
"notify_refill": true,
"created_date": "2017-01-27T21:09:44Z",
"fee": "0.49",
"language": "en",
"critical_care": false,
"birthday": "1976-06-14T00:00:00Z",
"esg_customer_token": ""
"secondary_account_holder": null
}
{
"success": true,
}
Meter
/meter/active_meters_report
Get the total number of active meters enrolled with Griddy. This requires an admin access token.
Request
The message in the ActiveMetersReportRequest is empty.
Response
Response will return the total number of active meters.
Parameters
- number_of_meters
- the number of active meters
{
}
{
"number_of_meters": "4494",
}
/meter/get_active_by_day
Get the total number of active meters on flow with Griddy on a operating day. This requires an admin access token.
Request
Call this to get meters that went on flow on a operating day
Parameters
- days required
- operating day on flow meters to be returned for ie to see all meters that went on flow 1 day ago enter
1
Response
Response will return the following;
Parameters
- meterID
- ESI ID of the meter
- memberID
- ID of the member associated with the meter
- settlement_point
- the sub-region within a load zone, but also refers to the load zone
- status
- status of the meter is returned with an
effective_dateand thestatusofconnected,disconnected,pending_connectionorpending_disconnection - service_address
- the service address for the meter
- enrollment_date
- the date the enrollment was completed; this is different from
start_datewhen the meter service begins or is on flow - start_date
- the date service started
- end_date
- the date service ended
- ID
- the member’s user ID
- meta_data
- many strings of data
- duns_number
- the DUNS number of the corresponding TDSP
- griddy_rate_class
- states whether the meter is classified as commercial/business or residential/home
- esg_meter_token
- the meter token assigned by ESG during the enrollment process
- enrollMode
- states whether the enrollment was a “switch” or a “movein”
- requested_start_date
- the date the member requested to be on flow with Griddy
- rate_class
- declares the POLR rate class of residential, small non-residential, medium non-residential, etc.
- tier_name
- indicates which tier the meter falls into based on average monthly usage for business - residential has only one tier
- membership_rate
- the monthly rate the member pays for their Griddy membership
- utility_rates
- the flat rate per month and volumetric rate per kWh that the TDSP charges for delivery
- polr_customer_class
- declares the POLR rate class of residential, small non-residential, medium non-residential, etc.
- load_profile
- null value
- tier:pending
- boolean value returns
trueif tier is pending otherwisefalse
{
"days": ""
}
{
"meters": [
{
"meterID": "1008901020900404380110",
"memberID": "ac9de492-8575-44db-8c24-eefe2d840170",
"settlement_point": "LZ_HOUSTON",
"status":
{
"status": "connected",
"effective_date": "2019-04-27T00:00:41Z"
},
"service_address": null,
"enrollment_date": "2019-03-15T14:26:36Z",
"start_date": "2019-04-27T00:00:00Z",
"end_date": "",
"ID": "17469",
"meta_data": {},
"duns_number": "957877905",
"griddy_rate_class": "residential",
"esg_meter_token": "",
"enrollMode": "switch",
"requested_start_date": "2019-04-27",
"rate_class": "residential",
"tier_name": "residential",
"membership_rate": "9.99",
"utility_rates":
{
"per_kwh": "0.00000000",
"monthly": "0.00000000"
},
"polr_customer_class": "residential",
"load_profile": "",
"tier_pending": true
},
{
"meterID": "1008901023815688330104",
"memberID": "3ccfaf2d-721c-4d17-b454-b592d1e41b7c",
"settlement_point": "LZ_HOUSTON",
"status":
{
"status": "connected",
"effective_date": "2019-04-27T00:00:41Z"
},
"service_address": null,
"enrollment_date": "2019-03-14T18:05:53Z",
"start_date": "2019-04-27T00:00:00Z",
"end_date": "",
"ID": "17413",
"meta_data": {},
"duns_number": "957877905",
"griddy_rate_class": "residential",
"esg_meter_token": "",
"enrollMode": "switch",
"requested_start_date": "2019-04-27",
"rate_class": "residential",
"tier_name": "residential",
"membership_rate": "9.99",
"utility_rates":
{
"per_kwh": "0.00000000",
"monthly": "0.00000000"
},
"polr_customer_class": "residential",
"load_profile": "",
"tier_pending": true
}
]
}
/meter/get_amu
Get a business member's average monthly usage. This requires an admin access token.
Request
Parameters
- ID required
- ID of the commercial meter that has a manually set average monthly usage amount (this is not the ESI ID)
Response
Response will return the average monthly usage for a member.
Parameters
- ID
- ID of the commercial meter record (this is not the ESI ID)
- amu
- the member’s average monthly usage
- created_date
- the date the member was created
{
"ID": "5555",
}
{
"ID": "5555",
"amu": "4598",
"created_date": "2017-01-03 16:32:11.412505 +0000 +0000",
}
/meter/get_meter
Get data about a specific meter or meters. This requires an admin access token.
Request
Parameters
- meterID
- ESI ID of the meter in question
- memberID
- ID of the member associated with the meter
- include_inactive
- include inactive meters with
trueor exclude withfalse - without_address
- include meters without addresses with
trueor exclude withfalse - all_statuses
- include meters of inactive statuses with
trueor exclude withfalse; must be used with eithermeterID,memberID, orID - ID
- meter ID of the meter you want to search
Response
Response will confirm the meterID and that meter’s status.
Parameters
- meterID
- ESI ID of the meter
- memberID
- ID of the member associated with the meter
- settlement_point
- the sub-region within a load zone, but also refers to the load zone
- status
- status of the meter is returned with an
effective_dateand thestatusofconnected,disconnected,pending_connectionorpending_disconnection - service_address
- the service address for the meter
- enrollment_date
- the date the enrollment was completed; this is different from
start_datewhen the meter service begins or is on flow - start_date
- the date service started
- end_date
- the date service ended
- ID
- the member’s user ID
- meta_data
- many strings of data
- duns_number
- the DUNS number of the corresponding TDSP
- griddy_rate_class
- states whether the meter is classified as commercial/business or residential/home
- esg_meter_token
- the meter token assigned by ESG during the enrollment process
- enrollMode
- states whether the enrollment was a “switch” or a “movein”
- requested_start_date
- the date the member requested to be on flow with Griddy
- rate_class
- declares the POLR rate class of residential, small non-residential, medium non-residential, etc.
- tier_name
- indicates which tier the meter falls into based on average monthly usage for business - residential has only one tier
- membership_rate
- the monthly rate the member pays for their Griddy membership
- utility_rates
- the flat rate per month and volumetric rate per kWh that the TDSP charges for delivery
- polr_customer_class
- declares the POLR rate class of residential, small non-residential, medium non-residential, etc.
{
"meterID": "102..770",
"memberID": "0c3...d64",
"date": "2017-01-03T01:30:00Z",
"include_inactive": false,
"without_address": false,
"all_statuses": true,
"ID": "3541346",
}
{
"meters": [
{
"meterID": "102..770",
"memberID": "0c3...d64",
"settlement_point": "LZ_HOUSTON",
"status": {
"status": "connected",
"effective_date": "2018-04-30T22:14:47Z",
},
"service_address": {
"name": ""
"lineOne": "123 Main st",
"lineTwo": "#915",
"city": "Anytown",
"state": "TX",
"postalCode": "77017"
"country": "USA",
"postalCode4": "4566",
"time_zone_name": "America/Chicago",
"county": "Magic County"
},
"enrollment_date": "2017-01-03T01:30:00Z",
"start_date": "2017-01-03T01:30:00Z",
"end_date": "2017-01-03T01:30:00Z",
"ID": "121332",
"meta_data": {
"griddy_rate_class": "residential",
"somekey": "somevalue",
"anotherkey": "anothervalue"
},
"duns_number": "1039940674000",
"griddy_rate_class": "residential",
"esg_meter_token": "0a8df488ds",
"enrollMode": "movein",
"requested_start_date": "2017-01-03",
"rate_class": "residential",
"tier_name": "residential",
"membership_rate": "9.99",
"utility_rates": {
"per_kwh": "0.00000000",
"monthly": "0.00000000"
},
"polr_customer_class": "residential",
"load_profile": "",
"tier_pending": true
},
],
"total": "25",
"has_next": false,
"page": "1",
"next": "2",
"limit": "15",
}
/meter/griddy_rate_classes
Get Griddy rate class data for a commercial member or meter.
Request
The message for GetGriddyRateClassRequest is empty.
Response
Response will return nested object within griddy_rate_class with the data…
Parameters
- ID
- the internal ID used to map each tier
- rate_class
- the rate class for that meter
- tier_name
- the name of the tier the member/meter qualifies for based on average monthly usage
- min_usage
- the minimum kWh usage in that tier’s range
- max_usage
- the maximum kWh usage in that tier’s range
- membership_rate
- the monthly price the member pays to use the Griddy app
{
}
{
"griddy_rate_class": [
{
"ID": "2",
"rate_class": "commercial",
"tier_name": "tier 1",
"min_usage": "0",
"max_usage": "5000",
"membership_rate": "9.99"
},
{
"ID": "3",
"rate_class": "commercial",
"tier_name": "tier 2",
"min_usage": "5000",
"max_usage": "15000",
"membership_rate": "99.0"
}...]
}
/meter/list
Get data about a specific meter or meters. This requires an admin access token.
Request
Parameters
- filters required
- filter the meter list results with one or more of the following
nameandvalues:- status (meter status):
connected,disconnected,pending_connection, orpending_disconnection - settlement_point: the sub-region within a load zone, but also refers to the load zone; must be in all caps
- duns_number: the DUNS number of the TDSP
- operating_day: operating date as it relates to each meter’s start and end dates
- status (meter status):
- limit
- limit the number of returned meters
- page
- limit the number of pages of the returned data
- without_address
- include meters without addresses with
true, else usefalse
Response
Response will return get_meter response
Parameters
- meterID
- ESI ID of the meter
- memberID
- ID of the member associated with the meter
- settlement_point
- : the sub-region within a load zone, but also refers to the load zone
- status
- status of the meter is returned with an
effective_dateand thestatusofconnected,disconnected,pending_connectionorpending_disconnection - service_address
- the service address for the meter
- enrollment_date
- the date the enrollment was completed; this is different from
start_datewhen the meter service begins or is on flow - start_date
- the date service started
- end_date
- the date service ended
- ID
- the member’s user ID
- meta_data
- many strings of data
- duns_number
- the DUNS number of the corresponding TDSP
- griddy_rate_class
- states whether the meter is classified as commercial/business or residential/home
- esg_meter_token
- the meter token assigned by ESG during the enrollment process
- enrollMode
- states whether the enrollment was a “switch” or a “movein”
- requested_start_date
- the date the member requested to be on flow with Griddy
- rate_class
- declares the POLR rate class of residential, small non-residential, medium non-residential, etc.
- tier_name
- indicates which tier the meter falls into based on average monthly usage for business - residential has only one tier
- membership_rate
- the monthly rate the member pays for their Griddy membership
- utility_rates
- the flat rate per month and volumetric rate per kWh that the TDSP charges for delivery
- polr_customer_class
- declares the POLR rate class of residential, small non-residential, medium non-residential, etc.
{
"filters": [
{
"name": "operating_day",
"values": [
"2018-03-31T00:00:00-05:00",
]
},
{
"name": "status",
"values": [
"connected"
]
},
{
"name": "settlement_point",
"values": [
"LZ_HOUSTON"
]
}...],
"limit": "15",
"page": "1",
"without_address": false,
}
{
"meters": [
{
"meterID": "102..770",
"memberID": "0c3...d64",
"settlement_point": "LZ_HOUSTON",
"status": {
"status": "connected",
"effective_date": "2018-04-30T15:40:45Z",
},
"service_address": {
"name": "Doe, Jane"
"lineOne": "123 Main st",
"lineTwo": "#915",
"city": "Anytown",
"state": "TX",
"postalCode": "77017"
"country": "USA",
"postalCode4": "4566",
"time_zone_name": "cst",
"county": "Magic County"
},
"enrollment_date": "2017-01-03T01:30:00Z",
"start_date": "2017-01-03T01:30:00Z",
"end_date": "2017-01-03T01:30:00Z",
"ID": "121332",
"meta_data": {
"griddy_rate_class": "residential",
"somekey": "somevalue",
"anotherkey": "anothervalue"
},
"duns_number": "1039940674000",
"griddy_rate_class": "residential",
"esg_meter_token": "0a8df488ds",
"enrollMode": "movein",
"requested_start_date": "2017-01-03",
"rate_class": "residential",
"tier_name": "residential",
"membership_rate": "9.99",
"utility_rates": {
"per_kwh": "0.00000000",
"monthly": "0.00000000"
},
"polr_customer_class": "residential",
"load_profile": "",
"tier_pending": true
}
],
"total": "25",
"has_next": false,
"page": "1",
"next": "2",
"limit": "15",
}
/meter/meters
Register a meter.
Request
Call this to add a meter with the ID returned from /meterLookup/search.
Parameters
- meterID required
- ID of the meter to add
- memberID required
- ID of the member adding the meter
- service_address required
- the address of the location where the member desires service
- enrollMode required
- member indicates if the request is either a “switch” or a “movein”
- requestedStartDate required
- the date the member is requesting electricity service to begin - this is required if
enrollMode=movein
Response
Response returns a bool indicating the success or failure of a meter registration request
Parameters
- success
- returns
trueif meter was successfully registered andfalseif the request failed
{
"meterID": "102..770",
"memberID": "0c3...d64",
"service_address": [{
"name": "Doe, Jane"
"lineOne": "123 main st",
"lineTwo": "#915",
"city": "anytown",
"state": "tx",
"postal_code": "77017"
"country": "USA",
"postalCode4": "4566",
"time_zone_name": "cst",
"county": "magic town"
}...],
"enrollMode": "switch",
"requestedStartDate": "2018-04-30"
}
{
"success": true,
}
/meter/remove_grc_override
Remove an override to a business member's monthly membership price. This requires an admin access token.
Request
Parameters
- ID required
- ID of the commercial meter record to update (this is not the ESI ID)
Response
Response will return a success response.
Parameters
- success
- returns
trueif override was successfully removed andfalseif the request failed
{
"ID": "1234567",
}
{
"success": "true",
}
/meter/set_amu
Set a business member's average monthly usage. This requires an admin access token.
Request
Parameters
- ID required
- ID of the commercial meter record to update (this is not the ESI ID)
- amu required
- the member’s average monthly usage
Response
Response will return a success response.
Parameters
- success
- returns
trueif the Griddy rate class was successfully set to the member andfalseif the request failed
{
"ID": "1234567",
"amu": "10834",
}
{
"success": "true",
}
/meter/set_commercial_tdsp_rates
Set a business member's tdsp rates. This requires an admin access token.
Request
Parameters
- meterID required
- ESI ID of the meter
- rates required
- per_kwh rate and monthly rate to be set
Response
Response will return a success response.
Parameters
- success
- returns
trueif the tdsp rates were successfully set to the meter andfalseif the request failed
{
"meterID": "10443720007500002",
"rates":
{
"per_kwh": "0.12",
"monthly": "0.11"
}
}
{
"success": "true",
}
/meter/set_grc_internal
This is a private endpoint for setting the GriddyRateClass ID on the meter record.
Request
This endpoint uses the amu to assign a Griddy rate class to business members
Parameters
- ID required
- ID of the commercial meter record to update (this is not the ESI ID)
- grcID required
- the Griddy rate class ID
Response
Response will return a success response.
Parameters
- success
- returns
trueif the Griddy rate class was successfully set andfalseif the request failed
{
"ID": "1234567",
"grcID": "2342",
}
{
"success": "true",
}
/meter/set_grc_override
Set an override to a business member's monthly membership price. This requires an admin access token.
Request
Parameters
- ID required
- ID of the commercial meter record to update (this is not the ESI ID)
- grc_override required
- the new monthly membership price for the override
Response
Response will return a success response.
Parameters
- success
- returns
trueif override was successfully added andfalseif the request failed
{
"ID": "1234567",
"grc_override": "599",
}
{
"success": "true",
}
/meter/set_load_profile
Set a meters' load profile. This requires an admin access token.
Request
Parameters
- load_profile required
- code assigned by ERCOT to each meter depending on their usage behavior
- esiID required
- ID of the meter
- start_date optional
- effective date of the load profile set
- end_date optional
- date the set load profile ends
- market_ID optional
- ID assigned to each market
Response
Response will return a success response.
Parameters
- success
- returns
trueif the load profile was successfully set to the meter andfalseif the request failed
{
"load_profile": "RESHIWR_COAST_IDR_WS_NOTOU",
"esiID": "10443720007500002",
"start_date": "",
"end_date": "",
"marketID": ""
}
{
"success": "true",
}
/meter/set_tax_exemption
Set a meter for specific tax exemption. This requires an admin access token.
Request
Parameters
- meterID required
- ESI ID of the meter
- exemption_code required
- code number for a specific tax to be exempted
Response
Response will return a success response.
Parameters
- success
- returns
trueif the tax exemption was successfully set to the meter andfalseif the request failed
{
"meterID": "10443720007500002",
"exemption_code": "14"
}
{
"success": "true",
}
/meter/update
Update a meter's status using the start and end dates. This requires an admin access token.
Request
Requests must contain the meter ID and a set of any following start and end date parameters (i.e. start_date or null_start_date cannot be present without either end_date or null_end_date):
- start_date
- end_date
- null_start_date
- null_end_date
If null_start_date = true is set, start_date should not be set.
Similarly, if null_end_date = true is set, end_date should not be set.
Parameters
- ID required
- ID of the meter record to update (this is not the ESI ID)
- start_date
- the start date of service; must be in RFC3339 format (2019-01-01T00:00:00Z)
- end_date
- the end date of service; must be in RFC3339 format (2019-01-31T00:00:00Z)
- esg_meter_token
- the token assigned by ESG to the meter - this is mainly here for ESG integration purposes and should not be set by front-end client calls
- null_start_date
- sets start date to null if set to
true - null_end_date
- sets end date to null if set to
true - send_notifications
- Notify the user about these changes.
Response
Response will return a success response.
Parameters
- success
- returns
trueif the meter was successfully updated andfalseif the request failed
{
"ID": "1234567",
"start_date": "2017-01-03T01:30:00Z",
"end_date": "2017-01-03T01:30:00Z",
"send_notifications": true
}
{
"success": "true",
}
/meter/update_grc
Update a member's Griddy rate class. This requires an admin access token.
Request
Parameters
- ID required
- ID of the commercial meter record to update (this is not the ESI ID)
- amu required
- the member’s average monthly usage
Response
Response will return a success response.
Parameters
- success
- returns
trueif the Griddy rate class was successfully updated andfalseif the request failed
{
"ID": "1234567",
"amu": "10834",
}
{
"success": "true",
}
/meter/weather_forecast
Get weather forecast by meter's record ID, localized when passed lang param (defaults to English).
Request
Parameters
- ID required
- record ID of the meter (not esiID)
- lang
- preferred language - e.g. “es” for Spanish
Response
Response will return weather_forecast response
Parameters
- latitude
- latitude of the meter
- longitude
- longitude of the meter
- timezone
- timezone of the meter, e.g. “America/Chicago”
- currently
- current weather conditions:
time,summary,icon,temperature. - hourly
summaryandiconfor the day,data: an hour-by-hour forecast for the next 48 hours.- daily
summaryandiconfor the week,data: a day-by-day forecast for the next week.- darkskyUnavailable
trueif DarkSky is unable to provide a forecast likely due to a temporary error / outage
{
"ID": "888",
"lang": "en",
}
{
"latitude": 29.772627,
"longitude": -95.40319,
"timezone": "America/Chicago",
"currently": {
"time": "1580929912",
"summary": "Overcast",
"icon": "cloudy",
"temperature": 45.12
},
"hourly": {
"summary": "Partly cloudy throughout the day.",
"icon": "rain",
"data": [
{
"time": "1580929200",
"summary": "Overcast",
"icon": "cloudy",
"temperature": 44.67
},
<...>
]
},
"daily": {
"summary": "Light rain throughout the week.",
"icon": "rain",
"data": [
{
"time": "1580882400",
"summary": "Possible light rain in the morning.",
"icon": "rain",
"temperatureHigh": 51.87,
"temperatureLow": 37.58
},
<...>
]
},
"darkskyUnavailable": false
}
Meter Lookup
/meterLookup/get
Search for meter data using the meter's ESI ID
Request
Parameters
- esiID
- the ESI of the meter to lookup
Response
Parameters
- esi
- the ESI of the meter to lookup
- address
- the address of the meter
- duns
- DUNS of the TDSP that manages the meter
- meter_read_cycle
- determines each billing cycle’s start and end dates based on a meter reading schedule set by the TDSP
- status
- the meter’s current service status; can be
status_unknown,status_active,status_inactive, orstatus_deenergized - premise
- the meter’s premise type; can be residential, small non-residential, medium non-residential, etc.
- power_region
- the area of the independent system operator (ISO) in which the meter resides
- station_code
- the identification code for the power station
- station_name
- the name of the station
- metered
- returns
yif metered ornif not metered - open_service_orders
- the number of open service orders for that meter
- polr_customer_class
- the POLR rate class for the meter
- supported_meter
- responds with
trueif Griddy supports that meter type, orfalseif it is not a supported meter type - tdsp_ams_indicator
- the meter type; one of
amsm,amsr, or empty string - switch_hold
- returns
trueif the meter has a switch hold andfalseif it does not have a switch hold - load_zone
- the load zone for the meter
- griddy_rate_class
- will identify the meter as residential or commercial
{
"esiID": "12345678901234567",
}
{
"esi": "1008901023815770490105",
"address": {
"line1": "123 MAIN ST",
"line2": "#915",
"city": "ANYTOWN",
"state": "TX",
"postal_code": "76871",
"country": "USA",
"postal_code_four": "5461"
},
"duns": "1052623364500",
"meter_read_cycle": "15",
"status": "status_inactive",
"premise": "premise_residential",
"power_region": "region_ercot",
"station_code": "stationCode",
"station_name": "stationName",
"metered": "y",
"open_service_orders": "",
"polr_customer_class": "residential",
"supported_meter": false,
"tdsp_ams_indicator": "amsr",
"switch_hold": false,
"load_zone": "LZ_NORTH",
"griddy_rate_class": "residential"
}
/meterLookup/search
Search ERCOT's public meter information for the given address.
Request
To find a meter, provide the address.
Parameters
- line1 required
- the street address
- line2 optional
- the apartment or suite number
- city
- the city
- state
- the state
- postal_code required
- the postal code
- country
- the country
- postal_code_four
- the four digits that follow the 5 digit zip code
Response
Response returns meter data.
Parameters
- esi
- the meter’s ESI ID
- address
- returns the address information for the meter (same as the request)
- supported_meter
- returns
trueif the meter is one supported by Griddy, or returnsfalseif the meter is not supported - griddy_rate_class
- will identify the meter as
residentialorcommercial
{
"line1": "500 EAST COYOTE TRAIL",
"line2": "",
"city": "RICHLAND SPRINGS",
"state": "TX",
"postal_code": "76871"
"country": "USA"
"postal_code_four": ""
}
{
"meters": [],
"supported_geography": false
}
{
"meters": [
{
"esi": "10443720001469977",
"address": {
"line1": "500 EAST COYOTE TRAIL",
"line2": "",
"city": "RICHLAND SPRINGS",
"state": "TX",
"postal_code": "76871",
"country": "USA",
"postal_code_four": ""
},
"duns": "1039940674000",
"meter_read_cycle": "18",
"status": "status_active",
"premise": "premise_residential",
"power_region": "region_ercot",
"station_code": "richsp",
"station_name": "richland springs",
"metered": "y",
"open_service_orders": "",
"polr_customer_class": "residential",
"supported_meter": true,
"tdsp_ams_indicator": "amsr",
"switch_hold": false,
"load_zone": "",
"griddy_rate_class": "residential"
},
{
"esi": "10443720002885158",
"address": {
"line1": "100 EAST COYOTE TRAIL",
"line2": "",
"city": "RICHLAND SPRINGS",
"state": "TX",
"postal_code": "76871",
"country": "USA",
"postal_code_four": "2035"
},
"duns": "1039940674000",
"meter_read_cycle": "18",
"status": "status_deenergized",
"premise": "premise_residential",
"power_region": "region_ercot",
"station_code": "richsp",
"station_name": "richland springs",
"metered": "y",
"open_service_orders": "",
"polr_customer_class": "residential",
"supported_meter": false,
"tdsp_ams_indicator": "",
"switch_hold": false,
"load_zone": "",
"griddy_rate_class": "residential"
}...],
"supported_geography": true
}
Notifications
/notifications/action
This is a private endpoint used to determine the needed action?
Request
Parameters
- member
- the member to receive the push notification
- billing
- WHAT IS THIS?
- service
- WHAT IS THIS?
- action
- do we take some action?
- correlationID
- WHAT IS THIS?
- data
- data necessary to the request
Response
Response returns information on the push notification.
Parameters
- id
- notification ID
- doAction
- are we even sending a message?
- service
- WHAT IS THIS?
- action
- WHAT IS THIS?
- address
- where to send it e.g. email or phone number
- medium
- how are we sending the message? e.g. email, txt, in-app message
- templateID
- what template to use for the notification
- subject
- the subject of the message
- body
- the body of the message
- variables
- any number of variables related to the notification
- correlationID
- WHAT IS THIS?
- time
- the time of the notification? or the time stamp? IS THAT RIGHT?
{
"member": 123456,
"billing": someValue,
"service": "someService",
"action": "someAction",
"correlationID": "someCorrelationID",
"data": {
"somekey": "someData",
"anotherkey": "moreData",
}
}
{
"notification": [{
"id": "1234",
"doAction": true,
"service": "someService",
"action": "someAction",
"address": "213-312-1213",
"medium": "pushNotification",
"templateID": "someTemplate",
"subject": "subjectTitle",
"body": "someBody",
"variables": {
"somekey": "someVariable",
"anotherkey": "anotherVariable"
}
"correlationID": "654321",
"time": "06:45:34",
}...]
}
/notifications/get
Get a notification. This endpoint is currently not in use.
Request
Parameters
- notificationID
- the ID for the notification to be sent IS THAT RIGHT?
Response
Response returns information on the push notification.
Parameters
- id
- notification ID
- doAction
- are we even sending a message?
- service
- WHAT IS THIS?
- action
- WHAT IS THIS?
- address
- where to send it e.g. email or phone number
- medium
- how are we sending the message? e.g. email, txt, in-app message
- templateID
- what template to use for the notification
- subject
- the subject of the message
- body
- the body of the message
- variables
- any number of variables related to the notification
- correlationID
- WHAT IS THIS?
- time
- the time of the notification? or the time stamp? IS THAT RIGHT?
{
"notificationID": "1234567",
}
{
"notifications": [{
"id": "1234",
"doAction": true,
"service": "someService",
"action": "someAction",
"address": "213-312-1213",
"medium": "pushNotification",
"templateID": "someTemplate",
"subject": "subjectTitle",
"body": "someBody",
"variables": {
"somekey": "someVariable",
"anotherkey": "anotherVariable"
}
"correlationID": "654321",
"time": "06:45:34",
}...]
}
/notifications/list
Get list of notifications. This endpoint is currently not in use.
Request
Parameters
- memberID
- the member ID
Response
Response returns information on the push notification.
Parameters
- id
- notification ID
- doAction
- are we even sending a message?
- service
- WHAT IS THIS?
- action
- WHAT IS THIS?
- address
- where to send it e.g. email or phone number
- medium
- how are we sending the message? e.g. email, txt, in-app message
- templateID
- what template to use for the notification
- subject
- the subject of the message
- body
- the body of the message
- variables
- any number of variables related to the notification
- correlationID
- WHAT IS THIS?
- time
- the time of the notification? or the time stamp? IS THAT RIGHT?
{
"memberID": "123456",
}
{
"notifications": [{
"id": "1234",
"doAction": true,
"service": "someService",
"action": "someAction",
"address": "213-312-1213",
"medium": "pushNotification",
"templateID": "someTemplate",
"subject": "subjectTitle",
"body": "someBody",
"variables": {
"somekey": "someVariable",
"anotherkey": "anotherVariable"
}
"correlationID": "654321",
"time": "06:45:34",
}...]
}
Payment
/payment/add_card
Add a credit or debit card
Request
After enrolling for payments, you may add a card.
Parameters
- memberID required
- the ID of the member being enrolled
- stripeToken required
- the token retrieved using Stripe.js
- is_default optional
truesets the new payment card as the default payment method,falsemakes no changes to the default payment method- replace_default optional
truereplaces the current default card with the new card being added,falsemakes no changes to the default card
Response
The response confirms the card was added
Parameters
- result
- confirms the the card was added and provides a success bool
- customerID
- the ID of the customer being charged
- cardID
- the cardID for the new card added to the account
{
"memberID": "b045...bf6",
"stripeToken": "tok_1B3r...Cfh1Q",
"is_default": true,
"replace_default": false,
"replace": "replaceCard"
}
{
"result": {
"customerID": "328978ds89ds898sf8",
"cardID": "327887",
"memberID": "b045...bf6",
"isSuccess": true,
}
"cardID": "card_1EFVMKBsCMNUt497GCFciGfy"
}
/payment/capture
Capture the charge made in `ChargeRequest` and generate a `chargeID`
Request
The request captures charges made to the member’s payment card
Parameters
- memberID required
- the member’s ID’
- authorized required
- the authorization process for the charge
Response
The response returns confirmation of success, a message, the cardID and the accrued fee
Parameters
- isSuccess
- the success message returns
trueif the charge was successful andfalseif the request failed - message
- a message may be returned in the ChargeResponse, it will show here
- fee
- the fee accrued for the credit card charge
- cardID
- the card ID for the payment card
{
"memberID": "b045...bf6",
"authorize": false,
}
{
"isSuccess": true,
"message": "anyMessage",
"fee": "2.50",
"cardID": "card_1EFVMKBsCMNUt497GCFciGfy",
}
/payment/charge
Charge a member's payment card through Stripe
Request
Important information for ChargeRequest… Authorize = true means charge later. Authorize = false means charge now. When authorize = true, capture the chargeID and then call CaptureChargeRequest with the chargeID and that charge.
Parameters
- memberID required
- the member ID for the member being charged
- authorized required
- the authorization process for the charge
- cardID required
- the card ID for the member’s payment card
- hashID required
- a unique ID used to prevent processing the same payment multiple times
Response
The response returns confirmation the charge was or was not successful, along with a message and the accruded fee for processing credit cards
Parameters
- chargeID
- the identification number for the charge request
- authorizeID
- the identification for the authorization of the charge
- isSuccess
- the success message returns
trueif the charge was successful andfalseif the request failed - message
- a message may be returned in the ChargeResponse, it will show here
- cardID
- the card ID for the payment card
- fee
- the fee accrued for the credit card charge
- cardLast4
- the last 4 digits of the payment card
- sourceFunding
- the card funding type. Can be
credit,debit,prepaid.
{
"memberID": "b045...bf6",
"amount": "49.00"
"authorize": true,
"cardID": "card_1EGBoZBsCMNUt497ek1SPjtc",
"hashID": "757...125",
}
{
"chargeID": "32897495",
"authorizedID": "ch_1EGBopBsCMNUt49790hRIreb",
"isSuccess": true,
"message": "anyMessage",
"cardID": "card_1EGBoZBsCMNUt497ek1SPjtc",
"fee": "",
"cardLast4": "4444",
"sourceFunding": "credit"
}
/payment/enroll
Establish payments with Stripe
Request
Before adding a card, you must enroll with payments.
Parameters
- memberID required
- ID of the member being enrolled
- phoneNumber optional
- the member’s phone number
- email required
- user’s email address associated with the member id being enrolled
Response
The response returns the result message confirming the payment data and a success message.
Parameters
- customerID
- the Stripe customer ID
- cardID
- the payment card ID
- memberID
- the member’s ID
- isSuccess
- the success message returns
trueif successful andfalseif the request failed
{
"memberID": "b045...bf6",
"emailAddress": "jane@example.com"
}
{
"result": [{
"customerID": "cus_EJs5qdR5pqMXVZ",
"cardID": "card_1EGBoJBsCMNUt497i5E9NLv3",
"memberID": "b045...bf6"
"isSuccess": true,
}...]
}
/payment/list_cards
Get a list of payment cards for a members account.
Request
Request to get a list of payment cards on a member’s account
Parameters
- memberID required
- the member’s ID
- emailAddress requierd
- the email associated with the member’s account
Response
The response returns a collection of data for each card listed on a member account
Parameters
- result
- returns the
customerID,cardID,memberIDand a success message inisSuccess - card
- data returned for the card or cards on a member’s account including card information and the billing address
- cvc_check
- is the CVC correct
- zip_check
- is the billing zip code correct
{
"memberID": "b045...bf6",
"emailAddress": "jane@jae.com"
}
{
"result":
{
"customerID": "cus_EJs5qdR5pqMXVZ",
"cardID": "card_1EGBoJBsCMNUt497i5E9NLv3",
"memberID": "b045...bf6"
"isSuccess": true,
}
"card" [
{
"cardID": "card_1EGBoJBsCMNUt497i5E9NLv3",
"cardType": "visa",
"lastFour": "9034",
"expirationMonth": "04",
"expirationYear": "2021",
"default": true,
"address": [
{
"lineOne": "3434 Street Ln",
"lineTwo": "apt 146",
"city": "Cityville",
"state": "stateoming",
"postalCode": "80091",
"country": "usa",
}...]
"cvc_check": "checkComplete",
"zip_check": "checkComplete",
"name": "Jane B. Doe",
}...]
}
/payment/list_charge
Get a list of charges made to a specific member's account in a specified time frame
Request
The request captures charges made to the member’s payment card
Parameters
- memberID required
- the member’s ID
- start_date required
- the authorization process for the charge
- end_date required
- the authorization process for the charge
Response
The response returns an object of charge data for each charge for a specified member in a specific time frame
Parameters
- memberID
- the member ID for the member being charged
- charges
- returns data for each charge including timestamps, failure messaging, and payment card details in the
CardInfomessage - amount
- the amount of the charge
- fee
- the fee accruded from the charge
- authorized
- returns
truefor if the charge was authorized andfalseif it was not authorized - refunded
- returns
trueif the member was refunded andfalseif no refund was issued - amount_refunded
- the total amount of the refund
- status
succeededif the charge went through andfailedif the charge failed
{
"memberID": "b045...bf6",
"start_date": "2017-01-03T01:30:00Z",
"end_date": "2017-01-03T01:30:00Z",
}
{
"memberID": "b045...bf6",
"charges": [{
"chargeID": "ch_1E67BGBsCMNUt497V8L3rVl0",
"captured": true,
"created": "2017-01-03T01:30:00Z",
"failed_code": "0",
"failed_message": "someMessage",
"card": [{
"cardID": "card_1DrELYBsCMNUt497KMgNwzGC",
"cardType": "visa",
"lastFour": "9034",
"expirationMonth": "04",
"expirationYear": "2021",
"default": true,
"address": [{
"lineOne": "3434 Street Ln",
"lineTwo": "apt 146",
"city": "Cityville",
"state": "stateoming",
"postalCode": "80091",
"country": "usa",
}...]
}...]
"Amount": "50.00",
"fee": "3.50",
"authorized": false,
"refunded": false,
"amount_refunded": "0.00",
"status": "succeeded"
}
/payment/refund
Refunding a member's account through Stripe
Request
Important information for ChargeRequest… Authorize = true means charge later. Authorize = false means charge now. When authorize = true, capture the chargeID and then call CaptureChargeRequest with the chargeID and that charge.
Parameters
- memberID required
- the member ID for the member being refunded
- chargeID
- the identification number for the charge of which refund is requested
- amount required
- the amount of money to charge to the member’s card
Response
The response returns the success or failure of the refund, along with a message
Parameters
- success
- the success message returns
trueif the refund was successful andfalseif the request failed - message
- a message may be returned in the ChargeResponse, it will show here
{
"memberID": "b045...bf6",
"chargeID": "ch_1E67BGBsCMNUt497V8L3rVl0"
"amount": "49.00"
}
{
"success": true,
"message": "anyMessage",
}
/payment/get_card
Get payment card data for a specific member.
Request
Parameters
- memberID required
- the member’s ID
- cardID required
- the card ID for the card to get
Response
The response returns a collection of data for card data
Parameters
- result
- returns the
customerID,cardID,memberIDand a success message inisSuccess - card
- data returned for the card or cards on a member’s account including card information and the billing address
{
"memberID": "b045...bf6",
"cardID": "card_1EGBoJBsCMNUt497i5E9NLv3",
}
{
"result": [{
"customerID": "cus_EJs5qdR5pqMXVZ",
"cardID": "",
"memberID": "b045...bf6"
"isSuccess": true,
}...]
"card": [{
"cardID": "card_1EGBoJBsCMNUt497i5E9NLv3",
"cardType": "visa",
"lastFour": "9034",
"expirationMonth": "04",
"expirationYear": "2021",
"default": true,
"address": [{
"lineOne": "3434 Street Ln",
"lineTwo": "apt 146",
"city": "Cityville",
"state": "stateoming",
"postalCode": "80091",
"country": "usa",
}...]
}...]
}
/payment/remove_card
Remove a card from a member account
Request
Request to remove an existing card
Parameters
- memberID required
- the member’s ID
- cardID required
- the card ID for the default card to be removed
Response
Response will return a success response
Parameters
- success
- returns
trueif the card was successfully removed andfalseif the request failed
{
"memberID": "b045...bf6",
"cardID": "card_1DrELYBsCMNUt497KMgNwzGC",
}
{
"success": true,
}
/payment/update_card
Update or set a payment card as the default card.
Request
Request to update an existing card
Parameters
- memberID required
- the member’s ID
- cardID required
- the card ID for the card to be updated
Response
Response will return a success response
Parameters
- success
- returns
trueif the card was successfully updated andfalseif the request failed
{
"memberID": "b045...bf6",
"cardID": "card_1DrELYBsCMNUt497KMgNwzGC",
}
{
"success": true,
}
/payment/update_card_info
Update card information.
Request
Parameters
- memberID required
- ID of the member being enrolled
- cardID required
- the card ID for the card to be updated
- postalCode
- the postal code of the credit card
- expirationMonth
- the expiration month of the credit card
- expirationYear
- the expiration year of the credit card
Response
Response will return a success response
Parameters
- success
- returns
trueif the card was successfully updated andfalseif the request failed - card
- the updated card if the card info was successfully updated
- cvc_check
- authentication of the cvc with the credit card
- zip_check
- authentication of the billing zip_code with credit card
- name
- authentication of the card with name
{
"memberID": "b045...bf6",
"cardID": "card_1EGBoZBsCMNUt497ek1SPjtc",
"postalCode": "77005",
"expirationMonth": "5",
"expirationYear": "2021"
}
{
"success": true,
"card": {
"cardID": "card_1EGBoZBsCMNUt497ek1SPjtc",
"cardType": "visa",
"lastFour": "9034",
"expirationMonth": "5",
"expirationYear": "2021",
"default": true,
"address": {
"lineOne": "3434 Street Ln",
"lineTwo": "apt 146",
"city": "Cityville",
"state": "TX",
"postalCode": "77005",
"country": "US",
}
"cvc_check": "checkcomplete",
"zip_check": "checkcomplete".
"name": "Jane B. Doe"
}
}
Promo
/promo/create
Create a new promo to be added to the promos table
Request
Create a new dollar_credit or free month membership promo.
Parameters
- type required
- the type of transaction from the transaction_types
- name required
- the name given to the new promo
- code required
- code assigned to the new promo. This will be the code used within promotional links
- description optional
- the description of what the new promo is
- unit required
- the unit can be in
dollarvalue for promos with dollar_credit ormonthfor promos giving free month membership - value required
- the value is returned as
3.00for promo with dollar amount value and as3(number of months) for free month membership promo - is_active required
- a boolean
truestates the promo is active andfalsestates the promo is inactive - start_date optional
- the date the promo begins
- end_date optional
- the date the promo ends
Response
A successful response will return a promo object with a promo code
Parameters
- successful
- a
trueresponse states the promo was successfully created andfalsestates the promo was not created - promo
- nested object with details related to the new promo created; type, name, code, description, unit, is_active, start_date, end_date, value, id
- id
- the ID assigned to the new promo created
Errors
Parameters
- 500 - Internal Server Error
- If there is some problem obtaining the trades given the parameters
- 403 - Permission Denied
- If the user is not authorized to create a promo
{
"type": "promo",
"name": "someName",
"code": "default",
"description": "1 month free default promo",
"unit": "month",
"value": "3",
"is_active": true,
"start_date": "yyyy-mm-day",
"end_date": "yyyy-mm-day"
}
}
{
"successful": true,
"promo": {
"type": "promo",
"name": "RunscopeTest",
"code": "default",
"description": "1 month free default promo",
"unit": "month",
"is_active": true,
"start_date": "",
"end_date": "",
"value": "3",
"id": "51"
},
"error": null
}
/promo/get
Get details on a specific promo code
Request
The request asks to get the details on a specific promo code
Parameters
- code required
- code assigned to the promo. code used within promotional links
Response
A successful response will return a promo object with the promo code details
Parameters
- successful
- a
trueresponse states the promo was successfully returned andfalsestates the promo was not returned - promo
- nested object with details related to the promo
- type
- the type of transaction from the transaction_types
- name
- the name of the promo
- code
- code assigned to the promo.
- description
- the description of what the promo is
- unit
- the unit can be in
dollarvalue for promos with dollar_credit ormonthfor promos giving free month membership - value
- the value is returned as
3.00for promo with dollar amount value and as3(number of months) for free month membership promo - is_active
- a boolean
truestates the promo is active andfalsestates the promo is inactive - start_date
- the date the promo begins
- end_date
- the date the promo ends
- id
- the ID assigned to the promo
Errors
Parameters
- 500 - Internal Server Error
- If there is some problem obtaining the trades given the parameters
{
"code": "default"
}
}
{
"successful": true,
"promo": {
"type": "promo",
"name": "RunscopeTest",
"code": "default",
"description": "1 month free default promo",
"unit": "month",
"is_active": true,
"start_date": "",
"end_date": "",
"value": "3",
"id": "51"
},
"error": null
}
/promo/get_all
Get details on all the promos
Request
The request asks to get the details on all the promos that exist within the system
No parameters are passed to return all promos
Response
A successful response will return all promo objects with the promo code details pertaining to each promo
Parameters
- successful
- a
trueresponse states each promo was successfully returned andfalsestates the promo was not returned - promo
- nested object with details related to the promo
- type
- the type of transaction from the transaction_types
- name
- the name of the promo
- code
- code assigned to the promo.
- description
- the description of what the promo is
- unit
- the unit can be in
dollarvalue for promos with dollar_credit ormonthfor promos giving free month membership - value
- the value is returned as
3.00for promo with dollar credit value and as3(number of months) for free month membership promo - is_active
- a boolean
truestates the promo is active andfalsestates the promo is inactive - start_date
- the date the promo begins
- end_date
- the date the promo ends
- id
- the ID assigned to the promo
Errors
Parameters
- 500 - Internal Server Error
- If there is some problem obtaining the trades given the parameters
- 403 - Permission Denied
- If the user is not authorized to create a promo
{
}
}
{
"successful": true,
"promo": {
"type": "promo",
"name": "RunscopeTest",
"code": "default",
"description": "1 month free default promo",
"unit": "month",
"is_active": true,
"start_date": "",
"end_date": "",
"value": "3",
"id": "1"
},
{
"successful": true,
"promo": {
"type": "promo",
"name": "RunscopeTest",
"code": "default",
"description": "$25 dollar promo",
"unit": "dollar",
"is_active": true,
"start_date": "",
"end_date": "",
"value": "25.00",
"id": "2"
}
"error": null
}
/promo/update
Update details on an existing promo
Request
Create a new dollar_credit or free month membership promo.
Parameters
- id required
- id of the promo to be updated
- name optional
- the new name to be updated
- code optional
- the new code to be updated
- description optional
- the new description to be updated
- is_active optional
- a boolean
truestates the promo is active andfalsestates the promo is inactive - start_date optional
- the date the promo begins
- end_date optional
- the date the promo ends
Response
A successful response will return a promo object with a promo code
Parameters
- successful
- a
trueresponse states the promo was successfully created andfalsestates the promo was not created - promo
- nested object with details related to the new promo created; type, name, code, description, unit, is_active, start_date, end_date, value, id
Errors
Parameters
- 500 - Internal Server Error
- If there is some problem obtaining the trades given the parameters
- 403 - Permission Denied
- If the user is not authorized to create a promo
- 404 - Not Found
- If formatting within the paramters is incorrect or if the endpoint does not exist yet
{
"id": "51",
"name": "update",
"code": "update",
"description": "update",
"is_active": true,
"start_date": "",
"end_date": ""
}
}
{
"successful": true,
"promo": {
"type": "promo",
"name": "update",
"code": "update",
"description": "update",
"unit": "month",
"is_active": true,
"start_date": "",
"end_date": "",
"value": "3",
"id": "51"
},
"error": null
}
Users
/users/email/everify
Verify a member's email.
Request
Parameters
- token required
- the request token associated with the email in question
Response
Response will return a success response.
Parameters
- success
- returns
trueif the member’s email was successfully verified andfalseif the request failed
{
"token": "eyJhbGciOi...uT9SO-W7iX0Ns",
}
{
"success": true,
}
/users/password/forgot
A member forgot their password and requests to reset it through the `ForgotPasswordRequest`
Request
Either one of email or phone are required, but not both.
Parameters
- the member’s email address
- phone
- the member’s mobile phone number
Response
Response will return a success response
Parameters
- success
- returns
trueif the request was successful andfalseif the request failed
{
"email": "jane.doe@example.com",
}
{
"success": true,
}
/users/password/reset
Reset a member's password
Request
Parameters
- token required
- the user’s password reset token
- password required
- the user’s new password - must be at least 8 characters in length with at least one each of uppercase, lowercase, and number
Response
Response will return a success response.
Parameters
- success
- returns
trueif the password was successfully reset andfalseif the request failed
{
"token": "eyJhbGciOi...uT9SO-W7iX0Ns",
"password": "MyNewPassword123",
}
{
"success": true,
}
/users/search
Search for users. This requires an admin access token.
Request
Either one of email or phone are required, but not both.
Parameters
- the member’s email address
- phone
- the member’s mobile phone number
Response
The response returns user data.
Parameters
- userID
- the user’s ID
- the user’s email address
- phone
- the user’s mobile phone number
- is_whitelisted
- returns
trueif whitelisted andfalseif not whitelisted - status
- status object provides boolean responses for status checks to a member’s account; see
user/statusfor details - meta_data
- just another fun nested JSON object with limitless possibilities
- devices
- data on the devices used by the member to access their account
{
"email": "jane.doe@example.com",
"phone": "2133211213",
}
{
"users": [
{
"userID": "12345",
"email": "jane.doe@example.com",
"phone": "+12133121213",
"is_whitelisted": false,
"status": null,
"meta_data": {
"somekey": "somevalue",
"anotherkey": "anothervalue"
},
"devices": {
"hwID": "someString",
"platform": "ios",
},
"gg_status": "unavailable",
"language": ""
}
]
}
/users/signin
Sign in to an account
Request
Parameters
- email required
- this is the primary mode of contact and where we will send any important notifications, including information about weather events and payment alerts
- password required
- to secure the account provide a password of at least 8 characters with at least one each of uppercase, lowercase, and number
- phone
- mobile phone number
Response
The signin response contains an access_token (and associated
refresh_token) that may be used immediately for further API requests. It also
contains a status object.
Parameters
- access_token
- the user’s access token
- refresh_token
- the user’s refresh token
- user_id
- id of the newly created user
- status
- status object provides boolean responses for status checks to a member’s account; see
user/statusfor details - gg_status
- Griddy Guest status. Possible values:
available= Initial value immediately after signup and before a Griddy Guest or actual member is created
active= Current Griddy Guest member
unavailable= Actual member; this user cannot enter Griddy Guest.
converted= Former Griddy Guest member who converted to actual member; they cannot enter Griddy Guest anymore.
{
"email": "jane.doe@example.com",
"password": "Password123",
}
{
"access_token": "eyJhbGciOi...YuIm5_MUeNFkA",
"refresh_token": "eyJhbGciOi...uT9SO-W7iX0Ns",
"userID": "12345",
"status": {
"member": false,
"name": false,
"address": false,
"birthday": false,
"billing_enroll": false,
"recharge_settings": false
"agreement": false,
"payment_enroll": false,
"payment_card": false,
"meter": false,
"is_whitelisted": true,
"billing_has_funds": false,
"has_register_device": false,
},
"gg_status": "unavailable"
}
/users/signout
Sign out of an account
Request
Parameters
- refresh_token required
- the user’s refresh token
Response
Response will return a success response.
Parameters
- success
- returns
trueif the member was successfully logged out andfalseif the request failed
{
"refresh_token": "eyJhbGciOi...uT9SO-W7iX0Ns",
}
{
"success": true,
}
/users/signup
Create a new user account
Request
Parameters
- email required
- this is the primary mode of contact and where we will send any important notifications, including information about weather events and payment alerts
- phone required
- mobile phone number
- password required
- to secure the account provide a password of at least 8 characters with at least one each of uppercase, lowercase, and number
- refresh_token required
- the refresh token assigned to the member
- access_token required
- the token assigned to the member
- agreed required
- boolean to indicate acceptance of the terms and conditions of the membership agreement and associated documents
Response
The signup response contains an access_token (and associated
refresh_token) that may be used immediately for further API requests. It also
contains a status object.
Parameters
- access_token
- the user’s access token
- refresh_token
- the user’s refresh token
- user_id
- id of the newly created user
- status
- status object provides boolean respones for status checks to a member’s account; see
user/statusfor details
{
"email": "jane.doe@example.com",
"phone": "3105551234",
"password": "Password123",
"refresh_token": "eyJhbGciOi...uT9SO-W7iX0Ns",
"access_token": "eyJhbGciOi...YuIm5_MUeNFkA",
"agreed": true,
}
{
"access_token": "eyJhbGciOi...YuIm5_MUeNFkA",
"refresh_token": "eyJhbGciOi...uT9SO-W7iX0Ns",
"userID": "12345",
"status": {
"member": false,
"name": false,
"address": false,
"birthday": false,
"billing_enroll": false,
"recharge_settings": false
"agreement": false,
"payment_enroll": false,
"payment_card": false,
"meter": false,
"is_whitelisted": true,
"billing_has_funds": false,
"has_register_device": false,
},
"gg_status": "unavailable"
}
/users/token/refresh
Refresh a member's token
Request
Parameters
- token required
- the refresh token so the member can reset their password
Response
Parameters
- access_token
- the user’s new token
{
"token": "eyJhbGciOi...YuIm5_MUeNFkA",
}
{
"access_token": "eyJhbGciOi...uT9SO-W7iX0Ns",
}
/users/update
Update a member's user record
Request
Parameters
- userID required
- the member’s user ID
- password
- the member’s password
- the member’s email address
- new_password
- the new password
- phone
- the member’s mobile phone number
Response
Response will return a success response.
Parameters
- success
- returns
trueif the member’s record was successfully updated andfalseif the request failed
{
"userID": "123456789",
"password": "somePassword2",
"email": "jane.doe@example.com",
"new_password": "newPassword",
"phone": "213-321-1213",
}
{
"success": true,
}
/users/whitelist
Whitelist a member. This requires an admin access token.
Request
Parameters
- the member’s email address
- phone
- the member’s mobile phone number
Response
Response will return a success response.
Parameters
- success
- returns
trueif the member was successfully whitelisted andfalseif the request failed
{
"email": "jane.doe@example.com",
"phone": "2133211213",
}
{
"success": true,
}
Objects
Price-Usage-Cost
Parameters
- timestamp
- this is the timestamp for the beginning of the interval
- price
quantityof the actual or forecasted energy generation price- usage
quantityof the actual or forecasted energy consumption- cost
quantityof the actual or forecasted cost- score
- the score on a scale of 0-99 measuring the relative goodness of the price, where 0 indicates a very good / low price and 99 indicates a very high price
{
"timestamp": "2017-09-15T06:20:00Z",
"duration": "PT5M",
"price": {"value": 1.25, "units": "¢/kWh"},
"usage": {"value": 3.14, "units": "kWh"},
"cost": {"value": 0.03925, "units": "$"},
"score": 15
}
Quantity
A quantity has a value and its associated units of measure.
Parameters
- units
- the units for the quantity
- value
- the numerical value of the quantity
{
"units": "¢/kWh",
"value": 1.25
}
User Status
The User Status object contains a set of flags to be used during login and enrollment to decide whether the user need to complete enrollment and if so which step(s) to display.
Parameters
- is_whitelisted
- true iff the user’s email and/or phone have been whitelisted
- note that currently all emails are whitelisted so this will always be true
- agreement
- true iff the user agreement has been accepted
- member
- true iff a member has been created
- name
- true iff the member’s name has been set
- address
- true iff the member’s address has been set
- birthday
- true iff the member’s birthday has been set
- recharge_settings
- true iff the member’s recharge settings have been configured
- billing_enroll
- true iff the billing account has been established
- billing_has_funds
- true iff the billing account has current or pending funds
- payment_enroll
- true iff the payment setup has been initialized
- payment_card
- true iff the member has a card on-file. note that this does not guarantee that the card on-file is good.
- meter
- true iff a meter registration has been attempted
- note that this does not guarantee that the meter registration will be accepted by the market
{
"is_whitelisted": true,
"member": false,
"name": false,
"address": false,
"birthday": false,
"agreement": false,
"payment_enroll": false,
"payment_card": false,
"meter": false,
"billing_has_funds": false,
"billing_enroll": false,
"recharge_settings": false
}