Accounts API

RevOps helps software businesses automate customer account creation and management, while simultaneously synchronizing information to billing, CRMs, and other connected apps.

The Accounts API lets you setup PII and PCI safe communication between your account activation and billing workflows.

Why manage customer accounts with RevOps?

Modern software businesses face many challenges onboarding and managing customers that have a variety of billing and payment preferences. RevOps.js lets businesses quickly build payment portals, automatically create new customer accounts, and capture billing information in a secure and compliant way.

For every customer created, RevOps keeps your customer information up-to-date across connected applications and build custom applications for your customer lifecycle, e.g., when they sign up, when they pay, and even detect fraud.

How does it work?

  1. Create a payment portal to capture customer information using revops-js
  2. Use the /v1/accounts REST API to View or modify customer account information
  3. RevOps will automate the rest!

Accounts Endpoints

Each endpoint assumes a default base url: https://vault.revops.io/v1/

Accounts List Resource

https://vault.revops.io/v1/accounts

Supported Methods:

  • GET - Retrieves a list of accounts
  • POST - Creates an account

API Key Accessibility

It is only possible to create POST requests to create new accounts publicly. The remaining methods are only accessible on use of the secret key.

HTTP Method Public Key Secret Key
GET N/A
POST

CREATE ACCOUNTS

POST /v1/accounts

Summary:

Creates and verifies payable Accounts in RevOps. Send as much account information to RevOps to validate the account.

Description:

A new account is created by sending a POST request to the resource URL /v1/accounts. You must always use a unique email address when creating accounts.

** Note for sandbox mode ** While you are testing in sandbox mode, you can send multiple requests with the same email address.

There are two required parameters:

  1. account_id
  2. email

The remaining fields can defined as much of the object as you'd like. If the account is provided complete credentials, either ACH, Card, or a Plaid linking token, then it will automatically move the account to active status.

HTTP Response Codes

Code Description Schema
201 Created account Account
400 Invalid request. API Error

Example

This example creates an account via the public key.

$> curl  https://vault.revops.io/v1/accounts \
        -X POST \
        -H 'Authorization: Bearer <public_key>' \
        -H 'Content-type: application/json' \
        -d '{ "account_id": "superkalifragilisticexpealidocious", "email": "i-love-chocolate@example.com" }'

Here is the same example in python.

from uuid import uuid4
import urllib.request
import json

api_key = "sk_sandbox_<yourkey>"
api_url = "https://vault.revops.io/v1/accounts"

account = {
    'account_id': "my-account-id",
    'email': "my-email",
    'billing_contact': {
        'address': '',
        'city': '',
        'country': '',
        'first_name': '',
        },
}

data = json.dumps(account).encode('utf8')

request = urllib.request.Request(
  api_url,
  method='POST',
  data=data,
  headers={
    'Content-type': 'application/json',
    'Authorization': "Bearer {}".format(api_key),
  },
)
try:
    with urllib.request.urlopen(request) as response:
        json_response = response.read().decode('utf-8')
        print(json.loads(json_response))
except urllib.error.HTTPError as httperror:
    print(httperror.read().decode('utf-8'))

GET ACCOUNTS

GET /v1/accounts

Summary:

Returns a list of Accounts.

Query Parameters for filtering accounts

In addition to pagination parameters , you can filter Accounts by any of these parameters.

Name Description
status Filters Accounts by status. Options are pending, activating, active, deleted. See Account Status for more info.
blocked Filters Accounts that are blocked. Options are true, false, or all .
verified Filters Accounts that have been verified by your team. true, false, or all.
email Filters Accounts on one or more comma separated emails.
accountId Filters Accounts on one or more comma separated accountIds.
planId Filters Accounts with one or more comma separated Plan ids.

Description:

A new account is created by sending a POST request to the resource URL /v1/accounts.

HTTP Response Codes

Code Description Schema
201 Created account Account
400 Invalid request API Error

Accounts Instance Resource

https://vault.revops.io/v1/accounts/:acct_id

Supported Methods:

  • GET - Retrieves Account
  • POST - Updates existing Account
  • DELETE - Deactivates Account
URL Parameters
Name Description Required Schema
acct_id Unique identifier for the Account generated by the API. Yes string

** Identifier Aliases **

To make the API as developer friendly as possible, the API will accept either a RevOps generated identifier (prefixed with acct_) or the unique identifier you provided when creating the account.

For example, if we assume an account created with the account id "superkalifragilisticexpealidocious" returns the unique id "acct_64783bb1f3a849d2b600a17ce041fc2d", then the two resources are interchangeable:

https://vault.revops.io/v1/accounts/acct_64783bb1f3a849d2b600a17ce041fc2d https://vault.revops.io/v1/accounts/superkalifragilisticexpealidocious

