Back to top

Urjanet Utility Data API

Last modified: 2018-11-27

Introduction and Goals

The Urjanet Utility Data API exists to provide customers with self-service methods to automate account enrollment and status reporting tasks in the Urjanet Platform. The scope of the API is as follows:

  • Management of Utility Accounts and Meters to be enrolled into the Urjanet data subscription service

    • Enrollment of new accounts and/or meters
    • Enrollment of new website credentials used to access accounts and meters
    • Assignment of Urjanet extraction templates to credentials
    • Assignment of customer-supplied attribute values to accounts and meters
    • Toggle platform features or delivery status on/off
    • Status queries for up-to-the minute reports covering the above entities
  • Management of Custom Attributes

    • Define valid set of allowable custom attribute names
    • Toggle custom attributes as required or optional
    • Query the full set of custom attributes
  • Searching and Filtering

    • Return accounts matching a supplied criteria
    • Return meters matching a supplied criteria
    • Return credentials matching a supplied criteria
  • Provider Metadata

    • Return Urjanet UtilityProvider record(s) that match a given criteria
    • Return information about any extraction templates associated with a UtilityProvider
  • Change log

General Usage Notes

  • The production URL is https://api.urjanet.net

  • The QA URL is https://apiqa.urjanet.net

  • Create requests must contain all required parameters

  • Create responses will contain the Urjanet id (uuid-string) for the newly created entity

  • Update requests must contain the Urjanet id of the entity to update, the fields and values targeted by the update request can be sparse

  • Status requests must contain the Urjanet id of the desired entity, and will return all documented fields, including null values if the field is unset or not currently applicable.

  • The ‘id’ field on the account object is meant to remain consistent, however, there are cases when it can change.

  • Search requests follow a query-by-example pattern.

    • See Appendix C for a detail description
  • Responses will use standard HTTP error codes to convey basic error status information

    • 200 for success
    • 400 for bad request
    • 401 for not-authorized
    • 404 for not-found
    • 500 for all other errors
  • Further error detail can be found within the “messages” array in the response body (when applicable)

  • All date fields will be represented as milliseconds-since-epoch long integers (analogous to java.util.Date’s getTime() value)

Security

Users must be authenticated with the Urjanet AuthServer before they can interact with the Utility Data Service. Authentication requires a username and password provided by Urjanet.

Please see the AuthServer API Documentation for more information.

The Utility Data Service API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

RESETTING PASSWORD

Using the SSO service available at https://sso.urjanet.net/ you can reset your API password.

Workflow:

  1. Visit SSO site https://sso.urjanet.net/.
  2. Click the link Forgot your password?, located below the Login button.
  3. Follow the steps on the page to reset your password, which will send an email message with a link to reset your password.

Accounts

Create an account

Create
POST/api/v1/account/create

Along with the account specific fields, a Credential must also be supplied (as extractionChannelId) when creating a new account request. This value can be either the id or extractionChannelId field of the Credential object.

Example URI

POST https://api.urjanet.net/api/v1/account/create
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    accountNumber: '1234',
    customerId: 'Customer1',
    utilityProviderId: 'GeorgiaPower',
    subscribed: true,
    pullHistory: false, [OPTIONAL]
    toBeDelivered: true,
    ebillRequirement: 'TURN_ON_EBILL', [OPTIONAL]
    extractionChannelId: 'Customer1_1-GeorgiaPower_1',
    customAttributes: {
        'attribute1': 'value1'
    }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string"
    },
    "accountNumber": {
      "type": "string"
    },
    "utilityProviderId": {
      "type": "string"
    },
    "subscribed": {
      "type": "boolean"
    },
    "toBeDelivered": {
      "type": "boolean"
    },
    "pullHistory": {
      "type": "boolean"
    },
    "ebillRequirement": {
      "type": "string",
      "enum": [
        "DO_NOT_CHANGE",
        "TURN_ON_EBILL",
        "TURN_OFF_EBILL"
      ]
    },
    "extractionChannelId": {
      "type": "string"
    },
    "customAttributes": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
        customerId: 'Customer',
        created: 1423851129417,        
        modified: 1423851129417,
        createdByUsername: 'username2',            
        lastModifiedByUsername: 'username',
        accountNumber: '123456789',
        normalizedAccountNumber: '123456789',
        summaryAccountNumber: '123',
        normalizedSummaryAccountNumber: '123',
        enrollmentStatus: 'PENDING',
        extractionStatus: null,
        monitoringStatus: 'UNKNOWN',
        providerClassification: null,
        message: null,
        pullHistory: false,
        historyRequested: null,
        subscribed: true,
        isSummaryAccount: false,
        subscriptionLastUpdated: null,
        unsubscribeDate: null,
        toBeDelivered: true,
        deliveryLastUpdated: null,
        deliveryDisabledDate: null,
        firstExtractDate: null,
        lastExtracted: null,
        lastSuccessfulExtraction: null,
        ebillRequirement: 'DO_NOT_CHANGE',
        lastDelivered: null,
        latestOrphanSourceDeliveredDate: null,
        nextExpectedPostDate: null,
        latestIntervalEnd: null,
        startToEndAvg: null,
        nextExpectedConfidence: null,
        latestTotalBillAmount: 326.84,
        latestStatementCreate: 1461843671000,
        lastSuccessfulExtractionChannel: null,
        utilityProvider: {
            id: '68c2e3ba-8c82-48a4-a6ac-e2686d4e2222',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/68c2e3ba-8c82-48a4-a6ac-e2686d4e2222'
            }
        },
        verifiedExtractionChannels: [],
        extractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        customAttributes: {
            'attribute1': 'value1',
            'attribute2': 'value2'
        }
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Enroll Candidate
POST/api/v1/account/enrollCandidate

This endpoint is for directly enrolling candidate accounts returned from the candidate search. Only the ID of the account and any required custom attributes are needed for this action.

Example URI

POST https://api.urjanet.net/api/v1/account/enrollCandidate
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
    customAttributes: {
       'attribute1': 'value1'
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
        customerId: 'Customer',
        created: 1423851129417,        
        modified: 1423851129417,
        createdByUsername: 'username2',            
        lastModifiedByUsername: 'username',
        accountNumber: '123456789',
        normalizedAccountNumber: '123456789',
        summaryAccountNumber: '123',
        normalizedSummaryAccountNumber: '123',
        enrollmentStatus: 'PENDING',
        extractionStatus: 'SUCCESS',
        monitoringStatus: 'UNKNOWN',
        providerClassification: 'PRIMARY',
        message: null,
        subscribed: true,
        isSummaryAccount: false,
        pullHistory: true,
        historyRequested: 1423851129417,
        subscriptionLastUpdated: null,
        unsubscribeDate: null,
        toBeDelivered: true,
        deliveryLastUpdated: null,
        deliveryDisabledDate: null,
        firstExtractDate: 1423851129417,
        lastExtracted: 1423851129417,
        lastSuccessfulExtraction: 1423851129417,
        ebillRequirement: 'DO_NOT_CHANGE',
        lastDelivered: 1423851129417,
        latestOrphanSourceDeliveredDate: null,
        nextExpectedPostDate: 1423851129417,
        latestIntervalEnd: 1423851129417,
        startToEndAvg: 29.54,
        nextExpectedConfidence: 'HIGH',
        latestTotalBillAmount: 326.84,
        latestStatementCreate: 1461843671000,
        lastSuccessfulExtractionChannel: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: 'Customer_1-GeorgiaPower_1',
            link: {
                rel: 'self',
                href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },
        utilityProvider: {
            id: '68c2e3ba-8c82-48a4-a6ac-e2686d4e2222',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/68c2e3ba-8c82-48a4-a6ac-e2686d4e2222'
            }
        },
        verifiedExtractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        extractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        customAttributes: {
            'attribute1': 'value1',
            'attribute2': null
        }
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Update an account

Update
POST/api/v1/account/update

This call will update a specified account with the given new field values. These fields are a small subset of the UtilityAccount fields on which changes are allowed. The return will be the full UtilityAccount in its updated state. Other than id all fields are optional. The provider associated with the account can be modified on accounts that have not already been extracted.

Although we only allow creation of accounts tied to a single extractionChannelId, we have added a new attribue, extractionChannelIds, to allow you to update an account with multiple extractionChannelIds. This will allow you to update an existing account tied to one credential and add a new relationship to another credential.

Example URI

POST https://api.urjanet.net/api/v1/account/update
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    id: '1e557643-1753-d931-b246-0e384cd92781',
    utilityProviderId: 'GeorgiaPower', [OPTIONAL]
    subscribed: true, [OPTIONAL]
    toBeDelivered: true, [OPTIONAL]
    pullHistory: true, [OPTIONAL]
    ebillRequirement: 'TURN_ON_EBILL' [OPTIONAL]
    extractionChannelId: 'Customer1_1-GeorgiaPower_1', [OPTIONAL]
    extractionChannelIds: ['Customer1_1-GeorgiaPower_1', 'Customer1_1-GeorgiaPower_2'], [OPTIONAL]
    customAttributes: { [OPTIONAL]
        'attribute1': 'value1'
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
        customerId: 'Customer',
        created: 1423851129417,        
        modified: 1423851129417,
        createdByUsername: 'username2',            
        lastModifiedByUsername: 'username',
        accountNumber: '123456789',
        normalizedAccountNumber: '123456789',
        summaryAccountNumber: '123',
        normalizedSummaryAccountNumber: '123',
        enrollmentStatus: 'PENDING',
        extractionStatus: 'SUCCESS',
        monitoringStatus: 'UNKNOWN',
        providerClassification: 'PRIMARY',
        message: null,
        subscribed: true,
        isSummaryAccount: false,
        pullHistory: true,
        historyRequested: 1423851129417,
        subscriptionLastUpdated: null,
        unsubscribeDate: null,
        toBeDelivered: true,
        deliveryLastUpdated: null,
        deliveryDisabledDate: null,
        firstExtractDate: 1423851129417,
        lastExtracted: 1423851129417,
        lastSuccessfulExtraction: 1423851129417,
        ebillRequirement: 'DO_NOT_CHANGE',
        lastDelivered: 1423851129417,
        latestOrphanSourceDeliveredDate: null,
        nextExpectedPostDate: 1423851129417,
        latestIntervalEnd: 1423851129417,
        startToEndAvg: 29.54,
        nextExpectedConfidence: 'HIGH',
        latestTotalBillAmount: 326.84,
        latestStatementCreate: 1461843671000,
        lastSuccessfulExtractionChannel: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: 'Customer_1-GeorgiaPower_1',
            link: {
                rel: 'self',
                href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },
        utilityProvider: {
            id: '68c2e3ba-8c82-48a4-a6ac-e2686d4e2222',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/68c2e3ba-8c82-48a4-a6ac-e2686d4e2222'
            }
        },
        verifiedExtractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        extractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        customAttributes: {
            'attribute1': 'value1',
            'attribute2': 'value2'
        }
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Get an account

