Forms

This is the object representing an authorization form that has be generated and can be submitted by a customer. This object contains a link to the form and any prefill information that's included by default.

API Endpoints

GET /api/v2/forms List or search your forms
POST /api/v2/forms Create a new form
GET /api/v2/forms/123 Get a specific form
PATCH /api/v2/forms/123 Modify an existing form
DELETE /api/v2/forms/123 Delete a form
POST /api/v2/forms/123/test-submit Simulate a user submitting a form

Attributes

Attribute	Format	Description	Example
`uid`	UID String	Unique identifier of the Form. These uids may appear as integers, but they are not guaranteed to stay that way, so you should treat them as strings.	`"3498573-pge"`
`created`	ISO8601	When the Form was created.	`"2016-01-01T12:30:24.653422+00:00"`
`updated`	ISO8601	When the Form was last updated.	`"2016-01-01T12:30:24.653422+00:00"`
`template_uid`	UID String	Unique identifier of the Template on which the form is based. This is a fixed uid form most users.	`"934845-8234"`
`authorization_uid`	UID String or `null`	Unique identifier of the Authorization for which this Form is an update. This is `null` for new forms and a UID String for reauthorizations.	`null`
`is_archived`	Boolean	Whether the Form is archived.	`false`
`disabled`	Boolean	Whether the Form is disabled from being loaded or submitted.	`false`
`user_email`	String	User who created the Form.	`"sales@acmesolar.com"`
`user_uid`	UID String	Unique identifier for the user who created the Form.	`"12345-6"`
`url`	URL	The public url for this authorization form that you can send to a customer. See URL Parameters for additional options.	`"https://utilityapi.com/portal/acme_solar?f=..."`
`customer_email`	String	The prefill value of the customer email field on the authorization form. If no prefill is set, this is an empty string (i.e. `""`).	`"heather.homeowner@yahoo.com"`
`utility`	UtilityID	The default selection for the utility in the authorization form. If no preset default is set, this is an empty string (i.e. `""`).	`"PG&E"`
`scope`	Scope	Any non-default authorization scope parameters that is being requested. If no scope is set, the default authorization scope is used (`{}`).	`{"expires": "until_revoked"}`

Examples

// Basic form with no prefilled information
{
    "uid": "12345",
    "created": "2016-01-01T12:30:24.653422+00:00",
    "updated": "2016-01-01T12:30:24.653422+00:00",
    "template_uid": "123423435",
    "authorization_uid": null,
    "is_archived": false,
    "disabled": false,
    "user_email": "sales@acmesolar.com",
    "user_uid": "1111",
    "url": "https://utilityapi.com/authorize/acme_solar?f=097jiosd-8iy5xci23-14fsasaf",
    "customer_email": "",
    "utility": "",
    "scope": {}
}

// Prefilled reauthorization with customer email, utility, and set to collect all Meters immediately
{
    "uid": "12345",
    "created": "2016-01-01T12:30:24.653422+00:00",
    "updated": "2016-01-01T12:30:24.653422+00:00",
    "template_uid": "123423435",
    "authorization_uid": "99995555-0",
    "is_archived": false,
    "disabled": false,
    "user_email": "sales@acmesolar.com",
    "user_uid": "1111",
    "url": "https://utilityapi.com/authorize/acme_solar?f=097jiosd-8iy5xci23-14fsasaf",
    "customer_email": "heather.homeowner@yahoo.com",
    "utility": "SDG&E",
    "scope": {
        "autocollect": true
    }
}

// Prefilled auto-registration with two accounts on PG&E utility
{
    "uid": "12345",
    "created": "2016-01-01T12:30:24.653422+00:00",
    "updated": "2016-01-01T12:30:24.653422+00:00",
    "template_uid": "123423435",
    "authorization_uid": null,
    "is_archived": false,
    "disabled": false,
    "user_email": "sales@acmesolar.com",
    "user_uid": "1111",
    "url": "https://utilityapi.com/authorize/acme_solar?f=097jiosd-8iy5xci23-14fsasaf",
    "customer_email": "hfarnsworth@planetexpress.com",
    "utility": "PG&E",
    "scope": {
        "pge_access_types": ["autoreg", "login"],
        "pge_autoreg_params": [
            {
                "owner_name": "Planet Express",
                "account_number": "111-222-3333-4",
                "phone_number": "555-555-5555"
            },
            {
                "owner_name": "Planet Express",
                "account_number": "111-222-3333-5",
                "phone_number": "555-555-5555"
            }
        ]
    }
}