API Key Accessibility

HTTP Method Public Key Secret Key
GET N/A
POST N/A
DELETE N/A

UPDATE ACCOUNTS

POST /v1/accounts/:acct_id

Example

$> curl  https://vault.revops.io/v1/accounts/:acct_id \
        -H 'Authorization: Bearer <api_key>' \
        -H 'Content-type: application/json' \
        -d '{ "account_id": "superkalifragilisticexpealidocious" }'
from uuid import uuid4
import urllib.request
import json

api_key = "sk_sandbox_<yourkey>"
api_url = "https://vault.revops.io/v1/accounts/:acct_id"

account = {
    'id': 'acct_id',
    'account_id': "my-account-id",
    'email': "my-email@example.com",
    'billing_contact': {
        'address': '123 Front st.',
        'city': 'San Francisco',
        'country': 'USA',
        'first_name': 'Chris',
        'last_name': 'Learner',
    }
    'primary_instrument_id': 'inst_id',
}

data = json.dumps(account).encode('utf8')

request = urllib.request.Request(
  api_url,
  method='POST',
  data=data,
  headers={
    'Content-type': 'application/json',
    'Authorization': "Bearer {}".format(api_key),
  },
)
try:
    with urllib.request.urlopen(request) as response:
        json_response = response.read().decode('utf-8')
        print(json.loads(json_response))
except urllib.error.HTTPError as httperror:
    print(httperror.read().decode('utf-8'))

Examples Response:

{
  "id": "acct_id",
  "uri": "/v1/accounts/:acct_id",
  "account_id": "your-favorite-accountId",
  "billing_contact": {
    "address": "",
    "address2": "",
    "bank_account_holder_name": "",
    "bank_account_holder_type": "",
    "bank_account_number": "",
    "bank_country": "",
    "bank_name": "",
    "bank_routing_number": "",
    "city": "",
    "country": "",
    "email": "",
    "first_name": "",
    "id": "48c89982-f06c-4f80-b575-ee773c56537d",
    "last_name": "",
    "middle_name": "",
    "payment_method": "",
    "phone": "",
    "postal_code": "",
    "province": "",
    "salesforce_contact_id": "",
    "title": ""
  },
  "blocked": false,
  "date_created": "2019-10-02T17:30:42+00:00",
  "date_updated": "2019-11-26T19:05:31.134470+00:00",
  "email": "example@email.com",
  "in_contract": false,
  "name": "",
  "parent_account_id": "",
  "payable": false,
  "primary_instrument_id": "",
  "plan_id": "plan_id",
  "status": "active",
  "stripe_customer_id": ":cus_id",
  "verified": false
}

Description:

An existing customer Account is updated by sending a POST request to the resource URL.

Responses

Code Description Schema
200 Updated Account Account
400 Invalid request. API Error

DELETE

Summary:

Customer Accounts created within RevOps cannot be deleted from the platform. Instead, an Account is deprovisioned and updated to reflect this status.

Description:

A customer can be deprovisioned by sending a DELETE request to the resource’s URL

Responses

Code Description
204 Successful operation. The server returns a 204 No Content status code if a deletion request is successful and no content is returned.
404 Account record not found. The server returns a 404 Not Found status code if a deletion request fails due to the resource not existing.

Models

Account

Account describes the relationship between your business, the Account, and how they like to pay. The list of properties for Account are:

Name Type Options Description Required
id string RevOps assigned unique identifier No
status string See Account Status for more info. pending, activating, active, deleted. Indicates the status of the Account. Possible values are: No
blocked boolean true, false Indicates whether the Account is blocked. No
in_contract boolean true, false Indicates whether the Account is contractual or pay-as-you-go customer. No
verified boolean true, false Indicates whether the Account has been verified by your team. No
uri string RevOps assigned URI for accessing the Account through a GET request
billing_contact [BillingContact] Billing contact information associated with the Account Yes
date_created ISO8601 Datetime in UTC Time that the event was submitted to RevOps. Automatically created if not provided No
date_updated ISO8601 Datetime in UTC Time that the event was submitted to RevOps. Automatically created if not provided No

Account Status

The Account Status helps track the lifecycle from signup to end of life.

Status Description
pending The Account has been created, but has not attempted to activate a payment.
activating The Account still requires information to become a paying account.
active The Account is an active paying account.
deleted The Account has been deleted.

API Error Response Format

The standard API response format is used to indicate when we were not able to process the request.

Name Type Description Required
code integer RevOps Error Code No
type string RevOps Error Code No
message string Human readable description of the error code No
BillingPreferences

BillingPreferences have been deprecated in favor of the Instruments API.