Status
GET/api/v1/account/status/{account_id}

Example URI

GET https://api.urjanet.net/api/v1/account/status/1e549f1d
URI Parameters
HideShow
account_id
string (required) Example: 1e549f1d

2ef6-db58-862f-0e384cd92781 (required, string) - UUID of the utility account

Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
        customerId: 'Customer',
        created: 1423851129417,        
        modified: 1423851129417,
        createdByUsername: 'username2',            
        lastModifiedByUsername: 'username',
        accountNumber: '123456789',
        normalizedAccountNumber: '123456789',
        summaryAccountNumber: '123',
        normalizedSummaryAccountNumber: '123',
        enrollmentStatus: 'PENDING',
        extractionStatus: 'EXISTS',
        monitoringStatus: 'UNKNOWN',
        providerClassification: 'PRIMARY',
        message: null,
        subscribed: true,
        isSummaryAccount: false,
        pullHistory: true,
        historyRequested: 1423851129417,
        subscriptionLastUpdated: null,
        unsubscribeDate: null,
        toBeDelivered: true,
        deliveryLastUpdated: null,
        deliveryDisabledDate: null,
        firstExtractDate: 1423851129417,
        lastExtracted: 1423851129417,
        lastSuccessfulExtraction: 1423851129417,
        ebillRequirement: 'DO_NOT_CHANGE',
        lastDelivered: 1423851129417,
        latestOrphanSourceDeliveredDate: null,
        nextExpectedPostDate: 1423851129417,
        latestIntervalEnd: 1423851129417,
        startToEndAvg: 29.54,
        nextExpectedConfidence: 'HIGH',
        latestTotalBillAmount: 326.84,
        latestStatementCreate: 1461843671000,
        lastSuccessfulExtractionChannel: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: 'Customer_1-GeorgiaPower_1',
            link: {
                rel: 'self',
                href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },
        utilityProvider: {
            id: '68c2e3ba-8c82-48a4-a6ac-e2686d4e2222',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/68c2e3ba-8c82-48a4-a6ac-e2686d4e2222'
            }
        },
        verifiedExtractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        extractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        customAttributes: {
            'attribute1': 'value1',
            'attribute2': 'value2'
        }
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Search accounts

Search
POST/api/v1/account/search

This action will search from among the accounts that have been explicitly requested either by creation through this API or enrollment forms through the web portal.

Example URI

POST https://api.urjanet.net/api/v1/account/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 10,
        sorts: [{
            field: "accountNumber",
            direction: "asc"
        }],
        filter: { 
            conditions: [{
                field: "enrollmentStatus",
                operator: "eq",
                value: "PENDING"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '80da2e51-83b3-4eed-8f47-b02ee248ff77',     
            customerId: 'Customer',
            created: 1423851129417,        
            modified: 1423851129417,
            createdByUsername: 'ExampleUser',            
            lastModifiedByUsername: 'ExampleUser',
            accountNumber: '1234-56789',
            normalizedAccountNumber: '123456789',
            summaryAccountNumber: '123',
            normalizedSummaryAccountNumber: '123',
            enrollmentStatus: 'PENDING',
            extractionStatus: 'SUCCESS',
            monitoringStatus: 'UNKNOWN',
            providerClassification: 'PRIMARY',
            message: null,
            subscribed: true,
            isSummaryAccount: false,
            subscriptionLastUpdated: null,
            unsubscribeDate: null,
            pullHistory: false,
            historyRequested: null,
            toBeDelivered: false,
            deliveryLastUpdated: null,
            deliveryDisabledDate: null,
            firstExtractDate: 1423851129417,
            lastExtracted: 1423851129417,
            lastSuccessfulExtraction: 1423851129417,
            ebillRequirement: 'DO_NOT_CHANGE',
            lastDelivered: null,
            latestOrphanSourceDeliveredDate: null,
            nextExpectedPostDate: 1423851129417,
            latestIntervalEnd: 1423851129417,
            startToEndAvg: 29.54,
            nextExpectedConfidence: 'HIGH',
            latestTotalBillAmount: 326.84,
            latestStatementCreate: 1461843671000,
            lastSuccessfulExtractionChannel: {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            },
            utilityProvider: {
                id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
                naturalKey: 'GeorgiaPower',
                link: {
                    rel: 'self',
                    href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
                }
            },
            verifiedExtractionChannels: [
                {
                    id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                    naturalKey: 'Customer_1-GeorgiaPower_1',
                    link: {
                        rel: 'self',
                        href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                    }
                }
            ],
            extractionChannels: [
                {
                    id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                    naturalKey: 'Customer_1-GeorgiaPower_1',
                    link: {
                        rel: 'self',
                        href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                    }
                }
            ],
            customAttributes: {
                'SiteID': 'Site 123'
            }
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: true,
    nextPageOffset: 10
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Candidates
POST/api/v1/account/candidates

The candidate search returns only accounts that we have extracted but have not been associated with a requested account. This can be useful to find out if we have extracted any accounts that you may be interested in but have not requested yet.

Example URI

POST https://api.urjanet.net/api/v1/account/candidates
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 10,
        sorts: [{
            field: "accountNumber",
            direction: "asc"
        }],
        filter: { 
            conditions: [{
                field: "extractionStatus",
                operator: "eq",
                value: "SUCCESS"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '80da2e51-83b3-4eed-8f47-b02ee248ff77',     
            customerId: 'Customer',
            created: 1423851129417,        
            modified: 1423851129417,
            createdByUsername: 'ExampleUser',            
            lastModifiedByUsername: 'ExampleUser',
            accountNumber: '1234-56789',
            normalizedAccountNumber: '123456789',
            summaryAccountNumber: '123',
            normalizedSummaryAccountNumber: '123',
            enrollmentStatus: 'PENDING',
            extractionStatus: 'SUCCESS',
            monitoringStatus: 'UNKNOWN',
            providerClassification: 'PRIMARY',
            message: null,
            subscribed: true,
            isSummaryAccount: false,
            subscriptionLastUpdated: null,
            unsubscribeDate: null,
            pullHistory: false,
            historyRequested: null,
            toBeDelivered: false,
            deliveryLastUpdated: null,
            deliveryDisabledDate: null,
            firstExtractDate: 1423851129417,
            lastExtracted: 1423851129417,
            lastSuccessfulExtraction: 1423851129417,
            ebillRequirement: 'DO_NOT_CHANGE',
            lastDelivered: null,
            latestOrphanSourceDeliveredDate: null,
            nextExpectedPostDate: 1423851129417,
            latestIntervalEnd: 1423851129417,
            startToEndAvg: 29.54,
            nextExpectedConfidence: 'HIGH',
            latestTotalBillAmount: 326.84,
            latestStatementCreate: 1461843671000,
            lastSuccessfulExtractionChannel: {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            },
            utilityProvider: {
                id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
                naturalKey: 'GeorgiaPower',
                link: {
                    rel: 'self',
                    href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
                }
            },
            verifiedExtractionChannels: [
                {
                    id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                    naturalKey: 'Customer_1-GeorgiaPower_1',
                    link: {
                        rel: 'self',
                        href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                    }
                }
            ],
            extractionChannels: [],
            customAttributes: {}
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: true,
    nextPageOffset: 10
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Meters

Create a meter

The fields that are initially settable on meter creation are the meter number, service type, ID of the account containing this meter, customer ID, and an optional map of any custom attributes to be associated with the meter. All fields but the custom attributes are required for meter creation.

Create
POST/api/v1/meter/create

Example URI

POST https://api.urjanet.net/api/v1/meter/create
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    meterNumber: 'meter-123',
    customerId: 'Customer1',
    utilityAccountId: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
    serviceType: 'GAS',
    customAttributes: {
        'attribute1': 'value1'
    }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string"
    },
    "meterNumber": {
      "type": "string"
    },
    "utilityAccountId": {
      "type": "string"
    },
    "serviceType": {},
    "customAttributes": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
        utilityAccount: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: null,
            link: {
                rel: 'self',
                href: '/account/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user1',
        meterNumber: 'meter-123',
        normalizedMeterNumber: 'meter123',
        serviceType: 'GAS',
        tariff: null,
        serviceAddress: '123 Main St',
        podNumber: null,
        previousMeterNumber: null,
        deactivated: false,
        customAttributes: {
            'attribute1': 'Value1'
        }
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Update a meter

The only fields that are modifiable on utility meters are custom-defined attributes.

Update
POST/api/v1/meter/update

Example URI

POST https://api.urjanet.net/api/v1/meter/update
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
    customAttributes: {
        'attribute1': 'value2'
    }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "customAttributes": {
      "type": "object",
      "properties": {}
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
        utilityAccount: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: null,
            link: {
                rel: 'self',
                href: '/account/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user1',
        meterNumber: 'meter-123',
        normalizedMeterNumber: 'meter123',
        serviceType: 'GAS',
        tariff: null,
        serviceAddress: '123 Main St',
        podNumber: null,
        previousMeterNumber: null,
        deactivated: false,
        customAttributes: {
            'attribute1': 'Value2'
        }
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Get a meter

Status
GET/api/v1/meter/status/{meter_id}

Example URI

GET https://api.urjanet.net/api/v1/meter/status/1e549f1d
URI Parameters
HideShow
meter_id
string (required) Example: 1e549f1d

2ef6-db58-862f-0e384cd92781 (required, string) - UUID of the utility meter

Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
        utilityAccount: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: null,
            link: {
                rel: 'self',
                href: '/account/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user1',
        meterNumber: 'meter-123',
        normalizedMeterNumber: 'meter123',
        serviceType: 'GAS',
        tariff: null,
        serviceAddress: '123 Main St',
        podNumber: null,
        previousMeterNumber: null,
        deactivated: false,
        customAttributes: {
            'attribute1': 'Value2'
        }
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Search meters

Search
POST/api/v1/meter/search

This action will search from among the meters that have been explicitly requested by creation through this API.

Example URI

POST https://api.urjanet.net/api/v1/meter/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: [{
            field: "meterNumber",
            direction: "asc"
        }],
        filter: { 
            conditions: [{
                field: "attribute1",
                operator: "eq",
                value: "value2"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
            utilityAccount: {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: null,
                link: {
                    rel: 'self',
                    href: '/account/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            },
            created: 1445525043973,
            modified: 1445525043973,
            lastModifiedByUsername: 'user1',
            createdByUsername: 'user1',
            meterNumber: 'meter-123',
            normalizedMeterNumber: 'meter123',
            serviceType: 'GAS',
            tariff: null,
            serviceAddress: '123 Main St',
            podNumber: null,
            previousMeterNumber: null,
            deactivated: false,
            customAttributes: {
                'attribute1': 'Value2'
            }
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: true,
    nextPageOffset: 100
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Candidates
POST/api/v1/meter/candidate

The candidate search returns only meters that we have extracted but have not been associated with a requested meter. This can be useful to find out if we have extracted any meters that you may be interested in but have not requested yet.

Example URI

POST https://api.urjanet.net/api/v1/meter/candidate
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: [{
            field: "meterNumber",
            direction: "asc"
        }],
        filter: { 
            conditions: [{
                field: "accountNumber",
                operator: "startsWith",
                value: "012345"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
            utilityAccount: {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: null,
                link: {
                    rel: 'self',
                    href: '/account/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            },
            created: 1445525043973,
            modified: 1445525043973,
            lastModifiedByUsername: 'user1',
            createdByUsername: 'user1',
            meterNumber: 'meter-123',
            normalizedMeterNumber: 'meter123',
            serviceType: 'GAS',
            tariff: null,
            serviceAddress: '123 Main St',
            podNumber: null,
            previousMeterNumber: null,
            deactivated: false,
            customAttributes: {
                'attribute1': 'Value2'
            }
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: true,
    nextPageOffset: 100
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

By Account
GET/api/v1/meter/byaccount/{account_id}

This action will return all utility meters associated with the specified utility account.

Example URI

GET https://api.urjanet.net/api/v1/meter/byaccount/1e549f1d
URI Parameters
HideShow
account_id
string (required) Example: 1e549f1d

2ef6-db58-862f-0e384cd92781 (required, string) - UUID of the utility meter

Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',     
            utilityAccount: {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: null,
                link: {
                    rel: 'self',
                    href: '/account/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            },
            created: 1445525043973,
            modified: 1445525043973,
            lastModifiedByUsername: 'user1',
            createdByUsername: 'user1',
            meterNumber: 'meter-123',
            normalizedMeterNumber: 'meter123',
            serviceType: 'GAS',
            tariff: null,
            serviceAddress: '123 Main St',
            podNumber: null,
            previousMeterNumber: null,
            deactivated: false,
            customAttributes: {
                'attribute1': 'Value2'
            }
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: true,
    nextPageOffset: 100
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Credentials

Create credentials

Any passwords will never be rendered back inside of any response from the API; they are only able to be updated, but never retrieved. It’s possible to override the Urjanet template a credential is associated with, but it is not required. If not provided, the template will be automatically assigned to the default template of the given utility provider. Duplication logic exists in the system that will prevent creation of any credentials that have the same username(s) and provider/template. This duplication logic can be relaxed on a case-by-case basis to include passwords (i.e. allow the same username with different passwords). This is a very rare case; for these, contact Urjanet support to discuss enabling this behavior for the provider in question with positive examples.

Additional credentials are used for uncommon cases where there are multiple steps during data acquisition that require input. For example, some utility provider websites may have a security question that needs to be answered before gaining access to the utility bill. In this case, username2 could be populated with the security question and password2 could be populated with the security answer. Other utility provider websites may require users to select their geographical region before logging in. In this case, additional username fields can be populated with the correct input.

In addition to web-based acquisition, Urjanet also supports bill acquisition via Amazon S3, with a bucket owned by you. You can use file prefixes to sort different providers within the same bucket by folder. The level of security for the bills is also configurable; you can use Amazon’s key management system (KMS) to encrypt all of the files, or restrict access to a particular IAM role and share that with us (contact Urjanet support for assistance setting this up).

Create
POST/api/v1/credential/create

Example URI

POST https://api.urjanet.net/api/v1/credential/create
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    username: 'user', [REQUIRED for WEB]
    username2: 'user2', [OPTIONAL]
    username3: 'user3', [OPTIONAL]
    username4: 'user4', [OPTIONAL]
    password: 'pass', [REQUIRED for WEB]
    password2: 'pass2', [OPTIONAL]
    password3: 'pass3', [OPTIONAL]
    password4: 'pass4', [OPTIONAL]
    acquisitionType: 'WEB', [OPTIONAL defaults to 'WEB']
    customerId: 'Customer',
    utilityProviderId: 'GeorgiaPower',
    url: 'https://www.google.com', [OPTIONAL]
    templateId: 'GeorgiaPowerTemplateProvider', [OPTIONAL]
    enabled: 'true' [OPTIONAL] defaults to true
    intervalDataEnabled: 'false', [OPTIONAL defaults to false]
    s3BucketName: 'my_s3_bucket', [REQUIRED for S3]
    s3FilePrefix: '/ComEd', [OPTIONAL]
    s3EncryptionKeyId: '1e4b3abd-34c2-d5ee-adef-0800270a0870', [OPTIONAL]
    s3RoleId: 'arn:aws:iam::AccountID:role/MyExampleRole' [OPTIONAL]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string"
    },
    "username": {
      "type": "string"
    },
    "username2": {
      "type": "string"
    },
    "username3": {
      "type": "string"
    },
    "username4": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "password2": {
      "type": "string"
    },
    "password3": {
      "type": "string"
    },
    "password4": {
      "type": "string"
    },
    "acquisitionType": {},
    "url": {
      "type": "string"
    },
    "utilityProviderId": {
      "type": "string"
    },
    "templateId": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    },
    "intervalDataEnabled": {
      "type": "boolean"
    },
    "s3BucketName": {
      "type": "string"
    },
    "s3FilePrefix": {
      "type": "string"
    },
    "s3EncryptionKeyId": {
      "type": "string"
    },
    "s3RoleId": {
      "type": "string"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
        extractionChannelId: 'Customer_1-GeorgiaPower_1',
        username: 'user',
        username2: 'user2',
        username3: 'user3',
        username4: 'user4',
        message: null,
        acquisitionType: 'WEB',
        s3BucketName: null,
        s3FilePrefix: null,
        lastAttempted: null,
        lastSuccess: null,     
        template: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: 'GeorgiaPowerTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },    
        utilityProvider: {
            id: '48af363c-36a0-487b-bd78-6acd4610880f',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/48af363c-36a0-487b-bd78-6acd4610880f'
            }
        },
        url: 'https://www.google.com',
        enabled: true,
        intervalDataEnabled: true,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user2'
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Update credentials

The URL, template, and credentials (primary and additional) are the only modifiable fields on a credential object.

Update
POST/api/v1/credential/update

Example URI

POST https://api.urjanet.net/api/v1/credential/update
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    id: 'Customer_1-GeorgiaPower_1',
    username: 'user3', [OPTIONAL]
    username2: 'user2', [OPTIONAL]
    username3: 'user3', [OPTIONAL]
    username4: 'user4', [OPTIONAL]
    enabled: true, [OPTIONAL]
    intervalDataEnabled: false, [OPTIONAL]
    password: 'pass', [OPTIONAL]
    password2: 'pass2', [OPTIONAL]
    password3: 'pass3', [OPTIONAL]
    password4: 'pass4', [OPTIONAL]
    url: 'https://www.google.com', [OPTIONAL]
    templateId: 'GeorgiaPowerTemplateProvider', [OPTIONAL]
    s3BucketName: 'my_s3_bucket', [OPTIONAL]
    s3FilePrefix: '/ComEd', [OPTIONAL]
    s3EncryptionKeyId: '1e4b3abd-34c2-d5ee-adef-0800270a0870', [OPTIONAL]
    s3RoleId: 'arn:aws:iam::AccountID:role/MyExampleRole' [OPTIONAL]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "username": {
      "type": "string"
    },
    "username2": {
      "type": "string"
    },
    "username3": {
      "type": "string"
    },
    "username4": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "password2": {
      "type": "string"
    },
    "password3": {
      "type": "string"
    },
    "password4": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    },
    "intervalDataEnabled": {
      "type": "boolean"
    },
    "url": {
      "type": "string"
    },
    "templateId": {
      "type": "object",
      "properties": {}
    },
    "s3BucketName": {
      "type": "string"
    },
    "s3FilePrefix": {
      "type": "string"
    },
    "s3EncryptionKeyId": {
      "type": "string"
    },
    "s3RoleId": {
      "type": "string"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
        extractionChannelId: 'Customer_1-GeorgiaPower_1',
        username: 'user3',    
        username2: 'user2',
        username3: 'user3',
        username4: 'user4',
        acquisitionType: 'WEB',
        s3BucketName: null,
        s3FilePrefix: null,
        message: 'Example Message',
        lastAttempted: 1445525043973,
        lastSuccess: 1445525043973,     
        template: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: 'GeorgiaPowerTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },    
        utilityProvider: {
            id: '48af363c-36a0-487b-bd78-6acd4610880f',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/48af363c-36a0-487b-bd78-6acd4610880f'
            }
        },
        url: 'https://www.google.com',
        enabled: false,
        intervalDataEnabled : true,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user2'
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Get a credential

Status
GET/api/v1/credential/status/{credential_id}

Example URI

GET https://api.urjanet.net/api/v1/credential/status/48af363c
URI Parameters
HideShow
credential_id
string (required) Example: 48af363c

36a0-487b-bd78-6acd4610880f (required, string) - UUID or extractionChannelId (natural key) of the credential

Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
        extractionChannelId: 'Customer_1-GeorgiaPower_1',
        username: 'user3',
        username2: null,
        username3: null,
        username4: null,
        acquisitionType: 'WEB',
        s3BucketName: null,
        s3FilePrefix: null,
        message: 'Example Message',
        lastAttempted: 1445525043973,
        lastSuccess: 1445525043973,
        template: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: 'GeorgiaPowerTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },    
        utilityProvider: {
            id: '48af363c-36a0-487b-bd78-6acd4610880f',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/48af363c-36a0-487b-bd78-6acd4610880f'
            }
        },
        url: 'https://www.google.com',
        enabled: true,
        intervalDataEnabled: false,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user2'
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Search credentials

Although they are not returned in any response, all of the password fields are searchable. However, because of encryption, any password filters are applied in a second step on the initial result set. For performance reasons, at least one non-password filter must be present any time a password field is used to filter the result set. The only allowable filter operation on passwords is an exact match (‘eq’). Furthermore, sorting is not allowed on any of the passwords.

Search
POST/api/v1/credential/search

Example URI

POST https://api.urjanet.net/api/v1/credential/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: null,
        filter: { 
            conditions: [{
                field: "utilityProviderId",
                operator: "includes",
                value: "Georgia"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            extractionChannelId: 'Customer_1-GeorgiaPower_1',
            username: 'user3',
            username2: null,
            username3: null,
            username4: null,
            acquisitionType: 'WEB',
            s3BucketName: null,
            s3FilePrefix: null,
            message: 'Example Message',
            lastAttempted: 1445525043973,
            lastSuccess: 1445525043973,
            template: {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'GeorgiaPowerTemplateProvider',
                link: {
                    rel: 'self',
                    href: '/template/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            },    
            utilityProvider: {
                id: '48af363c-36a0-487b-bd78-6acd4610880f',
                naturalKey: 'GeorgiaPower',
                link: {
                    rel: 'self',
                    href: '/provider/status/48af363c-36a0-487b-bd78-6acd4610880f'
                }
            },
            url: 'https://www.google.com',
            enabled: true,
            intervalDataEnabled: false,
            created: 1445525043973,
            modified: 1445525043973,
            lastModifiedByUsername: 'user1',
            createdByUsername: 'user2'
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: true,
    nextPageOffset: 100
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Attributes

Create attribute

Custom attributes (also called mixin data) allow customers to specify additional information about accounts which wouldn’t otherwise be available from the utility bill (e.g. Facility ID). Custom attributes must be created explicitly through the API before they can be referenced when creating or update accounts or meters.

Create
POST/api/v1/attribute/create

Example URI

POST https://api.urjanet.net/api/v1/attribute/create
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer',
    name: 'FacilityId',
    required: false, [OPTIONAL]
    cnbdPosition: 2 [OPTIONAL]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "cnbdPosition": {
      "type": "number"
    },
    "required": {
      "type": "boolean"
    },
    "urjanetKey": {}
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
        required: false,
        name: 'FacilityId',
        cnbdPosition: 2,
        urjanetKey: null,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user2'
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Update attribute

Update
POST/api/v1/attribute/update

Example URI

POST https://api.urjanet.net/api/v1/attribute/update
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
    name: 'NewName', [OPTIONAL]
    required: true, [OPTIONAL]
    cnbdPosition: 1 [OPTIONAL]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "cnbdPosition": {
      "type": "number"
    },
    "required": {
      "type": "boolean"
    },
    "urjanetKey": {}
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
        required: true,
        name: 'NewName',
        cnbdPosition: 1,
        urjanetKey: null,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user2'
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Get an attribute

Status
GET/api/v1/attribute/status/{attribute_id}

Example URI

GET https://api.urjanet.net/api/v1/attribute/status/48af363c
URI Parameters
HideShow
attribute_id
string (required) Example: 48af363c

36a0-487b-bd78-6acd4610880f (required, string) - UUID of the attribute

Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
        required: true,
        name: 'FacilityId',
        cnbdPosition: 1,
        urjanetKey: null,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user2'
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Search attributes

Search
POST/api/v1/attribute/search

Example URI

POST https://api.urjanet.net/api/v1/attribute/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: null,
        filter: null
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            required: true,
            name: 'FacilityId',
            cnbdPosition: 1,
            urjanetKey: null,
            created: 1445525043973,
            modified: 1445525043973,
            lastModifiedByUsername: 'user1',
            createdByUsername: 'user2'
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: false,
    nextPageOffset: 1
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Change Log

See Appendix B for more details about the possible event types and information supplied with each as well as a listing of what fields are searchable.

Search change log

Search
POST/api/v1/changelog/search

Example URI

POST https://api.urjanet.net/api/v1/changelog/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: null,
        filter: { 
            conditions: [{
                field: "eventName",
                operator: "eq",
                value: "AccountDeliveryChangeEvent"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            username: 'user',
            timestamp: 113213123123,
            eventName: 'AccountDeliveryChangeEvent',
            customerId: 'Customer1',
            eventFields: {
                accountNumber: '123',
                providerAlias: 'GeorgiaPower',
                oldStatus: 'false',
                newStatus: 'true'
        },
        ...
    ],
    status: "OK",
    message: [],
    morePages: false,
    nextPageOffset: 100
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Templates

Get a template

Status
GET/api/v1/template/status/{template_id}

Example URI

GET https://api.urjanet.net/api/v1/template/status/1e549f1d
URI Parameters
HideShow
template_id
string (required) Example: 1e549f1d

2ef6-db58-862f-0e384cd92781 (required, string) - UUID or template name (i.e. natural key) of the template

Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
        templateName: 'GeorgiaPowerTemplateProvider',
        website: 'https://www.utility-provider.com',
        hasInterval: true,
        hasHistory: true, 
        hasPdf: true,
        hasHtml: false,
        hasEdi: false,
        hasXls: false,
        hasCsv: false,
        hasOcr: false,
        tracksLoginFailure: true,
        utilityProviders: [{
            id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
            }
        }, {
            id: '236e3d5c-0a42-4d61-ae62-8780b6b6c974'
            naturalKey: 'SouthernCompany',
            link: {
                rel: 'self',
                href: '/provider/status/236e3d5c-0a42-4d61-ae62-8780b6b6c974'
            }
        }],
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user2'
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Search templates

Search
POST/api/v1/template/status/search

Example URI

POST https://api.urjanet.net/api/v1/template/status/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: null,
        filter: { 
            conditions: [{
                field: "templateName",
                operator: "includes",
                value: "Georgia"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            templateName: 'GeorgiaPowerTemplateProvider',
            website: 'https://www.utility-provider.com',
            hasInterval: true,
            hasHistory: true, 
            hasPdf: true,
            hasHtml: false,
            hasEdi: false,
            hasXls: false,
            hasCsv: false,
            hasOcr: false,
            tracksLoginFailure: true,
            utilityProviders: [{
                id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
                naturalKey: 'GeorgiaPower',
                link: {
                    rel: 'self',
                    href: '/provider/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
                }
            }, {
                id: '236e3d5c-0a42-4d61-ae62-8780b6b6c974'
                naturalKey: 'SouthernCompany',
                link: {
                    rel: 'self',
                    href: '/provider/status/236e3d5c-0a42-4d61-ae62-8780b6b6c974'
                }
            }],
            created: 1445525043973,
            modified: 1445525043973,
            lastModifiedByUsername: 'user1',
            createdByUsername: 'user2'
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: false,
    nextPageOffset: 5
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Service Types

Get a service type

Status
GET/api/v1/serviceType/status/{serviceType_id}

Example URI

GET https://api.urjanet.net/api/v1/serviceType/status/1e62e858
URI Parameters
HideShow
serviceType_id
string (required) Example: 1e62e858

d447-d234-b5ab-c48e8ffc23b7 (required, string) - UUID of Service Type

Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e62e858-d447-d234-b5ab-c48e8ffc23b7',
        name: 'Electric',
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'system',
        createdByUsername: 'system'
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

List Service Types

List
GET/api/v1/serviceType/list

Example URI

GET https://api.urjanet.net/api/v1/serviceType/list
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '1e62e858-d447-d234-b5ab-c48e8ffc23b7',
            name: 'Electric',
            created: 1445525043973,
            modified: 1445525043973,
            lastModifiedByUsername: 'system',
            createdByUsername: 'system'
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: false,
    nextPageOffset: 8
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Providers

Get a provider

Status
GET/api/v1/template/status/{provider_id}

Example URI

GET https://api.urjanet.net/api/v1/template/status/GeorgiaPower
URI Parameters
HideShow
provider_id
string (required) Example: GeorgiaPower

UUID or providerAlias field (i.e. natural key) of the utility provider object

Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
        providerAlias: 'GeorgiaPower',
        providerName: 'Georgia Power',
        classification: 'PRIMARY',
        serviceTypes: [{
            id: '1e62e858-d447-d234-b5ab-c48e8ffc23b7',
            naturalKey: 'Electric',
            link: {
                rel: 'self',
                href: '/servicetype/status/1e62e858-d447-d234-b5ab-c48e8ffc23b7'
            }
        ]},
        parentProvider: {
            id: '48af363c-36a0-487b-bd78-6acd4610880f',
            naturalKey: 'SouthernCompany',
            link: {
                rel: 'self',
                href: '/provider/status/48af363c-36a0-487b-bd78-6acd4610880f'
            }
        },
        childProviders: [],
        templateInfos: [{
            id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
            naturalKey: 'GeorgiaPowerTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
            }
        }, {
            id: '236e3d5c-0a42-4d61-ae62-8780b6b6c974',
            naturalKey: 'SouthernCompanyTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/236e3d5c-0a42-4d61-ae62-8780b6b6c974'
            }
        }],
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'user1',
        createdByUsername: 'user2'
    },
    status: "OK",
    message: []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {}
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    }
  }
}

Search providers

Search
POST/api/v1/provider/search

Example URI

POST https://api.urjanet.net/api/v1/provider/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: null,
        filter: { 
            conditions: [{
                field: "providerAlias",
                operator: "startsWith",
                value: "Georgia"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            providerAlias: 'GeorgiaPower',
            providerName: 'Georgia Power',
            classification: 'PRIMARY',
            serviceTypes: [{
                id: '1e62e858-d447-d234-b5ab-c48e8ffc23b7',
                naturalKey: 'Electric',
                link: {
                    rel: 'self',
                    href: '/servicetype/status/1e62e858-d447-d234-b5ab-c48e8ffc23b7'
                }
            ]},
            parentProvider: {
                id: '48af363c-36a0-487b-bd78-6acd4610880f',
                naturalKey: 'SouthernCompany',
                link: {
                    rel: 'self',
                    href: '/provider/status/48af363c-36a0-487b-bd78-6acd4610880f'
                }
            },
            childProviders: [],
            templateInfos: [{
                id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
                naturalKey: 'GeorgiaPowerTemplateProvider',
                link: {
                    rel: 'self',
                    href: '/template/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
                }
            }, {
                id: '236e3d5c-0a42-4d61-ae62-8780b6b6c974',
                naturalKey: 'SouthernCompanyTemplateProvider',
                link: {
                    rel: 'self',
                    href: '/template/status/236e3d5c-0a42-4d61-ae62-8780b6b6c974'
                }
            }],
            created: 1445525043973,
            modified: 1445525043973,
            lastModifiedByUsername: 'user1',
            createdByUsername: 'user2'
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: false,
    nextPageOffset: 8
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

By Service Type
GET/api/v1/provider/byServiceType/{serviceType_id}

Example URI

GET https://api.urjanet.net/api/v1/provider/byServiceType/1e62e858
URI Parameters
HideShow
serviceType_id
string (required) Example: 1e62e858

d447-d234-b5ab-c48e8ffc23b7 (required, string) - UUID of Service Type

Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            providerAlias: 'GeorgiaPower',
            providerName: 'Georgia Power',
            classification: 'PRIMARY',
            serviceTypes: [{
                id: '1e62e858-d447-d234-b5ab-c48e8ffc23b7',
                naturalKey: 'Electric',
                link: {
                    rel: 'self',
                    href: '/servicetype/status/1e62e858-d447-d234-b5ab-c48e8ffc23b7'
                }
            ]},
            parentProvider: {
                id: '48af363c-36a0-487b-bd78-6acd4610880f',
                naturalKey: 'SouthernCompany',
                link: {
                    rel: 'self',
                    href: '/provider/status/48af363c-36a0-487b-bd78-6acd4610880f'
                }
            },
            childProviders: [],
            templateInfos: [{
                id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
                naturalKey: 'GeorgiaPowerTemplateProvider',
                link: {
                    rel: 'self',
                    href: '/template/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
                }
            }, {
                id: '236e3d5c-0a42-4d61-ae62-8780b6b6c974',
                naturalKey: 'SouthernCompanyTemplateProvider',
                link: {
                    rel: 'self',
                    href: '/template/status/236e3d5c-0a42-4d61-ae62-8780b6b6c974'
                }
            }],
            created: 1445525043973,
            modified: 1445525043973,
            lastModifiedByUsername: 'user1',
            createdByUsername: 'user2'
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: false,
    nextPageOffset: 8
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "data": {
      "type": "array"
    },
    "status": {
      "type": "string",
      "enum": [
        "OK",
        "FAILURE"
      ]
    },
    "message": {
      "type": "array"
    },
    "morePages": {
      "type": "boolean"
    },
    "nextPageOffset": {
      "type": "number"
    }
  }
}

Workflow Examples

Example A: Enroll a new account

The primary use case for this API is to enroll new accounts. Not all of these steps are always required, but are included to give a better picture of what is happening.

Create
POST/api/v1/credential/create

Create a new credential

The first step in enrolling an account is to create the credential behind which the account exists. If this is not the first account being enrolled behind the credential, this step is not necessary and the existing credential can be referenced in future steps. The prerequisite for this process is knowing what utility provider the account/credential is for. The most reliable way to do this is to work with us beforehand and set up a static map from your provider list to our provider list. It’s possible to specify the template for the credential when creating it, but it isn’t required; our system will automatically assign a best-guess for the template based on the given provider and URL (if present). The additional credentials are only required if the account has security questions or some other necessary input to get to the bill outside of just the username and password.

Example URI

POST https://api.urjanet.net/api/v1/credential/create
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    username: 'user',
    username2: 'user2',
    password: 'pass',
    customerId: 'ExampleCustomer',
    utilityProviderId: 'GeorgiaPower', [UUID above also possible here]
    url: 'https://www.google.com'
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '46e68ffa-1477-4797-b549-b4dd3d713be0',
        extractionChannelId: 'ExampleCustomer_1-GeorgiaPower_1',
        username: 'user',
        username2: 'user2',
        username3: null,
        username4: null,
        acquisitionType: 'WEB',
        s3BucketName: null,
        s3FilePrefix: null,
        message: null,
        lastAttempted: null,
        lastSuccess: null,
        template: {
            id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
            naturalKey: 'GeorgiaPowerTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
            }
        },    
        utilityProvider: {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
            }
        },
        url: 'https://www.google.com',
        enabled: true,
        intervalDataEnabled: false,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'ExampleUser',
        createdByUsername: 'ExampleUser'
    },
    status: "OK",
    message: []
}

Create
POST/api/v1/attribute/create

Create a new custom attribute

This step is only needed once for each custom attribute in the system. Once they are all set up, you won’t have to worry about them again. For this example, let’s say we want to include a site name data field along with all of the accounts.

Example URI

POST https://api.urjanet.net/api/v1/attribute/create
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'ExampleCustomer',
    name: 'SiteID',
    required: false
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '076d662a-9ecd-4a04-96f0-b3154bebb9b3',
        required: false,
        name: 'SiteId',
        cnbdPosition: -1,
        urjanetKey: null,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'ExampleUser',
        createdByUsername: 'ExampleUser'
    },
    status: "OK",
    message: []
}

Create
POST/api/v1/account/create

Create a new account

Now that the prerequisite entities have been created, the account itself can be created.

Example URI

POST https://api.urjanet.net/api/v1/account/create
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    accountNumber: '1234-56789',
    customerId: 'ExampleCustomer',
    utilityProviderId: 'GeorgiaPower', [UUID also accepted]
    subscribed: true,
    pullHistory: false,
    toBeDelivered: true,
    extractionChannelId: 'ExampleCustomer_1-GeorgiaPower_1', [UUID also accepted]
    customAttributes: {
        'SiteID': 'Site 123'
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '80da2e51-83b3-4eed-8f47-b02ee248ff77',     
        customerId: 'Customer',
        created: 1423851129417,        
        modified: 1423851129417,
        createdByUsername: 'ExampleUser',            
        lastModifiedByUsername: 'ExampleUser',
        accountNumber: '1234-56789',
        normalizedAccountNumber: '123456789',
        summaryAccountNumber: '123',
        normalizedSummaryAccountNumber: '123',
        enrollmentStatus: 'PENDING',
        extractionStatus: 'SUCCESS',
        monitoringStatus: 'UNKNOWN',
        providerClassification: 'PRIMARY',
        message: null,
        subscribed: true,
        isSummaryAccount: false,
        subscriptionLastUpdated: null,
        unsubscribeDate: null,
        pullHistory: false,
        historyRequested: null,
        toBeDelivered: true,
        deliveryLastUpdated: null,
        deliveryDisabledDate: null,
        firstExtractDate: 1423851129417,
        lastExtracted: 1423851129417,
        lastSuccessfulExtraction: 1423851129417,
        ebillRequirement: 'DO_NOT_CHANGE',
        lastDelivered: null,
        latestOrphanSourceDeliveredDate: null,
        nextExpectedPostDate: 1423851129417,
        latestIntervalEnd: 1423851129417,
        startToEndAvg: 29.54,
        nextExpectedConfidence: 'HIGH',
        latestTotalBillAmount: 326.84,
        latestStatementCreate: 1461843671000,
        lastSuccessfulExtractionChannel: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: 'Customer_1-GeorgiaPower_1',
            link: {
                rel: 'self',
                href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },
        utilityProvider: {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
            }
        },
        verifiedExtractionChannels: [],
        extractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        customAttributes: {
            'SiteID': 'Site 123'
        }
    },
    status: "OK",
    message: []
}

Create
POST/api/v1/meter/create

Create a new meter

If we want to apply any meter-level mixin, we can do that once the utility account is created. For this step, let’s assume the custom attribute ‘MeterMixin’ has already been created. It’s worth noting that meter level mixin is currently not viewable via the web UI.

Example URI

POST https://api.urjanet.net/api/v1/meter/create
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <your-bearer-token>
Body
{
    meterNumber: 'meter-123',
    customerId: 'ExampleCustomer',
    utilityAccountId: '80da2e51-83b3-4eed-8f47-b02ee248ff77',
    serviceType: 'GAS',
    customAttributes: {
        'MeterMixin': 'value1'
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '5f7c8c54-bac4-4032-9a8e-43aad010ccb6',     
        utilityAccount: {
            id: '80da2e51-83b3-4eed-8f47-b02ee248ff77',
            naturalKey: null,
            link: {
                rel: 'self',
                href: '/account/status/80da2e51-83b3-4eed-8f47-b02ee248ff77'
            }
        },
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'ExampleUser',
        createdByUsername: 'ExampleUser',
        meterNumber: 'meter-123',
        normalizedMeterNumber: 'meter123',
        serviceType: 'GAS',
        tariff: null,
        serviceAddress: null,
        podNumber: null,
        previousMeterNumber: null,
        deactivated: false,
        customAttributes: {
            'MeterMixin': 'value1',
            'SiteID': null
        }
    },
    status: "OK",
    message: []
}

Example B: Turn delivery off for group of accounts

Search
POST/api/v1/account/search

Query for particular accounts

Example URI

POST https://api.urjanet.net/api/v1/account/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: null,
        filter: { 
            conditions: [{
                field: "SiteID",
                operator: "includes",
                value: "123"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [ {
            id: '80da2e51-83b3-4eed-8f47-b02ee248ff77',     
            customerId: 'Customer',
            created: 1423851129417,        
            modified: 1423851129417,
            createdByUsername: 'ExampleUser',            
            lastModifiedByUsername: 'ExampleUser',
            accountNumber: '1234-56789',
            normalizedAccountNumber: '123456789',
            summaryAccountNumber: '123',
            normalizedSummaryAccountNumber: '123',
            enrollmentStatus: 'PENDING',
            extractionStatus: 'SUCCESS',
            monitoringStatus: 'UNKNOWN',
            providerClassification: 'PRIMARY',
            message: null,
            subscribed: true,
            isSummaryAccount: false,
            subscriptionLastUpdated: null,
            unsubscribeDate: null,
            pullHistory: false,
            historyRequested: null,
            toBeDelivered: false,
            deliveryLastUpdated: null,
            deliveryDisabledDate: null,
            firstExtractDate: 1423851129417,
            lastExtracted: 1423851129417,
            lastSuccessfulExtraction: 1423851129417,
            ebillRequirement: 'DO_NOT_CHANGE',
            lastDelivered: null,
            latestOrphanSourceDeliveredDate: null,
            nextExpectedPostDate: 1423851129417,
            latestIntervalEnd: 1423851129417,
            startToEndAvg: 29.54,
            nextExpectedConfidence: 'HIGH',
            latestTotalBillAmount: 326.84,
            latestStatementCreate: 1461843671000,
            lastSuccessfulExtractionChannel: {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            },
            utilityProvider: {
                id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
                naturalKey: 'GeorgiaPower',
                link: {
                    rel: 'self',
                    href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
                }
            },
            verifiedExtractionChannels: [
                {
                    id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                    naturalKey: 'Customer_1-GeorgiaPower_1',
                    link: {
                        rel: 'self',
                        href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                    }
                }
            ],
            extractionChannels: [
                {
                    id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                    naturalKey: 'Customer_1-GeorgiaPower_1',
                    link: {
                        rel: 'self',
                        href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                    }
                }
            ],
            customAttributes: {
                'SiteID': 'Site 123'
            }
        }, 
        ... 
    ],
    status: "OK",
    message: [],
    morePages: true,
    nextPageOffset: 100
}

Update
POST/api/v1/account/update

Update accounts

From the list of utility accounts returned above, you can compile a list of the UUIDs and update them one-by-one (there is no batch update functionality in the API).

Example URI

POST https://api.urjanet.net/api/v1/account/update
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    id: '5f7c8c54-bac4-4032-9a8e-43aad010ccb6',
    toBeDelivered: false
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '80da2e51-83b3-4eed-8f47-b02ee248ff77',     
        customerId: 'Customer',
        created: 1423851129417,        
        modified: 1423851129417,
        createdByUsername: 'ExampleUser',            
        lastModifiedByUsername: 'ExampleUser',
        accountNumber: '1234-56789',
        normalizedAccountNumber: '123456789',
        summaryAccountNumber: '123',
        normalizedSummaryAccountNumber: '123',
        enrollmentStatus: 'PENDING',
        extractionStatus: 'SUCCESS',
        monitoringStatus: 'UNKNOWN',
        providerClassification: 'PRIMARY',
        message: null,
        subscribed: true,
        isSummaryAccount: false,
        subscriptionLastUpdated: null,
        unsubscribeDate: null,
        pullHistory: false,
        historyRequested: null,
        toBeDelivered: false,
        deliveryLastUpdated: null,
        deliveryDisabledDate: null,
        firstExtractDate: 1423851129417,
        lastExtracted: 1423851129417,
        lastSuccessfulExtraction: 1423851129417,
        ebillRequirement: 'DO_NOT_CHANGE',
        lastDelivered: null,
        latestOrphanSourceDeliveredDate: null,
        nextExpectedPostDate: 1423851129417,
        latestIntervalEnd: 1423851129417,
        startToEndAvg: 29.54,
        nextExpectedConfidence: 'HIGH',
        latestTotalBillAmount: 326.84,
        latestStatementCreate: 1461843671000,
        lastSuccessfulExtractionChannel: {
            id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
            naturalKey: 'Customer_1-GeorgiaPower_1',
            link: {
                rel: 'self',
                href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
            }
        },
        utilityProvider: {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
            }
        },
        verifiedExtractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        extractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        customAttributes: {
            'SiteID': 'Site 123'
        }
    },
    status: "OK",
    message: []
}

Example C: Enroll an account directly from candidate list

In addition to extracting the requested accounts behind a credential, Urjanet also maintains a list of additional accounts that have not been specifically requested. These accounts can be searched via the API on a separate search endpoint. It’s possible to directly enroll these accounts without needing to provide all the information that normal account creation requires. The regular account enrollment workflow also works for these accounts, this separate endpoint is merely provided as a convenience.

Search
POST/api/v1/account/candidates

The first step is to identify if the desired account is in the system as a candidate account and retrieve its id if so.

Query for candidate account

Example URI

POST https://api.urjanet.net/api/v1/account/candidates
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: null,
        filter: { 
            conditions: [{
                field: "normalizedAccountNumber",
                operator: "eq",
                value: "456"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: [{
        id: '80da2e51-83b3-4eed-8f47-b02ee248ff78',     
        customerId: 'Customer',
        created: 1423851129417,        
        modified: 1423851129417,
        createdByUsername: null,            
        lastModifiedByUsername: null,
        accountNumber: '456',
        normalizedAccountNumber: '456',
        summaryAccountNumber: '123',
        normalizedSummaryAccountNumber: '123',
        enrollmentStatus: null,
        extractionStatus: 'SUCCESS',
        providerClassification: 'PRIMARY',
        pullHistory: false,
        historyRequested: null,
        monitoringStatus: null,
        providerClassification: 'PRIMARY',
        message: null,
        subscribed: false,
        isSummaryAccount: false,
        subscriptionLastUpdated: null,
        unsubscribeDate: null,
        toBeDelivered: false,
        deliveryLastUpdated: null,
        deliveryDisabledDate: null,
        firstExtractDate: 1423851129417,
        lastExtracted: 1423851129417,
        lastSuccessfulExtraction: 1423851129417,
        ebillRequirement: null,
        lastDelivered: null,
        nextExpectedPostDate: 1423851129417,
        latestIntervalEnd: 1423851129417,
        startToEndAvg: 29.54,
        nextExpectedConfidence: 'HIGH',
        latestTotalBillAmount: 326.84,
        latestStatementCreate: 1461843671000,
        utilityProvider: {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
            }
        },
        verifiedExtractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        extractionChannels: [],
        customAttributes: {}
    }],
    status: "OK",
    message: [],
    morePages: true,
    nextPageOffset: 100
}

Enroll
POST/api/v1/account/enrollCandidate

Enroll the selected candidate account

With the candidate account ID in hand, all you need to do is simply pass that id to the candidate enrollment endpoint. If there are any custom attributes marked as required, those must be passed as well.

Example URI

POST https://api.urjanet.net/api/v1/account/enrollCandidate
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    id: '80da2e51-83b3-4eed-8f47-b02ee248ff78'
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '80da2e51-83b3-4eed-8f47-b02ee248ff78',     
        customerId: 'Customer',
        created: 1423851129417,        
        modified: 1423851129417,
        createdByUsername: 'username',            
        lastModifiedByUsername: 'username',
        accountNumber: '456',
        normalizedAccountNumber: '456',
        summaryAccountNumber: '123',
        normalizedSummaryAccountNumber: '123',
        enrollmentStatus: 'SUCCESSFUL_ENROLLED',
        extractionStatus: 'SUCCESS',
        monitoringStatus: 'UNKNOWN',
        providerClassification: 'PRIMARY',
        message: null,
        subscribed: true,
        isSummaryAccount: false,
        pullHistory: true,
        historyRequested: 1423851129417,
        subscriptionLastUpdated: 1423851129417,
        unsubscribeDate: null,
        toBeDelivered: true,
        deliveryLastUpdated: 1423851129417,
        deliveryDisabledDate: null,
        firstExtractDate: 1423851129417,
        lastExtracted: 1423851129417,
        lastSuccessfulExtraction: 1423851129417,
        ebillRequirement: 'DO_NOT_CHANGE',
        lastDelivered: 1423851129417,
        nextExpectedPostDate: 1423851129417,
        latestIntervalEnd: 1423851129417,
        startToEndAvg: 29.54,
        nextExpectedConfidence: 'HIGH',
        latestTotalBillAmount: 326.84,
        latestStatementCreate: 1461843671000,
        utilityProvider: {
            id: '68c2e3ba-8c82-48a4-a6ac-e2686d4e2222',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/68c2e3ba-8c82-48a4-a6ac-e2686d4e2222'
            }
        },
        verifiedExtractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        extractionChannels: [
            {
                id: '0f496f9f-2472-4966-9fcf-0a6889070a49',
                naturalKey: 'Customer_1-GeorgiaPower_1',
                link: {
                    rel: 'self',
                    href: '/credential/status/0f496f9f-2472-4966-9fcf-0a6889070a49'
                }
            }
        ],
        customAttributes: {}
    },
    status: "OK",
    message: []
}

Example D: Update an existing credential

This workflow covers the various scenarios around updating or creating credentials. Let’s say that in this case, you’re updating a credential pair user1/pass1 to user1/pass2 for provider GeorgiaPower. Depending on the exact situation, not all of these steps may be relevant in every case, but cover the most complete scenario.

Search
POST/api/v1/credential/search

The first step is to identify if the desired credential as-is (user1/pass2) exists in the system. If it does, then there is no further action required. Note that password filters are only possible if also searching on username, and the values are not returned back in the response. If there are additional credentials (username2, etc.) then you can also search on those fields.

Query for existing credential

Example URI

POST https://api.urjanet.net/api/v1/credential/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: null,
        filter: { 
            conditions: [{
                field: "username",
                operator: "eq",
                value: "user1"
            }, {
                field: "password",
                operator: "eq",
                value: "pass2"
            }, {
                field: "utilityProviderId",
                operator: "eq",
                value: "GeorgiaPower"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '46e68ffa-1477-4797-b549-b4dd3d713be0',
        extractionChannelId: 'Customer1_1-GeorgiaPower_1',
        username: 'user1',
        username2: 'user2',
        username3: null,
        username4: null,
        acquisitionType: 'WEB',
        s3BucketName: null,
        s3FilePrefix: null,
        message: 'Example Message',
        lastAttempted: 1445525043973,
        lastSuccess: 1445525043973,
        template: {
            id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
            naturalKey: 'SouthernCompanyTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
            }
        },    
        utilityProvider: {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
            }
        },
        url: 'https://www.google.com',
        enabled: true,
        intervalDataEnabled: false,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'ExampleUser',
        createdByUsername: 'ExampleUser'
    },
    status: "OK",
    message: []
}

Search
POST/api/v1/credential/search

If no credential is found in the first request, then it is still possible that a credential exists that you want to update (i.e. user1/pass1).

Query for existing credential

Example URI

POST https://api.urjanet.net/api/v1/credential/search
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    customerId: 'Customer1',
    queryCriteria: {
        start: 0,
        length: 100,
        sorts: null,
        filter: { 
            conditions: [{
                field: "username",
                operator: "eq",
                value: "user1"
            }, {
                field: "password",
                operator: "eq",
                value: "pass1"
            }, {
                field: "utilityProviderId",
                operator: "eq",
                value: "GeorgiaPower"
            }]
        }
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '46e68ffa-1477-4797-b549-b4dd3d713be0',
        extractionChannelId: 'Customer1_1-GeorgiaPower_1',
        username: 'user1',
        username2: 'user2',
        username3: null,
        username4: null,
        acquisitionType: 'WEB',
        s3BucketName: null,
        s3FilePrefix: null,
        message: 'Example Message',
        lastAttempted: 1445525043973,
        lastSuccess: 1445525043973,
        template: {
            id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
            naturalKey: 'SouthernCompanyTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
            }
        },    
        utilityProvider: {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
            }
        },
        url: 'https://www.google.com',
        enabled: true,
        intervalDataEnabled: false,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'ExampleUser',
        createdByUsername: 'ExampleUser'
    },
    status: "OK",
    message: []
}

Update
POST/api/v1/credential/update

If the last request did return a credential, then all you need to do is submit an update request for that credential.

Update credential

Example URI

POST https://api.urjanet.net/api/v1/credential/update
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    id: 'Customer_1-GeorgiaPower_1',
    password: 'pass2'
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '46e68ffa-1477-4797-b549-b4dd3d713be0',
        extractionChannelId: 'Customer1_1-GeorgiaPower_1',
        username: 'user1',
        username2: 'user2',
        username3: null,
        username4: null,
        acquisitionType: 'WEB',
        s3BucketName: null,
        s3FilePrefix: null,
        message: 'Example Message',
        lastAttempted: 1445525043973,
        lastSuccess: 1445525043973,
        template: {
            id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
            naturalKey: 'SouthernCompanyTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
            }
        },    
        utilityProvider: {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
            }
        },
        url: 'https://www.google.com',
        enabled: true,
        intervalDataEnabled: false,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'ExampleUser',
        createdByUsername: 'ExampleUser'
    },
    status: "OK",
    message: []
}

Create
POST/api/v1/credential/create

If no existing credential at all is found from the previous steps, then the next step should be to create the credential.

Create new credential

Example URI

POST https://api.urjanet.net/api/v1/credential/create
Request
HideShow
Headers
Authorization: Bearer <your-bearer-token>
Body
{
    username: 'user1',
    password: 'pass2',
    customerId: 'Customer',
    utilityProviderId: 'GeorgiaPower',
    url: 'https://www.georgiapower.com'
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    data: {
        id: '46e68ffa-1477-4797-b549-b4dd3d713be0',
        extractionChannelId: 'Customer1_1-GeorgiaPower_1',
        username: 'user1',
        username2: 'user2',
        username3: null,
        username4: null,
        acquisitionType: 'WEB',
        s3BucketName: null,
        s3FilePrefix: null,
        message: null,
        lastAttempted: null,
        lastSuccess: null,
        template: {
            id: '2532c257-fc5e-4477-a5a1-4afe52a0ebeb',
            naturalKey: 'SouthernCompanyTemplateProvider',
            link: {
                rel: 'self',
                href: '/template/status/2532c257-fc5e-4477-a5a1-4afe52a0ebeb'
            }
        },    
        utilityProvider: {
            id: '1e4b3abd-34c2-d5ee-adef-0800270a0870',
            naturalKey: 'GeorgiaPower',
            link: {
                rel: 'self',
                href: '/provider/status/1e4b3abd-34c2-d5ee-adef-0800270a0870'
            }
        },
        url: 'https://www.google.com',
        enabled: true,
        intervalDataEnabled: false,
        created: 1445525043973,
        modified: 1445525043973,
        lastModifiedByUsername: 'ExampleUser',
        createdByUsername: 'ExampleUser'
    },
    status: "OK",
    message: []
}

Appendix

Appendix A: Account Status Breakdown

Enrollment Status

Enrollment status can never move backwards - it is a record of the furthest this account has been in the enrollment flow over its entire history.

  • SUBMITTED - Initial state of account; should automatically proceed

  • NEEDS_CREDENTIAL- Account does not have a credential associated with it

  • NEEDS_TEMPLATE - Account has a credential but that credential does not have an assigned template

  • NOMINATED - Account has a fully provisioned credential which has not yet been run

  • FAILED_TO_ACCESS - Extraction returned nothing (could be new website or broken navigation)

  • FAILED_LOGIN - The navigation failed at the login step specifically (check user/pass)

  • ACCOUNT_MISSING - The credential ran and succeeded in some capacity, but there was no trace of this account

  • STATEMENT_MISSING - The credential ran and succeeded, and the account was seen on the website, but we were unable to extract a statement

  • STATEMENT_FAILED - A statement was extracted, but was not persisted because of audit failures, storage failures, etc.

  • SUCCESSFUL_NOT_ENROLLED - Extraction of account was successful, but the account in question is not subscribed

  • SUCCESSFUL_ENROLLED - Extraction of account was successful

  • SUCCESSFUL_DELIVERED - Extraction and delivery of account were successful

Extraction Status

  • EXISTS - Initial discovery

  • SUCCESS - Extraction was successful

  • FAILED_TO_ACCESS_DURING_LOGIN - Navigation failed around the login step, but it isn’t a confirmed login failure (template may not support confirmed login failure)

  • FAILED_TO_ACCESS - Navigation wasn’t even able to attempt to log in

  • ACCOUNT_MISSING - Statements have been extracted before, but the account wasn’t seen during the latest extraction

  • STATEMENT_MISSING - Extraction saw the account, but the statement itself was missing or we were unable to reach it for some reason

  • AUDIT_CHECKSUM - Charges in statement do not checksum correctly

  • AUDIT_VALID_USAGE - There is an invalid usage group in the extracted data

  • AUDIT_INVALID_INTERVAL - Invalid date interval in the extracted data

  • AUDIT_OTHER - Another audit fired while post-processing the extracted data

  • ERROR_DATA_TYPE - Some kind of formatting error occurred during extraction

  • ERROR_MISSING_REQUIREMENT - A required field was not extracted (e.g. usage group with no unit)

  • ERROR_STORAGE - Something went wrong when trying to store statement, such as a database timeout

  • ERROR_MODEL_COLLISION - The grouping of the extracted data didn’t make sense, or a group was created that was not part of our core model

  • CUSTOMER_REJECTED_HTML - Customer-enabled audit to reject HTML caused the latest statement to be rejected

  • LOGIN_FAILURE - Confirmed failure while attempting to submit credentials (check that user/pass are correct)

  • TRACKED_ACCOUNT_SKIPPED - Account has been assessed against its Next Expected Post date and the system indicates that the newest statement is already in Urjanet’s possession and doesn’t need to be extracted again. This status only applies to accounts with a Next Expected Confidence of MEDIUM or HIGH.

  • ACCESS_CHANNEL_SKIPPED - All accounts in an access channel have been assessed against their Next Expected Post dates and the system indicates that the newest statements are already in Urjanet’s possession and don’t need to be extracted again. This status only applies to accounts with a Next Expected Confidence of MEDIUM or HIGH.

Monitoring Status

Monitoring status is manually assigned by our internal operations employees for monitoring an account.

  • UNKNOWN

  • BLOCKED - Access to the account is blocked by the website

  • PRODUCTION - Account is in production

  • INACTIVE - Account exists but is inactive (no bills or activity for >100 days)

  • LOGIN_FAILURE - A login failure is confirmed for this account

  • FINALLED - Account is closed

  • DEACTIVATED - Account not required in delivery

  • TEMPLATE_FAILURE - An issue with the template prevented successful extraction

  • LOGIN_UPDATED - The credentials have been updated after failing but have not been tested since

  • AGED_BILL - Account has not posted a recent bill

  • ACCOUNT_MISSING - Requested account is missing from the website

  • ENROLLMENT_EVENT - Requested account is the enrollment stage

  • DAQ_PRODUCTION - Account is in production via direct acquisition (DAQ)

  • ERROR_WEBSITE_PROBLEM - The website is under maintenance or the website is inaccessible during the navigation process

  • TRACKED_BILL_NOT_YET_AVAILABLE - The account and new statement date is available but the bill is not yet available on the website

  • TRACKED_STATEMENT_MISSING - The account’s statement has been tracked but it’s currently missing from the website

Provider Classification

The provider classification is how Urjanet attempts to track the role a utility provider has played on invoices over the course of Urjanet’s history of extracting an account. The provider classification field is not intended to tell the difference between supply and delivery.

A primary provider issues the invoice and a secondary provider is only mentioned or cited via pass-thru charges. If Urjanet has seen a provider play both of these roles for an account over time, its provider classification will be both.

Appendix B: Change Event Types

Below is a summary of all current event types supported by our system along with the additional fields that are relevant to that event and are returned inside the eventFields list. Any maps are returned in a flat string format. All non-map event fields are able to be used in search queries through the API.

  • AccountLinkageEvent - An exected account is linked or unlinked from a system discovered utility account

    • manual (boolean)
    • linked (boolean)
    • accountNumber (string)
    • providerAlias (string)
  • AccountNominatedEvent - A new expected account is entered into the system

    • accountNumber (string)
    • providerAlias (string)
  • AccountDeliveryChangeEvent - Delivery has been toggled for an account

    • accountNumber (string)
    • providerAlias (string)
    • oldStatus (string)
    • newStatus (string)
  • AccountSubscribeChangeEvent - Subscription has been toggled for an account

    • accountNumber (string)
    • providerAlias (string)
    • oldStatus (string)
    • newStatus (string)
  • FormSubmissionEvent - An activation form is uploaded via the web portal

    • requestedByName (string)
    • requestedByEmail (string)
    • referenceTicketId (string)
  • MixinChangeEvent - Change occurred to an account’s custom attributes

    • oldValues (map)
    • newValues (map)
    • accountNumber (string)
    • providerAlias (string)
  • CredentialStateChangeEvent - Meta-data for a credential (e.g. environment to run in, interval data toggle, etc.) was changed

    • extractionChannelId (string)
    • oldValues (map)
    • newValues (map)
  • CredentialInputMapChangeEvent - Input map information such as username, password, or acquisition type were changed. Password values are not returned, but are noted to have changed

    • extractionChannelId (string)
    • oldValues (map)
    • newValues (map)
  • MeterLinkageEvent - An expected meter is linked or unlinked from a system discovered utility meter

    • meterNumber (string)
    • manual (boolean)
    • linked (boolean)
    • accountNumber (string)
    • providerAlias (string)
  • MeterMixinChangeEvent - Change occurred to a meter’s custom attributes

    • meterNumber (string)
    • accountNumber (string)
    • providerAlias (string)
    • oldValues (map)
    • newValues (map)
  • EnrollmentStatusChangeEvent - The enum status relating to enrollment was updated on an account

    • oldStatus (string)
    • newStatus (string)
    • accountNumber (string)
    • providerAlias (string)
  • MonitoringStatusChangeEvent - A manual status used by our operations team for monitoring purposes was updated on an account

    • oldStatus (string)
    • newStatus (string)
    • accountNumber (string)
    • providerAlias (string)
  • AccountDeletionEvent - An account request has been deleted

    • accountNumber (string)
    • providerAlias (string)
  • SummaryAccountDeletionEvent - A summary account entity associated with an account has been deleted

    • accountNumber (string)
    • summaryAccountNumber (string)
    • providerAlias (string)

Appendix C: Search Criteria Object Model

For search calls, a criteria object specifying the filter(s) and sort(s) is expected. The parameters for the query are taken is as a JSON string passed in the body of the POST for the applicable calls. The maximum return size of a search call is 1000 entities. If a greater length than this is specified, the result list will be truncated to the first 1000; if no length is specified, it will default to 100. If no criteria object is passed to the server, then it will default to the first 1000 entities in the database with no defined sort. An example is presented below.

{ start: 0, length: 100, sorts: [{ field: “accountNumber”, direction: “asc” }], filter: { conditions: [{ field: “accountNumber”, operator: “startswith”, value: “100” }] } }

Any value other than ‘asc’ for sort direction is handled as equivalent to a descending ordering. Data type is inferred from the field name that is supplied. Dates must be formatted as a long representing milliseconds since the standard base time known as “the epoch” (January 1, 1970 00:00:00 GMT). The possible values for the filter condition operator field are as follows:

  • ‘eq’ - Equal (for number / string values)

  • ‘neq’ or ‘ne’ - Not equal (for number / string values)

  • ‘gt’ - Greater than (for number values)

  • ‘lt’ - Less than (for number values)

  • ‘gte’ - Greater than or equal to (for number values)

  • ‘lte’ - Less than or equal to (for number values)

  • ‘include’ or ‘includes’ - Includes (for String values)

  • ‘startswith’ - Starts with (for String values)

  • ‘endswith’ - Ends with (for String values)

  • ‘notinclude’ - Does not include (for String values)

  • ‘is’ - Equal (for boolean values)

  • ‘before’ - Less than (for date values)

  • ‘after’ - Greater than (for date values)

  • ‘on’ - Equal to (for date values)

  • ‘isblank’ - Is null or empty string

  • ‘notblank’ - Is not null or empty string

Appendix D: Error Codes

Below is a comprehensive list of all possible error codes that can be returned as a value for the messageCode field of a response along with the respective HTTP status code.

  • SUCCESS (200)

  • INVALID_ARGUMENTS (400)

  • NOT_FOUND (404)

  • NOT_AUTHORIZED (401)

  • ALREADY_EXISTS (400)

  • PROVIDIER_NOT_FOUND (400)

  • MALFORMED_REQUEST (400)

  • ACCOUNT_CREATE_FAILURE (500)

  • ACCOUNT_CREATE_PARTIAL_FAILURE (500)

  • ACCOUNT_UPDATE_FAILURE (500)

  • ACCOUNT_SEARCH_FAILURE (500)

  • CREDENTIAL_CREATE_FAILURE (500)

  • CREDENTIAL_SEARCH_FAILURE (500)

  • CREDENTIAL_UPDATE_FAILURE (500)

  • METER_SEARCH_FAILURE (500)

  • METER_UPDATE_FAILURE (500)

  • PROVIDER_SEARCH_FAILURE (500)

  • TEMPLATE_SEARCH_FAILURE (500)

Appendix E: Verified Extraction Channel vs. Extraction Channel

UtilityAccounts have both an extractionChannels and a verifiedExtractionChannels field. The difference between these fields is subtle but important. verifiedExtractionChannels include any credential that we have ever extracted the account under. The extractionChannels field will only contain the credentials that are explicitly assigned by the customer for that account. In general, these will usually match, but over time they may diverge some. When you first submit an account request, verifiedExtractionChannels will be empty until our system extracts that account. Similarly, any candidate accounts you search for will have empty extractionChannels fields until they are requested.

Appendix F: Change Log

11/27/2018 - v. 1.0.27

  • Removed deprecated monitoring status

  • Added new monitoring statuses

  • Fixed various typographical errors

7/11/2018 - v. 1.0.26

  • Added new fields to Credential for S3 acquisition

4/04/2018 - v. 1.0.25

  • Added intervalDataEnabled boolean to create / update credential endpoint

1/10/2018 - v. 1.0.24

  • Added enabled boolean to create credential endpoint

  • Added extractionChannelIds list to update account endpoint

9/19/2017 - v. 1.0.23

  • Added message, lastAttempted, lastSuccess fields to Credential

8/15/2017 - v. 1.0.22

  • Added latestStatementCreate field to UtilityAccount

  • Fixed some missing status detail

8/15/2017 - v. 1.0.21

  • Added verifiedExtractionChannel field to UtilityAccount

8/11/2017 - v. 1.0.20

  • Updated the General Usage Notes section

  • Added additional notes on how to use additional username and password fields

  • Removed deprecated Monitoring statuses: ACCOUNT_NUMBER_MISMATCH, DELETED, DOES_NOT_EXIST, ENROLLMENT FAILURE, NO_BILL and PENDING

  • Added new Monitoring statuses: AGED_BILL, ATL_REVIEW, ACCOUNT_MISSING, ENROLLMENT and DAQ_PRODUCTION

  • Added new Extraction statuses: TRACKED_ACCOUNT_SKIPPED and ACCESS_CHANNEL_SKIPPED

  • Expanded some of the example response bodies

7/6/2017 - v. 1.0.19

  • Added lastSuccessfulExtractionChannel field to UtilityAccount

  • Improvements for usability of Credential search logic

  • Added Workflow Example D to documentation

1/23/2017 - v. 1.0.19

  • Added ProviderClassification enum value to UtilityAccount

  • Added firstExtractDate field to UtilityAccount

  • Added description of ProviderClassification enum values

12/21/2016 - v. 1.0.18

  • Added latestOrphanSourceDeliveredDate to UtilityAccount

12/20/2016 - v. 1.0.17

  • Added AccountDeletionEvent

  • Fixed some missing status detail

12/19/2016 - v. 1.0.16

  • Added workflow example for enrolling candidate accounts

11/2/2016 - v. 1.0.15

  • Added enrollCandidate endpoint to account module

10/27/2016 - v. 1.0.14

  • Added username2, username3, username4, password2, password3, and password4 fields to Credential object

  • Added additional notes to documentation on searching on password fields

  • Removed additionalCredentials array on Credential object from documentation

10/13/2016 - v. 1.0.13

  • Added isSummaryAccount boolean to UtilityAccount

8/30/2016 - v. 1.0.12

  • Added message field to UtilityAccount

8/23/2016 - v. 1.0.11

  • Added pullHistory and historyRequested fields to UtilityAccount

  • Added ability to toggle enabled flag on Credential updates

7/29/2016 - v. 1.0.10

  • Fixed incorrectly structured request examples

  • Removed FilterChangeEvent

  • Added AccountDeliveryChangeEvent

  • Added AccountSubscribeChangeEvent

7/8/2016 - v. 1.0.9

  • Added summaryAccountNumber and normalizedSummaryAccountNumber fields to UtilityAccount

6/10/2016 - v. 1.0.8

  • Added Service Type endpoints and relationship with UtilityProvider

  • Added hasOcr and tracksLoginFailure flags to TemplateInfo

  • Added classification enum to UtilityProvider

5/24/2016 - v. 1.0.7

  • Added lastDelivered, nextExpectedPostDate, latestIntervalEnd, and startToEndAvg fields to UtilityAccount

  • Fixed the format of Credential IDs to match that of all other IDs

4/20/2016 - v. 1.0.6

  • Added new statuses to MonitoringStatus enum

  • normalizedAccountNumber no longer contains leading zeroes

1/21/2016 - v. 1.0.5

  • Added enabled field to Credential object

  • Added url field to documentation of Credential object to reflect the existing state

  • Changed extractionChannel field on UtilityAccount to a list of EntityReference objects and changed name to extractionChannels

10/22/2015 - v. 1.0.4

  • Transferred API documentation to new API Blueprint format

8/19/2015 - v. 1.0.3

  • Added naturalKey field to EntityReference

  • Added a change history

  • All module names are now singular (e.g. /provider/search instead of /providers/search)

  • Switched relevant responses to use EntityReference objects instead of in-line aliases or UUIDS (i.e. all references to templates, accounts, credentials, and providers)

  • Added new set of change events to API

    • CredentialStateChangeEvent
    • CredentialInputMapChangeEvent
    • MeterLinkageEvent
    • MeterMixinChangeEvent
    • EnrollmentStatusChangeEvent
    • MonitoringStatusChangeEvent
  • Added monitoringStatus enum field to UtilityAccount

  • Modified accountNumber and providerAlias from being top-level fields to being fields under the eventFields map for ChangeEvent

  • customerId no longer needed when updating a UtilityAccount

  • References to “provider” are now “utilityProvider”; references to “account” are now “utilityAccount”

  • For incoming requests when specifying entities by ID or natural key, the same field is used (e.g. just one “utilityProviderId” that can be either instead of separate “providerId” and “providerAlias” fields)

  • Added this appendix to doc for tracking future changes to API and/or doc.

  • Added a short summary at the top of example API usage

  • accountId changed to id for UtilityAccount update request

  • Link fields changed from ref and uri to rel and href, respectively

  • Modified API to allow alias or UUID when specifying entity references in search

  • Remove requirement for manually specifying dataType in queryCriteria object when searching

  • Renamed dataField to field on the QueryCriteria object for sorting

Generated by aglio on 27 Nov 2018